static-analysis Skill 多维度简评

综合评分：9.0 / 10 ⭐⭐⭐⭐⭐ 类别：安全审计 / 静态分析 仓库：trailofbits/skills 维护者：Trail of Bits（应用安全领域权威机构） 理论基础：Trail of Bits Application Security Testing Handbook

一、核心定位与价值

static-analysis 是 Trail of Bits 在 Claude Code 技能市场发布的核心安全审计 Skill，把应用安全测试”三剑客”打包成一个工作流：

关键洞见：Semgrep 负责速度，CodeQL 负责深度，SARIF 负责聚合。三者结合才能既快又准。

适用场景

• 对代码库（任意语言）运行安全扫描
• 编写自定义 CodeQL 查询或 Semgrep 规则
• 处理和分析 SARIF 输出文件
• 在 CI/CD 流水线中设置静态分析
• 比较和聚合多工具的扫描结果
• 修复工作的优先级排序

不适用场景

• 从零写 Semgrep 规则 → 用 semgrep-rule-creator
• 动态分析或模糊测试 → 用 testing-handbook-skills
• 智能合约审计 → 用 building-secure-contracts
• PR 级安全审查 → 用 security-differential-review

二、核心能力

2.1 工具选择决策表

2.2 三层工具链架构

┌─────────────────────────────────────────────────┐
│             CodeQL (深度)                        │
│   - 编译期数据库                                 │
│   - 跨函数数据流                                 │
│   - 完整类型推断                                 │
│   - 适合：挖掘深层漏洞                           │
│   - 代价：需要完整 build，慢                      │
└─────────────────────────────────────────────────┘
                       ↑ 互补
┌─────────────────────────────────────────────────┐
│             Semgrep (速度)                       │
│   - 无需编译                                     │
│   - 模式匹配                                     │
│   - 在 IDE / pre-commit 即时反馈                 │
│   - 适合：日常扫描、CI 守门                       │
│   - 代价：精度不如 CodeQL                        │
└─────────────────────────────────────────────────┘
                       ↓ 输出
┌─────────────────────────────────────────────────┐
│          SARIF Parsing (聚合)                    │
│   - SARIF v2.1.0 标准化                          │
│   - 多工具结果去重                                │
│   - 按严重度分拣                                  │
│   - 集成 GitHub Code Scanning                    │
│   - 适合：CI/CD 流水线                            │
└─────────────────────────────────────────────────┘

2.3 核心子 Skill

仓库路径：

• skills/codeql/SKILL.md — CodeQL 子 Skill
• skills/semgrep/SKILL.md — Semgrep 子 Skill
• skills/sarif-parsing/SKILL.md — SARIF 解析子 Skill

三、完整使用流程

3.1 Semgrep 快速扫描

# 安装
pip install semgrep

# 用 Semgrep Registry 推荐规则集
semgrep --config=auto .

# 指定规则集
semgrep --config=p/security-audit .
semgrep --config=p/owasp-top-ten .
semgrep --config=p/cwe-top-25 .

# 多个规则集
semgrep \
  --config=p/security-audit \
  --config=p/secrets \
  --config=p/owasp-top-ten \
  .

特点：

• ⚡ 通常 30 秒 - 3 分钟跑完中型项目
• 📊 直接输出 30+ 种语言支持
• 🪶 轻量级，无需编译源码

3.2 CodeQL 深度分析

# 安装 CodeQL CLI
# macOS
brew install codeql
# Linux
wget https://github.com/github/codeql-cli-binaries/releases/latest/download/codeql-linux64.zip
unzip codeql-linux64.zip -d /opt/codeql
export PATH="/opt/codeql/codeql:$PATH"

# 拉取 CodeQL 查询包
codeql pack download codeql/python-queries
codeql pack download codeql/javascript-queries

# 创建数据库
codeql database create mydb --language=python --source-root=.

# 跑安全查询
codeql database analyze mydb \
  codeql/python-queries:codeql-suites/python-security-extended.qls \
  --format=sarif-latest \
  --output=results.sarif

特点：

• 🔬 完整构建数据库（类似编译器前端）
• 🌊 跨函数数据流追踪
• 🎯 高精度、低误报
• ⏱️ 跑全量通常 5-30 分钟

3.3 SARIF 解析与聚合

# 把 SARIF 转成可读 JSON
jq '.runs[].results[] | {ruleId, message: .message.text, location: .locations[0].physicalLocation.artifactLocation.uri}' results.sarif

# 用 Python SARIF 库处理
pip install sarif-tools
sarif diff results-v1.sarif results-v2.sarif  # 对比两次扫描
sarif stats results.sarif  # 统计
sarif html results.sarif --output report.html  # HTML 报告

3.4 完整工作流（Trail of Bits 官方推荐）

Step 1: Semgrep 快速扫描（CI 必跑）
  ↓ 报警
Step 2: CodeQL 深度分析（Nightly / PR 重触发）
  ↓ 输出 SARIF
Step 3: SARIF Parsing 聚合 + 去重 + 分拣
  ↓ 生成 PR 评论 / Issue
Step 4: 按 CVE/CWE 严重度排序
  ↓
Step 5: 修复 → 二次扫描验证

四、CodeQL 子 Skill 深度解析

4.1 核心查询包

4.2 三个套件（Suite）

# 轻量级 - 快速跑
codeql/python-queries:codeql-suites/python-security.qls

# 扩展级 - 默认推荐
codeql/python-queries:codeql-suites/python-security-extended.qls

# 完整 - Nightly 跑
codeql/python-queries:codeql-suites/python-security-and-quality.qls

4.3 自定义 CodeQL 查询

// Custom: 检测所有未加密的数据库连接字符串
import javascript

from DataFlow::SourceNode source, DataFlow::SinkNode sink
where
  source.getStringValue().regexpMatch(".*(mysql|postgres|mongodb)://.*password=.*")
  and sink = source.getAEnclosingExpr().flow().getSink()
select sink, "Unencrypted database connection with password: $@", source

# 保存为 custom.ql，运行
codeql database analyze mydb custom.ql --format=sarif-latest

4.4 跨函数数据流示例

// 追踪 user input 到达 SQL 字符串拼接的路径
import python
import semmle.python.security.dataflow.SqlInjectionQuery

from SqlInjectionConfiguration cfg, DataFlow::PathNode source, DataFlow::PathNode sink
where cfg.hasFlowPath(source, sink)
select sink.getNode(), source, sink,
  "SQL query constructed from $@.", source.getNode(),
  "user-provided value"

输出包含完整数据流路径：source → 中间函数 → sink。

五、Semgrep 子 Skill 深度解析

5.1 Semgrep Registry 规则分类

5.2 编写自定义 Semgrep 规则

# rules/no-console-log.yaml
rules:
  - id: no-console-log-in-production
    message: "Remove console.log before production"
    severity: WARNING
    languages: [javascript, typescript]
    metadata:
      category: best-practice
      cwe: "CWE-489: Active Debug Code"
    pattern-either:
      - pattern: console.log(...)
      - pattern: console.error(...)
    paths:
      exclude:
        - "**/*.test.*"
        - "**/scripts/**"

# 跑自定义规则
semgrep --config rules/no-console-log.yaml .

5.3 Semgrep taint mode（数据流）

# rules/sql-injection.yaml
rules:
  - id: python-flask-sql-injection
    message: "Untrusted input flows into SQL query"
    severity: ERROR
    languages: [python]
    frameworks: [flask]
    mode: taint
    pattern-sources:
      - pattern: flask.request.args.get(...)
      - pattern: flask.request.form.get(...)
    pattern-sinks:
      - pattern: |
          $QUERY = f"...{$X}..."
          $CURSOR.execute($QUERY)
    pattern-sanitizers:
      - pattern: psycopg2.sql.Identifier(...)

semgrep --config rules/sql-injection.yaml --json | jq '.results[].path'

5.4 Semgrep 性能优化

# 1. 排除 vendor 目录
semgrep --config=p/security-audit \
  --exclude='node_modules' \
  --exclude='vendor' \
  --exclude='*.min.js' \
  .

# 2. 并行扫描
semgrep --config=p/security-audit --jobs 8 .

# 3. 增量扫描（只扫变更）
semgrep --config=p/security-audit --diff .

# 4. 使用 baseline 抑制老报警
semgrep --config=p/security-audit . > current.json
# 后续扫描忽略已有
semgrep --config=p/security-audit . --baseline-commit=HEAD~10

六、SARIF Parsing 子 Skill 深度解析

6.1 什么是 SARIF

SARIF（Static Analysis Results Interchange Format）是 OASIS 标准的静态分析结果交换格式：

• JSON 格式
• 包含规则元数据 + 结果位置 + 数据流 + 严重度
• 工业级工具统一输出：CodeQL、Semgrep、Snyk、GitHub Code Scanning 等

6.2 SARIF 核心结构

{
  "version": "2.1.0",
  "$schema": "https://docs.oasis-open.org/sarif/sarif/v2.1.0/cos02/schemas/sarif-schema-2.1.0.json",
  "runs": [
    {
      "tool": {
        "driver": {
          "name": "Semgrep",
          "version": "1.45.0",
          "rules": [
            {
              "id": "python.flask.security.audit.eval",
              "name": "eval-injection",
              "shortDescription": { "text": "Detected eval()" }
            }
          ]
        }
      },
      "results": [
        {
          "ruleId": "python.flask.security.audit.eval",
          "level": "error",
          "message": { "text": "Avoid using eval() with user input" },
          "locations": [
            {
              "physicalLocation": {
                "artifactLocation": { "uri": "src/api.py" },
                "region": { "startLine": 42, "endLine": 42, "startColumn": 8 }
              }
            }
          ]
        }
      ]
    }
  ]
}

6.3 SARIF 处理工作流

# Python 处理 SARIF
import json
import sarif_om

with open("results.sarif") as f:
    sarif = json.load(f)

# 按严重度分拣
severity_map = {"error": "Critical", "warning": "High", "note": "Medium"}
findings = []
for run in sarif["runs"]:
    for result in run["results"]:
        findings.append({
            "rule": result["ruleId"],
            "severity": severity_map.get(result["level"], "Low"),
            "message": result["message"]["text"],
            "file": result["locations"][0]["physicalLocation"]["artifactLocation"]["uri"],
            "line": result["locations"][0]["physicalLocation"]["region"]["startLine"],
        })

# 生成 Markdown 报告
with open("report.md", "w") as f:
    f.write("# Static Analysis Report\n\n")
    f.write(f"Total findings: {len(findings)}\n\n")
    for sev in ["Critical", "High", "Medium", "Low"]:
        sev_findings = [f for f in findings if f["severity"] == sev]
        f.write(f"## {sev} ({len(sev_findings)})\n\n")
        for fnd in sev_findings:
            f.write(f"- **{fnd['rule']}** in `{fnd['file']}:{fnd['line']}`\n")
            f.write(f"  {fnd['message']}\n")

6.4 集成到 GitHub Code Scanning

# 把 SARIF 上传到 GitHub
gh code-scanning upload results.sarif --repo=myorg/myrepo
# 自动出现在 PR 的 Security 标签

# GitHub Actions 完整示例
name: Static Analysis
on: [push, pull_request]
jobs:
  semgrep:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install semgrep
      - run: semgrep --config=auto --sarif --output=semgrep.sarif .
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: semgrep.sarif
  codeql:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with:
          languages: javascript, python
      - uses: github/codeql-action/analyze@v3
        with:
          category: "/language:javascript"

七、真实踩坑案例

案例 1：CodeQL 数据库创建失败

现象：codeql database create 报 “no source code found”。 根因：项目根目录没有该语言代码，或路径配置错误。 解决：

# 确认语言支持
codeql resolve languages
# 显式指定源码根
codeql database create mydb \
  --language=python \
  --source-root=./src \
  --overwrite

案例 2：Semgrep 在大型 monorepo 卡死

现象：扫描 1M+ 行 monorepo，半小时没结果。 根因：默认全量扫描 + 没排除 vendor。 解决：

semgrep --config=p/security-audit \
  --exclude='**/node_modules/**' \
  --exclude='**/dist/**' \
  --exclude='**/build/**' \
  --exclude='**/.next/**' \
  --exclude='**/vendor/**' \
  --max-target-bytes=10000000 \
  --timeout=30 \
  --jobs=4 \
  .

案例 3：CodeQL 误报：log 语句被识别为密码泄漏

现象：logger.info("password reset") 被识别为硬编码密码。 根因：CodeQL 的 secrets 规则用正则匹配，没理解日志字符串语义。 解决：

// 自定义查询排除 logger 调用
import javascript

from StringLiteral s
where s.getValue().regexpMatch("(?i).*password.*")
  and not exists(LoggerCall lc | lc.getAnArgument() = s)
select s, "Possible hardcoded password"

案例 4：SARIF 字段不统一

现象：不同工具的 SARIF 输出字段名不同，处理脚本不通用。 根因：SARIF 是标准但允许工具自定义字段。 解决：用 sarif-om 库规范化处理。

案例 5：CodeQL build step 失败

现象：Java 项目 CodeQL 创建数据库时 mvn package 失败。 根因：Maven build 引入了外部依赖，CI 环境网络受限。 解决：

# 用 CodeQL 的 autobuild（自动检测 build tool）
codeql database create mydb --language=java --source-root=.
# 或显式指定
codeql database create mydb \
  --language=java \
  --command="mvn -o clean package" \
  --source-root=.

案例 6：Semgrep 规则冲突（多条同时命中）

现象：同一个漏洞被多条 Semgrep 规则同时报警。 根因：规则集重叠（p/owasp-top-ten 和 p/cwe-top-25 有交集）。 解决：

# 用 --severity 过滤
semgrep --config=p/owasp-top-ten --severity=ERROR --severity=WARNING .

# 或合并规则集
semgrep --config="p/security-audit;p/secrets" --severity=ERROR .

案例 7：CodeQL 跑全量 2 小时仍未结束

现象：C++ 项目 CodeQL 跑 2 小时卡住。 根因：C++ 数据库创建慢，全量查询包 300+ 条规则。 解决：

# 拆分：先跑 security 套件（轻量）
codeql database analyze mydb \
  codeql/cpp-queries:codeql-suites/cpp-security.qls \
  --threads=8 \
  --timeout=600 \
  --format=sarif-latest

# Nightly 才跑 full 套件
codeql database analyze mydb \
  codeql/cpp-queries:codeql-suites/cpp-security-and-quality.qls \
  --format=sarif-latest

案例 8：SARIF 报警爆炸（3000+ 报警）

现象：首次扫描报警 3000+ 条，无从下手。 根因：项目历史债务。 解决：

# 用 baseline 抑制老报警
semgrep ci --config=p/security-audit
# 首次跑会在 .semgrepbaseline 记录当前报警
# 后续 PR 只报警新增/变化的

八、性能与基准测试

8.1 扫描速度对比（10 万行代码）

8.2 准确率对比（Trail of Bits 公开数据）

结论：CodeQL 适合”不漏报”场景，Semgrep 适合”快迭代”场景。

8.3 多语言支持对比

九、CI/CD 集成最佳实践

9.1 分层策略

┌─────────────────────────────────────────────┐
│  Pre-commit hook (本地, 1 秒)               │
│  - Semgrep 极简规则                          │
│  - 阻止明显问题入库                           │
└─────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────┐
│  PR 检查 (CI, 1-3 分钟)                     │
│  - Semgrep 增量扫描                          │
│  - 失败门槛：新增 Critical/High              │
└─────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────┐
│  Nightly (Nightly, 10-30 分钟)              │
│  - CodeQL 全量分析                           │
│  - 报告到 Slack / Email                      │
│  - 不阻塞合并                                │
└─────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────┐
│  Weekly (深度, 1-2 小时)                     │
│  - 多工具 + 第三方扫描                       │
│  - SBOM 生成                                 │
│  - 趋势分析                                  │
└─────────────────────────────────────────────┘

9.2 GitHub Actions 完整配置

name: Static Analysis
on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'  # Nightly at 2 AM

jobs:
  semgrep-pr:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install semgrep
      - name: Semgrep CI
        run: semgrep ci --config=p/security-audit --error
        env:
          SEMGREP_APP_TOKEN: ${{ secrets.SEMGREP_APP_TOKEN }}
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: semgrep-results
          path: semgrep.sarif

  codeql-nightly:
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      actions: read
      contents: read
    strategy:
      matrix:
        language: [javascript, python, go]
    steps:
      - uses: actions/checkout@v4
      - uses: github/codeql-action/init@v3
        with:
          languages: ${{ matrix.language }}
          queries: security-and-quality
      - uses: github/codeql-action/analyze@v3
        with:
          category: "/language:${{ matrix.language }}"

9.3 GitLab CI 配置

stages:
  - test
  - security

semgrep:
  stage: security
  image: returntocorp/semgrep:latest
  script:
    - semgrep --config=p/security-audit --sarif --output=gl-sast-semgrep.sarif .
  artifacts:
    reports:
      sast: gl-sast-semgrep.sarif
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

codeql:
  stage: security
  image: github/codeql-action
  script:
    - codeql database create mydb --language=python --source-root=.
    - codeql database analyze mydb codeql/python-queries:codeql-suites/python-security-extended.qls
      --format=sarif-latest --output=gl-sast-codeql.sarif
  artifacts:
    reports:
      sast: gl-sast-codeql.sarif
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

十、与其他安全工具对比

十一、与 trailofbits 其他 Skills 配合

完整工作流：

audit-context-building (理解架构)
  ↓
static-analysis (发现初始漏洞)
  ↓
variant-analysis (横向排查同类)
  ↓
insecure-defaults (审计配置)
  ↓
fix (修复代码)
  ↓
fix-review (验证修复)
  ↓
security-differential-review (PR 审查)

十二、Q&A

Q: 必须订阅 Claude Code 吗？ A: Skill 推荐 Claude Opus 4.6+。但工具本身（Semgrep、CodeQL）无需 Claude 即可独立使用。

Q: 误报率高吗？ A: CodeQL 误报率约 10%，Semgrep 约 25%。可通过自定义规则、baseline 文件降低。

Q: 能修复吗？ A: 不会自动修改。Skill 输出建议，由人工修复或用 fix-review 验证。

Q: 私有项目能用吗？ A: 工具本身（Semgrep、CodeQL CLI）完全本地运行，无需联网。Claude API 调用需考虑数据敏感。

Q: 中文支持？ A: Skill 是英文，处理中文代码无障碍（变量名/注释可含中文）。

Q: 跑全量 CodeQL 太慢怎么办？ A: 用增量扫描（只跑变更文件）、拆 suite、并行 threads。

Q: 怎么开始？ A: 先用 Semgrep --config=auto 跑一遍 5 分钟看效果，再决定是否引入 CodeQL。

Q: 跟 Snyk / Dependabot 重叠吗？ A: Snyk/Dependabot 主要是依赖扫描（CVE），static-analysis 是代码扫描（漏洞模式）。两者互补。

十三、真实战绩（Trophy Case）

Trail of Bits 公开过多个实战发现：

• CodeQL 在 Ethereum 客户端中发现多个 Go 运行时漏洞
• Semgrep 自定义规则在数十个加密货币项目中找到 reentrancy
• CodeQL 数据流分析 揪出 ML-DSA 签名中的常量时间违规
• SARIF 聚合 帮助客户在 1000+ 仓库的 monorepo 中统一安全标准

十四、安装

# Claude Code
/plugin marketplace add trailofbits/skills
/plugin install static-analysis@trailofbits

# 通用
npx skills add trailofbits/skills --skill static-analysis

# 工具独立安装
pip install semgrep
codeql pack download codeql/python-queries

14.1 安装路径

• Claude Code: ~/.claude/plugins/marketplaces/trailofbits/skills/static-analysis/
• Cursor: ~/.cursor/skills/
• OpenCode: ~/.config/opencode/skills/

十五、8 条反合理化

十六、5 条实战技巧

1. Semgrep 跑 pre-commit：1 秒反馈，开发体验好
2. CodeQL 跑 Nightly：深度不阻塞 PR
3. SARIF 上传 GitHub：免费 Code Scanning 集成
4. 建立 baseline：抑制老报警，只查新问题
5. 持续维护规则集：根据业务加自定义规则

十七、总结

核心价值：

• 工业级 SAST 三件套打包（CodeQL + Semgrep + SARIF）
• 速度（Semgrep）与深度（CodeQL）兼顾
• 完整 CI/CD 集成
• 配套 Skills 形成完整安全工作流

适用人群：

• 所有需要安全审计的项目
• DevSecOps 团队
• 金融 / 医疗 / 政企（合规要求）
• 智能合约审计
• 大型 monorepo 维护者

投入产出比：⭐⭐⭐⭐⭐（5/5）—— 安全团队必装。

何时不要用：

• 纯前端 demo（无服务端）
• 一次性脚本
• 运行时漏洞（用 DAST / RASP）
• 第三方库漏洞（用 SCA / Snyk）

配套文档：variant-analysis 变体排查 | semgrep-rule-creator 规则编写 | security-differential-review PR审查 | 精选技能对比

参考资料

1. trailofbits/skills GitHub 仓库
2. CodeQL 官方文档
3. Semgrep 官方文档
4. OASIS SARIF 标准规范
5. GitHub Code Scanning 文档