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 .

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

What the output looks like

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.

First run on a mature repo

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.

GitHub Action and CI gating

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, f