ln-761-secret-scanner

路径： 文件路径（references/、../ln-*）相对于此技能目录。

Secret Scanner

类型： L3 Worker 类别： 7XX Bootstrap

扫描代码库中的硬编码密钥和凭据，并返回结构化发现结果以供修复。

目的与范围

• 使用可用工具（gitleaks、trufflehog）或手动模式检测硬编码密钥
• 按严重程度对发现结果分类（Critical/High/Medium/Low）
• 通过基线和允许列表过滤误报
• 针对每种发现类型提供修复指导
• 向父级编排器（ln-760）返回标准化报告

适用场景

• 项目引导期间（通过 ln-760-security-setup）
• 提交前钩子验证
• CI/CD 安全流水线
• 手动安全审计

---

工作流

阶段 1：工具检测

步骤 1：检查可用扫描器

• 检查是否已安装 gitleaks（首选）
• 检查是否已安装 trufflehog（备选）
• 如果两者均不可用：使用手动模式匹配作为后备方案

步骤 2：加载配置

• 如果项目中存在 .gitleaks.toml，则加载该文件（自定义规则）
• 如果存在 .gitleaksbaseline，则加载该文件（已知误报）
• 如果没有配置：使用 references/detection_patterns.md 中的默认模式

阶段 2：执行扫描

步骤 1：运行可用的扫描器

• 对项目根目录执行扫描器
• 以结构化格式捕获输出（优先使用 JSON/SARIF）
• 如果工具不可用：运行手动 grep 模式，查找高置信度密钥

步骤 2：解析结果

• 将输出规范化为通用格式：file、line、pattern、raw_match
• 如果工具提供了原始严重程度，则予以保留

阶段 3：生成报告

步骤 1：严重程度分类

• 根据 references/detection_patterns.md 将发现结果映射到严重程度级别
• Critical：AWS 密钥、私钥、JWT 密钥
• High：通用密码、连接字符串
• Medium：API 密钥（可能是测试数据）
• Low：需要人工审核的潜在密钥

步骤 2：过滤误报

• 应用基线排除项
• 应用允许列表模式（占位符、测试数据、文档）
• 将过滤后的项目标记为“excluded”，并说明原因

步骤 3：生成报告

• 按严重程度对发现结果分组
• 包含文件路径、行号、匹配模式
• 不要在报告中包含实际密钥值

阶段 4：修复指导

步骤 1：附加修复措施

• 为每项发现附加 references/remediation_guide.md 中的修复步骤
• 对于 Critical 级别的发现：强调必须立即轮换

步骤 2：返回结果

• 向编排器返回结构化发现列表
• 包含摘要：扫描总数、发现总数、各严重程度数量

---

关键规则

1. 绝不记录实际密钥值——所有输出均须脱敏
2. 将发现的任何密钥都视为已泄露——Critical 级别的密钥必须轮换
3. 保留基线——不要删除现有基线条目
4. 优先配置提交前检查——如果尚未配置，则建议添加提交前钩子
5. 注意 Git 历史记录——如果密钥可能存在于历史记录中，则发出警告（需要 git-filter-repo）

---

完成定义

• 已使用可用工具或手动模式完成扫描
• 已按严重程度对发现结果分类
• 已通过基线/允许列表过滤误报
• 已为每项发现附加修复指导
• 已以标准化格式返回报告（不含原始密钥值）
• 已标记 Critical 级别的发现，并注明轮换要求

---

参考文件

文件	用途
references/detection_patterns.md	按置信度级别划分的密钥模式
references/templates/gitleaks_config_template.toml	项目 gitleaks 配置模板
references/remediation_guide.md	按密钥类型划分的轮换流程

---

版本： 2.0.0 最后更新： 2026-01-10