OWASP/appsec-agent
GitHub: OWASP/appsec-agent
基于 Claude Agent SDK 构建的 TypeScript AppSec 代理工具包，通过多种 AI 代理实现代码审查、威胁建模、代码修复和 QA 验证等应用安全任务的自动化。
Stars: 4 | Forks: 1
# AppSec Agent (TypeScript)
一个提供 AI 驱动的应用程序安全 (AppSec) 任务代理的 TypeScript 包，基于 Claude Agent SDK 构建。它有助于自动化日常的应用程序安全操作并简化工作流程。
**📦 可在 npm 上获取**：通过 `npm install appsec-agent` 进行安装
**🌐 正在寻找完整的 Web 仪表板？** 请查看 [**AI Threat Modeler**](https://github.com/yangsec888/ai-threat-modeler/) —— 这是一个父应用程序，将 `appsec-agent` 打包到 Docker化 的 Next.js + Express 技术栈中，包含身份验证、交互式的威胁感知数据流图 (Data Flow Diagram) 画布、风险登记表导出 (PDF/CSV/JSON) 以及聊天 UI。这是无需编写代码即可使用此代理的最简单方法。
## 🚀 功能
- **AI 驱动的 AppSec 自动化**：利用 Claude 的功能进行应用程序安全防护
- **多种代理类型**：简单查询、代码审查、PR 审查、威胁建模（包含对抗性二次审查）、代码修复、QA 验证等
- **工具权限管理**：高级工具权限回调，为受信任的操作提供绕过模式
- **代码审查能力**：自动检测代码中的安全和隐私问题
- **模块化代理架构**：易于针对特定用例进行扩展和自定义
- **简单的集成**：基于 Claude Agent SDK 构建，实现无缝 AI 集成
- **生产就绪**：具有适当错误处理和配置的稳定包
- **适用于 Web 应用的线程安全**：专为 Web 应用中的并发使用而设计，具有隔离的实例状态
- **全面的测试**：完整的测试覆盖率，包括针对 Web 应用场景的并发测试
## 📋 目录
- [安装](#installation)
- [快速开始](#quick-start)
- [配置](#configuration)
- [可用的代理](#available-agents)
- [Web 应用使用](#web-application-usage)
- [架构](#architecture)
- [使用示例](#usage-examples)
- [开发](#development)
- [测试](#testing)
- [相关项目](#related-projects)
## 🛠 安装说明
### 前置条件
- Node.js 18.0 或更高版本
- npm 或 yarn
- Anthropic API key
### 步骤 1：安装 appsec-agent
从 npm 安装该包：
```
$ npm install appsec-agent
```
或者，如果您更喜欢全局安装（以便直接使用 CLI 命令）：
```
$ npm install -g appsec-agent
```
该包包含预构建的 JavaScript 文件，因此使用时无需进行构建步骤。
## ⚡ 快速开始
### 1. 设置环境变量
将这些内容添加到您的 shell 配置文件（`.bashrc`、`.zshrc` 等）中：
```
# Anthropic API 配置
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export ANTHROPIC_BASE_URL="https://api.anthropic.com"
```
### 2. 运行您的第一个代理
您可以使用 CLI 命令运行代理：
```
# 如果全局安装
$ agent-run
# 如果本地安装，使用 npx
$ npx agent-run
# 或者使用特定选项运行
$ npx agent-run -r simple_query_agent
```
## 🔧 配置
可以通过环境变量和配置文件对代理进行配置。关键配置选项包括：
- `ANTHROPIC_API_KEY`：您的 Anthropic API key（Claude 提供商必需）
- `ANTHROPIC_BASE_URL`：API endpoint URL（默认：https://api.anthropic.com）
- `AGENT_PROVIDER`：模型提供商 —— `claude`（默认）或 `codex`（选择性加入）。使用 `--provider` 覆盖。
- 在 `conf/appsec_agent.yaml` 中为每个角色配置 `max_turns`（例如 `threat_modeler` 为 **100**）。使用 `--max-turns ` 覆盖任何角色。
配置文件：`conf/appsec_agent.yaml`
### 模型提供商 (v3.0.0+)
所有角色均通过提供商中立的 `RoleSpec` 运行。在运行时选择后端：
```
# Claude（默认）— 使用 Anthropic API / Claude Agent SDK
$ npx agent-run -r code_reviewer -s ./src -m sonnet
# Codex（可选启用）— 使用 @openai/codex-sdk；接受 gpt-* / o* model ids
$ npx agent-run -r threat_modeler -s ./src -f json --provider codex -m gpt-4.1
```
设置 `AGENT_PROVIDER=codex` 或传递 `--provider codex`。对于支持的角色，MCP server 连接 (`--mcp-server-url`) 在这两个提供商上均可工作。
## 🤖 可用的代理
### 简单查询代理 (`simple_query_agent`)
一个通用的 AppSec 助手，可以：
- 回答与安全相关的问题
- 协助安全分析任务
- 提供安全最佳实践的指导
- 交互式查询处理
- 搜索和分析文件目录（使用 `--src_dir` 选项）
### 代码审查代理 (`code_reviewer`)
一个专门用于自动化代码分析的代理，可以：
- 审查代码中的安全漏洞
- 检测代码库中的隐私问题
- 生成全面的安全报告
- 支持多种输出格式（Markdown、JSON、XML、CSV、XLSX）
- 分析整个项目目录
- 使用高级工具：Read、Grep 和 Write 功能
- 通过 `-c/--context` 接收部署上下文，用于特定环境的分析
- 通过 `-d/--diff-context` 实现 **专注于 PR 的审查模式**，优化 token 使用
### 代码修复代理 (`code_fixer`)
一个专门用于生成精确安全修复的代理，可以：
- 通过 `--fix-context` 接收带有完整代码上下文的安全发现
- 生成最小化、有针对性的修复以解决漏洞
- 返回结构化的 JSON 输出 (`FixOutput`)，包含修复后的代码、行号、解释和置信度
- 保留原始缩进和代码功能
- 支持在之前的修复验证失败时的重试工作流
- 当提供 `--src_dir` 时，使用 `Read` 和 `Grep` 工具获取额外的源代码上下文
### QA 验证代理 (`qa_verifier`)
一个专门用于验证安全修复的代理，可以：
- 运行项目的测试套件以验证安全修复不会破坏功能
- 分析测试失败以确定是由修复引起的还是原本存在的
- 提供结构化的 JSON 结论 (`QaVerdict`)，包含通过/失败状态、失败详情和建议
- 通过带有安全限制的受限 Bash 工具执行 shell 命令
- 支持自定义测试命令、设置命令和环境变量
- 接收部署上下文以进行环境感知验证
### PR 审查器 (`pr_reviewer`)
`code_reviewer` 的一个专注于 PR 的变体，针对 diff 上下文进行了优化：
- 具备与 `code_reviewer` 相同的安全分析能力，专门针对 Pull Request diff 进行了调优
- 当使用 `-d/--diff-context` 时，**默认启用 PR diff 分块**（参见 [PR 分块](#pr-chunking-large-prs)）
- 当提供 `--mcp-server-url` 时支持 MCP 感知（`queryFindingsHistory`、`queryImportGraph`、`queryCodebaseGraph`、`queryRuntimeEnrichment`）
### 威胁建模器 (`threat_modeler`)
一个专门用于全面威胁建模的代理，可以：
- 生成结构化的 **`threat_model_report` JSON**（DFD + STRIDE 威胁 + 风险登记表）或传统的多文件 ASCII 交付物
- 对 DFD 执行 STRIDE 方法的威胁建模
- 创建带有修复计划的详细风险登记表报告
- 当证据确认时，通过可选的 **`source_locations`** (`file`、`line_numbers`、`symbol`、`snippet`) 将 DFD 节点、威胁和风险锚定到源代码 (v3.1.0)
- 分析代码库中的安全威胁和漏洞
- 默认情况下最多运行 **100 次工具使用轮次**（可在 yaml 中配置或通过 `--max-turns` 配置）
### 威胁对抗器 (`threat_adversary`, v3.1.0)
用于威胁建模的对抗性二次审查 —— 从首轮报告中过滤掉无根据的威胁：
- 输入：通过 `--adversarial-context` 传入的首轮 `threat_model_report` JSON
- 输出：过滤后的 `threat_model_report` JSON（相同的 schema）输出到明确的 `-o` 路径
- 仅保留具有具体攻击路径和确认的 `source_locations` 的威胁；丢弃通用的、已缓解的或无根据的项目
- 在过滤后重新协调风险登记表和 `metadata` 计数
- 使用与 `threat_modeler` 相同的模型提供商和 `max_turns` 默认值
## 📖 使用示例
### 基本查询
```
# 交互式查询 agent
$ npx agent-run
# 带有源代码目录上下文的查询 agent
$ npx agent-run -r simple_query_agent -s /path/to/source
```
### 代码审查示例
```
# 审查当前目录中的代码
$ npx agent-run -r code_reviewer
# 审查特定源代码目录
$ npx agent-run -r code_reviewer -s /path/to/source
# 自定义输出文件和格式
$ npx agent-run -r code_reviewer -o security_report.html -f html
# 使用部署上下文进行审查以获得更具针对性的分析
$ npx agent-run -r code_reviewer -s ./src \
-c "AWS Lambda function in production VPC, handles user authentication via API Gateway, processes PII data"
# 带有合规性上下文的 Kubernetes 微服务
$ npx agent-run -r code_reviewer -s ./payment-service \
-c "Kubernetes microservice on GKE, PCI-DSS compliant environment, internal service mesh only"
# 带有访问上下文的内部工具
$ npx agent-run -r code_reviewer -s ./admin-cli \
-c "Internal CLI tool run by DevOps, requires VPN access, elevated AWS IAM permissions"
```
`-c/--context` 选项提供部署和环境信息，帮助代理：
- 专注于特定环境的漏洞（例如，Lambda 事件注入、K8s secrets 暴露）
- 考虑已经到位的基础设施缓解措施
- 根据实际的威胁环境确定调查结果的优先级
- 推荐适合所述架构的最佳实践
### 专注于 PR 的代码审查（Diff 上下文模式）
对于 Pull Request 审查，使用 `-d/--diff-context` 选项提供一个仅包含更改代码的 JSON 文件。通过将审查重点放在实际更改上而不是整个代码库，这大大减少了 token 的使用。
```
# 使用 diff 上下文审查 PR
$ npx agent-run -r code_reviewer -d pr-diff.json
# 需要时与源代码目录结合以获取完整的文件访问权限
$ npx agent-run -r code_reviewer -d pr-diff.json -s ./src
# 带有额外的部署上下文
$ npx agent-run -r code_reviewer -d pr-diff.json -c "Production API, handles PII"
```
Diff 上下文 JSON 文件应遵循以下结构：
```
{
"prNumber": 123,
"baseBranch": "main",
"headBranch": "feature/auth",
"headSha": "abc123def456",
"owner": "your-org",
"repo": "your-repo",
"files": [
{
"filePath": "src/auth/login.ts",
"language": "typescript",
"fileType": "modified",
"imports": "import bcrypt from 'bcrypt';",
"hunks": [
{
"startLine": 42,
"endLine": 55,
"beforeContext": "// Previous context",
"changedCode": "+const password = req.body.password;",
"afterContext": "// Following context",
"containingFunction": "async function login(req, res)"
}
]
}
],
"totalFilesChanged": 1,
"totalLinesAdded": 10,
"totalLinesRemoved": 5
}
```
**注意：** 如果在未指定 `code_reviewer` 角色的情况下提供了 `--diff-context`，将会显示警告，因为该选项仅适用于代码审查。
#### PR 分块（大型 PR）
当 PR diff 超过模型的上下文限制时，**分块** 会将 diff 拆分为多个批次，审查每个批次，然后将报告合并为一个输出文件。
- **配置**（在 `conf/appsec_agent.yaml` 中）：PR diff 分块选项位于 **`pr_reviewer.options`** 下，并且当您使用 `pr_reviewer` 角色配合 `-d/--diff-context` 时 **默认开启**。`code_reviewer` 角色默认不开启分块。
- `diff_review_max_tokens_per_batch`：例如 `150000`（0 或省略 = 不分块）
- `diff_review_max_batches`：例如 `3`（每次运行的批次上限）
- `diff_review_max_files`：可选的审查文件数量上限；其余将被跳过
- `diff_review_exclude_paths`：可选的要排除的路径模式列表（例如 `["src/analytics/*"]`）
- **CLI**（覆盖配置）：`--diff-max-tokens `、`--diff-max-batches `、`--diff-max-files `、`--diff-exclude `（可重复）
当使用分块时，合并后的报告可能包含一个 **已跳过** 部分，列出被排除或超过批次限制的文件。总 API 成本将按批次和总计进行记录，并且（对于 JSON 报告）包含在 `meta.total_cost_usd` 中。
```
# 使用 -d 时，pr_reviewer 默认开启 chunking
$ npx agent-run -r pr_reviewer -d pr-diff.json
# 或者在使用 code_reviewer 时通过 CLI 启用 chunking（覆盖配置）
$ npx agent-run -r code_reviewer -d pr-diff.json --diff-max-tokens 150000 --diff-max-batches 3
```
#### 对抗性二次审查 (`pr_adversary`)
在 `pr_reviewer` 运行之后，父应用可以调用 **二次审查**，丢弃没有具体失败/利用路径的调查结果。输入是一个列出候选调查结果的 JSON 文件；输出是一个 **过滤后** 的 `security_review_report`（与主 PR 报告的 schema 相同）。
```
# 过滤候选发现（JSON 输入 → JSON 输出）。可选：使用相同的 PR diff 作为上下文。
$ npx agent-run -r pr_adversary --adversarial-context candidates.json -s ./repo -f json \
-o adversarial_code_review_report.json
# 可选：包含 diff 上下文（大型 diff 在 prompt 中会被截断）
$ npx agent-run -r pr_adversary --adversarial-context candidates.json --diff-context pr-diff.json -s ./repo -f json
```
- **`--experiment-enabled`：** 为此审查添加更严格的误报指令；对于 `pr_reviewer`，当您的集成器传递此标志时，也会收紧初始的 diff 审查。
#### 全仓库对抗性误报过滤器 (`fp_adversary`, v2.8.0)
`pr_adversary` 的 Lane-2 对应项：`pr_adversary` 重新过滤 PR 范围内的调查结果，而 `fp_adversary` 作用于整个仓库首轮 `code_reviewer` 的调查结果，并针对每个调查结果发出一个 **结论**（`confirm` 或 `dismiss`），包含 0-1 的数字置信度和具体的依据。输出的结构是一个专用的 `fp_adversary_report`（与 `security_review_report` 不同），以便父应用可以将低置信度的驳回路由到“预驳回” UI 状态，并且仅在高于操作员配置的置信度阈值时才自动驳回。
```
# Full-repo 误报过滤器 — 相同的 --adversarial-context flag，不同的输入/输出 schema。
$ npx agent-run -r fp_adversary --adversarial-context fp_in.json -s ./repo -f json \
-o fp_adversary_report.json
```
**输入结构**（`findings[].fingerprint` 是往返的 key；这四个姿态字段和 `similar_dismissed` 先例数组都是可选的，但推荐使用）：
```
{
"findings": [
{
"fingerprint": "fp-sha256-of-cwe-file-snippet-line",
"id": "SEC-001",
"title": "SQL injection",
"file": "src/db.ts",
"description": "…",
"severity": "HIGH",
"confidence": "MEDIUM",
"cwe_id": "CWE-89"
}
],
"project_summary": "A Next.js SaaS app",
"security_context": "Prisma ORM with parameterized queries",
"deployment_context": "Vercel, multi-tenant",
"developer_context": "PHI handling rules apply to user_data",
"similar_dismissed": [
{ "fingerprint": "fp-old", "file": "src/db.ts", "cwe": "CWE-89", "dismissal_reason": "Prisma parameterized query" }
],
"metadata": { "project_name": "parent-app" }
}
```
**输出结构：**
```
{
"fp_adversary_report": {
"verdicts": [
{
"fingerprint": "fp-sha256-of-cwe-file-snippet-line",
"verdict": "dismiss",
"confidence": 0.92,
"rationale": "Prisma parameterized query mitigates; no concrete bypass path observed.",
"cost_usd_estimate": 0.001
}
]
}
}
```
`fp_adversary` 是 MCP 感知的：在运行时传递 `--mcp-server-url` 会公开 `queryFindingsHistory`、`queryImportGraph`、`queryCodebaseGraph` 和 `queryRuntimeEnrichment`，以便代理在确认之前可以验证可达性。
**输入文件结构**（每个调查结果的最少要求：`id`、`title`、`file`、`description`）：
```
{
"findings": [
{
"id": "SEC-001",
"title": "…",
"file": "src/a.ts",
"description": "…",
"severity": "HIGH",
"confidence": "HIGH",
"recommendation": "…"
}
],
"pr_number": 123,
"head_sha": "abc123"
}
```
### 代码修复示例
```
# 修复 fix context JSON 文件中描述的漏洞
$ npx agent-run -r code_fixer --fix-context fix_context.json
# 使用源代码目录作为额外上下文
$ npx agent-run -r code_fixer --fix-context fix_context.json -s ./src
# 自定义输出文件
$ npx agent-run -r code_fixer --fix-context fix_context.json -o my_fix.json
```
修复上下文 JSON 文件应遵循以下结构：
```
{
"finding": {
"title": "SQL Injection",
"severity": "HIGH",
"cwe": "CWE-89",
"owasp": "A03:2021",
"file": "src/db.ts",
"line": 42,
"description": "User input directly concatenated into SQL query",
"recommendation": "Use parameterized queries",
"category": "Injection"
},
"code_context": {
"language": "typescript",
"imports": "import { db } from './database';",
"vulnerable_section": "const result = db.query(`SELECT * FROM users WHERE id = ${userId}`);",
"vulnerable_section_start": 40,
"vulnerable_section_end": 44,
"full_file_with_line_numbers": " 40| const result = db.query(...);",
"indentation_guidance": "Use 2-space indentation"
},
"security_guidance": "Use parameterized queries to prevent SQL injection.",
"learned_examples": "",
"negative_examples": "",
"custom_instructions": "",
"chain_of_thought": false
}
```
代理返回一个结构化的 `FixOutput`：
```
{
"fixed_code": "const result = db.query('SELECT * FROM users WHERE id = ?', [userId]);",
"start_line": 42,
"end_line": 42,
"explanation": "Replaced string interpolation with parameterized query to prevent SQL injection",
"confidence": "high",
"breaking_changes": false
}
```
### QA 验证示例
```
# 通过运行项目的测试来验证安全修复
$ npx agent-run -r qa_verifier --qa-context qa_context.json
# 使用源代码目录作为额外上下文
$ npx agent-run -r qa_verifier --qa-context qa_context.json -s ./src
# 自定义输出文件
$ npx agent-run -r qa_verifier --qa-context qa_context.json -o qa_verdict.json
```
QA 上下文 JSON 文件应遵循以下结构：
```
{
"pr_url": "https://github.com/owner/repo/pull/42",
"test_command": "npm test",
"test_framework": "jest",
"setup_commands": "npm ci",
"timeout_seconds": 120,
"block_on_failure": true,
"deployment_context": "Production Kubernetes cluster",
"environment_variables": {
"NODE_ENV": "test"
}
}
```
代理返回一个结构化的 `QaVerdict`：
$ cd appsec-agent
```
2. 安装依赖：
```
$ npm install
```
3. 构建项目：
```
$ npm run build
```
这会将 TypeScript 源代码文件编译到 `dist/` 目录中的 JavaScript。
### 构建包
```
# 构建 package
$ npm run build
# 清理构建产物
$ npm run clean
```
### 从源码运行
在开发过程中，您可以直接从源码运行代理：
```
# 使用 ts-node（无需构建）
$ npx ts-node bin/agent-run.ts
# 或者先构建，然后运行
$ npm run build
$ node dist/bin/agent-run.js
```
## 🧪 测试
该项目包括全面的测试覆盖率，包括针对 Web 应用场景的并发测试。
### 运行测试
```
# 运行所有测试
$ npm test
# 在 watch 模式下运行测试
$ npm run test:watch
# 运行带有覆盖率的测试
$ npm run test:coverage
# 运行特定的测试文件
$ npm test -- concurrency.test.ts
```
### 测试覆盖率
- **单元测试**：所有组件的核心功能
- **集成测试**：端到端代理工作流
- **并发测试**：Web 应用使用下的线程安全验证
- 对话历史隔离
- 工具使用日志隔离
- 并发文件操作
- 竞态条件预防
- 内存泄漏预防
### 测试结果
所有测试均通过，包括：
- ✅ 跨越 40 个套件的 644 个总测试
- ✅ 针对 Web 应用使用的并发和线程安全覆盖
- ✅ Diff 上下文验证、威胁模型 / 威胁对抗 schema 以及提供商一致性测试
- ✅ 核心功能的全面覆盖
## 🔗 相关项目
### [AI Threat Modeler](https://github.com/yangsec888/ai-threat-modeler/) — 父应用程序
`appsec-agent` 驱动着 [**AI Threat Modeler**](https://github.com/yangsec888/ai-threat-modeler/)，这是一个用于 AppSec 自动化的完整开源 Web 应用。如果您希望通过精致的 UI 而不是 CLI 或库 API 来使用这些代理，父应用是推荐的入门方式。
亮点：
- 🐳 使用 `docker-compose up -d --build` 实现 **一键设置**
- 🖥️ **Next.js Web 仪表板**，具有身份验证（JWT、bcrypt、基于角色的访问）以及管理员管理的 Anthropic API 凭据
- 🧵 **威胁建模工作流** —— 上传一个仓库 ZIP，并获得结构化的 JSON 威胁模型（由 `appsec-agent` v1.6+ 驱动），包含基于代码的 `source_locations` 和可选的对抗性过滤（`threat_adversary`，v3.1.0+）：
- 交互式的威胁感知 **数据流图**（带有平移/缩放、搜索、过滤器、信任边界的 React Flow 画布）
- 带有 STRIDE 类别和严重性徽章的可排序威胁表
- 具有交叉引用威胁 ID 的风险登记表
- 导出为 **PDF**（带有嵌入式矢量 SVG 的 DFD 和威胁模型）、**CSV**（风险登记表）或 **原始 JSON**
- 💬 **聊天界面**，具有持久的对话历史记录，由 `appsec-agent` 交互模式提供支持
- 📚 位于 `/api-docs` 的 **OpenAPI 3.0 / Swagger** 文档
- 🧪 全面的后端、前端和 Playwright E2E 测试覆盖
快速开始：
```
git clone https://github.com/yangsec888/ai-threat-modeler.git
cd ai-threat-modeler
docker-compose up -d --build
# 然后打开 http://localhost:3000 （默认登录：admin / admin）
```
有关完整详情，请参阅 [AI Threat Modeler README](https://github.com/yangsec888/ai-threat-modeler/blob/main/README.md) 和 [SETUP.md](https://github.com/yangsec888/ai-threat-modeler/blob/main/SETUP.md)。
## 📚 参考
- [AI Threat Modeler（父应用）](https://github.com/yangsec888/ai-threat-modeler/)
- [Claude Agent SDK 文档](https://docs.claude.com/en/api/agent-sdk)
- [Anthropic API 文档](https://docs.anthropic.com/)
- [Claude Code 文档](https://docs.anthropic.com/claude-code)
## 📄 许可证
该项目基于 [Apache License 2.0](LICENSE) 授权 —— 有关详情，请参阅 `LICENSE` 文件。
## 👥 作者
**Sam Li** - *初始工作* - [yang.li@owasp.org](mailto:yang.li@owasp.org)
*为 AppSec 社区倾注 ❤️ 打造*
标签：MITM代理, TypeScript, 人工智能, 威胁建模, 安全插件, 暗色界面, 用户模式Hook绕过, 聊天机器人, 自动化攻击, 请求拦截