企业官网建设流程全解析

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等工具，就存在两类风险：一是审计过程中误改代码，污染了本应"原样取证"的代码库；二是审查工具本身可能被被审代码中的陷阱内容误导而执行危险操作。把工具面收窄到Read+Grep，等于从机制上排除了这两类风险——这也是 ja/04-subagents/README.md 在最佳实践中强调的"工具访问要限制——只授予 Agent 目的所需的工具"这一原则的落地范例。

安全审查的五大焦点

系统提示词给secure-reviewer划定了五个审查领域，这基本对齐 OWASP 的经典分类。以下是原文档的完整清单：

1. 认证问题（Authentication Issues）
   • 弱密码策略
   • 缺少多因素认证（MFA）
   • 会话管理缺陷
2. 授权问题（Authorization Issues）
   • 破损的访问控制
   • 权限提升
   • 缺失的角色检查
3. 数据暴露（Data Exposure）
   • 日志中的敏感数据
   • 未加密的存储
   • API 密钥暴露
   • PII（个人身份信息）处理
4. 注入漏洞（Injection Vulnerabilities）
   • SQL 注入
   • 命令注入
   • XSS（跨站脚本）
   • LDAP 注入
5. 配置问题（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"

逐条拆解这些模式背后的意图：

需要说明适用前提：这些模式是"高召回、低精度"的初筛——例如password = ""空值、测试夹具里的假密钥都会命中，最终定性要结合上下文由 Agent（或人）判断。这正是secure-reviewer采用Read+Grep双工具的原因：Grep负责快速缩小包围圈，Read负责打开命中的文件确认上下文。

标准化的漏洞报告输出格式

一个只读审查 Agent 的最终产物是报告。原文档为每条漏洞规定了固定的六字段输出结构：

• Severity（严重度）：Critical / High / Medium / Low
• Type（类型）：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）的项。

三种调用方式：

1. 自动委派——主 Agent 根据任务描述与description字段自行决定是否转交；
2. 显式指名——对话中直接说"用 secure-reviewer 子代理审查这个模块"；
3. @-mention 强制调用——@secure-reviewer可绕过自动委派的启发式判断，确保该 Agent 被唤起。

此外还可以用claude --agent secure-reviewer把整个会话跑成以它为主代理的模式，或ctrl+scrollback场景下把长审计任务Ctrl+B转入后台执行。

仓库纵深：与它配套的两类安全组件

在 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-reviewer（Read, Grep），做需要执行检测工具的 PR 安全门禁用插件版（Read, Grep, Bash）——权限面与任务需求精确匹配，这正是子代理设计的核心纪律。

2. security-scan.sh：PostToolUse 钩子（时机更早）

security-scan.sh 是一个绑定在PostToolUse（matcher 为Write）事件上的钩子脚本，在每次文件写入之后自动运行，与事后审查的secure-reviewer形成互补。它的检测面更细，可以对照原文档的 grep 包来看：

• 硬编码密码：同时匹配 JSON 形式"password": "value"与代码形式password = 'value'；
• API 密钥：匹配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这个文件本身，它示范了子代理安全设计的三个要点：

1. 能力即声明：tools: Read, Grep一行就把"不能执行、不能改、不能跑测试"从口头约定变成了机制约束——Agent 连尝试破坏的入口都没有；
2. 提示词即审计清单：五大审查焦点 + 检索模式 + 六字段输出格式，让每次审计的范围和产物格式都确定可预期，不同项目间结果可比；
3. 审计者与被审者隔离：审计过程对代码库零写入，保证"审查不留痕"，与主会话的上下文也相互隔离，长审计不污染主对话。

如果你需要在自己的项目里落地这套实践，最直接的路径就是：把 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