@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/tracing-transitive-vulnerabilities/references/PLAYBOOK.md

@@ -0,0 +1,233 @@
+# PLAYBOOK — Trace-Driven Remediation
+
+## End-to-end triage flow
+
+```
+                +-------------------------+
+                | Initial audit (noisy)   |
+                +------------+------------+
+                             |
+                             v
+                +-------------------------+
+                | Trace via this skill    |
+                +------------+------------+
+                             |
+            +----------------+----------------+
+            |                |                |
+     leverage report    deep-transitive   unreachable
+            |                |                |
+            v                v                v
+       bump highest-     consider          add override
+       leverage parent   override          OR vendor+patch
+            |                |                |
+            v                v                v
+                  Re-run trace (post-fix)
+                             |
+                             v
+                  (loop until clean OR
+                   remaining findings are
+                   all overrides/vendor)
+```
+
+## SBOM generation patterns (cyclonedx, syft, anchore)
+
+The skill builds an in-memory graph. For long-term SBOM hygiene
+you want a persisted SBOM file. Tools that generate one from a
+project:
+
+### npm — `@cyclonedx/cyclonedx-npm`
+
+```bash
+npm install -g @cyclonedx/cyclonedx-npm
+cyclonedx-npm --output-file sbom.json
+```
+
+Produces CycloneDX JSON. Includes per-package license, version,
+hash, and dependency edges. Can be fed to `grype` or `trivy` for
+CVE scanning of the SBOM itself.
+
+### Python — `cyclonedx-bom`
+
+```bash
+pip install cyclonedx-bom
+cyclonedx-py environment -o sbom.json     # from active venv
+cyclonedx-py requirements requirements.txt -o sbom.json
+```
+
+### Multi-language — `syft`
+
+```bash
+syft <directory> -o cyclonedx-json=sbom.json
+```
+
+Syft auto-detects ecosystem and produces a unified SBOM across
+languages.
+
+### Vulnerability scanning the SBOM — `grype`
+
+```bash
+grype sbom:./sbom.json -o json > vulns.json
+```
+
+This skill consumes audit JSON from the per-language skills
+(`auditing-npm-dependencies` / `auditing-python-dependencies`). The
+SBOM path is parallel — both can coexist; the SBOM is more useful
+for long-term tracking, while the audit JSON is more useful for
+PR-time gating.
+
+## When to override vs vendor-patch
+
+| Decision factor | Override wins | Vendor-patch wins |
+|---|---|---|
+| Fix-version available | YES → override | n/a |
+| Maintainer accepting PRs | YES → override + upstream PR | n/a |
+| Maintainer unresponsive | n/a | YES |
+| Override produces resolution conflicts | n/a | YES |
+| Multiple direct deps converge on the vulnerable transitive | YES → single override clears all | n/a |
+| The vulnerability is in a function YOU need patched, not just upgraded | n/a | YES |
+| Maintenance is a concern (small team) | YES → override is cheap | n/a |
+| Maintenance is not a concern (security team has bandwidth) | n/a | acceptable |
+
+## Per-runtime override mechanics
+
+### npm overrides (npm 8.3+)
+
+```json
+{
+  "overrides": {
+    "lodash": "^4.17.21"
+  }
+}
+```
+
+After editing, run `npm install` to refresh the lockfile. The
+override applies to every transitive consumer.
+
+### npm overrides — nested form
+
+```json
+{
+  "overrides": {
+    "express": {
+      "qs": "^6.10.3"
+    }
+  }
+}
+```
+
+Forces `qs@^6.10.3` only when reached via `express`. Use when the
+flat override breaks unrelated consumers.
+
+### pnpm overrides
+
+```json
+{
+  "pnpm": {
+    "overrides": {
+      "lodash": "^4.17.21"
+    }
+  }
+}
+```
+
+Same semantics, different config block.
+
+### Yarn resolutions
+
+```json
+{
+  "resolutions": {
+    "lodash": "^4.17.21"
+  }
+}
+```
+
+Yarn's equivalent. Predates npm overrides; works in Yarn 1, 2, 3, 4.
+
+### Python — pin in requirements
+
+```
+boto3==1.34.0
+urllib3>=2.0.2     # transitive pin, overrides boto3's loose pin
+```
+
+Python doesn't have a first-class override; pinning the transitive
+as a direct dep is the pattern.
+
+### Python — poetry constraints
+
+```toml
+[tool.poetry.dependencies]
+urllib3 = "^2.0.2"
+```
+
+Adding the transitive as a direct dep with a constraint accomplishes
+the override.
+
+## Trace re-run cadence
+
+After applying any override or parent-bump:
+
+1. Re-run the per-language audit skill to refresh the finding list.
+2. Re-run this trace skill against the new audit output.
+3. Confirm the previously-flagged paths are gone.
+4. Repeat until the residual is overrides + vendor work only.
+
+A clean trace run (zero deep-transitive findings, zero unreachable
+findings) is the gate for merging the dependency-refresh PR.
+
+## Multi-finding direct-dep upgrade workflow
+
+When the leverage report identifies a direct dep that's the
+ancestor for ≥3 CVEs, plan the upgrade as a single PR:
+
+1. Identify the direct dep + bump target.
+2. Read its changelog from the previous-pinned to the target
+   version. Note any documented breaking changes.
+3. Run your full test suite against the bumped version (don't merge
+   on green-CI alone for a 3+ CVE bump — local validation matters).
+4. If the parent's API changed, update YOUR call sites in the same
+   PR.
+5. Commit the dep bump + call-site updates + lockfile in one PR.
+6. After merge, re-run the trace and confirm CVE clearance.
+
+## When to give up on a CVE
+
+A finding with NO fix in ANY reachable version, where the package
+has no maintainer response and no available replacement, sometimes
+just sits. Document the exception with:
+
+- Date of last upstream maintainer activity (`npm view <pkg> time`)
+- Vulnerability detail (CVE / GHSA)
+- Reachability assessment (is the vulnerable function actually called
+  in your code path?)
+- Mitigation in place (WAF rule, input sanitization upstream, etc.)
+- Re-evaluation date (typically 90 days)
+
+This is the security-register equivalent of an `# noqa` comment.
+It's not pretty, but it's honest. The skill's "unreachable" finding
+class is the surface where this kind of exception arises.
+
+## Integration with auditing-* skills
+
+This skill is intended to be run AFTER the per-language audit:
+
+```bash
+# Pipeline
+python3 .../auditing-npm-dependencies/scripts/audit_npm.py . \
+    --format json --output /tmp/npm-audit.json
+python3 .../tracing-transitive-vulnerabilities/scripts/trace_vulns.py . \
+    --audit-input /tmp/npm-audit.json --format markdown --output trace.md
+```
+
+For a polyglot project, run both per-language audits and merge:
+
+```bash
+python3 .../auditing-npm-dependencies/scripts/audit_npm.py . \
+    --format json --output /tmp/npm-audit.json
+python3 .../auditing-python-dependencies/scripts/audit_python.py . \
+    --format json --output /tmp/py-audit.json
+jq -s 'add' /tmp/npm-audit.json /tmp/py-audit.json > /tmp/all-audit.json
+python3 .../tracing-transitive-vulnerabilities/scripts/trace_vulns.py . \
+    --audit-input /tmp/all-audit.json --format markdown --output trace.md
+```

package/skills/tracing-transitive-vulnerabilities/references/THEORY.md

@@ -0,0 +1,138 @@
+# THEORY — Why Transitive Vulnerability Tracing Matters
+
+## The reachability problem
+
+A modern dependency graph has hundreds to thousands of nodes. A CVE
+attached to one of those nodes affects every transitive consumer.
+The question "can this CVE actually be exploited in my code path?"
+has three possible answers:
+
+1. **Yes, directly** — the vulnerable code is loaded at runtime and
+   reachable through normal program flow.
+2. **Maybe** — the dep is loaded but its vulnerable function is
+   only called in a configuration you don't use.
+3. **No, but it's still on disk** — the vulnerable code is installed
+   but never imported (test fixtures, lazy-loaded plugins, etc.).
+
+Most audit tools (npm audit, pip-audit) answer "is the vulnerable
+version installed?" — that's case 1+2+3 collapsed into a single
+finding. This skill doesn't solve the reachability problem fully
+(true reachability requires program analysis), but it does
+distinguish *graph reachability* — which direct deps would have to
+be touched to clear the finding.
+
+## Why deep transitive depth is risky
+
+A CVE at depth 0 (direct dep) is easy to remediate — bump the
+version pin. A CVE at depth 1 (one parent away) is also easy —
+bump that parent if it has a newer release, or pin the transitive
+dep explicitly.
+
+A CVE at depth 3+ becomes interesting:
+
+- The relationship to your code is multi-step. The vulnerable
+  function may not be reachable through any code path you use.
+- Multiple direct deps may converge on the same vulnerable
+  transitive — a bump in one direct dep doesn't necessarily clear
+  the finding because another direct dep still pulls in the
+  vulnerable version.
+- The "blast radius" of the package is hard to estimate. Deep deps
+  are often utility libraries (string parsers, date handlers,
+  serializers) whose call graph touches everything.
+
+The skill bumps deep-transitive findings to at-least HIGH severity
+to surface this. The override-or-vendor decision is more often the
+right answer at depth 3+ than at depth 1.
+
+## Graph traversal and cycle handling
+
+The skill's path tracer does a depth-first search from a target
+package back through its parents to a direct dep. Cycles can occur:
+
+- Package A depends on B, which depends on A (rare but real in npm)
+- Self-references in poorly-published packages
+- Optional peer-dep cycles where each declares the other
+
+The tracer maintains a `visiting` set during traversal and breaks
+on cycle detection. The reported depth is the shallowest path from
+a direct dep — practically what an operator can target.
+
+## SBOM standards
+
+The Software Bill of Materials concept formalizes what this skill
+builds locally. The major standards:
+
+| Standard | Maintained by | Output | Strengths |
+|---|---|---|---|
+| CycloneDX | OWASP | JSON / XML / protobuf | Vulnerability mapping built-in |
+| SPDX 3.0 | Linux Foundation | JSON-LD / RDF | License-aware; ISO/IEC 5962 standardization |
+| SWID Tags | ISO/IEC 19770-2 | XML | Enterprise asset-management focused |
+
+For a pentester's purposes, CycloneDX is the most practical because
+it natively maps SBOMs to CVE findings via `vulnerabilities` arrays.
+The skill currently builds an in-memory graph rather than emitting
+a full CycloneDX BOM; emitting CycloneDX is a planned addition.
+
+## Why this skill is graph-based, not query-based
+
+An alternative implementation would query a vulnerability database
+for each installed package. That approach has two failures:
+
+1. Network round-trip per package — slow.
+2. Stale results — the audit tool's CVE database may diverge from
+   the query API.
+
+The graph + intersect approach trusts the per-language audit tool's
+output and adds the graph-walking layer locally. The audit tool's
+authority is preserved; this skill is a triage assistant, not a
+re-implementation.
+
+## Exploit Prediction Scoring System (EPSS)
+
+CVSS measures intrinsic severity; EPSS measures real-world
+exploitation probability. A high-CVSS finding with low EPSS is
+"theoretically severe but not actively exploited." A medium-CVSS
+finding with high EPSS is "actively exploited despite a modest
+intrinsic score."
+
+The skill currently doesn't query EPSS; the per-language audit
+skills can be extended to fetch EPSS via the FIRST.org API
+(api.first.org/data/v1/epss) and pass through enrichment. Planned
+integration via the `mcp__pen-tester-cve` MCP server.
+
+## When override is safe, when it's not
+
+The skill recommends `npm overrides` / pip pin / poetry constraint
+for findings reachable via multiple direct deps. Conservative
+operators worry about overrides because they can cause runtime
+breakage. The risk profile:
+
+| Situation | Override safety |
+|---|---|
+| Patch-version override (1.0.4 → 1.0.5) | Almost always safe; SemVer guarantees compatible API |
+| Minor-version override (1.0.x → 1.1.x) | Usually safe; may introduce new APIs but shouldn't remove old |
+| Major-version override (1.x.x → 2.x.x) | RISKY; major-version changes commonly break parent's API expectations |
+| Pre-release override (1.0.4 → 2.0.0-beta) | RISKY in production; reserve for emergency CVE response |
+
+The recommendation in the skill's remediation text defaults to
+"check the parent's changelog and bump the parent if possible" —
+that's the lower-risk path. Override is the escape hatch when
+parent-bump isn't available.
+
+## Why the "highest-leverage upgrade" recommendation matters
+
+When an audit produces 20+ findings, the natural impulse is to fix
+them in arbitrary order. The leverage report inverts that: identify
+the single direct-dep bump that clears the most findings, do that
+first, re-run, repeat.
+
+This isn't novel — it's textbook gradient-descent applied to
+dependency hygiene. But because audit tools don't natively
+aggregate findings by direct-ancestor, most operators don't see the
+shape of their CVE surface and end up fixing trivial findings while
+missing the high-leverage one.
+
+The skill computes the leverage map after path tracing, emits the
+top-5 direct-dep upgrade candidates by count, and lets the operator
+pick the order. The expected next step is a follow-up trace run
+post-upgrade to confirm clearance.