@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/mapping-findings-to-owasp-top10/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: mapping-findings-to-owasp-top10
+description: |
+  Annotate every pentest finding with its OWASP Top 10 (2021)
+  category by applying a deterministic rule table keyed on source
+  skill, finding category, detail keywords, and CWE identifier when
+  present. Produces an enriched findings JSONL plus a per-category
+  rollup report showing how findings distribute across A01 through
+  A10. Required for customer-facing OWASP coverage sections and
+  compliance contexts (PCI DSS 6.5, SOC2 CC7, ISO 27001 A.14.2).
+  Use when: enriching findings after cluster 1-4 scans, regenerating
+  the report with OWASP tags, producing the OWASP coverage section
+  for an exec summary, or auditing engagement OWASP coverage.
+  Threshold: unclassifiable findings emitted as INFO with UNMAPPED
+  category for operator review.
+  Trigger with: "map to OWASP", "owasp top 10 mapping",
+  "annotate owasp categories", "owasp coverage check".
+allowed-tools:
+  - Read
+  - Write
+  - Bash(python3:*)
+  - Glob
+disallowed-tools:
+  - Bash(rm:*)
+  - Bash(curl:*)
+  - Bash(wget:*)
+  - Write(.env)
+  - Edit(.env)
+version: 3.0.0-dev
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatibility: Designed for Claude Code
+tags:
+  - security
+  - reporting
+  - owasp
+  - top10
+  - pentest
+---
+
+# 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
+
+| Finding | Severity | Threshold | Affected control |
+|---|---|---|---|
+| Finding unmapped after rule application | **INFO** | No rule matched the finding | (operational) |
+| Source JSONL unparseable | **HIGH** | Standard JSONL parse error | (operational) |
+| Annotation written back successfully | **INFO** | Confirmation per source file | (informational) |
+| Coverage report generated | **INFO** | Coverage report path emitted | (informational) |
+| Engagement covers all 10 categories | **INFO** | At least one finding in each A01-A10 bucket | (positive observation) |
+| Engagement covers <5 of 10 categories | **MEDIUM** | Suggests scope may have been narrow | (informational) |
+
+## OWASP Top 10 (2021) reference
+
+| Category | Description |
+|---|---|
+| 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 |
+
+## 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
+
+```bash
+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
+
+```bash
+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
+
+```yaml
+# .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
+```
+
+```bash
+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)
+
+```bash
+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

package/skills/mapping-findings-to-owasp-top10/references/PLAYBOOK.md

@@ -0,0 +1,193 @@
+# PLAYBOOK — Mapping Rules and Workflow
+
+## Default skill → OWASP mappings (reference table)
+
+| Cluster | Skill | OWASP | Reason |
+|---|---|---|---|
+| 1 | analyzing-tls-config | A02 | Cryptographic Failures |
+| 1 | detecting-ssl-cert-issues | A02 | Cryptographic Failures |
+| 1 | auditing-cors-policy | A01 | Broken Access Control |
+| 1 | checking-http-security-headers | A05 | Security Misconfiguration |
+| 1 | probing-dangerous-http-methods | A05 | Security Misconfiguration |
+| 2 | detecting-exposed-secrets-files | A02 | Cryptographic Failures (.env, .git exposures) |
+| 2 | detecting-debug-endpoints | A05 | Misconfiguration |
+| 2 | fingerprinting-server-software | A06 | Outdated components signal |
+| 2 | detecting-directory-listing | A05 | Misconfiguration |
+| 3 | scanning-for-hardcoded-secrets | A02 | Hardcoded credentials |
+| 3 | detecting-sql-injection-patterns | A03 | Injection |
+| 3 | detecting-command-injection-patterns | A03 | Injection |
+| 3 | detecting-eval-exec-usage | A03 | Injection (code execution) |
+| 3 | detecting-insecure-deserialization | A08 | Integrity Failures |
+| 3 | detecting-weak-cryptography | A02 | Crypto failures |
+| 4 | auditing-npm-dependencies | A06 | Vulnerable Components |
+| 4 | auditing-python-dependencies | A06 | Vulnerable Components |
+| 4 | checking-license-compliance | A06 | Components hygiene |
+| 4 | tracing-transitive-vulnerabilities | A06 | Vulnerable Components |
+| 5 | confirming-pentest-authorization | A04 | Insecure Design |
+| 5 | defining-pentest-scope | A04 | Insecure Design |
+| 5 | recording-pentest-engagement | A09 | Logging / Monitoring |
+
+Cluster 5 (governance) findings aren't technical application
+vulnerabilities; the A04 / A09 mapping is for COVERAGE-REPORTING
+purposes (so engagement-governance findings show up somewhere
+in the OWASP narrative rather than being invisible).
+
+## Overrides YAML format
+
+```yaml
+# .owasp-overrides.yaml
+- 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 leaks treated as crypto failure for this customer
+
+- skill_id: tracing-transitive-vulnerabilities
+  detail_contains: "deep"
+  owasp_category: A08:2021 — Software and Data Integrity Failures
+  reason: deep-transitive vulns treated as integrity concern for this customer
+```
+
+An override applies when:
+
+- `skill_id` matches AND
+- `detail_contains` matches (if specified — substring match)
+
+The `owasp_category` must be one of the canonical strings (e.g.
+"A05:2021 — Security Misconfiguration"). The skill parses the
+leading code (`A05`) for table lookup.
+
+Add a `reason` field on every override. Reasons become part of
+the engagement archive's audit trail.
+
+## Coverage-report interpretation
+
+### "All 10 categories covered"
+
+Customer report's OWASP section can claim "the engagement evaluated
+all 10 OWASP Top 10 categories." This is the strongest possible
+coverage claim and what most customers want.
+
+### "8 of 10 categories covered"
+
+Customer report should explicitly note which categories had no
+findings AND whether each "no findings" reflects clean results
+or out-of-scope testing. Phrasing template:
+
+> The engagement covered 8 of the 10 OWASP Top 10 (2021)
+> categories. A04 (Insecure Design) and A10 (Server-Side Request
+> Forgery) had no findings within this engagement's scope.
+
+### "3 of 10 categories covered"
+
+Either a deliberately narrow scope or a rule-table coverage gap.
+Investigate before shipping the report:
+
+1. Check the unmapped findings list. Are findings falling into the
+   "no rule matched" bucket?
+2. Check the scope. Did the engagement explicitly include only
+   network testing (which would naturally cover A02 + A05 + A06)?
+3. If the narrow coverage is intentional, document it in the
+   engagement summary's scope section.
+
+## Per-customer category-emphasis patterns
+
+### PCI DSS customers
+
+PCI DSS Req 6.5 lists specific vulnerability classes that must be
+addressed. The skill's standard A0X mapping covers most of these.
+Recommend including a "PCI DSS Req 6.5 coverage" section in the
+report that cross-references A0X findings to specific Req 6.5
+items. Out of scope for this skill (separate mapping).
+
+### HIPAA customers
+
+A02 (Crypto) and A09 (Logging) get the most scrutiny. Recommend
+running A02 + A09 specifically (auditing-tls-config + checking
+for security logging + monitoring failures) regardless of
+broader scope.
+
+### SOC2 customers
+
+CC7 (System Operations) maps loosely to A06 + A09. CC8 (Change
+Management) maps to A04 + A08. The full coverage report supports
+the SOC2 audit narrative.
+
+### ISO 27001 customers
+
+Annex A.14.2 (Security in Development) maps to A04 + A08. Annex
+A.12.6 (Vulnerability Management) maps to A06. The full coverage
+report supports the ISO 27001 audit narrative.
+
+## Workflow patterns
+
+### Standalone enrichment
+
+```bash
+python3 ./scripts/map_owasp.py engagements/acme-2026-q2/
+```
+
+Enriched JSONL at `findings/all-with-owasp.jsonl`.
+Coverage report at `reports/owasp-coverage.md`.
+
+### Enrichment with overrides
+
+```bash
+python3 ./scripts/map_owasp.py engagements/acme-2026-q2/ \
+    --overrides engagements/acme-2026-q2/.owasp-overrides.yaml
+```
+
+### Coverage audit only (no enrichment)
+
+```bash
+python3 ./scripts/map_owasp.py engagements/acme-2026-q2/ \
+    --enrich-output /dev/null \
+    --coverage-output /tmp/coverage.md
+```
+
+### Re-compose vulnerability report after enrichment
+
+```bash
+# Step 1: enrich
+python3 ./scripts/map_owasp.py engagements/acme-2026-q2/
+
+# Step 2: re-compose report from enriched findings
+python3 plugins/security/penetration-tester/skills/composing-vulnerability-report/scripts/compose_report.py \
+    engagements/acme-2026-q2/ \
+    --source engagements/acme-2026-q2/findings/all-with-owasp.jsonl \
+    --report-output engagements/acme-2026-q2/reports/vulnerability-report-v2.md
+```
+
+## When to extend the rule table
+
+Add a new entry to `SKILL_TO_OWASP` when:
+
+- A new cluster 1-4 skill is added to the pack.
+- A skill's default classification proves consistently wrong in
+  practice.
+- A new CWE → OWASP mapping is needed (extend `CWE_TO_OWASP`).
+
+Add a new entry to `DETAIL_KEYWORDS` when:
+
+- An UNMAPPED-finding pattern is recognizable by detail keywords
+  that no current rule catches.
+- A detail-keyword rule is sometimes a useful fallback for
+  third-party tools whose output passes through this skill.
+
+Don't add overrides as rule-table extensions — overrides are
+engagement-specific by design. Rule-table changes are global.
+
+## Integration with executive-summary
+
+The exec-summary skill consumes the enriched findings JSONL plus
+the coverage report. The exec summary's "OWASP coverage" section
+quotes per-category counts from the coverage report and risk
+score from the unified findings.
+
+Order of operations: cluster 1-4 → this skill → exec summary.
+Optionally re-run compose-vulnerability-report between this skill
+and exec-summary so the OWASP tags appear in the main report's
+per-finding sections.

package/skills/mapping-findings-to-owasp-top10/references/THEORY.md

@@ -0,0 +1,160 @@
+# THEORY — OWASP Top 10 Mapping
+
+## What the OWASP Top 10 actually is
+
+The OWASP Top 10 is a community-curated list of the most critical
+web application security risks, updated every 3-4 years. The
+current version is the 2021 edition. The Top 10 is NOT a complete
+taxonomy of all possible vulnerabilities — it's a prioritization
+framework. Findings outside the Top 10 still matter; they just
+don't get their own A0X slot.
+
+The 2021 edition's categories (with their derivation from 2017
+predecessors):
+
+| 2021 | Notes |
+|---|---|
+| A01 Broken Access Control | Promoted from A05 (2017); broadest category, includes path traversal + IDOR |
+| A02 Cryptographic Failures | Renamed from A03 "Sensitive Data Exposure"; emphasizes the failure modes not the data |
+| A03 Injection | Demoted from A01 (2017); XSS folded in here |
+| A04 Insecure Design | NEW; threat-modeling-failure findings |
+| A05 Security Misconfiguration | Includes XML External Entities (was A04 in 2017) |
+| A06 Vulnerable and Outdated Components | Promoted from A09 (2017) |
+| A07 Identification and Authentication Failures | Renamed from A02 "Broken Authentication" |
+| A08 Software and Data Integrity Failures | NEW; supply-chain-attack-shaped |
+| A09 Security Logging and Monitoring Failures | Renamed from A10 (2017) |
+| A10 Server-Side Request Forgery | NEW as a Top 10 entry |
+
+The 2025 edition is in draft as of this skill's authorship. When
+it ships, this skill's mapping table should be reviewed against
+the new category set.
+
+## CWE → OWASP cross-walk
+
+OWASP publishes an authoritative mapping from CWE identifiers to
+OWASP categories at https://owasp.org/Top10/A0X_2021-<name>/. The
+mapping is one-to-many in both directions: a single CWE can map
+to multiple OWASP categories depending on context, and a single
+OWASP category encompasses many CWEs.
+
+This skill's `CWE_TO_OWASP` table captures the most common
+mappings deterministically. Edge cases:
+
+- CWE-200 (Information Exposure) — typically A01 but can map to
+  A05 or A09 depending on context.
+- CWE-352 (CSRF) — included in A01 in 2021 (was A08 in 2017).
+- CWE-89 (SQL Injection) — A03, no ambiguity.
+
+When a CWE has multiple plausible mappings, the skill picks the
+most common one in practice. Override via the engagement-specific
+overrides YAML for cases where the customer expects a different
+classification.
+
+## Why deterministic rules, not LLM classification
+
+It's tempting to feed each finding to an LLM and ask "which OWASP
+category fits best?" Two problems:
+
+1. **Reproducibility.** A pentest report claims to be the result
+   of a defined methodology. An LLM-classified report changes
+   slightly on every regeneration (model temperature, prompt
+   variation, training-data drift). Auditors hate this.
+
+2. **Explainability.** A finding's mapping needs a defensible
+   reason ("this is A06 because the source skill is
+   `auditing-npm-dependencies` which detects vulnerable
+   third-party components" is defensible; "the LLM said so" is
+   not).
+
+The skill uses a deterministic rule table. Rules are auditable.
+The classifier can be wrong, but it's wrong consistently — and
+the operator can extend the table to fix patterns.
+
+## Rule precedence
+
+The skill applies rules in this order:
+
+1. **Engagement-specific overrides** (from `--overrides FILE`).
+   Highest precedence; lets customers express their own
+   classification preferences.
+2. **CWE-based mapping** when the finding has a `cwe_id`.
+3. **Skill-ID default** when no CWE is present or matches.
+4. **Detail-keyword fallback** as a last-resort heuristic.
+
+Each successful classification records WHICH rule matched in the
+operational Finding. Operators can see the reasoning chain when
+debugging unexpected classifications.
+
+## Coverage interpretation
+
+The coverage report shows count per A0X category. Interpretation:
+
+| Pattern | What it usually means |
+|---|---|
+| All 10 categories have findings | Broad-coverage engagement, comprehensive scope |
+| 6-9 categories | Typical engagement; some categories not in scope |
+| 1-5 categories | Narrow scope OR rule table missed mappings |
+| 0 categories with HIGH/CRITICAL | Either remarkably clean target OR scans didn't run |
+
+The skill flags fewer-than-5 categories as MEDIUM. The operator
+should determine whether the narrow coverage is intentional (and
+document so) or a sign of incomplete testing.
+
+## When a finding genuinely doesn't fit a single category
+
+Some findings are cross-cutting:
+
+- A misconfigured database cluster (A05 Misconfiguration + A09
+  Logging + A02 Crypto-at-rest) — could legitimately appear in
+  three categories.
+- A supply-chain compromise (A06 Components + A08 Software Integrity)
+  — both apply.
+- An authentication bypass via path traversal (A07 + A01).
+
+The Top 10 doesn't tolerate multi-category findings. The convention
+is to pick the PRIMARY category (the failure mode that most
+directly causes exploitation) and accept that the finding will be
+reported under one A0X bucket. Cross-references in the report body
+can point to the secondary category.
+
+## Customer-specific category preferences
+
+Some customers care about specific A0X categories for compliance
+reasons:
+
+- **PCI DSS** customers care about A02 (Crypto) and A07 (Auth).
+- **Healthcare (HIPAA)** customers care about A02 + A09 (Logging).
+- **SOC2 CC7** customers want broad coverage across all categories.
+
+The skill's overrides YAML is the mechanism for capturing these
+preferences. An override re-classifies a finding's category for
+the specific engagement without changing the default rule table.
+
+## OWASP Top 10 vs ASVS
+
+The OWASP Application Security Verification Standard (ASVS) is a
+much more granular framework — 286 verification requirements across
+14 chapters. Some engagements demand ASVS coverage instead of (or
+in addition to) Top 10 coverage. This skill maps Top 10 only;
+ASVS mapping would be a separate skill (or extension to this one)
+because the rule table is differently shaped.
+
+## Mapping precision tradeoffs
+
+The skill optimizes for:
+
+- **Coverage** — every finding gets a mapping if at all possible.
+- **Reproducibility** — same input → same output, always.
+- **Auditability** — the rule that matched is recorded.
+- **Extensibility** — operators can add overrides without code changes.
+
+It does NOT optimize for:
+
+- **Per-finding precision** — a finding might fit two categories;
+  the skill picks one deterministically.
+- **2025-edition forward compatibility** — when OWASP 2025
+  finalizes, the table needs review.
+- **ASVS coverage** — out of scope.
+
+These tradeoffs are deliberate. The skill is a triage tool, not a
+substitute for human judgment on contested classifications.