code-security-scan

name	code-security-scan
description	用于扫描代码仓库、源码目录、文件系统和配置文件中的密钥、依赖漏洞、IaC 错误配置和常见安全问题。适合组合 gitleaks、trufflehog、semgrep-offline、semgrep、trivy 对项目进行本地安全检查。

代码、密钥和供应链安全扫描

这份技能提供本地代码安全扫描的工具知识和结果判断方法。根据项目语言、仓库规模、部署方式和当前问题选择扫描器；不必为了“覆盖完整流程”运行所有工具。

目标

检查项目中的：

• 密钥和 Token 泄露。
• 代码安全问题。
• 依赖漏洞。
• Dockerfile、Kubernetes、Terraform、CI 配置风险。
• 文件系统中的综合安全问题。

适用输入

• Git 仓库。
• 源码目录。
• 压缩包解压后的项目。
• Dockerfile 或 IaC 目录。
• package-lock、requirements、pom.xml、go.mod 等依赖文件。
• 容器镜像名称。

开始前先判断

确认：

1. 扫描路径。
2. 是否扫描 Git 历史。
3. 是否只允许离线扫描。
4. 是否允许联网规则。
5. 结果中是否需要隐藏 secret。
6. 项目语言和包管理器。
7. 是否要生成机器可读输出。

数据新鲜度和下载量策略

当前镜像已经内置常用模板、规则、缓存或数据库。默认先使用内置资源，不要每次任务都在线更新。

临时更新前，先按下面标准判断是否划算：

预计新增下载量	默认策略
0–20 MB	可以直接更新，适合增量更新或小规则集
20–50 MB	通常可以更新，但要确认任务确实需要较新数据
50–100 MB	谨慎更新；只有近期漏洞、近期 PoC 或用户要求最新结果时才做
>100 MB	默认不更新；除非用户明确要求，并且这个任务强依赖最新数据
无法估算大小	默认不更新，先使用镜像内置资源

同时考虑耗时：

• 预计 1–2 分钟内完成：可以接受。
• 预计超过几分钟：默认不做，除非用户明确要求。
• 需要拉取大型仓库、完整漏洞库、语言生态数据库或框架更新：默认不在任务中临时执行。

更新失败时不要阻塞主流程，直接回退到镜像内置资源，并在结果里说明“使用的是内置数据，可能不是最新”。

如果工具支持 dry-run、增量更新或只更新索引，优先使用这种方式。不要为了普通任务下载大型字典、完整框架或未知来源的 PoC 仓库。

临时更新建议

代码扫描相关数据更新要看下载量和任务目标。

Trivy 漏洞库

Trivy DB 可能不小；如果只是普通项目初筛，默认使用镜像内置 DB。
如果用户要求最新 CVE 覆盖，或项目涉及近期漏洞，再临时更新。

建议加时间上限：

timeout 180 env TRIVY_SKIP_DB_UPDATE=false trivy fs . \
  --format json \
  --output code-scan/raw/trivy_fs_fresh.json

只想提前更新 DB 时：

timeout 180 env TRIVY_SKIP_DB_UPDATE=false trivy image --download-db-only --no-progress

Java DB 往往更大、更慢。只有在扫描 Java 项目、并且用户需要最新 Java 依赖漏洞时才考虑：

timeout 240 env TRIVY_SKIP_JAVA_DB_UPDATE=false trivy image --download-java-db-only --no-progress

如果更新超时或失败，回退到内置 DB：

trivy fs . --format json --output code-scan/raw/trivy_fs_builtin.json

Semgrep 规则

默认使用离线规则：

semgrep-offline . --json -o code-scan/raw/semgrep_offline.json

如果用户允许在线规则，并且希望规则覆盖更广，可以使用：

semgrep --config auto . --json -o code-scan/raw/semgrep_auto.json

如果要更新内置规则仓库，只有在目录可写、网络可用、更新量较小、且用户需要较新规则时才做：

timeout 120 git -C "${SEMGREP_RULES_DIR:-/opt/semgrep-rules}" pull --ff-only

如果 git pull 显示更新量很大、耗时过长或失败，不要继续等待，直接使用已有离线规则。

semgrep-offline 会保留这份规则仓库的 Git 元数据，但运行时只加载顶层规则目录并跳过 scripts、stats、tests，不会把仓库根目录元数据当作规则解析。

不建议临时更新

• seclists、wordlists：普通任务不更新。
• 大型语言生态数据库：除非目标项目强依赖，而且用户明确需要。
• 未知来源规则仓库：不要临时拉取。

常见分析路径

密钥、代码模式、依赖和部署配置属于不同证据面，可以独立检查，也可以互相印证。下面命令展示常见起点。

理解扫描对象和范围

mkdir -p code-scan/{raw,clean,final,notes}

确认当前目录：

pwd
find . -maxdepth 2 -type f | sed 's#^\./##' | head -100

寻找密钥和敏感信息线索

先用 Gitleaks：

gitleaks detect \
  --source . \
  --report-format json \
  --report-path code-scan/raw/gitleaks.json

如果不是 Git 仓库：

gitleaks detect \
  --no-git \
  --source . \
  --report-format json \
  --report-path code-scan/raw/gitleaks_nogit.json

再用 TruffleHog 做补充：

trufflehog filesystem . \
  --json > code-scan/raw/trufflehog_filesystem.jsonl

如果需要扫 Git 历史：

trufflehog git file://"$PWD" \
  --json > code-scan/raw/trufflehog_git.jsonl

检查危险代码模式

默认离线规则：

semgrep-offline . \
  --json \
  -o code-scan/raw/semgrep_offline.json

如果用户允许在线规则：

semgrep --config auto . \
  --json \
  -o code-scan/raw/semgrep_auto.json

如果用户提供规则目录：

semgrep --config ./rules . \
  --json \
  -o code-scan/raw/semgrep_custom.json

检查依赖、部署和配置风险

文件系统综合扫描：

trivy fs . \
  --format json \
  --output code-scan/raw/trivy_fs.json

只看配置风险：

trivy config . \
  --format json \
  --output code-scan/raw/trivy_config.json

如果用户给的是镜像：

trivy image IMAGE_NAME \
  --format json \
  --output code-scan/raw/trivy_image.json

提取便于复核的结果

Trivy 摘要：

jq '.Results[]? | {Target, Vulnerabilities, Misconfigurations, Secrets}' \
  code-scan/raw/trivy_fs.json > code-scan/final/trivy_summary.json

Semgrep 摘要：

jq -r '.results[]? | [.extra.severity, .check_id, .path, (.start.line|tostring), .extra.message] | @tsv' \
  code-scan/raw/semgrep_offline.json > code-scan/final/semgrep_findings.tsv

Gitleaks 摘要，避免输出 secret 原文：

jq -r '.[]? | [.RuleID, .File, (.StartLine|tostring), .Description] | @tsv' \
  code-scan/raw/gitleaks.json > code-scan/final/gitleaks_findings.tsv

工具使用要点

gitleaks

适合快速发现 Git 仓库里的密钥。

gitleaks detect --source . --report-format json --report-path gitleaks.json

要点：

• Git 仓库会包含历史。
• 面向用户输出要脱敏。
• 如果仓库很大，运行时间会变长。

trufflehog

适合更深入的 secret 发现，尤其是 Git 历史和可验证 secret。

trufflehog filesystem . --json > trufflehog.jsonl
trufflehog git file://"$PWD" --json > trufflehog_git.jsonl

要点：

• JSONL 逐行解析。
• Verified secret 优先级更高。
• 不展示完整 secret。

semgrep-offline

适合默认静态代码扫描。

semgrep-offline . --json -o semgrep.json

要点：

• 使用镜像内置规则。
• 离线稳定，适合默认流程。
• 结果需要结合代码上下文判断。

semgrep

适合在线规则或用户给定规则。

semgrep --config auto . --json -o semgrep_auto.json

要点：

• 需要联网时先确认。
• 不要把私有代码上传到外部服务，除非用户明确允许。

trivy

适合依赖漏洞、配置错误、Secret、文件系统或镜像扫描。

trivy fs . --format json --output trivy_fs.json
trivy config . --format json --output trivy_config.json
trivy image IMAGE_NAME --format json --output trivy_image.json

要点：

• 当前镜像预置漏洞库，默认不需要运行时更新。
• 如果用户要求最新漏洞数据，再考虑在线更新。

值得保留的证据

• 实际扫描的目录、仓库历史、镜像、配置和依赖清单范围。
• 密钥线索是否真实、是否仍有效、出现在哪里，以及是否已脱敏。
• 静态规则命中对应的数据流、可达入口、危险操作和缓解条件。
• 依赖的实际版本、CVE、调用或部署情况、修复版本和缓解措施。
• IaC 与部署配置的运行环境、默认值和实际暴露条件。

扫描器命中更适合作为代码审查入口；只有结合上下文后，才能判断它是漏洞、测试样例、不可达代码还是误报。

判断与复核要点

• 密钥、Token、私钥、密码必须脱敏。
• 不上传源码或依赖清单，除非用户明确允许。
• 区分真实风险、测试样例、误报。
• 依赖漏洞要说明包名、版本、CVE、修复版本。
• 代码问题要给文件路径和行号，但不要贴大段源码。