tkdtaylor/code-scanner
GitHub: tkdtaylor/code-scanner
一款在 Docker 沙箱中对代码仓库、包和 AI agent skill 进行恶意软件与供应链风险扫描的工具，支持 Markdown 报告和 SARIF 输出并可集成至 CI 门禁。
Stars: 0 | Forks: 0
# 代码扫描器
[](LICENSE)
[](https://github.com/tkdtaylor/code-scanner/commits)
**一款用于代码仓库、包和 agent skill 的恶意软件扫描器** — 分析目标是否存在已知的 CVE、恶意模式、供应链攻击和后门。远程目标在一次性 Docker 沙箱中运行，因此下载的内容不会接触到宿主机；本地路径则通过只读分析进行就地扫描。返回 Markdown 报告或可供 CI 门禁使用的机器可读 SARIF。
可作为 Claude Skill（或 GitHub Copilot、Cursor、Windsurf、Kiro、Antigravity 中的兼容 agent skill）以及用于验证门禁的无头 CLI 使用。它是 [Secure Agent Ecosystem](#the-building-blocks) 的一部分，采用 Apache-2.0 许可证。
## 目录
- [快速开始](#quick-start)
- [工作原理](#how-it-works)
- [检测内容](#what-it-detects)
- [作为 skill 使用](#use-as-a-skill)
- [作为 CLI 使用（门禁）](#use-as-a-cli-gates)
- [技术栈](#tech-stack)
- [赞助](#sponsorship)
- [企业支持](#enterprise-support)
- [许可证](#license)
## 快速开始
作为 **Claude Skill**，通过对话触发：
```
User: Scan this repo and tell me if it's safe to run: https://github.com/owner/repo
```
Claude 会将仓库下载到一次性的 Docker 沙箱中，检查其是否存在 CVE 和恶意软件模式，并将报告写入 `./code-scanner-reports/scan-report-*.md`。远程仓库中的任何内容都不会接触到您的宿主机。
作为 **无头 CLI**（用于 CI / 验证门禁）：
```
code-scanner . # scan current directory
code-scanner . --sarif out.sarif # emit SARIF for gate consumption
code-scanner https://github.com/owner/repo # scan remote target
# 退出代码：0 = clean · 1 = findings · 2 = tool error
```
该 skill 可在 Claude Code、GitHub Copilot (Agent Mode)、Cursor、Windsurf、Kiro 和 Antigravity 中运行。通过将 `code-scanner/SKILL.md` 和 `code-scanner/references/` 复制到您 agent 的 skill 目录中进行安装。CLI 需要 Python 3 + Docker（如果仅针对本地路径目标，则只需 Python 3）。
## 工作原理
两种隔离策略 — **远程目标**使用一次性沙箱；**本地路径**使用原生只读分析。
```
Remote target (GitHub URL, package, archive)
├─ Create Docker volume (isolated from host)
├─ Download target into volume (execute perms stripped)
├─ Scan with OSV-Scanner, Semgrep, dep-scan (--network none)
├─ Follow download URLs, inspect payloads in sandbox
├─ Write report to host (output only)
└─ Destroy volume (nothing leaves sandbox)
Local path (folder already on disk)
├─ Skip sandbox entirely
├─ Run grep/find against files in place, read-only
├─ No copy, no download, no volume
└─ Write report to ./code-scanner-reports/
```
**为什么本地模式是安全的：** 沙箱可防止在安装过程中*执行*不受信任的代码（hooks、setup 脚本、postinstall 触发器）。只读文本分析绝不会执行它所读取的代码。如果代码已经存在于您的磁盘上，说明您已经接受了其存在的风险；使用 grep 扫描它不会增加任何风险。
## 检测内容
**代码仓库和包：**
| 类别 | 检测内容 |
|----------|-----------|
| **CVE / 依赖项** | 已知漏洞（OSV 数据库）、typosquatting、包发布时间 < 48小时、维护者变更、依赖项混淆、传递依赖树扫描（npm、Rust、Go lockfiles） |
| **恶意软件模式** | Base64/hex payload、eval/exec 模式、`curl \| bash`、凭证窃取、反向 shell、挖矿程序、web shell、C2 基础设施、持久化机制 |
| **供应链** | 恶意安装 hooks（postinstall、setup.py、`__init__.py`）、Python `.pth` 持久化、未固定版本的 CI/CD actions |
| **递归 payload** | 在沙箱内获取并检查二级下载 URL |
**Claude skill 文件：**
| 类别 | 检测内容 |
|----------|-----------|
| **注入** | Prompt injection、system-prompt 泄露、旨在覆盖 Claude 行为的指令 |
| **身份** | 虚假声称验证、企图取代 Claude 的角色 |
| **数据渗透** | 将数据发送到远程 endpoint 的指令、凭证访问指令 |
| **自主性** | 未经 human-in-the-loop 的自主高影响操作、无限制的工具授权、不安全的默认设置 |
| **恶意 agent** | 自我修改的 skill、未经授权的跨会话持久化、MCP server 威胁 |
注意：没有任何自动化工具能保证绝对安全。code-scanner 会检测已知的模式；但新颖的或经过充分混淆的威胁可能会逃避检测。请将结果与您自己的判断结合使用。
## 作为 skill 使用
**Claude Code** (Mac/Linux)：
```
git clone https://github.com/tkdtaylor/code-scanner /tmp/code-scanner
cp -r /tmp/code-scanner/code-scanner ~/.claude/skills/
```
dep-scan Docker 镜像会在首次扫描时自动构建（此后将被缓存）。若要预先构建它：`docker build -t dep-scan:latest -f /tmp/code-scanner/code-scanner/docker/Dockerfile.dep-scan /tmp/code-scanner`
**GitHub Copilot、Cursor、Windsurf、Kiro、Antigravity：** 将 `code-scanner/SKILL.md` 和 `code-scanner/references/` 复制到您 agent 的 `.github/skills/`、`.cursorrules`、`.windsurfrules`、`.kiro/steering/` 或等效的 skill 目录中。有关布局，请参见 `code-scanner/` 文件夹结构。
**触发短语：** “Scan this repo for malware”、“Is this npm package safe to install”、“Check this GitHub URL before I run it”、“Review this skill for injection attacks”，或任何暗示评估代码安全性的表述。
添加 `--security-review` 以强制进行补充性的 Claude Code 审查，即使未检测到 HIGH/CRITICAL 级别的发现也会执行。
## 作为 CLI 使用（门禁）
```
code-scanner [TARGET] [--sarif PATH] [--severity-threshold LEVEL]
```
**退出代码：**
| 代码 | 含义 |
|------|---------|
| `0` | 干净 — 没有达到或超过阈值的门禁发现 |
| `1` | 存在门禁发现（确定性工具：OSV-Scanner、Semgrep、dep-scan） |
| `2` | 工具错误或没有可用的确定性工具 |
| `64` | 使用错误 |
**可靠性层级：**
- **确定性**（OSV-Scanner、Semgrep、dep-scan）— 用于拦截构建（gate the build）
- **启发式**（模式库）— 仅供参考，决不拦截构建
CLI 针对**内置的离线 Semgrep 规则集**运行（无需拉取 registry，多次运行结果可复现）。需要 Python 3 以及 PATH 上的原生工具：`osv-scanner`、`semgrep`、`dep-scan`。缺少某个工具会降低覆盖率，但除非所有确定性工具都缺失，否则不会导致失败（fail-closed）。
有关在 rootless 环境中基于 Docker 的执行，请参见 [cli/README.md](./cli/README.md)。
## 技术栈
**Skill：** Claude Skill 格式（.md + 引用文件），使用 Docker 进行远程目标的沙箱隔离。
**CLI：** Python 3（仅使用标准库，无依赖项），并集成了原生工具（OSV-Scanner、Semgrep、dep-scan）。
有关设计原理，请参见 [docs/architecture/decisions/](./docs/architecture/decisions/)（ADR-001：SARIF 格式，ADR-002：沙箱执行模型）。
## 企业支持
提供商业支持、集成帮助和 SLA。Apache-2.0 意味着您可以自由地基于 code-scanner 进行构建；付费支持是您需要时的合作伙伴，绝不是硬性要求。联系 [tools@taylorguard.me](mailto:tools@taylorguard.me)。
## 许可证
[Apache License 2.0](LICENSE) — 可免费使用、修改和分发。有关归属声明，请参见 [NOTICE](NOTICE)；有关 DCO 贡献条款（inbound=outbound，无 CLA），请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。code-scanner 是 [Secure Agent Ecosystem](https://github.com/tkdtaylor/agent-builder#the-building-blocks) 中的一个区块；有关运行时沙箱隔离，请参见 [exec-sandbox](https://github.com/tkdtaylor/exec-sandbox)；有关运行时防御，请参见 [armor](https://github.com/tkdtaylor/armor)；有关依赖项扫描，请参见 [dep-scan](https://github.com/tkdtaylor/dep-scan)。
有关详细的设置、测试和开发信息，请参见 [code-scanner/](./code-scanner/)（skill 结构）、[cli/](./cli/)（无头 CLI 契约）和 [tests/](./tests/)。
标签：Docker沙箱, 图数据库, 恶意软件扫描, 请求拦截