Back to Details

ln-761-secret-scanner

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Secret Scanner

密钥扫描工具

Scans codebase for hardcoded secrets and credentials, returning structured findings for remediation.
扫描代码库中的硬编码密钥和凭证，返回结构化的检测结果以指导修复。

Purpose & Scope

目的与范围

  • Detect hardcoded secrets using available tools (gitleaks, trufflehog) or manual patterns
  • Classify findings by severity (Critical/High/Medium/Low)
  • Filter false positives via baseline and allowlists
  • Provide remediation guidance per finding type
  • Return normalized report to parent orchestrator (ln-760)
  • 使用可用工具（gitleaks、trufflehog）或手动规则检测硬编码密钥
  • 按严重性等级（Critical/高/中/低）分类检测结果
  • 通过基线和允许列表过滤误报
  • 针对不同类型的检测结果提供修复指导
  • 向父编排器（ln-760）返回标准化报告

When to Use

使用场景

  • During project bootstrap (via ln-760-security-setup)
  • Pre-commit hook validation
  • CI/CD security pipeline
  • Manual security audit
  • 项目启动阶段（通过ln-760-security-setup）
  • 预提交钩子验证
  • CI/CD安全流水线
  • 手动安全审计

Workflow

工作流程

Phase 1: Tool Detection

阶段1：工具检测

Step 1: Check Available Scanners
  • Check if gitleaks is installed (preferred)
  • Check if trufflehog is installed (alternative)
  • If neither available: use manual pattern matching as fallback
Step 2: Load Configuration
  • Load project 
    .gitleaks.toml
    if exists (custom rules)
  • Load 
    .gitleaksbaseline
    if exists (known false positives)
  • If no config: use default patterns from 
    references/detection_patterns.md
步骤1：检查可用扫描工具
  • 检查是否已安装gitleaks（首选工具）
  • 检查是否已安装trufflehog（备选工具）
  • 如果两者都不可用：使用手动规则匹配作为备选方案
步骤2：加载配置
  • 如果存在，加载项目的
    .gitleaks.toml
    （自定义规则）
  • 如果存在，加载
    .gitleaksbaseline
    （已知误报）
  • 如果没有配置文件：使用
    references/detection_patterns.md
    中的默认规则

Phase 2: Scan Execution

阶段2：扫描执行

Step 1: Run Available Scanner
  • Execute scanner against project root
  • Capture output in structured format (JSON/SARIF preferred)
  • If tool unavailable: run manual grep patterns for high-confidence secrets
Step 2: Parse Results
  • Normalize output to common format: file, line, pattern, raw_match
  • Preserve original severity if provided by tool
步骤1：运行可用扫描工具
  • 在项目根目录执行扫描工具
  • 以结构化格式（优先JSON/SARIF）捕获输出
  • 如果工具不可用：运行手动grep规则检测高可信度密钥
步骤2：解析结果
  • 将输出标准化为通用格式：文件、行号、规则、匹配内容
  • 保留工具提供的原始严重性等级

Phase 3: Report Generation

阶段3：报告生成

Step 1: Severity Classification
  • Map findings to severity levels per 
    references/detection_patterns.md
  • Critical: AWS keys, private keys, JWT secrets
  • High: Generic passwords, connection strings
  • Medium: API keys (may be test data)
  • Low: Potential secrets requiring manual review
Step 2: False Positive Filtering
  • Apply baseline exclusions
  • Apply allowlist patterns (placeholders, test data, docs)
  • Mark filtered items as "excluded" with reason
Step 3: Build Report
  • Group findings by severity
  • Include file path, line number, pattern matched
  • Do NOT include actual secret values in report
步骤1：严重性分类
  • 根据
    references/detection_patterns.md
    将检测结果映射到严重性等级
  • Critical：AWS密钥、私钥、JWT密钥
  • 高：通用密码、连接字符串
  • 中：API密钥（可能为测试数据）
  • 低：需要手动复查的潜在密钥
步骤2：误报过滤
  • 应用基线排除规则
  • 应用允许列表规则（占位符、测试数据、文档）
  • 将过滤项标记为“已排除”并注明原因
步骤3：生成报告
  • 按严重性等级分组检测结果
  • 包含文件路径、行号、匹配的规则
  • 报告中禁止包含实际密钥值

Phase 4: Remediation Guidance

阶段4：修复指导

Step 1: Attach Remediation Actions
  • For each finding, attach remediation steps from 
    references/remediation_guide.md
  • For Critical findings: emphasize immediate rotation requirement
Step 2: Return Results
  • Return structured findings list to orchestrator
  • Include summary: total scanned, total found, by severity
步骤1：附加修复操作
  • 为每个检测结果附加
    references/remediation_guide.md
    中的修复步骤
  • 对于Critical级别的结果：强调立即轮换的要求
步骤2：返回结果
  • 向编排器返回结构化的检测结果列表
  • 包含摘要：总扫描文件数、总检测数、各严重性等级数量

Critical Rules

核心规则

  1. Never log actual secret values - redact in all outputs
  2. Treat any found secret as compromised - rotation required for Critical
  3. Preserve baseline - do not remove existing baseline entries
  4. Pre-commit priority - recommend pre-commit hook if not configured
  5. Git history awareness - warn if secret may exist in history (requires git-filter-repo)
  1. 绝对禁止记录实际密钥值 - 在所有输出中进行脱敏处理
  2. 所有检测到的密钥均视为已泄露 - Critical级别的密钥必须轮换
  3. 保留基线配置 - 不得删除现有基线条目
  4. 优先使用预提交钩子 - 如果未配置，建议启用预提交钩子
  5. 关注Git历史 - 如果密钥可能存在于历史记录中，发出警告（需要git-filter-repo工具）

Definition of Done

完成标准

  • Scan completed using available tool or manual patterns
  • Findings classified by severity
  • False positives filtered via baseline/allowlist
  • Remediation guidance attached to each finding
  • Report returned in normalized format (no raw secret values)
  • Critical findings flagged with rotation requirement
  • 使用可用工具或手动规则完成扫描
  • 检测结果已按严重性等级分类
  • 已通过基线/允许列表过滤误报
  • 每个检测结果都附加了修复指导
  • 报告以标准化格式返回（不包含原始密钥值）
  • Critical级别的检测结果已标记轮换要求

Reference Files

参考文件

FilePurpose
references/detection_patterns.md
Secret patterns by confidence level
references/gitleaks_config_template.toml
Template for project gitleaks config
references/remediation_guide.md
Rotation procedures by secret type
Version: 2.0.0 Last Updated: 2026-01-10
文件用途
references/detection_patterns.md
按可信度等级划分的密钥规则
references/gitleaks_config_template.toml
项目gitleaks配置模板
references/remediation_guide.md
按密钥类型划分的轮换流程
版本： 2.0.0 最后更新： 2026-01-10