claude-howto 的 secure-reviewer 子代理用最小权限设计构建只读安全审计 Agent【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto本文以 claude-howto 仓库中的 secure-reviewer 子代理 为核心完整解析这个最小权限安全审计 Agent的设计与配置从 YAML frontmatter 的权限声明、五类安全审查焦点、可直接复制的漏洞检索命令到标准化的漏洞报告输出格式。读完之后你可以把它复制到自己的项目.claude/agents/目录中立即在 Claude Code 里获得一个只能读、不能改、不能执行的安全审查员。角色定位一个被锁死权限的安全专家secure-reviewer是一个 Claude Code 子代理subagent的完整定义文件它由 YAML frontmatter 加 Markdown 系统提示词两部分构成。frontmatter 声明了 Agent 的身份与能力边界--- name: secure-reviewer description: Security-focused code review specialist with minimal permissions. Read-only access ensures safe security audits. tools: Read, Grep model: inherit ---几个关键字段的含义可对照仓库中 子代理完全参考指南 的配置字段表name: secure-reviewer唯一标识符遵循小写字母加连字符的命名规范调用时用它指名道姓。description自然语言说明该 Agent 何时被调用。description不仅描述用途还会影响 Claude 的自动委派判断——在 claude-howto 的其他示例中description里写入 use PROACTIVELY 之类的措辞可以促进自动调用。本例的 description 强调最小权限 只读点明了它的审计属性。tools: Read, Grep这是整个设计的灵魂。根据子代理参考文档tools字段省略时会继承全部工具而这里显式收窄为仅两个只读工具。model: inherit继承主会话的模型避免为一个纯审查任务单独指定模型。系统提示词部分开宗明义地声明了能力清单原文即是一份权限说明书你是一名只专注于识别漏洞的安全专家。本 Agent 按设计只拥有最小权限可以读取文件进行分析可以搜索模式不能执行代码不能修改文件不能运行测试这确保审查者在安全审计期间不会意外破坏任何东西。为什么要把权限锁死从源码结构看子代理在独立于主会话的上下文窗口中运行其工具集完全由 frontmatter 决定。安全审计是典型的长流程任务——要逐个文件地读、逐条模式地搜一旦 Agent 被赋予Write、Edit、Bash等工具就存在两类风险一是审计过程中误改代码污染了本应原样取证的代码库二是审查工具本身可能被被审代码中的陷阱内容误导而执行危险操作。把工具面收窄到ReadGrep等于从机制上排除了这两类风险——这也是 ja/04-subagents/README.md 在最佳实践中强调的工具访问要限制——只授予 Agent 目的所需的工具这一原则的落地范例。安全审查的五大焦点系统提示词给secure-reviewer划定了五个审查领域这基本对齐 OWASP 的经典分类。以下是原文档的完整清单认证问题Authentication Issues弱密码策略缺少多因素认证MFA会话管理缺陷授权问题Authorization Issues破损的访问控制权限提升缺失的角色检查数据暴露Data Exposure日志中的敏感数据未加密的存储API 密钥暴露PII个人身份信息处理注入漏洞Injection VulnerabilitiesSQL 注入命令注入XSS跨站脚本LDAP 注入配置问题Configuration Issues生产环境开启调试模式默认凭据不安全的默认值这五个类别覆盖了安全审计中人和配置层面的多数入口认证与授权决定谁能动数据暴露决定秘密藏得深不深注入决定输入边界守不守得住配置问题则是最常见也最容易被忽视的低垂果实。审查时按此清单逐项过能保证报告不遗漏常见类别。漏洞检索模式可直接运行的 grep 命令包原文档给出了一组针对硬编码密钥、SQL 注入与命令注入的检索命令。这些命令同时服务于两种场景Claude 的Grep工具内部检索时的模式参考以及开发者手动对仓库做快速扫描时的现成脚本# 硬编码密钥Hardcoded secrets grep -r password\s* --include*.js --include*.ts grep -r api_key\s* --include*.py grep -r SECRET --include*.env* # SQL 注入风险 grep -r query.*\$ --include*.js grep -r execute.*% --include*.py # 命令注入风险 grep -r exec( --include*.js grep -r os.system --include*.py逐条拆解这些模式背后的意图命令目标语言命中的风险信号grep -r password\s* --include*.js --include*.tsJS/TS源码里直接给密码变量赋值而非从环境变量读取grep -r api_key\s* --include*.pyPython硬编码 API key 的赋值语句grep -r SECRET --include*.env*环境文件.env系列文件中的密钥定义用于核对是否被提交进了版本库grep -r query.*\$ --include*.jsJS字符串拼接构造查询\$匹配美元符号即模板插值/拼接痕迹SQL 注入的经典形态grep -r execute.*% --include*.pyPython用%格式化直接拼进execute参数未走占位符绑定grep -r exec( --include*.jsJSexec/execSync类调用输入不可信时即命令注入grep -r os.system --include*.pyPythonos.system直接走 shell 解析是注入高发 API需要说明适用前提这些模式是高召回、低精度的初筛——例如password 空值、测试夹具里的假密钥都会命中最终定性要结合上下文由 Agent或人判断。这正是secure-reviewer采用ReadGrep双工具的原因Grep负责快速缩小包围圈Read负责打开命中的文件确认上下文。标准化的漏洞报告输出格式一个只读审查 Agent 的最终产物是报告。原文档为每条漏洞规定了固定的六字段输出结构Severity严重度Critical / High / Medium / LowType类型OWASP 分类Location位置文件路径与行号Description描述该漏洞是什么Risk风险被利用后的潜在影响Remediation修复建议如何修复这套格式的价值在于可机读、可排序按 Severity 降序排列即可得到修复优先级Location 字段让每条发现都能直接跳转定位Type 字段则让不同审查报告可以按 OWASP 类别聚合统计。对团队来说这意味着安全审计结果可以直接进入 issue 跟踪流程而不是散落在自由文本里。安装与调用方式根据 ja/04-subagents/README.md 的安装步骤把该子代理用起来有三种途径推荐前两种方式一复制进项目项目级作用域# 进入你的项目 cd /path/to/your/project mkdir -p .claude/agents cp /path/to/claude-howto/ja/04-subagents/secure-reviewer.md .claude/agents/方式二复制进用户目录全局作用域mkdir -p ~/.claude/agents cp /path/to/claude-howto/ja/04-subagents/secure-reviewer.md ~/.claude/agents/验证安装在 Claude Code 中运行/agents应能看到secure-reviewer与内置代理一同列出。同名代理同时存在于多级作用域时加载优先级为CLI--agents定义仅当前会话 项目级.claude/agents/ 用户级~/.claude/agents/ 插件级agents/高优先级覆盖低优先级claude agents命令还会标出被覆盖override的项。三种调用方式自动委派——主 Agent 根据任务描述与description字段自行决定是否转交显式指名——对话中直接说用 secure-reviewer 子代理审查这个模块-mention 强制调用——secure-reviewer可绕过自动委派的启发式判断确保该 Agent 被唤起。此外还可以用claude --agent secure-reviewer把整个会话跑成以它为主代理的模式或ctrlscrollback场景下把长审计任务CtrlB转入后台执行。仓库纵深与它配套的两类安全组件在 claude-howto 仓库中secure-reviewer并不是孤立存在还有两个值得对照的安全组件分别代表更宽的权限面和更自动的触发时机。1. pr-review 插件中的 security-reviewer权限更宽pr-review 插件 自带一个 security-reviewer 代理frontmatter 为tools: Read, Grep, Bash——比secure-reviewer多了一个Bash。它的审查清单与本文介绍的五大焦点一致认证/授权、数据暴露、注入、安全配置配套的 check-security 命令 还会追加加密弱点与日志中的敏感数据两项。可以推断多出的Bash是为了让代理在 PR 审查时运行 git diff、调用外部扫描器之类需要命令行的动作。这正好构成一组对照做纯静态只读审计用secure-reviewerRead, Grep做需要执行检测工具的 PR 安全门禁用插件版Read, Grep, Bash——权限面与任务需求精确匹配这正是子代理设计的核心纪律。2. security-scan.shPostToolUse 钩子时机更早security-scan.sh 是一个绑定在PostToolUsematcher 为Write事件上的钩子脚本在每次文件写入之后自动运行与事后审查的secure-reviewer形成互补。它的检测面更细可以对照原文档的 grep 包来看硬编码密码同时匹配 JSON 形式password: value与代码形式password valueAPI 密钥匹配api_key/apikey/access_token的 JSON 赋值通用 secret/token 赋值私钥文件BEGIN.*PRIVATE KEY特征AWS 访问密钥AKIA[0-9A-Z]{16}格式若环境中装有semgrep或trufflehog还会静默调用它们做深度扫描。发现可疑内容时脚本按 Claude Code 钩子协议输出hookSpecificOutput.additionalContext的 JSON向 Agent 注入一条非阻断式警告提示改用环境变量而不是中断流程。脚本开头还刻意跳过二进制文件与node_modules、.git、dist、build等目录避免噪音。两者组合起来是一条完整的安全防线security-scan.sh在写入瞬间拦截新引入的密钥secure-reviewer在审计时点对整个代码库做结构化深查pr-review 插件则把审查动作固化进 PR 流程。设计启示最小权限如何落到一行 frontmatter回到secure-reviewer这个文件本身它示范了子代理安全设计的三个要点能力即声明tools: Read, Grep一行就把不能执行、不能改、不能跑测试从口头约定变成了机制约束——Agent 连尝试破坏的入口都没有提示词即审计清单五大审查焦点 检索模式 六字段输出格式让每次审计的范围和产物格式都确定可预期不同项目间结果可比审计者与被审者隔离审计过程对代码库零写入保证审查不留痕与主会话的上下文也相互隔离长审计不污染主对话。如果你需要在自己的项目里落地这套实践最直接的路径就是把 ja/04-subagents/secure-reviewer.md 复制为项目内.claude/agents/secure-reviewer.md用/agents验证加载再按需追加 OWASP 之外与你技术栈相关的检索模式——权限声明保持Read, Grep不动这是它全部安全性的来源。【免费下载链接】claude-howtoA visual, example-driven guide to Claude Code — from basic concepts to advanced agents, with copy-paste templates that bring immediate value.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-howto创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考