| 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 等依赖文件。
- 容器镜像名称。
开始前先判断
确认：
- 扫描路径。
- 是否扫描 Git 历史。
- 是否只允许离线扫描。
- 是否允许联网规则。
- 结果中是否需要隐藏 secret。
- 项目语言和包管理器。
- 是否要生成机器可读输出。
数据新鲜度和下载量策略
当前镜像已经内置常用模板、规则、缓存或数据库。默认先使用内置资源，不要每次任务都在线更新。
临时更新前，先按下面标准判断是否划算：
| 预计新增下载量 | 默认策略 |
|---|
| 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、修复版本。
- 代码问题要给文件路径和行号，但不要贴大段源码。
