@intentsolutionsio/penetration-tester 2.0.0 → 3.0.4

package/skills/probing-dangerous-http-methods/scripts/probe_methods.py

@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+"""HTTP method probe — flags methods that shouldn't be enabled.
+
+Companion to skill `probing-dangerous-http-methods`. Sends each
+canonical "dangerous" method against the target and grades the response.
+
+Methods probed:
+    TRACE     — XST attack vector (RFC 7231 §4.3.8)
+    PUT       — unrestricted upload (CWE-434)
+    DELETE    — unauthorized resource removal
+    CONNECT   — proxy abuse (CWE-441)
+    DEBUG     — legacy IIS/dev-server diagnostic
+    PROPFIND  — WebDAV directory listing (RFC 4918)
+    MKCOL     — WebDAV directory creation
+    COPY      — WebDAV file copy
+    MOVE      — WebDAV file move
+    OPTIONS   — enumerate Allow header (informational, can disclose)
+
+References:
+    RFC 7231 §4.3 — HTTP method semantics
+    RFC 4918 — WebDAV
+    OWASP WSTG-CONF-06 — Test HTTP Methods
+    CWE-441 Unintended Proxy or Intermediary
+    CWE-538 File and Directory Information Exposure
+    CWE-693 Protection Mechanism Failure (XST)
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+_PLUGIN_ROOT = Path(__file__).resolve().parents[3]
+if str(_PLUGIN_ROOT) not in sys.path:
+    sys.path.insert(0, str(_PLUGIN_ROOT))
+
+from lib.authz_check import require_authorization  # noqa: E402
+from lib.finding import Finding, Severity  # noqa: E402
+from lib.http_client import make_session  # noqa: E402
+from lib.report import emit, exit_code  # noqa: E402
+
+SKILL_ID = "probing-dangerous-http-methods"
+
+# Probe set — (method, expected_failure_codes, severity_if_succeeds, finding_template)
+DANGEROUS_METHODS = [
+    ("TRACE", {405, 403, 404, 400, 501}, Severity.HIGH, "TRACE method enabled (XST attack vector)"),
+    ("CONNECT", {405, 403, 400, 501, 502}, Severity.CRITICAL, "CONNECT method enabled (proxy abuse)"),
+    ("DEBUG", {405, 403, 404, 501}, Severity.HIGH, "DEBUG method enabled (legacy diagnostic)"),
+    ("PROPFIND", {405, 403, 404, 501}, Severity.HIGH, "WebDAV PROPFIND enabled"),
+    ("MKCOL", {405, 403, 404, 501}, Severity.HIGH, "WebDAV MKCOL enabled"),
+    ("COPY", {405, 403, 404, 501}, Severity.HIGH, "WebDAV COPY enabled"),
+    ("MOVE", {405, 403, 404, 501}, Severity.HIGH, "WebDAV MOVE enabled"),
+]
+
+# These are only "dangerous" outside API endpoints
+API_DEPENDENT_METHODS = [
+    ("PUT", {405, 403, 404, 401}, Severity.HIGH, "PUT method enabled outside API path"),
+    ("DELETE", {405, 403, 404, 401}, Severity.HIGH, "DELETE method enabled outside API path"),
+]
+
+
+def _probe_method(sess, method: str, url: str, timeout: float):
+    try:
+        # Use sess.request to handle non-standard methods (PROPFIND, MKCOL, etc.)
+        resp = sess.request(method, url, timeout=timeout, allow_redirects=False)
+        return resp
+    except Exception:
+        return None
+
+
+def _grade_response(
+    method: str, resp, expected_fail: set, severity: Severity, title: str, target: str, is_xst: bool = False
+) -> list[Finding]:
+    if resp is None:
+        return []
+    if resp.status_code in expected_fail:
+        return []  # Method correctly blocked
+    if resp.status_code >= 500:
+        return [
+            Finding(
+                skill_id=SKILL_ID,
+                title=f"{method} returns {resp.status_code} (error handling concern)",
+                severity=Severity.INFO,
+                target=target,
+                detail=(
+                    f"The {method} method returned {resp.status_code}. While "
+                    "blocking is the intended behavior, a 500 suggests the server "
+                    "tried to handle the method and crashed — better to return "
+                    "405 cleanly."
+                ),
+                remediation=f"Configure the server to return 405 Method Not Allowed for {method}.",
+            )
+        ]
+    # Status 2xx, 3xx, or 405-like — the method was handled successfully or
+    # at least not cleanly rejected. This is the finding.
+    detail = (
+        f"The {method} method returned status {resp.status_code}. "
+        f"This method should be rejected with 405 Method Not Allowed."
+    )
+    if is_xst:
+        # Check if the response body echoes the request — confirms XST
+        if "TRACE / HTTP" in (resp.text or "") or method.encode() in (resp.content or b""):
+            detail += (
+                " Response body echoes the request, confirming XST viability. "
+                "An attacker who can execute JavaScript on the origin can "
+                "use TRACE-via-XHR to read HttpOnly cookies."
+            )
+
+    return [
+        Finding(
+            skill_id=SKILL_ID,
+            title=title,
+            severity=severity,
+            target=target,
+            detail=detail,
+            remediation=_remediation_for(method),
+            cwe_id=_cwe_for(method),
+            owasp_category="A05:2021",
+            evidence=(("status_code", resp.status_code), ("response_len", len(resp.content or b""))),
+        )
+    ]
+
+
+def _remediation_for(method: str) -> str:
+    base = {
+        "TRACE": (
+            "Disable TRACE explicitly. nginx: `if ($request_method = TRACE) "
+            "{ return 405; }`. Apache: `TraceEnable Off`. "
+            "Load balancers (ALB/Cloudflare): block at the LB level."
+        ),
+        "CONNECT": (
+            "Disable CONNECT. nginx and Apache reject by default; if you see "
+            "this enabled, you have a misconfigured proxy. Audit your reverse "
+            "proxy rules for `proxy_method` or `ProxyRequests On`."
+        ),
+        "DEBUG": (
+            "Legacy IIS / dev-server method. Disable in production. "
+            "IIS: remove DEBUG verb from handler mappings. Express dev "
+            "middleware: ensure NODE_ENV=production."
+        ),
+        "PUT": (
+            "If this endpoint shouldn't accept PUT, return 405. nginx: "
+            "`limit_except GET POST { deny all; }`. Express: ensure no "
+            "PUT route handler is registered."
+        ),
+        "DELETE": (
+            "If this endpoint shouldn't accept DELETE, return 405. Same "
+            "pattern as PUT above. If DELETE should be available, ensure "
+            "authentication + authorization are wired."
+        ),
+        "PROPFIND": "Disable WebDAV. nginx: `dav_methods off;`. Apache: `<Limit PROPFIND>Require all denied</Limit>`.",
+        "MKCOL": "Disable WebDAV — see PROPFIND remediation.",
+        "COPY": "Disable WebDAV — see PROPFIND remediation.",
+        "MOVE": "Disable WebDAV — see PROPFIND remediation.",
+    }
+    return base.get(method, f"Disable {method} method at the server level.")
+
+
+def _cwe_for(method: str) -> str:
+    mapping = {
+        "TRACE": "CWE-693",
+        "CONNECT": "CWE-441",
+        "DEBUG": "CWE-489",
+        "PUT": "CWE-434",
+        "DELETE": "CWE-285",
+        "PROPFIND": "CWE-538",
+        "MKCOL": "CWE-538",
+        "COPY": "CWE-538",
+        "MOVE": "CWE-538",
+    }
+    return mapping.get(method, "CWE-200")
+
+
+def _check_options(sess, url: str, timeout: float, target: str) -> list[Finding]:
+    try:
+        resp = sess.options(url, timeout=timeout, allow_redirects=False)
+    except Exception:
+        return []
+    if resp is None:
+        return []
+    allow = resp.headers.get("Allow", "")
+    if not allow:
+        return []
+    if "*" in allow:
+        return [
+            Finding(
+                skill_id=SKILL_ID,
+                title="OPTIONS Allow header is wildcard",
+                severity=Severity.LOW,
+                target=target,
+                detail="Server advertises Allow:* — information disclosure.",
+                remediation="Configure server to return explicit allowed-method list.",
+                cwe_id="CWE-200",
+            )
+        ]
+    methods = [m.strip().upper() for m in allow.split(",")]
+    unused = [m for m in methods if m in {"DEBUG", "TRACE", "PROPFIND", "MKCOL", "COPY", "MOVE", "CONNECT"}]
+    if unused:
+        return [
+            Finding(
+                skill_id=SKILL_ID,
+                title=f"OPTIONS Allow header discloses unused methods: {', '.join(unused)}",
+                severity=Severity.LOW,
+                target=target,
+                detail=(
+                    "The Allow header lists methods that are typically not used "
+                    "in a modern web app. Either disable them or remove from "
+                    "the Allow advertisement."
+                ),
+                remediation="See findings on individual methods for remediation steps.",
+                cwe_id="CWE-200",
+            )
+        ]
+    return []
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="HTTP method probe")
+    parser.add_argument("url")
+    parser.add_argument("--authorized", action="store_true")
+    parser.add_argument("--output", default=None)
+    parser.add_argument("--format", choices=("json", "jsonl", "markdown"), default="markdown")
+    parser.add_argument("--min-severity", choices=("critical", "high", "medium", "low", "info"), default="info")
+    parser.add_argument("--timeout", type=float, default=10.0)
+    parser.add_argument("--is-api", action="store_true", help="Target is an API endpoint (PUT/DELETE are expected)")
+    args = parser.parse_args(argv)
+
+    require_authorization(args.url, args.authorized)
+
+    sess = make_session(timeout=args.timeout)
+    target = args.url
+    findings: list[Finding] = []
+
+    method_set = list(DANGEROUS_METHODS)
+    if not args.is_api:
+        method_set.extend(API_DEPENDENT_METHODS)
+
+    for method, expected_fail, sev, title in method_set:
+        resp = _probe_method(sess, method, args.url, args.timeout)
+        findings.extend(
+            _grade_response(
+                method,
+                resp,
+                expected_fail,
+                sev,
+                title,
+                target,
+                is_xst=(method == "TRACE"),
+            )
+        )
+
+    findings.extend(_check_options(sess, args.url, args.timeout, target))
+
+    floor = Severity(args.min_severity)
+    findings = [f for f in findings if f.severity.numeric >= floor.numeric]
+
+    emit(findings, args.output, args.format, target)
+    return exit_code(findings)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/recording-pentest-engagement/SKILL.md

@@ -0,0 +1,253 @@
+---
+name: recording-pentest-engagement
+description: |
+  Package an engagement's findings, scan outputs, evidence, and
+  signed ROE into a timestamped archive with a SHA-256 manifest
+  covering every file. Establishes chain of custody so legal
+  counsel, internal audit, or an outside SOC can verify the archive
+  hasn't been modified after closeout. Optionally signs the
+  manifest with GPG for cryptographic attestation.
+  Use when: closing an engagement, snapshotting evidence after
+  each scan day, before handing artifacts to customer, or after
+  an emergency-stop event.
+  Threshold: file in tree without a manifest entry, hash mismatch,
+  out-of-tree path referenced in findings, unsigned manifest when
+  signing was requested.
+  Trigger with: "record engagement", "archive evidence", "create
+  chain of custody", "package pentest artifacts".
+allowed-tools:
+  - Read
+  - Bash(python3:*)
+  - Bash(tar:*)
+  - Bash(gpg:*)
+  - 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
+  - engagement-governance
+  - evidence
+  - chain-of-custody
+  - pentest
+---
+
+# Recording Pentest Engagement
+
+## Overview
+
+A penetration test produces a lot of artifacts: scan outputs in
+multiple formats, screenshots showing the state of vulnerable
+pages, raw tool logs (nmap, Burp, custom scripts), the ROE and any
+amendments, exec-summary docs, and the findings themselves. Six
+months after the engagement closes, a question arises — sometimes
+benign ("can you remind me what we found?"), sometimes adversarial
+("the customer claims we accessed an out-of-scope system; show us
+the logs"). The answer needs to be: "yes, here's the archive, and
+here's cryptographic proof it hasn't been touched since the
+engagement closed."
+
+This skill packages the engagement directory into a single
+timestamped archive with a SHA-256 manifest covering every file.
+Optionally signs the manifest with GPG. The result is a portable,
+self-verifying record of what the engagement produced.
+
+The skill also surfaces inconsistencies that would weaken the
+chain-of-custody claim: out-of-tree paths referenced in findings
+(meaning the finding refers to a file not actually in the archive),
+files in the directory not listed in the manifest, manifest
+entries whose hashes don't match. These are HIGH findings — they
+mean the archive is incomplete or has been modified after the
+fact, neither of which is acceptable for evidence purposes.
+
+## When the skill produces findings
+
+| Finding | Severity | Threshold | Affected control |
+|---|---|---|---|
+| File in tree not in manifest | **HIGH** | Found during walk; manifest entry missing | (evidence integrity) |
+| Manifest entry hash mismatch | **CRITICAL** | Computed SHA-256 differs from manifest | (evidence integrity) |
+| Manifest entry without file | **HIGH** | Manifest lists a path that doesn't exist | (evidence integrity) |
+| Findings reference out-of-tree path | **MEDIUM** | A finding's `evidence` field points to a file not in the archive | (evidence completeness) |
+| Symlink in tree | **MEDIUM** | Symlinks break archive portability and integrity | (evidence integrity) |
+| Empty file in tree | **INFO** | 0-byte file; possibly an export error | (operational) |
+| Archive package complete | **INFO** | All checks pass | (positive confirmation) |
+| Manifest signed | **INFO** | GPG signature present and valid form | (positive confirmation) |
+
+## Prerequisites
+
+- Python 3.9+
+- An engagement directory laid out as recommended (see structure
+  below)
+- Optional GPG installed for manifest signing
+
+## Recommended engagement directory structure
+
+```
+engagements/acme-2026-q2/
+├── roe.yaml
+├── roe.amendments/
+│   └── amendment-001-20260615.yaml
+├── scope/
+│   ├── allowed-ips.txt
+│   └── normalized-targets.json
+├── findings/
+│   ├── cluster1-tls-2026-06-05.json
+│   ├── cluster1-headers-2026-06-05.json
+│   ├── cluster3-secrets-2026-06-07.json
+│   └── ...
+├── evidence/
+│   ├── screenshots/
+│   ├── tool-logs/
+│   └── raw-scan-output/
+├── reports/
+│   ├── vulnerability-report.md
+│   ├── owasp-mapping.json
+│   └── executive-summary.md
+└── manifest.sha256        # produced by this skill
+```
+
+## Instructions
+
+### Step 1 — Identify the engagement directory
+
+```bash
+python3 ./scripts/record_engagement.py engagements/acme-2026-q2/
+```
+
+The skill walks the directory recursively, builds a SHA-256
+manifest, and produces a chain-of-custody report.
+
+### Step 2 — Run the packager
+
+Options:
+
+```
+Usage: record_engagement.py PATH [OPTIONS]
+
+Options:
+  --output FILE              Findings output
+  --format FMT               json | jsonl | markdown (default: markdown)
+  --min-severity SEV         default info
+  --manifest FILE            Manifest output path (default: PATH/manifest.sha256)
+  --tar FILE                 Also create a .tar.gz archive at this path
+  --sign                     Sign the manifest with GPG (uses default identity)
+  --signer KEY               GPG key ID to sign with
+  --exclude GLOB             Skip files matching glob (repeatable)
+```
+
+### Step 3 — Verify the manifest
+
+The skill emits a SHA-256 manifest in standard `sha256sum` format
+(one line per file: hash + two-space + path). The manifest is
+verifiable independent of the skill:
+
+```bash
+sha256sum -c engagements/acme-2026-q2/manifest.sha256
+```
+
+Anyone with access to the archive can run this check; if the
+output is "all OK," the archive is intact.
+
+### Step 4 — Sign the manifest (optional)
+
+```bash
+python3 ./scripts/record_engagement.py engagements/acme-2026-q2/ --sign
+```
+
+The skill shells out to `gpg --detach-sign` against the manifest,
+producing `manifest.sha256.asc`. Later verification:
+
+```bash
+gpg --verify manifest.sha256.asc manifest.sha256
+sha256sum -c manifest.sha256
+```
+
+Both checks together: the manifest's contents match the archive,
+AND the manifest itself is signed by an identifiable party.
+
+### Step 5 — Create the portable archive (optional)
+
+```bash
+python3 ./scripts/record_engagement.py engagements/acme-2026-q2/ \
+    --tar engagements/archives/acme-2026-q2.tar.gz
+```
+
+The tarball contains the engagement directory + manifest +
+signature. Hand the tarball to legal / archive / customer.
+
+## Examples
+
+### Example 1 — End-of-engagement closeout
+
+```bash
+python3 ./scripts/record_engagement.py engagements/acme-2026-q2/ \
+    --sign \
+    --tar engagements/archives/acme-2026-q2.tar.gz \
+    --output engagements/acme-2026-q2/chain-of-custody.md
+```
+
+### Example 2 — Daily snapshot during a long engagement
+
+```bash
+DATE=$(date +%Y%m%d)
+python3 ./scripts/record_engagement.py engagements/acme-2026-q2/ \
+    --manifest engagements/acme-2026-q2/manifest-$DATE.sha256 \
+    --output engagements/acme-2026-q2/snapshot-$DATE.md
+```
+
+Daily snapshots build a time-series of the engagement's state
+which can be useful in incident-investigation contexts.
+
+### Example 3 — Pre-handoff integrity check
+
+```bash
+# Customer claims the archive is incomplete; verify before disputing
+python3 ./scripts/record_engagement.py engagements/acme-2026-q2/ --min-severity high
+```
+
+If exit code is 0, the archive is internally consistent.
+
+## Output
+
+JSON / JSONL / Markdown per `lib/report.py`. Exit codes: 0 clean,
+1 high/critical, 2 error.
+
+Each Finding includes:
+
+- `id` — `evidence::<issue>::<path>`
+- `severity` — CRITICAL / HIGH / MEDIUM / INFO
+- `category` — `evidence-chain`
+- `summary` — what's wrong with the artifact
+- `evidence` — file path, expected hash, observed hash, manifest entry
+
+## Error Handling
+
+- **Path doesn't exist** → exits 2 with operational error.
+- **Permission denied reading a file** → emits HIGH finding,
+  continues walking other files.
+- **GPG not installed** with `--sign` requested → emits HIGH
+  finding, manifest written unsigned, exits 1.
+- **GPG signing fails** (no default identity, etc.) → emits HIGH
+  finding, manifest written unsigned, exits 1.
+- **tar command fails** with `--tar` requested → manifest still
+  written; archive creation failure surfaces as HIGH finding.
+
+## Resources
+
+- `references/THEORY.md` — Chain of custody as a legal concept,
+  evidence-integrity standards (NIST SP 800-86), SHA-256 vs
+  SHA-3 vs SHA-512 tradeoffs, GPG detached-signature semantics,
+  archive format choices (tar vs zip vs WORM), retention horizons
+  per jurisdiction
+- `references/PLAYBOOK.md` — Engagement directory templates per
+  engagement type, daily-snapshot cron pattern, customer-handoff
+  protocol, dispute-resolution playbook (when the customer
+  challenges the archive), long-term storage and access-control
+  patterns