mapping-findings-to-owasp-top10

用途

OWASP Top 10 是 Web 应用风险类别的权威分类法。面向客户的渗透测试报告通常包含"OWASP 覆盖"章节，因为客户、审计方和保险方都期望看到发现结果与 Top 10 的对应关系。该技能为每条发现标注其所属的 OWASP 分类，将 CVE 和错误配置的冗长列表转化为结构化评估。

主要能力

基于确定性规则表对每条发现进行 OWASP 分类标注。规则依据以下键值：
- 来源技能 ID（例如来自 auditing-npm-dependencies 的发现几乎总是 A06——易受攻击和过时的组件）
- 发现类别（每技能类别标签，如 dependency-vulnerability、engagement-scope）
- CWE 标识符（若存在；CWE 到 OWASP 有成熟的映射）
- 明细关键词作为上述无法确定时的兜底
输出增强 JSONL（每条发现新增 owasp_category 字段）以及覆盖率报告，展示发现结果在 A01-A10 之间的分布。
未映射（UNMAPPED）的发现以 INFO 级别呈现以供人工审查，可扩展规则表或接受该发现为跨类别。

使用方式

前提条件

Python 3.9+
一个或多个 cluster 1-4 发现文件
可选的 .owasp-overrides.yaml 用于特定评估的分类规则

步骤

识别发现来源：默认读取 engagement/findings/*.json[l] 下的所有文件，可通过 --source FILE（可重复）覆盖。
运行映射器：

python3 ./scripts/map_owasp.py engagements/acme-2026-q2/

选项：

Usage: map_owasp.py PATH [OPTIONS]

Options:
  --source FILE           Specific findings file (repeatable)
  --enrich-output FILE    Write annotated findings JSONL here
                          (default: PATH/findings/all-with-owasp.jsonl)
  --coverage-output FILE  Coverage report path
                          (default: PATH/reports/owasp-coverage.md)
  --overrides FILE        Optional rule-overrides YAML
  --output FILE           Operational findings output
  --format FMT            json | jsonl | markdown (default: markdown)
  --min-severity SEV      default info

审查未映射的发现：UNMAPPED 以 INFO 呈现。检查是否存在 CWE；若存在，CWE 到 OWASP 的映射本应捕获，需扩展规则表。检查发现来源技能 ID 是否在规则表中；若否，添加技能级默认值。若确实不适配单一 A0X 类别，接受 UNMAPPED 并在评估备注中记录。
阅读覆盖率报告：报告列出每个 A0X 类别的发现数量、类别内严重性分布、具体发现指针。对于广泛覆盖测试的评估，十个类别应各至少有一条记录。零发现的类别要么反映范围（"我们未测试此项"），要么反映清洁结果（"我们测试了但未发现"）。

输出

增强发现 JSONL（--enrich-output）：每条发现新增 owasp_category 字段。
覆盖率报告 Markdown（--coverage-output）：按类别汇总。

每条操作发现包含：id（owasp::<issue>::<finding-fingerprint>）、severity（多为 INFO；解析错误为 HIGH）、category（owasp-mapping）、summary（发现发生了什么）、evidence（原始发现指纹、推导的 OWASP 类别、匹配的规则）。

技能产生的发现

发现	严重性	阈值	受影响控制
规则应用后未映射的发现	INFO	无规则匹配该发现	（操作）
源 JSONL 无法解析	HIGH	标准 JSONL 解析错误	（操作）
标注成功写回	INFO	每个源文件的确认	（信息）
覆盖率报告已生成	INFO	输出覆盖率报告路径	（信息）
评估覆盖全部 10 个类别	INFO	A01-A10 每个桶至少一条发现	（正面观察）
评估覆盖少于 10 个类别中的 5 个	MEDIUM	提示范围可能过窄	（信息）

OWASP Top 10（2021）参考

类别	描述
A01:2021	Broken Access Control
A02:2021	Cryptographic Failures
A03:2021	Injection
A04:2021	Insecure Design
A05:2021	Security Misconfiguration
A06:2021	Vulnerable and Outdated Components
A07:2021	Identification and Authentication Failures
A08:2021	Software and Data Integrity Failures
A09:2021	Security Logging and Monitoring Failures
A10:2021	Server-Side Request Forgery

示例

示例 1——评估结束时增强：

python3 ./scripts/map_owasp.py engagements/acme-2026-q2/

生成 engagements/acme-2026-q2/findings/all-with-owasp.jsonl（增强发现）和 engagements/acme-2026-q2/reports/owasp-coverage.md（覆盖率报告）。

示例 2——应用评估特定覆盖：

# .owasp-overrides.yaml — engagement-specific classifications
- skill_id: auditing-cors-policy
  owasp_category: A05:2021 — Security Misconfiguration
  reason: customer treats CORS as misconfig, not access-control
- skill_id: scanning-for-hardcoded-secrets
  detail_contains: ".env"
  owasp_category: A02:2021 — Cryptographic Failures
  reason: env-file leaks treated as crypto failure for this engagement

python3 ./scripts/map_owasp.py engagements/acme-2026-q2/ \
    --overrides engagements/acme-2026-q2/.owasp-overrides.yaml

示例 3——覆盖率审计（不写回增强）：

python3 ./scripts/map_owasp.py engagements/acme-2026-q2/ \
    --enrich-output /dev/null \
    --coverage-output /tmp/coverage.md

生成覆盖率报告而不修改发现文件。

错误处理

PATH 缺失 → CRITICAL 操作发现，退出码 1。
源文件无法解析 → HIGH 操作发现，跳过该文件。
未找到来源 → HIGH 操作发现，退出码 1。
覆盖 YAML 无法解析 → HIGH 操作发现，回退到默认规则。
增强输出路径不可写 → HIGH 操作发现，退出码 1。

资源

references/THEORY.md——OWASP Top 10 历史及 2021 年变更、CWE 到 OWASP 映射、规则表设计原理、发现确实不适配时的处理、OWASP A0X 精度权衡（宽类别与具体发现）
references/PLAYBOOK.md——cluster 1-4 技能的默认规则表、覆盖 YAML 格式、覆盖率审计解读、客户特定类别偏好、与 PCI DSS 6.5 / NIST 800-53 控制映射的集成

适用场景和限制

适用于需要将渗透测试发现结构化映射到 OWASP Top 10 的安全评估场景，尤其是报告、审计与保险合规用途。使用要求 Python 3.9+，输入为 cluster 1-4 的发现文件。该技能依赖确定性规则表，未映射的发现需人工复核。部分发现可能天然不适配单一类别。详细信息以参考文档为准；资料未提供平台的收费、价格或具体平台信息。