Repository navigation
Releases
1.1.1: fix confirmation
Fix confirmation. The in-the-loop integrations now close the loop: when a developer resolves a risk that ai-surface flagged, ai-surface confirms it, by name, in the same session.
Added
- Fix confirmation: the hook and MCP diff report cleared risks. When an edit puts a human approval gate in front of a flagged financial or destructive action, the Claude Code hook posts "a flagged risk was cleared by this edit" and the
check_new_ai_surfacediff reportsrisks_removedand arisks_clearedcount, instead of staying silent. Previously the rolling baseline only ever reported additions, so a fix produced no feedback.
Changed
- The
no-human-oversightaudit flag is mirrored as a severity-free risk indicator (no human approval gate on a high-risk action) so the gate's absence and its later presence both survive the baseline diff. - Once an approval gate is detected on the path, the
financial-actionanddestructive-actionremediation reads "Approval gate detected on this path. Keep it in front of the action and least-privilege the agent." rather than telling the user to add a gate that is already there. Severity is unchanged.
Fixed
- Upgrading from 1.1.0 no longer produces a one-time "risk added: no human approval gate" message for agents that were already ungated: a baseline written by an older version is reconciled on its first diff, so only changes the developer makes are reported.
Install or upgrade: pip install -U apisec-ai-surface (pip install -U "apisec-ai-surface[mcp]" for the MCP server)
1.1.0: MCP server and Claude Code hook
ai-surface now runs inside the AI coding tools that write the code: as an MCP server, and as an automatic post-edit hook for Claude Code. The finding arrives at the moment the surface is created, not at PR time.
Added
- MCP server:
ai-surface mcp. A stdio Model Context Protocol server any MCP client can launch (Claude Code, Cursor, Windsurf, Cline). Two tools:scan_ai_surface(path, max_surfaces)inventories a path with counts, top risks, governance frameworks, and the highest-severity surfaces;check_new_ai_surface(path, baseline_file)reports only what is NEW, MODIFIED, or REMOVED since the previous call, or since a given committed baseline. Every entry carries the compliance block (OWASP LLM Top 10 ids, EU AI Act / NIST AI RMF / ISO 42001 clauses, remediation). Read-only, offline, no network listener. Installed with the optional extrapip install "apisec-ai-surface[mcp]"(Python 3.10+; works with mcp 1.x and 2.x). - Claude Code hook:
ai-surface hook claude-code. APostToolUsehook that diffs the AI surface after everyEdit/Write/MultiEdit/NotebookEdit/Bashcall and injects the finding into the session when a change introduces or expands AI surface, plus aSessionStartmode that seeds the baseline so the very first surface-adding edit is caught. Silent on ordinary edits, exits 0 on every internal error so it never breaks the editor, refuses to scan a home directory or filesystem root, and scans once per edit (in-process).--resetforgets the rolling baseline. ai-surface init --claude-code. Writes the hook into.claude/settings.jsonand the MCP server into.mcp.jsonfor the current repo, merging with existing entries and idempotent on re-run.docs/INTEGRATIONS.mdcovering both integrations, the hook contract, state location, and troubleshooting.
Changed
- Integration state lives outside the repository. The rolling baselines used by the MCP tool and the hook are stored under a per-user state directory (
$XDG_CACHE_HOME/ai-surface,~/.cache/ai-surface, or%LOCALAPPDATA%\ai-surface; override withAI_SURFACE_STATE_DIR), keyed by repo path. They never touch a committed.ai-surface-baseline.json, which stays a reviewable CI control, and never appear as untracked files. - Diff JSON carries governance standards.
scan --baseline -o json(and the Action's diff) now serializes added and removed findings through the JSON reporter, so their risk flags include thestandardsjoin exactly as in a full report. Additive; schema version unchanged. - The self-test matrix and the security scan install the
[mcp]extra so the MCP protocol round-trip runs in CI on Python 3.10+.
Install: pip install "apisec-ai-surface[mcp]" then ai-surface init --claude-code. Full guide: docs/INTEGRATIONS.md.
1.0.8: unsafe command-allowlist detection for MCP servers
Added
- Unsafe command-allowlist detection (MCP). Flags MCP servers whose command allowlist (e.g.
ALLOW_COMMANDS) names a binary with its own argument-level execution primitive, where checkingargv[0]alone does not restrict execution:git -c alias,find -exec,python -c,tar --checkpoint-action, and shells /env/xargs/ssh. Raised as aconfirmedrisk under the MCP audit and mapped to OWASP LLM06 (Excessive Agency). Token-based key matching excludes denylists (DISALLOW_COMMANDS), unrelated toggles (ALLOW_COMMAND_LOGGING), and full-argument-vector allowlists (ALLOW_COMMANDS="git status"). Original detection contributed inapisec-inc/mcp-audit.
1.0.7: verdicts on findings, scan scorecard, one-command CI setup
Findings now carry a verdict, every scan ends on a scorecard, and CI setup is one command.
Added
- Verdicts on every risky finding. Each finding with risk signal is tagged
CONFIRMED RISK(an unambiguous fact of the code or config as written: a declared capability, a present secret name, a declared remote endpoint) orLIKELY RISK(inferred from a pattern, a reputation signal, or an absence of signal; wants a human look). Verdicts render in the terminal, JSON, SARIF, the PR comment, and the offline UI. A verdict never claims runtime exploitability; proving that against the running application is what the APIsec platform validates. - AI Surface Scorecard. Every terminal scan now ends with a compact scorecard: a posture grade (A through D), surface / confirmed / likely counts, and the single worst finding.
ai-surface init. Writes the recommended GitHub Action workflow into your repo so every PR is gated on net-new AI attack surface, and prints the pre-commit snippet.- pre-commit support. The repo now ships
.pre-commit-hooks.yaml; addapisec-inc/AI-Surfaceto your.pre-commit-config.yamlto scan before every commit.
Fixed
- The runtime version string now matches the release. 1.0.6 shipped with an un-bumped
__version__, soai-surface versionand thetool_versionfield in reports said 1.0.5.
Install: pip install apisec-ai-surface · Docs: README · CHANGELOG
ai-surface v1.0.6
Fixes the GitHub Action's net-new PR diff, which silently degraded to a full-inventory comparison in the published Docker action.
Fixed
- Action: PR base-branch diff works again. The Docker action runs as root while the checked-out workspace is owned by the runner user, so
git fetch origin <base_ref>hit git's dubious-ownership guard and the action silently fell back to comparing against the full inventory instead of net-new findings. The workspace is now marked as a gitsafe.directorybefore the base fetch, and an already-fetchedorigin/<base_ref>(fromactions/checkoutwithfetch-depth: 0) is used as a fallback if the fetch fails.fail-onnow gates on net-new findings in PRs, as documented.
Added
- A one-line star ask in the CLI footer, the markdown report footer, the Action's PR comment, and the README.
Full Changelog: v1.0.5...v1.0.6
ai-surface v1.0.5
ai-surface v1.0.4
ai-surface v1.0.3
ai-surface v1.0.2
ai-surface maps the AI attack surface in your codebase — LLM calls, agents, MCP servers, RAG/vector stores, model gateways, provider keys, and the HTTP APIs that expose them. It generates an AI-BOM, maps findings to OWASP LLM Top 10 / EU AI Act / NIST / ISO, and gates new high-risk findings at PR time. Local, offline, no telemetry, no credentials.
Use it in CI
- uses: actions/checkout@v4
with:
fetch-depth: 0 # required for base-vs-head diff
- uses: apisec-inc/AI-Surface@v1
with:
comment-on-pr: 'true'
fail-on: 'high' # fail only on NEW high/critical findingsPosts a sticky PR comment showing what the PR changed, and fails the build only on newly introduced high-or-critical findings. Uses the built-in GITHUB_TOKEN — no API keys.
This release (1.0.2)
Maintenance: widened rich (<16) and pathspec (<2.0) dependency bounds so installs aren't pinned to old majors. No functional changes.
Full changelog: https://github.com/apisec-inc/AI-Surface/blob/main/CHANGELOG.md