@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/composing-vulnerability-report/scripts/compose_report.py

@@ -0,0 +1,396 @@
+#!/usr/bin/env python3
+"""composing-vulnerability-report — render cluster 1-4 findings into a deliverable.
+
+Reads JSON/JSONL findings files, deduplicates by Finding.fingerprint(),
+groups by severity, and writes a single deliverable-grade markdown
+vulnerability report. Emits operational Findings via lib/finding.py for any
+parse / structural issue encountered while composing.
+
+Usage:
+    python3 compose_report.py PATH [--source FILE]
+                                   [--report-output FILE]
+                                   [--engagement-id ID]
+                                   [--output FILE] [--format json|jsonl|markdown]
+                                   [--min-severity sev] [--include-info]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import Counter, defaultdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+# --- lib/ import -------------------------------------------------------------
+_LIB_ROOT = Path(__file__).resolve().parents[3]
+sys.path.insert(0, str(_LIB_ROOT))
+
+from lib.finding import Finding, Severity, from_json as finding_from_json  # noqa: E402
+from lib import report  # noqa: E402
+
+
+SKILL_ID = "composing-vulnerability-report"
+CATEGORY = "report-composition"
+REQUIRED_FIELDS = ("title", "severity", "target", "detail", "remediation")
+
+
+# --- Helpers ----------------------------------------------------------------
+
+
+def _f(
+    severity: Severity,
+    title: str,
+    target: str,
+    detail: str,
+    remediation: str,
+    evidence: tuple[tuple[str, Any], ...] = (),
+) -> Finding:
+    return Finding(
+        skill_id=SKILL_ID,
+        title=title,
+        severity=severity,
+        target=target,
+        detail=detail,
+        remediation=remediation,
+        evidence=evidence,
+    )
+
+
+# --- Source discovery -------------------------------------------------------
+
+
+def discover_sources(root: Path, explicit: list[str]) -> list[Path]:
+    if explicit:
+        return [Path(p).resolve() for p in explicit]
+    out: list[Path] = []
+    findings_dir = root / "findings"
+    if findings_dir.is_dir():
+        out.extend(sorted(findings_dir.glob("**/*.json")))
+        out.extend(sorted(findings_dir.glob("**/*.jsonl")))
+    return out
+
+
+def load_finding_records(path: Path) -> tuple[list[dict[str, Any]], str | None]:
+    """Load findings from a file. Returns (records, error_message_or_None)."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as e:
+        return [], f"read failed: {e}"
+    text = text.strip()
+    if not text:
+        return [], None
+    out: list[dict[str, Any]] = []
+    if path.suffix == ".jsonl" or "\n{" in text:
+        for line in text.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                out.append(json.loads(line))
+            except json.JSONDecodeError as e:
+                return out, f"jsonl line parse error: {e}"
+        return out, None
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as e:
+        return [], f"json parse error: {e}"
+    if isinstance(data, list):
+        out = [r for r in data if isinstance(r, dict)]
+    elif isinstance(data, dict) and "findings" in data:
+        out = [r for r in data["findings"] if isinstance(r, dict)]
+    elif isinstance(data, dict):
+        out = [data]
+    return out, None
+
+
+# --- Finding normalization + dedup ------------------------------------------
+
+
+def normalize_record(record: dict[str, Any]) -> tuple[Finding | None, str | None]:
+    """Convert a record dict into a Finding. Returns (finding, error_or_None)."""
+    missing = [f for f in REQUIRED_FIELDS if f not in record]
+    if missing:
+        return None, f"missing required fields: {', '.join(missing)}"
+    try:
+        return finding_from_json(record), None
+    except (KeyError, ValueError, TypeError) as e:
+        return None, f"finding parse error: {e}"
+
+
+# --- Engagement-id detection ------------------------------------------------
+
+
+def detect_engagement_id(root: Path) -> str:
+    roe = root / "roe.yaml"
+    if not roe.exists():
+        return root.name
+    try:
+        text = roe.read_text(encoding="utf-8")
+    except OSError:
+        return root.name
+    for line in text.splitlines():
+        line = line.strip()
+        if line.startswith("engagement_id:"):
+            return line.split(":", 1)[1].strip().strip('"').strip("'")
+    return root.name
+
+
+# --- Report rendering -------------------------------------------------------
+
+
+def render_summary_table(
+    by_severity: dict[Severity, list[Finding]],
+) -> str:
+    lines = ["| Severity | Count |", "|---|---|"]
+    for sev in (Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW, Severity.INFO):
+        count = len(by_severity.get(sev, []))
+        lines.append(f"| **{sev.value.upper()}** | {count} |")
+    return "\n".join(lines)
+
+
+def render_finding_section(f: Finding) -> str:
+    anchor = f.fingerprint()
+    refs = "\n".join(f"- {r}" for r in f.references) if f.references else "(none)"
+    evidence_lines = "\n".join(f"- **{k}**: `{v}`" for k, v in f.evidence) if f.evidence else "(none)"
+    sev = f.severity.value.upper()
+    cvss = f"\n- **CVSS v3.1:** {f.cvss_score:.1f}" if f.cvss_score else ""
+    cve = f"\n- **CVE:** {f.cve_id}" if f.cve_id else ""
+    cwe = f"\n- **CWE:** {f.cwe_id}" if f.cwe_id else ""
+    owasp = f"\n- **OWASP:** {f.owasp_category}" if f.owasp_category else ""
+
+    return f"""### {f.title}
+<a id="finding-{anchor}"></a>
+
+- **Severity:** {sev}
+- **Affected target:** `{f.target}`
+- **Source skill:** `{f.skill_id}`{cvss}{cve}{cwe}{owasp}
+
+#### Detail
+
+{f.detail}
+
+#### Remediation
+
+{f.remediation}
+
+#### Evidence
+
+{evidence_lines}
+
+#### References
+
+{refs}
+
+---
+"""
+
+
+def render_report(
+    findings: list[Finding],
+    engagement_id: str,
+    source_files: list[Path],
+    include_info: bool,
+) -> str:
+    by_severity: dict[Severity, list[Finding]] = defaultdict(list)
+    for f in findings:
+        if not include_info and f.severity == Severity.INFO:
+            continue
+        by_severity[f.severity].append(f)
+
+    now = datetime.now(timezone.utc).isoformat()
+
+    header = f"""# Vulnerability Report — {engagement_id}
+
+> Generated by `{SKILL_ID}` at {now}.
+> Source files: {", ".join(str(s.name) for s in source_files) or "(none)"}.
+
+## Summary
+
+{render_summary_table(by_severity)}
+
+"""
+
+    sections: list[str] = []
+    for sev in (Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW, Severity.INFO):
+        bucket = by_severity.get(sev, [])
+        if not bucket:
+            continue
+        if sev == Severity.INFO and not include_info:
+            continue
+        sections.append(f"## {sev.value.upper()} ({len(bucket)})\n")
+        # Stable sort: by skill_id then title
+        for f in sorted(bucket, key=lambda x: (x.skill_id, x.title)):
+            sections.append(render_finding_section(f))
+    return header + "\n".join(sections)
+
+
+# --- CLI ---------------------------------------------------------------------
+
+
+def _build_arg_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    p.add_argument("path", help="Engagement directory")
+    p.add_argument("--source", action="append", default=[], help="Findings file (repeatable)")
+    p.add_argument("--report-output", default=None)
+    p.add_argument("--engagement-id", default=None)
+    p.add_argument("--output", default=None)
+    p.add_argument("--format", default="markdown", choices=["json", "jsonl", "markdown"])
+    p.add_argument(
+        "--min-severity",
+        default="info",
+        choices=["info", "low", "medium", "high", "critical"],
+    )
+    p.add_argument("--include-info", action="store_true")
+    return p
+
+
+def _filter_min_severity_for_report(findings: list[Finding], min_sev: str) -> list[Finding]:
+    floor = Severity(min_sev).numeric
+    return [f for f in findings if f.severity.numeric >= floor]
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_arg_parser().parse_args(argv)
+    root = Path(args.path).resolve()
+    if not root.exists():
+        f = _f(
+            Severity.CRITICAL,
+            f"engagement path missing: {root}",
+            str(root),
+            f"PATH `{root}` does not exist; cannot compose report.",
+            "Verify the engagement directory and re-run.",
+        )
+        report.emit([f], args.output, args.format, scan_target=str(root))
+        return 1
+
+    sources = discover_sources(root, args.source)
+    if not sources:
+        f = _f(
+            Severity.HIGH,
+            "no findings sources",
+            str(root),
+            f"No JSON or JSONL findings files were found under `{root}`.",
+            "Run at least one cluster 1-4 scan skill to produce findings, or pass explicit --source paths.",
+        )
+        report.emit([f], args.output, args.format, scan_target=str(root))
+        return 1
+
+    op_findings: list[Finding] = []
+    all_findings: list[Finding] = []
+    fp_counts: Counter[str] = Counter()
+
+    for src in sources:
+        records, err = load_finding_records(src)
+        if err:
+            op_findings.append(
+                _f(
+                    Severity.HIGH,
+                    f"source unparseable: {src.name}",
+                    str(src),
+                    err,
+                    "Fix the source file or exclude it via explicit --source list.",
+                )
+            )
+            continue
+        if not records:
+            op_findings.append(
+                _f(
+                    Severity.INFO,
+                    f"source empty: {src.name}",
+                    str(src),
+                    "Source file contained no records.",
+                    "Skipped.",
+                )
+            )
+            continue
+        for rec in records:
+            f, ferr = normalize_record(rec)
+            if f is None:
+                op_findings.append(
+                    _f(
+                        Severity.HIGH,
+                        f"record dropped from {src.name}",
+                        str(src),
+                        ferr or "unknown normalization error",
+                        "Fix the record's structure; re-run.",
+                    )
+                )
+                continue
+            fp = f.fingerprint()
+            fp_counts[fp] += 1
+            if fp_counts[fp] == 1:
+                all_findings.append(f)
+
+    if fp_counts:
+        dup_count = sum(1 for c in fp_counts.values() if c > 1)
+        if dup_count:
+            op_findings.append(
+                _f(
+                    Severity.INFO,
+                    f"deduplicated {dup_count} duplicate fingerprint(s)",
+                    str(root),
+                    f"{dup_count} unique findings appeared in more than one source; each was included exactly once.",
+                    "No action required.",
+                    evidence=(("unique_findings", len(fp_counts)), ("duplicates_collapsed", dup_count)),
+                )
+            )
+
+    if not all_findings:
+        op_findings.append(
+            _f(
+                Severity.HIGH,
+                "no findings to report",
+                str(root),
+                "All sources were empty, malformed, or contained only records missing required fields.",
+                "Resolve source issues and re-run.",
+            )
+        )
+
+    engagement_id = args.engagement_id or detect_engagement_id(root)
+    filtered_for_report = _filter_min_severity_for_report(all_findings, args.min_severity)
+    report_md = render_report(filtered_for_report, engagement_id, sources, args.include_info)
+
+    report_path = (
+        Path(args.report_output).resolve() if args.report_output else root / "reports" / "vulnerability-report.md"
+    )
+    try:
+        report_path.parent.mkdir(parents=True, exist_ok=True)
+        report_path.write_text(report_md, encoding="utf-8")
+        op_findings.append(
+            _f(
+                Severity.INFO,
+                f"vulnerability report written: {report_path.name}",
+                str(report_path),
+                f"Report contains {len(filtered_for_report)} findings across "
+                f"{sum(1 for f in filtered_for_report if f.severity == Severity.CRITICAL)} critical, "
+                f"{sum(1 for f in filtered_for_report if f.severity == Severity.HIGH)} high, "
+                f"{sum(1 for f in filtered_for_report if f.severity == Severity.MEDIUM)} medium, "
+                f"{sum(1 for f in filtered_for_report if f.severity == Severity.LOW)} low.",
+                "Hand off to customer per the engagement closeout protocol.",
+                evidence=(
+                    ("report_path", str(report_path)),
+                    ("finding_count", len(filtered_for_report)),
+                    ("source_count", len(sources)),
+                ),
+            )
+        )
+    except OSError as e:
+        op_findings.append(
+            _f(
+                Severity.HIGH,
+                "report write failed",
+                str(report_path),
+                f"OSError: {e}",
+                "Resolve permissions/path; re-run.",
+            )
+        )
+
+    report.emit(op_findings, args.output, args.format, scan_target=str(root))
+    return report.exit_code(op_findings)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/confirming-pentest-authorization/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: confirming-pentest-authorization
+description: |
+  Verify that a penetration test has explicit, written, signed
+  authorization before any scanning begins. Reads a Rules-of-
+  Engagement (ROE) attestation file, validates required fields
+  (authorizer, in-scope targets, time window, emergency contact,
+  signature), checks the signer against an allowlist, and emits a
+  CRITICAL finding if anything is missing. Designed as the first
+  skill the orchestrator routes to.
+  Use when: starting a new engagement, after a scope change, or
+  before any cluster 1-4 scan skill runs.
+  Threshold: any missing or unsigned ROE field; any time-window
+  expiry; any in-scope target outside the authorized list.
+  Trigger with: "confirm authorization", "verify ROE", "check
+  pentest authz", "pre-flight authorization".
+allowed-tools:
+  - Read
+  - Bash(python3:*)
+  - Glob
+disallowed-tools:
+  - Bash(rm:*)
+  - Bash(curl:*)
+  - Bash(wget:*)
+  - Bash(nmap:*)
+  - Bash(nikto:*)
+  - Bash(sqlmap:*)
+  - Write(.env)
+  - Edit(.env)
+version: 3.0.0-dev
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+license: MIT
+compatibility: Designed for Claude Code
+tags:
+  - security
+  - engagement-governance
+  - authorization
+  - roe
+  - pentest
+---
+
+# Confirming Pentest Authorization
+
+## Overview
+
+Penetration testing is computer access. Without explicit
+authorization from the owner of the system under test, that
+access is a crime — Computer Fraud and Abuse Act in the US,
+Computer Misuse Act in the UK, equivalent laws everywhere
+else. The line between an authorized pentester and an
+unauthorized attacker is one signature on one document.
+
+The penetration-tester pack's other skills (TLS analysis, CORS
+audit, dependency CVE scan, etc.) all assume that line has been
+crossed correctly. This skill is the first gate the orchestrator
+routes to. It refuses to declare an engagement authorized until
+a Rules of Engagement (ROE) attestation file exists, is signed,
+and contains the fields any real-world legal review will look for.
+
+This is not paranoia or paperwork theater. Engagements DO go
+sideways: scope creeps mid-test, a tester probes an out-of-scope
+adjacent system, an SOC team escalates a "real" attack to legal,
+and the question "show us the ROE" comes up. If the ROE is in
+order, the answer is "here it is." If not, the conversation gets
+expensive fast.
+
+## When the skill produces findings
+
+| Finding | Severity | Threshold | Affected control |
+|---|---|---|---|
+| ROE file missing | **CRITICAL** | No attestation file at the expected path | (legal) |
+| Required field missing | **CRITICAL** | authorizer, in_scope_targets, time_window, emergency_contact, or signature absent | (legal) |
+| Signature missing | **CRITICAL** | No signature_block in ROE | (legal) |
+| Signer not in allowlist | **CRITICAL** | signer email/key id not in `.allowed-authorizers` | (legal) |
+| Time window expired | **HIGH** | current time outside `time_window.start` / `time_window.end` | (legal) |
+| Time window not yet active | **HIGH** | current time before `time_window.start` | (legal) |
+| In-scope target list empty | **HIGH** | `in_scope_targets` field present but empty | (legal) |
+| Out-of-scope override (manual flag) | **MEDIUM** | tester requests a target not in the in-scope list | (legal) |
+| Stale ROE (>30 days from sign date) | **MEDIUM** | last_signed_at older than 30 days; suggests refresh | (operational) |
+| ROE present + signed + in window | **INFO** | All gates pass; engagement is authorized | (positive confirmation) |
+
+## Prerequisites
+
+- Python 3.9+
+- ROE attestation file at `./roe.yaml` (or pass `--roe FILE`).
+- Optional `.allowed-authorizers` file listing email addresses or
+  GPG key fingerprints permitted to sign ROEs.
+
+## ROE attestation file schema
+
+```yaml
+engagement_id: ACME-2026-Q2-PENTEST-001
+authorizer:
+  name: Jane Doe
+  email: jane.doe@acme.example
+  role: CISO
+  organization: ACME Corp
+in_scope_targets:
+  - host: app.acme.example
+    notes: production web app, full-stack pentest authorized
+  - host: api.acme.example
+  - cidr: 10.50.0.0/16
+    notes: internal corporate range
+out_of_scope_targets:
+  - host: payments.acme.example
+    reason: PCI scope, separate authz required
+  - cidr: 10.99.0.0/16
+    reason: production database tier, separate authz required
+time_window:
+  start: 2026-06-01T00:00:00Z
+  end: 2026-06-30T23:59:59Z
+emergency_contact:
+  name: SOC On-Call
+  phone: "+1-555-555-5555"
+  email: soc@acme.example
+rules:
+  - No exploitation of confirmed findings without written prompt approval
+  - No password cracking against production accounts
+  - All testing pauses on declared business-hours blackouts
+signature_block:
+  signer: jane.doe@acme.example
+  signed_at: 2026-05-30T14:22:00Z
+  signature: |
+    -----BEGIN PGP SIGNATURE-----
+    ...
+    -----END PGP SIGNATURE-----
+```
+
+## Instructions
+
+### Step 1 — Locate the ROE
+
+The skill looks for `./roe.yaml` by default. Override with
+`--roe FILE`. The ROE file should live with the engagement
+artifacts, NOT in the repo under test — typical layout is
+`engagements/<client>-<date>/roe.yaml`.
+
+### Step 2 — Run the verification
+
+```bash
+python3 ./scripts/check_authorization.py --roe engagements/acme-2026-q2/roe.yaml
+```
+
+Options:
+
+```
+Usage: check_authorization.py [OPTIONS]
+
+Options:
+  --roe FILE              Path to ROE attestation YAML (default: ./roe.yaml)
+  --allowed FILE          Path to allowed-authorizers list (default: .allowed-authorizers)
+  --check-target HOST     Verify HOST is in the in-scope list (repeatable)
+  --output FILE           Write findings to FILE
+  --format FMT            json | jsonl | markdown (default: markdown)
+  --min-severity SEV      Default info
+```
+
+### Step 3 — Interpret findings
+
+CRITICAL = engagement is NOT authorized. Halt all testing
+immediately. Resolve the missing requirement before any further
+skill runs.
+
+HIGH = the engagement was authorized at some point but the
+current state is out-of-window. Either extend the time window
+with a new signature or wait.
+
+MEDIUM = operational concerns that warrant attention but don't
+block testing. A stale ROE should be refreshed; a manual
+out-of-scope target request needs explicit additional authz.
+
+INFO = positive confirmation that the engagement is authorized.
+
+### Step 4 — Save the result
+
+The skill's output IS the authorization record. Save the markdown
+report alongside the ROE itself; it becomes part of the engagement
+evidence chain (see `recording-pentest-engagement` for the
+storage pattern).
+
+## Examples
+
+### Example 1 — Pre-flight check before any scan
+
+```bash
+python3 ./scripts/check_authorization.py --roe engagements/acme-2026-q2/roe.yaml --format markdown
+# If exit code != 0, halt testing.
+```
+
+### Example 2 — Confirm a specific target is in-scope before probing
+
+```bash
+python3 ./scripts/check_authorization.py \
+    --roe engagements/acme-2026-q2/roe.yaml \
+    --check-target app.acme.example \
+    --check-target api.acme.example
+```
+
+The skill returns an explicit INFO Finding per target if all
+checks pass, and a HIGH/CRITICAL Finding per target if any are
+out-of-scope.
+
+### Example 3 — Generate authorization evidence for the audit trail
+
+```bash
+python3 ./scripts/check_authorization.py --roe engagements/acme-2026-q2/roe.yaml \
+    --format json \
+    --output engagements/acme-2026-q2/evidence/authz-check-$(date +%Y%m%d).json
+```
+
+## Output
+
+JSON / JSONL / Markdown per `lib/report.py`. Exit codes: 0 clean,
+1 high/critical (engagement NOT authorized), 2 error.
+
+Each Finding includes:
+
+- `id` — `authz::<field>` or `authz::target::<target>`
+- `severity` — CRITICAL / HIGH / MEDIUM / INFO
+- `category` — `engagement-authorization`
+- `summary` — what's missing or wrong
+- `evidence` — engagement_id, authorizer email, time window, target
+
+## Error Handling
+
+- **ROE file not found** → emits a CRITICAL finding and exits 1.
+- **Unparseable YAML** → emits a CRITICAL finding with the parser
+  error and exits 2.
+- **Allowed-authorizers file missing** → emits an INFO finding
+  (allowlist is recommended but not required) and proceeds with
+  field-level verification only.
+- **Signature block present but unparseable** → emits a CRITICAL
+  finding flagging the issue; does NOT attempt to verify
+  cryptographically (separate `gpg --verify` step recommended for
+  signature validation; this skill validates the structural
+  presence and signer-identity claim).
+
+## Resources
+
+- `references/THEORY.md` — Why pentest authorization is a legal
+  primitive (CFAA, CMA, equivalent statutes), ROE structure
+  history (OSSTMM / PTES origins), signature options
+  (PGP / S/MIME / DocuSign), scope-creep failure modes
+- `references/PLAYBOOK.md` — ROE templates per engagement type
+  (external pentest, internal pentest, red team, purple team),
+  authorization escalation flow, time-window extension procedures,
+  emergency-stop protocol