ai-surface

Find the AI attack surface your code is about to ship. Locally, offline, before the PR merges.

ai-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.

Who is this for?

Use ai-surface if you are:

• adding agents, MCP servers, RAG, model gateways, or LLM calls to an application
• reviewing AI-related pull requests before they merge
• adding an AI risk gate to CI/CD
• building an AI-BOM or AI-governance inventory from source code
• trying to understand where AI risk enters your codebase

Built for DevOps, DevSecOps, platform engineering, AppSec, and security-minded engineering teams.

Table of Contents

• Who is this for?
• Quick start
• What the output looks like
• First run on a mature repo
• GitHub Action and CI gating
• Inside your AI coding tool: MCP server and Claude Code hook
• Open the local UI
• What it detects
• Proven on real code
• Output formats
• CLI reference
• Compliance and governance
• How it works
• Comparison with adjacent tools
• What it does not do
• Roadmap
• Runtime validation
• Development
• Project
• License

Quick start

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 .