Skip to content
Back to search

AI-Surface

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/apisec-inc--ai-surface/badge.svg)](/listings/apisec-inc--ai-surface)

HTML

<a href="/listings/apisec-inc--ai-surface"><img src="/api/listings/apisec-inc--ai-surface/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 540 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # ai-surface
  3. **Find the AI attack surface your code is about to ship. Locally, offline, before the PR merges.**
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  5. [![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
  6. [![Version](https://img.shields.io/badge/version-1.1.0-blue.svg)](https://github.com/apisec-inc/AI-Surface/blob/main/CHANGELOG.md)
  7. [![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)](https://github.com/apisec-inc/AI-Surface/tree/main/tests)
  8. [![Runs offline](https://img.shields.io/badge/no_telemetry-runs_offline-brightgreen.svg)](https://github.com/apisec-inc/AI-Surface/blob/main/docs/PRIVACY.md)
  9. </div>
  10. `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.
  11. 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.
  12. 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`.
  13. 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.
  14. Try it without installing:
  15. ```bash
  16. uvx --from apisec-ai-surface ai-surface scan .
  17. ```
  18. If ai-surface is useful to you, [star the repo](https://github.com/apisec-inc/AI-Surface) so more engineers find it.
  19. 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](#compliance-and-governance)). Runtime exploit validation is out of scope for this OSS scanner.
  20. <div align="center">
  21. ![ai-surface attack surface map](https://raw.githubusercontent.com/apisec-inc/AI-Surface/main/docs/images/surface-map.png)
  22. <sub>The optional <code>--ui</code> map shows detected AI surfaces as nodes grouped by category. It is served on loopback and runs locally.</sub>
  23. </div>
  24. ## Who is this for?
  25. Use `ai-surface` if you are:
  26. - adding agents, MCP servers, RAG, model gateways, or LLM calls to an application
  27. - reviewing AI-related pull requests before they merge
  28. - adding an AI risk gate to CI/CD
  29. - building an AI-BOM or AI-governance inventory from source code
  30. - trying to understand where AI risk enters your codebase
  31. Built for DevOps, DevSecOps, platform engineering, AppSec, and security-minded engineering teams.
  32. ## Table of Contents
  33. - [Who is this for?](#who-is-this-for)
  34. - [Quick start](#quick-start)
  35. - [What the output looks like](#what-the-output-looks-like)
  36. - [First run on a mature repo](#first-run-on-a-mature-repo)
  37. - [GitHub Action and CI gating](#github-action-and-ci-gating)
  38. - [Inside your AI coding tool: MCP server and Claude Code hook](#inside-your-ai-coding-tool-mcp-server-and-claude-code-hook)
  39. - [Open the local UI](#open-the-local-ui)
  40. - [What it detects](#what-it-detects)
  41. - [Proven on real code](#proven-on-real-code)
  42. - [Output formats](#output-formats)
  43. - [CLI reference](#cli-reference)
  44. - [Compliance and governance](#compliance-and-governance)
  45. - [How it works](#how-it-works)
  46. - [Comparison with adjacent tools](#comparison-with-adjacent-tools)
  47. - [What it does not do](#what-it-does-not-do)
  48. - [Roadmap](#roadmap)
  49. - [Runtime validation](#runtime-validation)
  50. - [Development](#development)
  51. - [Project](#project)
  52. - [License](#license)
  53. ## Quick start
  54. Install once, then run `ai-surface` anywhere:
  55. ```bash
  56. pipx install apisec-ai-surface
  57. ai-surface scan .
  58. # if the ai-surface command is not found after install, run: pipx ensurepath
  59. # then open a new shell
  60. # or run once with no install
  61. uvx --from apisec-ai-surface ai-surface scan .
  62. # or in a project venv
  63. pip install apisec-ai-surface && ai-surface scan .
  64. # explore the results visually
  65. ai-surface scan . --ui
  66. ```
  67. Requires Python 3.9+. The CLI runs locally; `--ui` serves on loopback only.
  68. ### What the output looks like
  69. 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.
  70. ```text
  71. AI Attack Surface Report
  72. ────────────────────────────────────────────────────────────────
  73. Project: demo-app
  74. 19 production AI surfaces · 25 risk indicators · across 8 detector(s)
  75. Severity: 3 high · 1 medium
  76. AGENT FRAMEWORKS
  77. • AWS Strands Agent: triage_agent (in src/support_workflow.py)
  78. Tools/perms: fetch_customer_profile, search_knowledge_base, escalate_to_human
  79. • LangChain Agent: support_agent (in src/chat_agent.py) CONFIRMED RISK [HIGH]
  80. Tools/perms: lookup_order, refund_payment, cancel_subscription
  81. ⚠ financial action exposed ⚠ high blast-radius combination
  82. ⚑ [HIGH] financial-action
  83. Agent can invoke financial tools (refund_payment)
  84. OWASP: LLM06 Governance: EU AI Act Art. 9
  85. Fix: Gate financial tools behind human approval; least-privilege the agent.
  86. ⚑ [HIGH] no-human-oversight
  87. High-risk action runs with no human approval / in-the-loop gate detected
  88. OWASP: LLM06, LLM09 Governance: EU AI Act Art. 14
  89. MCP SERVERS
  90. • MCP Server: stripe-mcp CONFIRMED RISK [HIGH] Trust: verified (90/100)
  91. Tools/perms: read_charges, refund, customer:read
  92. ⚑ [HIGH] financial-action
  93. MCP exposes financial tools (refund, charge, payout) to the model.
  94. OWASP: LLM06 Governance: EU AI Act Art. 9
  95. ⚑ [MEDIUM] unverified-source
  96. MCP is not from a known/verified publisher; its posture is unknown.
  97. OWASP: LLM03 Governance: ISO 42001 A.10
  98. • MCP Server: github-mcp CONFIRMED RISK [MEDIUM]
  99. ⚑ [MEDIUM] remote-mcp MCP connects to a remote server via URL
  100. ⚑ [MEDIUM] broad-permissions MCP is granted broad (admin/write) scopes
  101. LLM SDK CALL SITES
  102. • Anthropic SDK LIKELY RISK · claude-3-5-sonnet · src/llm_service.py
  103. ⚠ non-literal data flows into LLM call
  104. • AWS Bedrock · us.anthropic.claude-sonnet-4 · src/support_workflow.py
  105. VECTOR-STORE
  106. • Vector store: pgvector LIKELY RISK ⚠ retrieved content reaches the model (RAG)
  107. • RAG pipeline: LangChain LIKELY RISK ⚠ ingests external content (RAG poisoning surface)
  108. API ENDPOINTS
  109. • REST API: GET /orders/{order_id} LIKELY RISK ⚠ object-id in path (BOLA candidate)
  110. • REST API: PATCH /customers/{customer_id} LIKELY RISK ⚠ object-id in path (BOLA candidate)
  111. Governance: evidence for EU AI Act, NIST AI RMF, ISO/IEC 42001, OWASP LLM Top 10
  112. ────────────────────────────────────────────────────────────────
  113. AI Surface Scorecard D
  114. 19 surfaces · 4 confirmed risk · 11 likely risk
  115. Worst finding: MCP Server: stripe-mcp: MCP exposes financial tools (refund, charge, payout) to the model.
  116. ```
  117. ### First run on a mature repo
  118. 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:
  119. ```bash
  120. ai-surface scan . --update-baseline # 1. snapshot today's inventory
  121. ai-surface scan . --baseline # 2. show only what changed
  122. ai-surface scan . --baseline --fail-on high # 3. in CI, fail only on NEW high+ risk
  123. ```
  124. `--baseline --fail-on high` is the recommended PR gate: low-noise, non-blocking on pre-existing debt, and actionable.
  125. ## GitHub Action and CI gating
  126. The fastest path is one command from your repo root:
  127. ```bash
  128. ai-surface init
  129. ```
  130. It writes the recommended workflow below into `.github/workflows/ai-surface.yml` and prints a [pre-commit](https://pre-commit.com) snippet for local scans (the repo ships `.pre-commit-hooks.yaml`).
  131. Or drop this into `.github/workflows/ai-surface.yml` yourself:
  132. ```yaml
  133. name: AI Surface Check
  134. on: [pull_request]
  135. permissions:
  136. contents: read
  137. pull-requests: write # required when comment-on-pr is true
  138. jobs:
  139. ai-surface:
  140. runs-on: ubuntu-latest
  141. steps:
  142. - uses: actions/checkout@v4
  143. with:
  144. fetch-depth: 0 # required for base-vs-head diff
  145. - uses: apisec-inc/AI-Surface@v1
  146. with:
  147. path: '.'
  148. comment-on-pr: 'true'
  149. fail-on: 'high' # fail only on NEW high-or-critical findings
  150. ```
  151. 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.
  152. No API keys are required. The action uses the built-in `GITHUB_TOKEN` to post or update the PR comment.
  153. For non-GitHub CI, the gate is just an exit code:
  154. ```bash
  155. ai-surface scan . --fail-on high
  156. ```
  157. See [`docs/CI_INTEGRATION.md`](https://github.com/apisec-inc/AI-Surface/blob/main/docs/CI_INTEGRATION.md) for permissions, fork PR behavior, baseline options, SARIF upload, policy files, and multi-repo rollups.
  158. ## Inside your AI coding tool: MCP server and Claude Code hook
  159. 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.
  160. Two pieces, both local, offline, and read-only:
  161. - **An MCP server.** `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.
  162. - **A Claude Code hook.** `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.
  163. Set both up for a repo with one command:
  164. ```bash
  165. pip install "apisec-ai-surface[mcp]" # the MCP server needs Python 3.10+; the hook has no extra needs
  166. ai-surface init --claude-code
  167. ```
  168. 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.
  169. For Cursor and other MCP clients, register the server as a stdio command:
  170. ```json
  171. { "mcpServers": { "ai-surface": { "command": "ai-surface", "args": ["mcp"] } } }
  172. ```
  173. 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`](https://github.com/apisec-inc/AI-Surface/blob/main/docs/INTEGRATIONS.md) for the tool reference, the hook contract, where state is kept, and troubleshooting.
  174. ## Open the local UI
  175. After installing `ai-surface`, you can open the interactive AI attack-surface map from any repo:
  176. ```bash
  177. ai-surface scan . --ui
  178. ```
  179. The UI shows detected AI surfaces as nodes grouped by category, with risk indicators, governance badges, evidence, and AI-BOM download where available.
  180. The UI is served locally over `127.0.0.1` from a temporary directory.
  181. The analysis never runs in the browser, your source code never leaves your machine, and no telemetry is collected.
  182. To stop the local UI server, press `Ctrl-C` in the terminal.
  183. ## What it detects
  184. `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`](https://github.com/apisec-inc/AI-Surface/blob/main/docs/LANGUAGE_SUPPORT.md) for the full matrix.
  185. | Category | Coverage | What it finds |
  186. |---|---|---|
  187. | Agent frameworks | 11 Python + 7 JS/TS frameworks | LangChain, LangGraph, CrewAI, LlamaIndex, AutoGen, Haystack, Semantic Kernel, Pydantic AI, AWS Strands, the OpenAI Agents SDK and the Claude Agent SDK (Python); LangChain.js, LangGraph.js, Vercel AI SDK, Mastra, OpenAI Agents SDK, LlamaIndex.ts, and the Claude Agent SDK (TS/JS). Extracts agent tool inventories and flags financial, destructive, and high-blast-radius authority. |
  188. | MCP servers | Discovery + deep-dive audit | Configured MCP servers such as `.mcp.json` entries and in-house source servers. Audited findings include risk flags, remediation, detected secrets by name/type only, and registry/trust signals. |
  189. | Vector stores / RAG | 13 stores + 2 frameworks | Pinecone, Weaviate, Chroma, Qdrant, Milvus, FAISS, LanceDB, pgvector, Elasticsearch/OpenSearch/Vespa/Redis in vector mode, plus LangChain and LlamaIndex retrieval pipelines. Flags managed-store egress, RAG data flow, embeddings, and external ingestion. |
  190. | LLM SDK call sites | 13 providers | Anthropic, OpenAI, Azure OpenAI, AWS Bedrock, Google Generative AI, Vertex AI, Together, Mistral, Cohere, Replicate, Groq, LiteLLM, and Vercel AI SDK. Extracts models where visible and flags non-literal prompt/message flow. |
  191. | API endpoints | HTTP/REST + OpenAPI | OpenAPI/Swagger specs and framework routes including FastAPI, Starlette, Flask, Express, Spring, and Django. Captures method, path, framework, auth style, and object-id path segments that may need BOLA review. |
  192. | Model gateways | Configs + source | LiteLLM proxy, Portkey, Helicone, Cloudflare AI Gateway, and OpenRouter. Captures routed-model inventories where visible. |
  193. | AI infrastructure | Manifests + IaC | Kubernetes, Helm, Docker Compose, Dockerfiles, and Terraform for AI runtimes and managed AI services such as Ollama, vLLM, TGI, SGLang, Triton, llama.cpp, Bedrock, SageMaker, and Vertex endpoints. |
  194. | AI provider keys | Names only | Common provider key names such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and `AZURE_OPENAI_*` across environment files and config. Values are never read or printed. |
  195. 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`](https://github.com/apisec-inc/AI-Surface/blob/main/docs/DETECTORS.md) for every pattern matched.
  196. ## Proven on real code
  197. 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.
  198. 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.
  199. 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.
  200. Across the 12 application repos, `ai-surface` found:
  201. | Signal | Apps |
  202. |---|---|
  203. | Ship AI agents | 83% |
  204. | Have a vector store / RAG layer | 83% |
  205. | Expose API endpoints | 83% |
  206. | Have API endpoints that may need BOLA review | 67% |
  207. | Expose MCP servers | 42% |
  208. | Run an agent/MCP surface with no observability wired | 33% |
  209. | Interpolate PII into prompts | 17% |
  210. | Trip at least one risk and one governance rule | 100% |
  211. 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.
  212. Full methodology, per-app appendix, framework/library appendix, and caveats are in the [State of AI Surface](https://github.com/apisec-inc/AI-Surface/blob/main/docs/STATE_OF_AI_SURFACE.md) report.
  213. <div align="center">
  214. ![State of AI Surface report](https://raw.githubusercontent.com/apisec-inc/AI-Surface/main/docs/images/state-of-ai-surface.png)
  215. </div>
  216. ## Output formats
  217. ```bash
  218. ai-surface scan . # terminal report
  219. ai-surface scan . --ui # interactive map in a local browser
  220. ai-surface scan . --output json # machine-readable JSON (schema 1.0)
  221. ai-surface scan . --output markdown # human-readable Markdown report
  222. ai-surface scan . --output cyclonedx # CycloneDX AI-BOM
  223. ai-surface scan . --output sarif # SARIF 2.1.0 for GitHub code scanning
  224. ai-surface scan . --write-inventory # write .ai-inventory.md to the project root
  225. ai-surface scan . --quiet # one-line CI summary
  226. ```
  227. CycloneDX output is the AI-BOM: an inventory artifact generated in CI the way teams already generate SBOMs, with AI governance mappings attached.
  228. SARIF output can be uploaded to GitHub code scanning for Security tab visibility and inline PR annotations.
  229. 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.
  230. ## CLI reference
  231. ```bash
  232. # Map the current project
  233. ai-surface scan .
  234. # Open the local interactive map
  235. ai-surface scan . --ui
  236. # Produce machine-readable or human-readable output
  237. ai-surface scan . --output json
  238. ai-surface scan . --output markdown
  239. ai-surface scan . --output cyclonedx
  240. ai-surface scan . --output sarif
  241. # Filter to specific categories
  242. # aliases: mcp, agents, llm, gateway, infra, keys, api, vector
  243. ai-surface scan . --categories mcp,agents
  244. ai-surface scan . --categories vector
  245. # Focus on AI-specific surface (drop plain, non-AI API endpoints)
  246. ai-surface scan . --ai-only
  247. # Show per-finding governance clauses (EU AI Act / NIST / ISO)
  248. # Off by default; a one-line governance summary always shows.
  249. ai-surface scan . --governance
  250. # Gate CI by assessed severity
  251. ai-surface scan . --fail-on high # fail on high or critical findings
  252. ai-surface scan . --fail-on critical # fail only on critical findings
  253. # Severity floor the baseline cannot suppress (closes baseline-acceptance gap)
  254. # New high+ blocks the PR; any critical always blocks, even if pre-existing.
  255. ai-surface scan . --baseline --fail-on high --always-fail-on critical
  256. # Aggressive gate: fail on any risk indicator
  257. ai-surface scan . --fail-on-risk
  258. # Baseline existing AI surfaces, then show only what changed
  259. ai-surface scan . --update-baseline
  260. ai-surface scan . --baseline
  261. ai-surface scan . --baseline --fail-on high
  262. # Compare two reports
  263. ai-surface compare base.json head.json
  264. ```
  265. Editor and agent integrations:
  266. | Command | What it does |
  267. |---|---|
  268. | `ai-surface init --claude-code` | Wire the hook and the MCP server into this repo's Claude Code config |
  269. | `ai-surface mcp` | Run the MCP server over stdio (needs the `[mcp]` extra, Python 3.10+) |
  270. | `ai-surface hook claude-code` | The Claude Code `PostToolUse` / `SessionStart` hook; reads the payload on stdin |
  271. | `ai-surface hook claude-code --reset` | Forget the hook's rolling baseline for the current repo |
  272. ## Compliance and governance
  273. `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.
  274. 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.
  275. `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.
  276. <div align="center">
  277. ![Governance evidence and AI-BOM](https://raw.githubusercontent.com/apisec-inc/AI-Surface/main/docs/images/overview-governance.png)
  278. </div>
  279. ### What the mappings cover
  280. | Evidence kind | Examples | Framework use |
  281. |---|---|---|
  282. | Inventory | agents, MCP servers, RAG/vector stores, LLM calls, gateways, AI infra | AI-BOM, system documentation, governance inventory |
  283. | Risk | financial tools, destructive tools, high-blast-radius agents, secret-bearing MCP config | risk review and assessment evidence |
  284. | Human oversight | high-risk action with no detected approval gate | EU AI Act Art. 14 review signal |
  285. | Logging / monitoring | agent or MCP execution surface with no detected tracing | EU AI Act Art. 12, NIST MEASURE 3, ISO A.6.2.6 evidence |
  286. | Data governance | RAG/vector layer, PII interpolated into prompts | EU AI Act Art. 10, ISO A.7 evidence |
  287. ### Example risk-flag mappings
  288. | Risk flag | OWASP | EU AI Act | NIST AI RMF | ISO/IEC 42001 |
  289. |---|---|---|---|---|
  290. | `secrets-in-env` | LLM02 | Art. 15 | - | - |
  291. | `financial-action` / `destructive-action` / `high-blast-radius` | LLM06 | Art. 9 | - | - |
  292. | `no-human-oversight` | LLM06 / LLM09 | Art. 14 | - | - |
  293. | `no-observability` | - | Art. 12 | MEASURE 3 | A.6.2.6 |
  294. | `pii-to-llm` | LLM02 | Art. 10 | - | A.7 |
  295. | `unverified-source` / `remote-mcp` / `local-binary` | LLM03 | - | - | A.10 |
  296. | vector store / RAG present | LLM08 | Art. 10 | data | A.7 |
  297. The reported footprint is a floor, not a ceiling: static analysis can miss risks in code that builds tools dynamically or through factory functions.
  298. Full mapping details, caveats, and AI-BOM generation guidance are in [`docs/COMPLIANCE.md`](https://github.com/apisec-inc/AI-Surface/blob/main/docs/COMPLIANCE.md).
  299. ## How it works
  300. `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.
  301. ```mermaid
  302. flowchart TD
  303. A[Developer writes AI code] --> B[Opens PR]
  304. B --> C[CI runs ai-surface]
  305. C --> D[Read repo files locally]
  306. D --> E[Detect AI surfaces<br/>agents · MCP · RAG · LLMs · APIs]
  307. E --> F[Audit risk indicators<br/>+ map governance evidence]
  308. F --> G[Compare base vs head<br/>+ attach AI-BOM]
  309. G --> H{DevOps / security reviewer}
  310. H --> I[Request changes]
  311. H --> J[Merge]
  312. style E fill:#00a99d,stroke:#0b6b63,stroke-width:2px,color:#ffffff
  313. style F fill:#7c3aed,stroke:#4c1d95,stroke-width:2px,color:#ffffff
  314. style H fill:#d97706,stroke:#7c4a14,stroke-width:2px,color:#ffffff
  315. style J fill:#16a34a,stroke:#0f7a37,stroke-width:2px,color:#ffffff
  316. ```
  317. The CLI executes no code, uses no credentials, sends no telemetry, and makes no network calls.
  318. 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.
  319. Deep dive: [`docs/ARCHITECTURE.md`](https://github.com/apisec-inc/AI-Surface/blob/main/docs/ARCHITECTURE.md).
  320. ## Comparison with adjacent tools
  321. 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.
  322. | Tool | What it tells you | When it sees AI |
  323. |---|---|---|
  324. | SAST (Semgrep, CodeQL) | Code-pattern vulnerabilities | After commit; usually does not build an AI surface inventory |
  325. | DAST (Burp, ZAP) | Reachable web vulnerabilities | After deploy; sees HTTP behavior, not LLM/agent internals |
  326. | SCA (Snyk, Dependabot) | Vulnerable dependencies | After commit; sees packages, not how AI components are used |
  327. | Observability (Helicone, LangSmith, Arize, Phoenix) | What LLM calls happened at runtime | After deploy; requires runtime traffic |
  328. | AI-SPM / AI governance tools | Cloud/runtime AI inventory and posture | Often runtime/cloud-first; not usually a local PR-time gate |
  329. | **`ai-surface`** | **What AI attack surface is about to ship, mapped to governance evidence** | **At PR time, before merge, offline** |
  330. | APIsec platform | Which AI/API surfaces are actually exploitable | Runtime validation with replayable evidence |
  331. `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.
  332. ## What it does not do
  333. - **Runtime telemetry or behavior monitoring.** Use tools like Helicone, LangSmith, Arize, or Phoenix.
  334. - **Runtime exploit validation.** `ai-surface` maps and audits statically; it does not prove exploitability against a running app (see [Runtime validation](#runtime-validation)).
  335. - **Prompt injection, jailbreak, bias, or accuracy testing.** Out of scope by design. `ai-surface` is a structural analyzer, not a model evaluator.
  336. - **Full cross-file dataflow for tool resolution.** Regex/AST-light today; agent tools built through factory functions may not be fully resolved. Treat the map as a strong floor, not proof of complete coverage. AST/dataflow is the top roadmap item.
  337. - **Secret-value reads or PII classification.** Secrets are reported by name and type only, with values redacted. Use a dedicated secret scanner for value-level coverage.
  338. ## Roadmap
  339. | Version | Status | What's in it |
  340. |---|---|---|
  341. | v1.1 | Shipped | MCP server (`ai-surface mcp`) for Claude Code, Cursor, Windsurf, Cline; Claude Code post-edit hook; `ai-surface init --claude-code`. |
  342. | v1.1.1 | Shipped | Fix confirmation: the hook and the MCP diff report cleared risks, so a fix gets an all-clear; once an approval gate is detected the remediation says so instead of asking for one. |
  343. | v1.0 | Shipped | 8-category mapping, MCP + agent + RAG audits, OWASP + EU/NIST/ISO governance mapping, AI-BOM + SARIF, interactive `--ui` map, frozen schema 1.0, GitHub Action with PR diff comments, `--baseline` and `--fail-on` gates. |
  344. | Fast-follow | Planned | AST / cross-file dataflow for tool resolution, `.ai-surface.yml` policy file, GitLab CI component. |
  345. | Later | Planned | kubectl plugin, live cluster discovery, continuous mode + drift alerts, multi-repo rollup, plugin SDK. |
  346. ## Runtime validation
  347. <a id="runtime-validation"></a>
  348. `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.
  349. It does not prove exploitability against a running application.
  350. For runtime validation with replayable evidence, see [APIsec](https://www.apisec.ai/products):
  351. | Source surface | Runtime validation path |
  352. |---|---|
  353. | AI / agent surfaces | agent validation |
  354. | MCP servers | MCP runtime validation |
  355. | Discovered APIs | API outside-in runtime testing |
  356. 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.
  357. ## Development
  358. ```bash
  359. git clone https://github.com/apisec-inc/AI-Surface
  360. cd AI-Surface
  361. python -m venv .venv
  362. source .venv/bin/activate
  363. pip install -e ".[dev]"
  364. pytest # tests
  365. ruff check src/ tests/ # lint
  366. mypy src/ # types
  367. ```
  368. To add a detector, implement the `Detector` protocol in `types.py`, register it in `default_detectors()`, and add fixtures and tests under `tests/`.
  369. The report shape is frozen in [`docs/SCHEMA_v1.md`](https://github.com/apisec-inc/AI-Surface/blob/main/docs/SCHEMA_v1.md). See [CONTRIBUTING.md](https://github.com/apisec-inc/AI-Surface/blob/main/CONTRIBUTING.md) for contributor guidance.
  370. ## Project
  371. | Resource | Link |
  372. |---|---|
  373. | Detectors | [docs/DETECTORS.md](https://github.com/apisec-inc/AI-Surface/blob/main/docs/DETECTORS.md) |
  374. | Compliance mapping | [docs/COMPLIANCE.md](https://github.com/apisec-inc/AI-Surface/blob/main/docs/COMPLIANCE.md) |
  375. | Language support | [docs/LANGUAGE_SUPPORT.md](https://github.com/apisec-inc/AI-Surface/blob/main/docs/LANGUAGE_SUPPORT.md) |
  376. | Architecture | [docs/ARCHITECTURE.md](https://github.com/apisec-inc/AI-Surface/blob/main/docs/ARCHITECTURE.md) |
  377. | CI integration | [docs/CI_INTEGRATION.md](https://github.com/apisec-inc/AI-Surface/blob/main/docs/CI_INTEGRATION.md) |
  378. | Report schema | [docs/SCHEMA_v1.md](https://github.com/apisec-inc/AI-Surface/blob/main/docs/SCHEMA_v1.md) |
  379. | State of AI Surface | [docs/STATE_OF_AI_SURFACE.md](https://github.com/apisec-inc/AI-Surface/blob/main/docs/STATE_OF_AI_SURFACE.md) |
  380. | Privacy | [docs/PRIVACY.md](https://github.com/apisec-inc/AI-Surface/blob/main/docs/PRIVACY.md) |
  381. | Changelog | [CHANGELOG.md](https://github.com/apisec-inc/AI-Surface/blob/main/CHANGELOG.md) |
  382. ## License
  383. MIT. See [LICENSE](https://github.com/apisec-inc/AI-Surface/blob/main/LICENSE).
  384. ---
  385. <div align="center">
  386. Maintained by [APIsec](https://apisec.ai). Part of the APIsec Labs OSS family.
  387. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.