agent-surface-scan
Scan the AI-agent attack surface of a repository. A single-binary, dependency-free static scanner that finds prompt-injection vectors, remote-execution instructions, exfiltration prompts, approval-bypass language, hidden characters, deceptive links, hardcoded live secrets and dangerous MCP configurations — in the files coding agents actually read: AGENTS.md, CLAUDE.md, .cursorrules, README, issue templates, skills, MCP configs and docs.
中文简介:一个零依赖单二进制扫描器,专门检查「AI 编码代理会读到的仓库文本」里的提示注入、远程执行、数据外泄、绕过审批、隐藏字符、欺骗性链接、硬编码密钥与危险 MCP 配置。输出文本 / Markdown / JSON / SARIF,可做 CI 门禁,17 条规则全部映射 OWASP Agentic Security Initiative(ASI)分类。
Why
Coding agents trust repository text as instructions. Attackers have moved from attacking the code to attacking the context: poisoned READMEs that make the agent run remote code and bypass human approval. agent-surface-scan is a CI gate for that context — static, fast, and opinionated about what agent-facing text must never do.
Features
- 17 rules mapped to the OWASP Agentic Security Initiative (ASI) taxonomy, with severity tiers (bare
sudo= low, real escalation = high) - Discovers 6 classes of agent-facing files (instructions, README, contributing/security docs, issue/PR templates, skills, MCP configs, docs)
- Four output formats: text, Markdown, JSON, SARIF 2.1.0 (upload straight to GitHub Code Scanning)
--fail-onCI gate with exit codes;--excludepath patterns;.surface-scanignoreallowlist- Rule selection:
--rules,--skip-rules,--min-severityfor noisy repositories - Single-file scanning (
surface-scan scan README.md) plus directory scanning - Inline suppression markers (
surface-scan:ignore,surface-scan:ignore-file) - Claude Code and Codex hooks — block the agent from reading flagged files
- DSH plugin (
agentscan-dsh) — thesurface_scantool +agentscanskill inside DeepSeek Harness - Benchmark cases modeled on real-world incidents, enforced in CI
- False-positive report on real repositories: 0 high/critical findings on gin, express, flask, axios and fastapi
- Pure Go standard library — no runtime dependencies; builds to one binary
Demo
Scanning the bundled malicious corpus (6 files, 16 findings, exit code 2 — the CI gate working as intended):

Animated walkthrough: docs/demo.gif · Real-repository noise data: false-positive report
Install
No Go required — download a prebuilt binary from Releases:
| Platform | File |
|---|---|
| Windows x64 | surface-scan_windows_amd64.exe |
| Linux x64 / arm64 | surface-scan_linux_amd64 / surface-scan_linux_arm64 |
| macOS Intel / Apple Silicon | surface-scan_darwin_amd64 / surface-scan_darwin_arm64 |
# Windows: download and run
curl.exe -LO https://github.com/CN-001/agent-surface-scan/releases/latest/download/surface-scan_windows_amd64.exe
.\surface-scan_windows_amd64.exe scan . --fail-on high
With Go 1.24+:
go install github.com/CN-001/agent-surface-scan/cmd/surface-scan@v0.2.2
Or build from source:
git clone https://github.com/CN-001/agent-surface-scan.git
cd agent-surface-scan
go build -o surface-scan ./cmd/surface-scan
Scanning this repository? It ships an intentionally malicious sample corpus. Exclude it (or use
.surface-scanignore):surface-scan scan . --exclude testdata,benchTroubleshooting: if
go buildfails withmkdir ...\Temp\go-build...: Access is denied, pointGOTMPDIRat a writable directory. Vendored SDK/cache directories (toolchains/,gopath/,.gocache/,node_modules/, …) are skipped automatically.
Usage
# scan the current repository (exit code 2 when anything >= high is found)
surface-scan scan .
# SARIF for GitHub Code Scanning
surface-scan scan . --format sarif --out results.sarif --fail-on high
# see which files are treated as agent-facing context
surface-scan scan . --list
# exclude fixtures and vendored docs
surface-scan scan . --exclude testdata,examples
# allowlist: .surface-scanignore lines are "<pattern> <ruleID|*>"
# testdata *
# docs/legacy AGI-003
surface-scan scan . --allowlist .surface-scanignore
# scan a single file (fast path used by the hooks)
surface-scan scan path/to/README.md
# tune noisy repositories: only run a rule set, or hide low findings
surface-scan scan . --rules AGX-001,AGS-001
surface-scan scan . --skip-rules AGC-004 --min-severity high
# generate a GitHub Actions workflow for this repo
surface-scan init-ci
# list all rules
surface-scan rules
Suppression
Two markers, both written as ordinary comments:
| Marker | Effect |
|---|---|
# surface-scan:ignore |
suppresses findings on that line (any comment style: #, //, <!-- -->) |
# surface-scan:ignore-file |
suppresses all findings in the file |
Use them for intentional, reviewed exceptions (for example a documented example command in your own README) — and require a comment explaining why.
Example of a real report (the flagged line is suppressed in this documentation on purpose):
README.md
L6 [CRITICAL] AGX-001 Remote command execution (ASI07)
Instructions that download content from a URL and execute it...
Rules
| ID | Severity | ASI | Description |
|---|---|---|---|
| AGI-001 | high | ASI01 | Explicit "ignore previous instructions" phrasing |
| AGI-002 | high | ASI01 | Role flips and guardrail-disabling language |
| AGI-003 | high / medium | ASI03 | Over-broad autonomy grants (any-command grants = high, generic "full access" = medium) |
| AGX-001 | critical | ASI07 | Remote code execution (download then pipe to a shell, package install from URL) |
| AGX-002 | high / low | ASI07 | Privilege escalation phrasing (admin elevation, permissive bits = high; bare sudo = low) |
| AGX-003 | high | ASI07 | Approval / human-in-the-loop bypass |
| AGE-001 | critical | ASI06 | Data exfiltration instructions (secrets to external endpoints) |
| AGE-002 | medium | ASI06 | Suspicious webhook / out-of-band endpoints |
| AGEV-001 | medium | ASI01 | Instruction text hidden in HTML comments / invisible elements |
| AGEV-002 | medium | ASI01 | Encoded payloads next to execution verbs |
| AGEV-003 | medium | ASI01 | Invisible zero-width characters |
| AGD-001 | medium | ASI01 | Deceptive links, URL shorteners, homoglyph domains |
| AGS-001 | critical | ASI03 | Hardcoded live secrets (provider token formats, JWTs, private keys) |
| AGC-001 | high | ASI05 | MCP server executing remote code |
| AGC-002 | high | ASI03 | MCP autoApprove / alwaysAllow without scoping |
| AGC-003 | low | ASI05 | Unparseable MCP config |
| AGC-004 | low | ASI03 | MCP server with no permission scoping |
Integrations
| Integration | Where | What it does |
|---|---|---|
| GitHub Actions / Code Scanning | surface-scan init-ci |
CI gate + SARIF upload |
| Claude Code | hooks/claude-code-hook.mjs | denies Read/Edit/Write on flagged files |
| OpenAI Codex CLI | hooks/codex-hook.ps1 | blocks Read/Edit on flagged files |
| DeepSeek Harness | dsh/ | surface_scan tool + agentscan skill |
Layout
cmd/surface-scan CLI entry point
internal/model shared types
internal/rules rule engine (17 rules, OWASP ASI mapping)
internal/scan file discovery, engine, report rendering
testdata/corpus malicious / benign regression corpus
testdata/repo end-to-end demo repository
bench/cases real-world-inspired benchmark cases
hooks/ Claude Code + Codex hook scripts
dsh/ DeepSeek Harness plugin (agentscan-dsh)
Development
go test ./...
go vet ./...
gofmt -l .
Roadmap
- DSH plugin (
agentscan-dsh):surface_scantool + skill inside DeepSeek Harness - Codex / Claude Code hooks: warn before an agent reads a dangerous file
- Benchmark cases modeled on real-world poisoned-context incidents
- Coverage benchmark against a larger public corpus + false-positive report on big repos
-
--allowlistreview workflow UI (record who reviewed what)
Security & scope
This tool is defensive: it audits your own repositories and is intended for use inside CI and on authorized code only. The bundled corpus contains only synthetic, minimal samples for detection tests — not weaponized payloads. See SECURITY.md.
Author
Created and maintained by Aurox — GitHub @CN-001.
No comments yet. Be the first to write one.