mapping-findings-to-owasp-top10

Imported from jeremylongshore/tons-of-skills-marketplace (skills/.curated/mapping-findings-to-owasp-top10/SKILL.md). Install upstream with npx skills add jeremylongshore/tons-of-skills-marketplace --skill mapping-findings-to-owasp-top10. Copyright stays with the author (MIT).

Mapping Findings to OWASP Top 10

Overview

OWASP Top 10 is the canonical taxonomy of web-application risk categories. Every customer-facing pentest report has an "OWASP coverage" section because customers, auditors, and insurers expect to see findings mapped against the Top 10. Without the mapping, a long list of CVEs and misconfigurations reads as noise; with the mapping, it reads as a structured assessment.

This skill applies a deterministic rule table to annotate each finding with its OWASP category. Rules are keyed on:

1. Source skill ID (a finding from auditing-npm-dependencies is almost always A06 — Vulnerable and Outdated Components).
2. Finding category (the per-skill category tag, e.g. dependency-vulnerability, engagement-scope).
3. CWE identifier if present (CWE → OWASP is a well-trodden mapping; OWASP themselves publish the cross-walk).
4. Detail keywords as a fallback when the above don't determine a category.

Output is an enriched JSONL (each finding gets an owasp_category field) plus a coverage report showing how the engagement's findings distribute across A01-A10. UNMAPPED findings are surfaced for human review — extend the rule table or accept the finding as cross-cutting (some findings genuinely don't fit a single A0X bucket).

When the skill produces findings

OWASP Top 10 (2021) reference

Prerequisites

• Python 3.9+
• One or more cluster 1-4 findings files
• Optional .owasp-overrides.yaml for engagement-specific classification rules

Instructions

Step 1 — Identify findings sources

Default: every file under engagement/findings/*.json[l]. Override with --source FILE (repeatable).

Step 2 — Run the mapper

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

Options:

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

Step 3 — Review unmapped findings

UNMAPPED findings are surfaced as INFO. For each:

1. Check whether a CWE was present; if so, the canonical CWE → OWASP cross-walk should have caught it. Extend the rule table.
2. Check whether the finding's source skill ID is in the rule table; if not, add a skill-level default.
3. If the finding genuinely doesn't fit a single A0X bucket, accept UNMAPPED and document in the engagement notes.

Step 4 — Read the coverage report

The coverage report lists each A0X category with:

• Count of findings mapped to that category
• Severity breakdown within the category
• Pointer to specific findings

For an engagement intended as broad-coverage testing, all ten categories should have at least one entry. Categories with zero findings either reflect scope ("we didn't test for this") or clean results ("we tested and found nothing").

Examples

Example 1 — End-of-engagement enrichment

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

Produces engagements/acme-2026-q2/findings/all-with-owasp.jsonl (enriched findings) and engagements/acme-2026-q2/reports/owasp-coverage.md (coverage report).

Example 2 — Apply engagement-specific overrides

# .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

Example 3 — Coverage audit (no enrichment write-back)

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

Produces the coverage report without modifying findings files.

Output

JSON / JSONL / Markdown per lib/report.py for operational findings. PRIMARY outputs:

1. Enriched findings JSONL at --enrich-output — every finding from the sources has an owasp_category field added.
2. Coverage report markdown at --coverage-output — per- category rollup.

Each operational Finding includes:

• id — owasp::<issue>::<finding-fingerprint>
• severity — INFO mostly; HIGH for parse errors
• category — owasp-mapping
• summary — what happened to the finding
• evidence — original finding fingerprint, derived OWASP category, rule that matched

Error Handling

• PATH missing → CRITICAL operational finding, exits 1.
• Source file unparseable → HIGH op finding, skip file.
• No sources found → HIGH op finding, exits 1.
• Override YAML unparseable → HIGH op finding, falls back to default rules.
• Enriched output path not writable → HIGH op finding, exits 1.

Resources

• references/THEORY.md — OWASP Top 10 history and 2021 changes, CWE → OWASP cross-walk, rule-table design rationale, when a finding genuinely doesn't fit, OWASP A0X precision tradeoffs (broad categories vs specific findings)
• references/PLAYBOOK.md — Default rule table per cluster 1-4 skill, override YAML format, coverage-audit interpretation, customer-specific category preferences, integration with PCI DSS 6.5 / NIST 800-53 control mapping