ai-surface
Find the AI attack surface your code is about to ship. Locally, offline, before the PR merges.
Agenten stärken
Installation vom Herausgeber. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
Noch kein paketiertes Release in der Registry. Folgen Sie der README des Repositorys.
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
Startenai-surface maps the AI attack surface in your codebase: LLM calls, agents, MCP servers, RAG/vector stores, model gateways, self-hosted runtimes, provider keys, and the HTTP APIs that expose them. Run it locally, in CI, or inside your AI coding tool to see what AI surfaces a change introduces, generate an AI-BOM, and gate new high-risk findings before merge.
Most layers of a codebase already have a check that runs before merge: Trivy for container images, Gitleaks for committed secrets, an SCA for dependencies. The AI layer, the agents, MCP servers, RAG, and LLM calls, has not had one. ai-surface is that check.
Every risky finding carries a verdict: confirmed risk (an unambiguous fact of the code as written, like a financial-action tool with no approval step) or likely risk (inferred, wants a human look). Every scan ends on a scorecard with a posture grade. CI setup is one command: ai-surface init.
It runs as a local static analysis pass that executes no code, makes no network calls, sends no telemetry, and requires no credentials, so your source never leaves the host.
Try it without installing:
uvx --from apisec-ai-surface ai-surface scan .
If ai-surface is useful to you, star the repo so more engineers find it.
Findings map to the OWASP LLM Top 10 and the EU AI Act, NIST AI RMF, and ISO 42001, so the AI-BOM doubles as governance evidence (see Compliance). Runtime exploit validation is out of scope for this OSS scanner.
The optional --ui map shows detected AI surfaces as nodes grouped by category. It is served on loopback and runs locally.
Use ai-surface if you are:
Built for DevOps, DevSecOps, platform engineering, AppSec, and security-minded engineering teams.
Install once, then run ai-surface anywhere:
pipx install apisec-ai-surface
ai-surface scan .
# if the ai-surface command is not found after install, run: pipx ensurepath
# then open a new shell
# or run once with no install
uvx --from apisec-ai-surface ai-surface scan .
# or in a project venv
pip install apisec-ai-surface && ai-surface scan .
# explore the results visually
ai-surface scan . --ui
Requires Python 3.9+. The CLI runs locally; --ui serves on loopback only.
Reproduce this yourself on the bundled demo app: ai-surface scan examples/demo-app --governance (add --ui for the interactive map). Each risky finding carries a verdict: CONFIRMED RISK when the risk is a fact of the code as written (a declared capability, a present secret, a financial tool with no approval step) or LIKELY RISK when it is inferred and wants a human look. The run ends on a scorecard. The block is shown with --governance so the per-finding EU AI Act / NIST / ISO clauses are visible; by default those collapse to a single summary line (Governance: evidence for EU AI Act, NIST AI RMF, ISO/IEC 42001, OWASP LLM Top 10). Add --ai-only to drop the plain API-endpoint section. Output below is trimmed for length.
AI Attack Surface Report
────────────────────────────────────────────────────────────────
Project: demo-app
19 production AI surfaces · 25 risk indicators · across 8 detector(s)
Severity: 3 high · 1 medium
AGENT FRAMEWORKS
• AWS Strands Agent: triage_agent (in src/support_workflow.py)
Tools/perms: fetch_customer_profile, search_knowledge_base, escalate_to_human
• LangChain Agent: support_agent (in src/chat_agent.py) CONFIRMED RISK [HIGH]
Tools/perms: lookup_order, refund_payment, cancel_subscription
⚠ financial action exposed ⚠ high blast-radius combination
⚑ [HIGH] financial-action
Agent can invoke financial tools (refund_payment)
OWASP: LLM06 Governance: EU AI Act Art. 9
Fix: Gate financial tools behind human approval; least-privilege the agent.
⚑ [HIGH] no-human-oversight
High-risk action runs with no human approval / in-the-loop gate detected
OWASP: LLM06, LLM09 Governance: EU AI Act Art. 14
MCP SERVERS
• MCP Server: stripe-mcp CONFIRMED RISK [HIGH] Trust: verified (90/100)
Tools/perms: read_charges, refund, customer:read
⚑ [HIGH] financial-action
MCP exposes financial tools (refund, charge, payout) to the model.
OWASP: LLM06 Governance: EU AI Act Art. 9
⚑ [MEDIUM] unverified-source
MCP is not from a known/verified publisher; its posture is unknown.
OWASP: LLM03 Governance: ISO 42001 A.10
• MCP Server: github-mcp CONFIRMED RISK [MEDIUM]
⚑ [MEDIUM] remote-mcp MCP connects to a remote server via URL
⚑ [MEDIUM] broad-permissions MCP is granted broad (admin/write) scopes
LLM SDK CALL SITES
• Anthropic SDK LIKELY RISK · claude-3-5-sonnet · src/llm_service.py
⚠ non-literal data flows into LLM call
• AWS Bedrock · us.anthropic.claude-sonnet-4 · src/support_workflow.py
VECTOR-STORE
• Vector store: pgvector LIKELY RISK ⚠ retrieved content reaches the model (RAG)
• RAG pipeline: LangChain LIKELY RISK ⚠ ingests external content (RAG poisoning surface)
API ENDPOINTS
• REST API: GET /orders/{order_id} LIKELY RISK ⚠ object-id in path (BOLA candidate)
• REST API: PATCH /customers/{customer_id} LIKELY RISK ⚠ object-id in path (BOLA candidate)
Governance: evidence for EU AI Act, NIST AI RMF, ISO/IEC 42001, OWASP LLM Top 10
────────────────────────────────────────────────────────────────
AI Surface Scorecard D
19 surfaces · 4 confirmed risk · 11 likely risk
Worst finding: MCP Server: stripe-mcp: MCP exposes financial tools (refund, charge, payout) to the model.
The first run maps the AI surfaces already present in the codebase. The pattern that scales is to baseline existing surfaces, then gate only new high-risk findings in pull requests:
ai-surface scan . --update-baseline # 1. snapshot today's inventory
ai-surface scan . --baseline # 2. show only what changed
ai-surface scan . --baseline --fail-on high # 3. in CI, fail only on NEW high+ risk
--baseline --fail-on high is the recommended PR gate: low-noise, non-blocking on pre-existing debt, and actionable.
The fastest path is one command from your repo root:
ai-surface init
It writes the recommended workflow below into .github/workflows/ai-surface.yml and prints a pre-commit snippet for local scans (the repo ships .pre-commit-hooks.yaml).
Or drop this into .github/workflows/ai-surface.yml yourself:
name: AI Surface Check
on: [pull_request]
permissions:
contents: read
pull-requests: write # required when comment-on-pr is true
jobs:
ai-surface:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # required for base-vs-head diff
- uses: apisec-inc/AI-Surface@v1
with:
path: '.'
comment-on-pr: 'true'
fail-on: 'high' # fail only on NEW high-or-critical findings
Every PR gets a sticky comment showing what changed in the PR, not just the current repo state. fail-on gates on assessed severity, so inventory-only findings do not fail the build. With fail-on: high, the build fails only when the PR introduces a new high-or-critical finding.
No API keys are required. The action uses the built-in GITHUB_TOKEN to post or update the PR comment.
For non-GitHub CI, the gate is just an exit code:
ai-surface scan . --fail-on high
See docs/CI_INTEGRATION.md for permissions, fork PR behavior, baseline options, SARIF upload, policy files, and multi-repo rollups.
AI assistants now write a growing share of application code, and AI-written code is exactly where new AI attack surface appears: a new agent tool, a new MCP server, a new LLM call, usually added by someone who cannot see what they just exposed. ai-surface can sit inside that loop and flag the surface at the moment it is created.
Two pieces, both local, offline, and read-only:
ai-surface mcp exposes two tools to any MCP client (Claude Code, Cursor, Windsurf, Cline): scan_ai_surface inventories a path, and check_new_ai_surface reports only what changed since the last check, with the OWASP LLM Top 10 ids and EU AI Act, NIST AI RMF, and ISO 42001 clauses for each finding.ai-surface hook claude-code runs automatically after every edit. When a change introduces or expands AI surface, the finding is injected into the session so Claude tells you and can offer a guard, for example a human approval step in front of a refund tool. When a later edit puts that guard in place, the hook says so. This is fix confirmation: a flagged risk cleared gets its own all-clear line, so the loop is flag, fix, confirm. It is silent on ordinary edits, never fails a tool call, and keeps its rolling baseline outside your repository.Set both up for a repo with one command:
pip install "apisec-ai-surface[mcp]" # the MCP server needs Python 3.10+; the hook has no extra needs
ai-surface init --claude-code
This writes the hook into .claude/settings.json and the server into .mcp.json, merging with anything already there. Start claude in the repo and approve both when prompted.
For Cursor and other MCP clients, register the server as a stdio command:
{ "mcpServers": { "ai-surface": { "command": "ai-surface", "args": ["mcp"] } } }
The pre-commit hook and the GitHub Action remain the editor-agnostic guarantees: they catch the same surface regardless of which tool wrote the code. See docs/INTEGRATIONS.md for the tool reference, the hook contract, where state is kept, and troubleshooting.
After installing ai-surface, you can open the interactive AI attack-surface map from any repo:
ai-surface scan . --ui
The UI shows detected AI surfaces as nodes grouped by category, with risk indicators, governance badges, evidence, and AI-BOM download where available.
The UI is served locally over 127.0.0.1 from a temporary directory.
The analysis never runs in the browser, your source code never leaves your machine, and no telemetry is collected.
To stop the local UI server, press Ctrl-C in the terminal.
ai-surface looks for eight categories of AI surface. Configuration files, provider keys, manifests, and specs are detected across stacks; deeper code-level detection is strongest today for Python and TypeScript/JavaScript. See docs/LANGUAGE_SUPPORT.md for the full matrix.
Inventory categories do not get severity by default. Severity is assigned only when the deep-dive audit has enough evidence, currently in MCP, agent, and RAG findings. See docs/DETECTORS.md for every pattern matched.
We tested ai-surface against 19 popular open-source AI projects on GitHub, representing about 941k combined stars at the time of analysis. The set included AutoGPT, Dify, RAGFlow, AutoGen, CrewAI, LlamaIndex, Continue, Danswer, and others.
This was a static, offline analysis only: each repo was shallow-cloned, analyzed locally, and deleted. No application was run. No code left the host.
The set split into 12 applications and 7 framework/library repos. Frameworks and libraries are reported separately because they often include many integrations as code paths, so their raw component counts are not comparable to applications.
Across the 12 application repos, ai-surface found:
These are category-presence signals, not exploitability claims. The numbers are a floor, not a ceiling: tool resolution is regex/AST-light today, so some agent/tool risks can under-fire on larger platforms. Raw per-component counts are useful for investigation but can vary by framework, coding style, and detector coverage.
Full methodology, per-app appendix, framework/library appendix, and caveats are in the State of AI Surface report.
ai-surface scan . # terminal report
ai-surface scan . --ui # interactive map in a local browser
ai-surface scan . --output json # machine-readable JSON (schema 1.0)
ai-surface scan . --output markdown # human-readable Markdown report
ai-surface scan . --output cyclonedx # CycloneDX AI-BOM
ai-surface scan . --output sarif # SARIF 2.1.0 for GitHub code scanning
ai-surface scan . --write-inventory # write .ai-inventory.md to the project root
ai-surface scan . --quiet # one-line CI summary
CycloneDX output is the AI-BOM: an inventory artifact generated in CI the way teams already generate SBOMs, with AI governance mappings attached.
SARIF output can be uploaded to GitHub code scanning for Security tab visibility and inline PR annotations.
The --ui viewer serves over 127.0.0.1 from a throwaway temp directory; the analysis never runs in the browser, nothing is sent off your machine, and there is no telemetry.
# Map the current project
ai-surface scan .
# Open the local interactive map
ai-surface scan . --ui
# Produce machine-readable or human-readable output
ai-surface scan . --output json
ai-surface scan . --output markdown
ai-surface scan . --output cyclonedx
ai-surface scan . --output sarif
# Filter to specific categories
# aliases: mcp, agents, llm, gateway, infra, keys, api, vector
ai-surface scan . --categories mcp,agents
ai-surface scan . --categories vector
# Focus on AI-specific surface (drop plain, non-AI API endpoints)
ai-surface scan . --ai-only
# Show per-finding governance clauses (EU AI Act / NIST / ISO)
# Off by default; a one-line governance summary always shows.
ai-surface scan . --governance
# Gate CI by assessed severity
ai-surface scan . --fail-on high # fail on high or critical findings
ai-surface scan . --fail-on critical # fail only on critical findings
# Severity floor the baseline cannot suppress (closes baseline-acceptance gap)
# New high+ blocks the PR; any critical always blocks, even if pre-existing.
ai-surface scan . --baseline --fail-on high --always-fail-on critical
# Aggressive gate: fail on any risk indicator
ai-surface scan . --fail-on-risk
# Baseline existing AI surfaces, then show only what changed
ai-surface scan . --update-baseline
ai-surface scan . --baseline
ai-surface scan . --baseline --fail-on high
# Compare two reports
ai-surface compare base.json head.json
Editor and agent integrations:
ai-surface maps audited findings to the OWASP LLM Top 10 and to evidence-relevant clauses in the EU AI Act, NIST AI RMF, and ISO/IEC 42001.
In terminal and markdown output, the per-finding clauses are off by default and a single governance summary line is shown instead; pass --governance to print the clause under each risk flag. The UI shows these mappings as badges. JSON output always carries them as structured standards fields. CycloneDX output carries them as component properties, making it your AI-BOM artifact.
ai-surface produces evidence; it does not certify, attest, or assert compliance. A framework requirement is reported only when the analysis produced that kind of evidence.
The reported footprint is a floor, not a ceiling: static analysis can miss risks in code that builds tools dynamically or through factory functions.
Full mapping details, caveats, and AI-BOM generation guidance are in docs/COMPLIANCE.md.
ai-surface maps AI surfaces from source code and configuration. It reads files, matches known AI-surface signatures, runs deep-dive audits where enough evidence exists, attaches governance mappings, and produces reports for developers, CI systems, and security teams.
flowchart TD
A[Developer writes AI code] --> B[Opens PR]
B --> C[CI runs ai-surface]
C --> D[Read repo files locally]
D --> E[Detect AI surfaces<br/>agents · MCP · RAG · LLMs · APIs]
E --> F[Audit risk indicators<br/>+ map governance evidence]
F --> G[Compare base vs head<br/>+ attach AI-BOM]
G --> H{DevOps / security reviewer}
H --> I[Request changes]
H --> J[Merge]
style E fill:#00a99d,stroke:#0b6b63,stroke-width:2px,color:#ffffff
style F fill:#7c3aed,stroke:#4c1d95,stroke-width:2px,color:#ffffff
style H fill:#d97706,stroke:#7c4a14,stroke-width:2px,color:#ffffff
style J fill:#16a34a,stroke:#0f7a37,stroke-width:2px,color:#ffffff
The CLI executes no code, uses no credentials, sends no telemetry, and makes no network calls.
When PR comments are enabled, the GitHub Action uses the repository's GITHUB_TOKEN to post or update a comment through the GitHub API. It does not send source code, findings, or metadata to APIsec.
Deep dive: docs/ARCHITECTURE.md.
Trivy checks container images, Gitleaks checks git history, an SCA checks dependencies. ai-surface is the equivalent pre-merge check for the AI layer. It sits alongside the tools below rather than replacing any of them.
ai-surface does not replace these tools. It focuses on the local, PR-time AI attack-surface gap that most adjacent tools do not cover directly.
ai-surface maps and audits statically; it does not prove exploitability against a running app (see Runtime validation).ai-surface is a structural analyzer, not a model evaluator.ai-surface maps AI attack surfaces from source code and configuration. It identifies where agents, MCP servers, RAG paths, LLM calls, gateways, infrastructure, provider keys, and AI-exposed APIs exist, and flags risk indicators where static evidence is present.
It does not prove exploitability against a running application.
For runtime validation with replayable evidence, see APIsec:
The boundary is intentional: free local discovery here, runtime exploit validation in APIsec. Bridges are an upgrade path, not a data-sharing integration. No finding data leaves your machine; the bridge is a deep link.
git clone https://github.com/apisec-inc/AI-Surface
cd AI-Surface
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest # tests
ruff check src/ tests/ # lint
mypy src/ # types
To add a detector, implement the Detector protocol in types.py, register it in default_detectors(), and add fixtures and tests under tests/.
The report shape is frozen in docs/SCHEMA_v1.md. See CONTRIBUTING.md for contributor guidance.
MIT. See LICENSE.
Maintained by APIsec. Part of the APIsec Labs OSS family.
Find and govern AI attack surfaces in application code, at PR time and inside your AI coding tool (MCP server, Claude Code hook). Free, OSS, runs offline.
Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
In diesem Eintrag ist keine erforderliche Umgebungsvariable aufgeführt.
AI Surface läuft lokal über stdio.
Zuletzt geprüft: 2026-10-26. Find and govern AI attack surfaces in application code, at PR time and inside your AI coding tool (MCP server, Claude Code hook). Free, OSS, runs offline.