lucasrosati/claude-security-agents

# Claude Code 安全代理：自动化红队 + 蓝队 将两个 `.md` 文件放入你的项目。获得自动化的渗透测试和修复——无需框架、无需基础设施、无需安全背景。 🇧🇷 [Leia em Português](./README.pt-BR.md) ## 目录 1. [问题](#the-problem) 2. [解决方案](#the-solution) 3. [工作原理](#how-it-works) 4. [设置（2 分钟）](#setup-2-minutes) 5. [红队 — 进攻代理](#red-team--offensive-agent) 6. [蓝队 — 防御代理](#blue-team--defensive-agent) 7. [运行代理](#running-the-agents) 8. [发现的真实漏洞](#real-vulnerabilities-found) 9. [针对你的技术栈定制](#customizing-for-your-stack) 10. [常见问题](#faq) ## 问题 你正在快速构建产品、交付功能。但安全总是被推迟到“以后”。 meanwhile，你的代码库在悄悄积累漏洞：未经过滤的 HTML 渲染、公共 API 端点、未受保护的管理路由、不验证签名的 Webhook 处理器。你不会在代码审查中发现它们——它们隐藏在组件之间的交互中，隐藏在你凌晨 2 点的假设里，隐藏在从文档复制粘贴的第三方集成中。 雇佣渗透测试人员花费数千美元。运行 SAST 工具会给你 200 个通用警告，其中大多数是误报。而且你仍然有功能要交付。 ## 解决方案 两个针对 Claude Code 的专用代理——每个都是一个约 120 行的 Markdown 文件： | 代理 | 角色 | 模式 | 作用 | |-------|------|------|-------------| | **红队** | 攻击者 | 只读 | 扫描代码库中的漏洞。 像渗透测试人员一样思考。 生成包含严重性、攻击场景和修复建议的结构化报告 | | **蓝队** | 防御者 | 编辑模式 | 接收红队报告并修复每个漏洞。编写代码、添加测试、提交更改 | 它们作为一个反馈循环工作： ``` Red Team scans → finds 14 vulnerabilities → generates report ↓ Blue Team reads report → fixes 12/14 → commits fixes ↓ Red Team re-scans → finds 3 new issues → generates report ↓ Blue Team fixes → hardening complete ``` 每一轮只需几分钟，而不是几天。 ## 工作原理 Claude Code 支持 [自定义代理](https://docs.anthropic.com/en/docs/claude-code/agents) —— 位于 `.claude/agents/` 的 Markdown 文件，为 Claude 提供专门的人格、方法论和受限的工具访问。 红队代理获得 **只读工具**（读取、grep、glob、npm audit）。它可以分析一切，但不能修改任何内容。 蓝队代理获得 **编辑工具**（读取、写入、编辑、git）。它可以修改代码、安装包、运行测试并提交。 两者都从 `CLAUDE.md` 继承项目上下文，因此它们无需额外配置即可理解你的技术栈、架构和约束。 ## 设置（2 分钟） ### 1. 创建代理目录 ``` mkdir -p .claude/agents ``` ### 2. 复制代理文件 ``` # 选项 A：克隆此仓库并复制 git clone https://github.com/lucasrosati/claude-security-agents.git /tmp/security-agents cp /tmp/security-agents/agents/red-team-scanner.md .claude/agents/ cp /tmp/security-agents/agents/blue-team-defender.md .claude/agents/ # 选项 B：直接下载 curl -o .claude/agents/red-team-scanner.md https://raw.githubusercontent.com/lucasrosati/claude-security-agents/main/agents/red-team-scanner.md curl -o .claude/agents/blue-team-defender.md https://raw.githubusercontent.com/lucasrosati/claude-security-agents/main/agents/blue-team-defender.md ``` ### 3. 运行首次审计 在项目中打开 Claude Code 并输入： ``` Run the red-team-scanner agent on this codebase ``` 仅此而已。没有配置文件、没有 API 密钥、没有 Docker 容器。 ## 红队 — 进攻代理 **文件：** [`agents/red-team-scanner.md`](./agents/red-team-scanner.md) **模型：** Sonnet（快速、成本高效的扫描） **权限模式：** `plan`（只读 — 不能修改代码） ### 分析内容 | 类别 | 示例 | |----------|---------| | 身份验证与授权 | 破损的身份验证、弱 JWT 验证、缺少速率限制、IDOR、权限提升 | | API 安全 | 公共端点、缺少对象级授权、Mass Assignment、枚举 | | 输入验证与注入 | SQL/NoSQL 注入、XSS（存储/反射/DOM）、SSRF、路径遍历 | | 文件上传 | MIME 欺骗、缺少魔数验证、公共存储暴露 | | 数据安全与合规 | 硬编码密钥、日志中的 PII、不安全的令牌存储、LGPD/HIPAA 缺口 | | 基础设施 | CORS 配置错误、缺少安全头（CSP、HSTS）、容器问题 | | 管理面板 | 未受保护的管理路由、隐藏端点、会话劫持 | | 支付与计费 | 缺少 Webhook 验证、价格操纵、订阅绕过 | | Supabase 特定 | 破损的 RLS 策略、service_role 密钥泄露、跨租户访问 | ### 输出格式 对于发现的每个漏洞： ``` [VULN-001] XSS via unsanitized AI content rendering Severity: HIGH Location: src/pages/StudySession.tsx:267 Description: AI-generated HTML rendered via dangerouslySetInnerHTML without sanitization Attack scenario: Attacker injects into content now renders as plain text Prevention: All AI content must pass through sanitizeAIContent() before dangerouslySetInnerHTML ``` ### 强化检查清单 修复所有漏洞后，蓝队会生成最终检查清单： ``` - [x] Security headers implemented - [x] Rate limiting active on auth and API - [x] CORS restricted to known origins - [x] Logging and audit trail working - [x] Sensitive data encrypted at rest and in transit - [x] Secrets in env vars (none hardcoded) - [x] Dependencies updated (0 critical/high CVEs) - [x] RLS policies audited - [x] Input validation on all endpoints - [x] File upload secured - [x] Admin panel protected - [x] Webhooks verified - [ ] LGPD compliance (consent, data retention, audit log) ``` ## 运行代理 ### 首次审计（红队） ``` # In Claude Code > Run the red-team-scanner agent on this codebase ``` 红队将： 1. 映射你的技术栈、端点、路由和中间件 2. 运行静态分析以查找脆弱模式 3. 运行 `npm audit` 检查依赖项中的已知 CVE 4. 检查配置（环境变量、CORS、头信息） 5. 跟踪敏感数据流（PII、令牌、凭证） 6. 生成编号报告（VULN-001、VULN-002、...） ### 应用修复（蓝队） ``` # In Claude Code，在收到红队报告后 > Run the blue-team-defender agent. Here is the Red Team report: [paste report] ``` 蓝队将： 1. 按严重性优先（CRITICAL 和 HIGH 优先） 2. 反向工程每个攻击向量 3. 在代码中实现修复 4. 运行测试验证未破坏功能 5. 分别提交每个修复组：`fix(security): [VULN-XXX] 描述` 6. 生成强化检查清单 ### 重新扫描（迭代） ``` # 再次运行红队以捕获回归或新问题 > Run the red-team-scanner agent again. Previous audit fixed VULN-001 through VULN-012. ``` 重复此过程，直到红队报告返回干净结果。 ### 快捷命令 | 命令 | 作用 | |---------|-------------| | `Run red-team-scanner` | 完整安全审计 | | `Run blue-team-defender` | 修复红队报告中的漏洞 | | `Run red-team-scanner on src/api/` | 扫描特定目录 | | `Run red-team-scanner focusing on authentication` | 针对性扫描 | ## 发现的真实漏洞 这些是代理在一个生产 SaaS 应用（React + Supabase + Edge Functions）中发现的真实漏洞： ### 严重 | ID | 漏洞 | 影响 | |----|--------------|--------| | VULN-002 | 附属系统中的自引用 | 用户可为自己生成佣金 | | VULN-010 | 重复的佣金处理 | 同一支付可能触发双重佣金 | ### 高危 | ID | 漏洞 | 影响 | |----|--------------|--------| | VULN-003 | 4 个页面中的 XSS（通过 `dangerouslySetInnerHTML`） | 脚本、学习内容、会话窃取 | | VULN-004 | 无身份验证的 API 端点 | 任何人都可消耗 AI 配额 | | VULN-005 | 通过竞争条件访问的管理路由 | 普通用户可访问管理面板 | | VULN-006 | 可被覆盖的推荐字段 | 附属归因操纵 | | VULN-007 | 易受 HTML 注入的邮件模板 | 通过操纵用户名进行钓鱼 | | VULN-008 | 未验证签名的 JWT 解析 | 身份验证绕过 | ### 中危 | ID | 漏洞 | 影响 | |----|--------------|--------| | VULN-009 | 批量导入端点无有效负载限制 | 通过超大请求进行 DoS | | VULN-011 | 服务器到服务器 Webhook 的 CORS 通配符 | 跨源请求滥用 | | VULN-012 | 无身份验证的 CPF 枚举 | LGPD 违规、数据收集 | | VULN-013 | SQL 函数具有错误的易失性 | 查询计划器中的缓存中毒 | 所有漏洞均由蓝队代理自动修复。 ## 针对你的技术栈定制 这些代理开箱即用，适用于 Claude Code 支持的任何技术栈。如需针对你的项目优化： ### 1. 修改身份行 在两个代理文件中替换项目描述： 两个代理文件都以通用身份行开头。将其替换为你的项目上下文： ``` # 默认（通用） You are the **Red Team Scanner** for this project. # 定制（示例） You are the **Red Team Scanner** for Acme Corp — a B2B fintech SaaS handling payment processing. ``` ### 2. 添加特定技术栈部分 如果你使用 Firebase 而非 Supabase，替换第 9 节： ``` ### 9. Firebase 特定 - Firestore security rules audit - Firebase Auth configuration - Cloud Functions input validation - Storage rules (public vs private) ``` ### 3. 添加合规要求 ``` ### 10. SOC 2 合规 - Access logging for all sensitive operations - Data encryption at rest and in transit - Incident response procedures documented - Vendor security assessment ``` ### 4. 修改模型 如需更深入分析，切换至 Opus： ``` model: opus # more thorough, higher cost ``` 如需对大型代码库进行更快的扫描： ``` model: haiku # faster, cheaper, less thorough ``` ### 5. 修改语言 代理可在 Claude 支持的任何语言中工作。只需重写指令： ``` # 英文版本 You are the **Red Team Scanner** for this project. ## 身份 - Senior Security Engineer specialized in SaaS, OWASP Top 10, API Security ``` ## 常见问题 **使用这些代理需要安全经验吗？** 不需要。红队以通俗语言解释每个漏洞及攻击场景。蓝队会自动修复它们。你只需检查变更。 **红队会修改我的代码吗？** 不会。它运行在 `plan` 模式（只读）。它可以读取文件、搜索代码并运行 `npm audit`，但不能写入、编辑或执行任意命令。 **蓝队会破坏我的应用吗？** 它在每次修复后运行测试并单独提交更改。如果出现问题，你可以回滚单个提交。它还运行在 `acceptEdits` 模式，因此每次更改前你都需要批准。 **成本是多少？** 这些代理使用你现有的 Claude Code 订阅或 API 信用。对中等项目（约 100 个文件）的完整审计通常需要 5–15 分钟（使用 Sonnet）。 **可以在 CI/CD 中运行吗？** 不能直接运行——Claude Code 代理是交互式的。但你可以将定期审计安排为安全工作流的一部分。 **代理是特定于语言的吗？** 指令是葡萄牙语，但适用于任何编程语言。Claude Code 理解任何代码库。随意将代理文件翻译为你偏好的语言。 **与 Snyk 或 SonarQube 等工具有何不同？** SAST 工具基于模式查找问题（已知 CVE、简单代码异味）。这些代理理解你的架构、跨组件追踪数据流，并发现逻辑漏洞（如自引用、竞争条件、权限提升），这是静态工具无法发现的。 ## 架构 ``` .claude/ └── agents/ ├── red-team-scanner.md ← ~120 lines, read-only └── blue-team-defender.md ← ~140 lines, edit mode Workflow: ┌──────────────┐ report ┌──────────────┐ fixes ┌──────────┐ │ Red Team │ ──────────→ │ Blue Team │ ─────────→ │ Codebase │ │ (scanner) │ │ (defender) │ │ (safer) │ └──────────────┘ └──────────────┘ └──────────┘ ↑ │ └───────────────── re-scan ─────────────────────────────┘ ``` ## 致谢与链接 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) —— Anthropic 的编码代理 - [Claude Code 代理](https://docs.anthropic.com/en/docs/claude-code/agents) —— 自定义代理文档 - [OWASP Top 10](https://owasp.org/www-project-top-ten/) —— 安全漏洞参考 **如果这帮助你保护了应用，请给仓库一颗 ⭐ 并分享给其他快速交付的开发者。**

标签：AI 安全, Claude Code, CSRF, Markdown, SEO: Claude 安全代理, SEO: 代码安全无门槛, SEO: 漏洞扫描工具, SEO: 红队蓝队自动化, SEO: 自动化安全审计, SSRF, Web 漏洞, XSS, 代码安全, 代码审查, 信息泄露, 单文件代理, 开发者安全, 快速部署, 攻击模拟, 数据展示, 无框架, 无需基础设施, 暗色界面, 权限绕过, 漏洞情报, 漏洞枚举, 红队, 自动化渗透测试, 防御修复, 防御加固, 驱动签名利用