websec-validator 0.2.0__py3-none-any.whl

websec_validator/scanners.py

@@ -0,0 +1,248 @@
+"""Static scanner registry + detection + execution.
+
+v1 philosophy: the tool does NOT install scanners and does NOT import them. It
+detects which are on PATH (or reachable via Docker) and shells out to the ones
+that are present, writing each tool's native JSON to the output dir. Missing
+tools are reported in the briefing so the agent can offer to install them — we
+never hard-fail because a scanner is absent.
+
+Each scanner runs read-only against the filesystem (no network target, no
+running app). Anything that needs a live instance (ZAP, Nuclei DAST) is NOT
+here — that is the dynamic phase, which v1 leaves to the agent + human.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Scanner:
+    key: str
+    name: str
+    category: str          # sast | sca | secrets | iac | cloud
+    binary: str            # what we look for on PATH
+    languages: tuple = ()  # () == language-agnostic
+    install: str = ""      # one-line install hint for the briefing
+    # argv builder: (target, out_file) -> list[str]; None means "detect only" for now
+    argv: object = None
+
+
+def _trivy(target: Path, out: Path) -> list:
+    # SCA + secrets + IaC misconfig in one pass; pinned by the user's install.
+    return ["trivy", "fs", "--scanners", "vuln,secret,misconfig",
+            "--skip-dirs", "node_modules", "--skip-dirs", "security",
+            "--format", "json", "--output", str(out), str(target)]
+
+
+def _gitleaks(target: Path, out: Path) -> list:
+    return ["gitleaks", "detect", "--source", str(target), "--no-banner",
+            "--report-format", "json", "--report-path", str(out)]
+
+
+def _semgrep(target: Path, out: Path) -> list:
+    return ["semgrep", "scan", "--config", "auto", "--json",
+            "--output", str(out), str(target)]
+
+
+def _checkov(target: Path, out: Path) -> list:
+    return ["checkov", "-d", str(target), "--compact", "-o", "json",
+            "--output-file-path", str(out.parent)]
+
+
+REGISTRY: tuple = (
+    Scanner("trivy", "Trivy", "sca", "trivy",
+            install="brew install trivy  # pin by digest in CI", argv=_trivy),
+    Scanner("gitleaks", "Gitleaks", "secrets", "gitleaks",
+            install="brew install gitleaks", argv=_gitleaks),
+    Scanner("semgrep", "Semgrep/OpenGrep", "sast", "semgrep",
+            install="pipx install semgrep  # or opengrep for fully-OSS", argv=_semgrep),
+    Scanner("checkov", "Checkov", "iac", "checkov",
+            install="pipx install checkov", argv=_checkov),
+    Scanner("bandit", "Bandit", "sast", "bandit", languages=("python",),
+            install="pipx install bandit"),
+    Scanner("osv-scanner", "OSV-Scanner", "sca", "osv-scanner",
+            install="brew install osv-scanner"),
+    Scanner("prowler", "Prowler", "cloud", "prowler",
+            install="pipx install prowler  # needs AWS creds"),
+)
+
+
+def detect(stack_languages: list | None = None) -> dict:
+    """Return {'available': [...], 'missing': [...]} for the relevant scanners.
+
+    A language-specific scanner (e.g. Bandit/python) is only considered relevant
+    when that language is present in the stack.
+    """
+    langs = set(stack_languages or [])
+    available, missing = [], []
+    for s in REGISTRY:
+        if s.languages and not (set(s.languages) & langs):
+            continue  # not relevant to this repo's stack
+        entry = {"key": s.key, "name": s.name, "category": s.category}
+        if shutil.which(s.binary):
+            available.append(entry)
+        else:
+            missing.append({**entry, "install": s.install})
+    return {"available": available, "missing": missing}
+
+
+def run_available(target: Path, outdir: Path, stack_languages: list | None = None,
+                  timeout: int = 600) -> list:
+    """Execute every available, runnable static scanner. Returns per-scanner status.
+
+    Raw JSON lands in outdir/scanners/<key>.json. We capture status only here;
+    cross-tool normalization + de-duplication is a separate (next) step.
+    """
+    langs = set(stack_languages or [])
+    scan_dir = outdir / "scanners"
+    scan_dir.mkdir(parents=True, exist_ok=True)
+    results = []
+    for s in REGISTRY:
+        if s.argv is None:
+            continue  # detect-only for now
+        if s.languages and not (set(s.languages) & langs):
+            continue
+        if not shutil.which(s.binary):
+            continue
+        out_file = scan_dir / f"{s.key}.json"
+        try:
+            proc = subprocess.run(s.argv(target, out_file), capture_output=True,
+                                  text=True, timeout=timeout)
+            results.append({"key": s.key, "name": s.name, "category": s.category,
+                            "exit_code": proc.returncode, "output": str(out_file),
+                            "findings": _count_findings(s.key, out_file)})
+        except subprocess.TimeoutExpired:
+            results.append({"key": s.key, "name": s.name, "status": "timeout"})
+        except Exception as e:  # never let one scanner sink the run
+            results.append({"key": s.key, "name": s.name, "status": f"error: {e}"})
+    return results
+
+
+def _count_findings(key: str, out_file: Path) -> int:
+    """Best-effort finding count from a scanner's native JSON (for the summary)."""
+    if not out_file.exists():
+        return 0
+    try:
+        data = json.loads(out_file.read_text())
+    except Exception:
+        return 0
+    if key == "trivy":
+        return sum(len(r.get("Vulnerabilities", []) or []) +
+                   len(r.get("Secrets", []) or []) +
+                   len(r.get("Misconfigurations", []) or [])
+                   for r in (data.get("Results") or []))
+    if key == "gitleaks":
+        return len(data) if isinstance(data, list) else 0
+    if key == "semgrep":
+        return len(data.get("results", []) or [])
+    return 0
+
+
+# ---- cross-tool normalization + de-duplication -------------------------------------------
+# The thing no OSS orchestrator does: one ranked finding even when two scanners
+# report the same CVE / secret / misconfig. Fingerprints are scheme-shared across
+# tools so e.g. a secret found by both Gitleaks and Trivy collapses to one row.
+
+SEV_ORDER = {"CRITICAL": 4, "HIGH": 3, "MEDIUM": 2, "LOW": 1, "INFO": 0, "UNKNOWN": 1}
+
+
+def _sev(s: str) -> str:
+    s = (s or "").upper()
+    return s if s in SEV_ORDER else "MEDIUM"
+
+
+def _norm_trivy(data: dict) -> list:
+    out = []
+    for res in (data.get("Results") or []):
+        tgt = res.get("Target", "")
+        for v in (res.get("Vulnerabilities") or []):
+            out.append({"tool": "trivy", "category": "sca", "severity": _sev(v.get("Severity")),
+                        "key": v.get("VulnerabilityID", ""), "file": tgt, "line": 0,
+                        "title": f"{v.get('PkgName')} {v.get('InstalledVersion')} → {v.get('FixedVersion', '(no fix)')}",
+                        "fingerprint": f"cve|{v.get('PkgName')}|{v.get('VulnerabilityID')}"})
+        for s in (res.get("Secrets") or []):
+            out.append({"tool": "trivy", "category": "secret", "severity": _sev(s.get("Severity") or "HIGH"),
+                        "key": s.get("RuleID", ""), "file": tgt, "line": s.get("StartLine", 0),
+                        "title": f"secret: {s.get('Title') or s.get('RuleID')}",
+                        "fingerprint": f"secret|{tgt}|{s.get('RuleID')}"})
+        for m in (res.get("Misconfigurations") or []):
+            out.append({"tool": "trivy", "category": "iac", "severity": _sev(m.get("Severity")),
+                        "key": m.get("ID", ""), "file": tgt, "line": 0, "title": (m.get("Title") or "")[:90],
+                        "fingerprint": f"iac|{tgt}|{m.get('ID')}"})
+    return out
+
+
+def _norm_gitleaks(data) -> list:
+    rows = data if isinstance(data, list) else (data.get("findings") or [])
+    out = []
+    for x in rows:
+        f, rule = x.get("File", ""), x.get("RuleID", "")
+        out.append({"tool": "gitleaks", "category": "secret", "severity": "HIGH",
+                    "key": rule, "file": f, "line": x.get("StartLine", 0),
+                    "title": f"secret: {(x.get('Description') or rule)[:80]}",
+                    "fingerprint": f"secret|{f}|{rule}"})
+    return out
+
+
+def _norm_semgrep(data: dict) -> list:
+    sevmap = {"ERROR": "HIGH", "WARNING": "MEDIUM", "INFO": "INFO"}
+    out = []
+    for r in (data.get("results") or []):
+        rule = (r.get("check_id", "")).split(".")[-1]
+        path = r.get("path", "")
+        line = (r.get("start") or {}).get("line", 0)
+        sev = sevmap.get((r.get("extra") or {}).get("severity", "INFO"), "MEDIUM")
+        out.append({"tool": "semgrep", "category": "sast", "severity": sev,
+                    "key": rule, "file": path, "line": line,
+                    "title": ((r.get("extra") or {}).get("message") or rule)[:90],
+                    "fingerprint": f"sast|{path}|{line}|{rule}"})
+    return out
+
+
+_PARSERS = {"trivy": _norm_trivy, "gitleaks": _norm_gitleaks, "semgrep": _norm_semgrep}
+
+
+def normalize_findings(scan_results: list, outdir: Path) -> dict:
+    """Merge every scanner's native JSON into one de-duplicated, severity-ranked
+    findings.json. Returns a summary (raw vs deduped, by severity/category)."""
+    raw = []
+    for r in scan_results:
+        out, key = r.get("output"), r.get("key")
+        parser = _PARSERS.get(key)
+        if not (out and parser and Path(out).exists()):
+            continue
+        try:
+            raw += parser(json.loads(Path(out).read_text() or "{}"))
+        except Exception:
+            continue
+
+    by_fp: dict = {}
+    for f in raw:
+        fp = f["fingerprint"]
+        if fp in by_fp:
+            if f["tool"] not in by_fp[fp]["tools"]:
+                by_fp[fp]["tools"].append(f["tool"])
+            if SEV_ORDER[f["severity"]] > SEV_ORDER[by_fp[fp]["severity"]]:
+                by_fp[fp]["severity"] = f["severity"]
+        else:
+            f = dict(f)
+            f["tools"] = [f.pop("tool")]
+            by_fp[fp] = f
+    deduped = sorted(by_fp.values(), key=lambda f: -SEV_ORDER[f["severity"]])
+    (outdir / "findings.json").write_text(json.dumps(deduped, indent=2))
+
+    by_sev, by_cat = {}, {}
+    for f in deduped:
+        by_sev[f["severity"]] = by_sev.get(f["severity"], 0) + 1
+        by_cat[f["category"]] = by_cat.get(f["category"], 0) + 1
+    return {"total_raw": len(raw), "total": len(deduped),
+            "cross_tool_or_dup_merged": len(raw) - len(deduped),
+            "by_severity": by_sev, "by_category": by_cat,
+            "top": [{"severity": f["severity"], "category": f["category"], "title": f["title"],
+                     "file": f["file"], "tools": f["tools"]} for f in deduped[:15]]}
+

websec_validator/templates/probes/bola-cross-tenant.sh

@@ -0,0 +1,192 @@
+#!/usr/bin/env bash
+#
+# bola-cross-tenant.sh — manual BOLA / cross-tenant probe.
+#
+# ZAP's automated scanner can't tell when Agent A reading Agent B's tenant
+# data is a violation — it just sees "another 200". This script does the
+# two-account probe a pentest team will run on day 1:
+#
+#   1. Mint two agent tokens (Agent A in tenant_A, Agent B in tenant_B).
+#   2. Discover each agent's accessible tenants via /api/auth/me (or your
+#      project's equivalent "current user" endpoint).
+#   3. For every tenant-scoped endpoint pattern, try Agent A's token against
+#      Agent B's tenantId, and vice versa. Expect 403 or 404 (either prevents
+#      the data leak).
+#
+# Usage:
+#   1. In .env, set:
+#         ZAP_AGENT_USER  / ZAP_AGENT_PASS   (Agent A in tenant X)
+#         ZAP_AGENT2_USER / ZAP_AGENT2_PASS  (Agent B in tenant Y — DIFFERENT tenant)
+#   2. ./bola-cross-tenant.sh
+#   3. Output is one PASS/FAIL line per probe + a summary; nonzero exit on FAIL.
+#
+# Requires: bash, curl, jq, python3.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+[[ -f .env ]] || { echo "No .env found in $(pwd)" >&2; exit 1; }
+
+# Parse .env literally (handles passwords with shell-special chars)
+read_env() {
+    local key="$1"
+    python3 -c "
+for l in open('.env'):
+    l = l.rstrip('\n')
+    if l.startswith('#') or '=' not in l: continue
+    k, v = l.split('=', 1)
+    if k.strip() == '$key':
+        print(v); break
+"
+}
+
+TARGET="$(read_env ZAP_TARGET)"
+A_USER="$(read_env ZAP_AGENT_USER)"
+A_PASS="$(read_env ZAP_AGENT_PASS)"
+B_USER="$(read_env ZAP_AGENT2_USER)"
+B_PASS="$(read_env ZAP_AGENT2_PASS)"
+
+[[ -n "$TARGET" && -n "$A_USER" && -n "$A_PASS" && -n "$B_USER" && -n "$B_PASS" ]] || {
+    cat >&2 <<EOF
+ERROR: missing required .env values. Need:
+  ZAP_TARGET, ZAP_AGENT_USER, ZAP_AGENT_PASS,
+  ZAP_AGENT2_USER (the second agent in a DIFFERENT tenant), ZAP_AGENT2_PASS
+
+The cross-tenant probe is moot if both agents are in the same tenant.
+EOF
+    exit 2
+}
+
+# TODO: adjust login URL / payload / response shape to match your API.
+login() {
+    local user="$1" pass="$2"
+    local body
+    body=$(jq -nc --arg e "$user" --arg p "$pass" '{email:$e,password:$p}')
+    curl -fsS -X POST "$TARGET/api/auth/login" \
+        -H 'Content-Type: application/json' \
+        -d "$body" \
+    | jq -r '.tokens.accessToken'
+}
+
+echo "==> minting Agent A token..."
+A_TOKEN="$(login "$A_USER" "$A_PASS")"
+[[ -n "$A_TOKEN" ]] || { echo "Agent A login failed" >&2; exit 3; }
+
+echo "==> minting Agent B token..."
+B_TOKEN="$(login "$B_USER" "$B_PASS")"
+[[ -n "$B_TOKEN" ]] || { echo "Agent B login failed" >&2; exit 3; }
+
+# TODO: adjust /api/auth/me to your project's "current user" endpoint.
+# We need each agent's tenant-id list. Adjust the jq filter below to your shape.
+fetch_me() {
+    local token="$1"
+    curl -fsS "$TARGET/api/auth/me" -H "Authorization: Bearer $token"
+}
+
+A_ME="$(fetch_me "$A_TOKEN")"
+B_ME="$(fetch_me "$B_TOKEN")"
+
+# TODO: this jq expects {user: {groupIds: [...]}} or {groupIds: [...]}.
+# Change groupIds to whatever your tenancy field is (orgIds, workspaceIds, accountIds).
+A_GROUPS=( $(echo "$A_ME" | jq -r '(.user.groupIds // .groupIds // []) | .[]') )
+B_GROUPS=( $(echo "$B_ME" | jq -r '(.user.groupIds // .groupIds // []) | .[]') )
+
+[[ ${#A_GROUPS[@]} -gt 0 ]] || { echo "Agent A has no tenant ids" >&2; exit 3; }
+[[ ${#B_GROUPS[@]} -gt 0 ]] || { echo "Agent B has no tenant ids" >&2; exit 3; }
+
+# Pick the first tenant each that the OTHER agent does NOT belong to
+A_TARGET_GROUP=""
+for g in "${A_GROUPS[@]}"; do
+    if ! printf '%s\n' "${B_GROUPS[@]}" | grep -qx "$g"; then
+        A_TARGET_GROUP="$g"; break
+    fi
+done
+B_TARGET_GROUP=""
+for g in "${B_GROUPS[@]}"; do
+    if ! printf '%s\n' "${A_GROUPS[@]}" | grep -qx "$g"; then
+        B_TARGET_GROUP="$g"; break
+    fi
+done
+
+[[ -n "$A_TARGET_GROUP" && -n "$B_TARGET_GROUP" ]] || {
+    echo "ERROR: Agent A and B share all tenants — cannot run a meaningful cross-tenant test." >&2
+    echo "Agent A tenants: ${A_GROUPS[*]}" >&2
+    echo "Agent B tenants: ${B_GROUPS[*]}" >&2
+    echo "Move one agent into a different tenant via the admin UI, then re-run." >&2
+    exit 3
+}
+
+echo "==> Agent A will try to access B's tenant: $B_TARGET_GROUP"
+echo "==> Agent B will try to access A's tenant: $A_TARGET_GROUP"
+echo
+
+# PROJECT-SPECIFIC START
+# Probe matrix: each is a (METHOD, PATH_TEMPLATE, EXPECTED_BLOCKED_CODES) tuple.
+# {group} is substituted with the OTHER agent's tenant id. We accept 403 or 404
+# (either prevents the leak). REPLACE these with your project's tenant-scoped
+# endpoints. Look at backend routes for any path containing /:groupId or /:orgId.
+PROBES=(
+    "GET /api/groups/{group}/conversations 403|404"
+    "GET /api/groups/{group}/users 403|404"
+    "GET /api/groups/{group}/tags 403|404"
+    "GET /api/groups/{group}/canned-responses 403|404"
+    "POST /api/groups/{group}/tags 403|404"
+    "GET /api/groups/{group} 403|404"
+)
+# PROJECT-SPECIFIC END
+
+PASS=0
+FAIL=0
+FAIL_LINES=()
+
+probe() {
+    local label="$1" token="$2" method="$3" url="$4" allowed_codes="$5"
+    local code
+    if [[ "$method" == "GET" ]]; then
+        code=$(curl -s -m 10 -o /dev/null -w '%{http_code}' \
+            -H "Authorization: Bearer $token" "$url")
+    elif [[ "$method" == "POST" ]]; then
+        code=$(curl -s -m 10 -o /dev/null -w '%{http_code}' -X POST \
+            -H "Authorization: Bearer $token" \
+            -H 'Content-Type: application/json' \
+            -d '{}' "$url")
+    else
+        code=$(curl -s -m 10 -o /dev/null -w '%{http_code}' -X "$method" \
+            -H "Authorization: Bearer $token" "$url")
+    fi
+    if [[ "|$allowed_codes|" == *"|$code|"* ]]; then
+        printf '  %-4s %-6s %-7s %s  expected:%s  actual:%s\n' "PASS" "$label" "$method" "$url" "$allowed_codes" "$code"
+        PASS=$((PASS+1))
+    else
+        printf '  %-4s %-6s %-7s %s  expected:%s  actual:%s\n' "FAIL" "$label" "$method" "$url" "$allowed_codes" "$code"
+        FAIL=$((FAIL+1))
+        FAIL_LINES+=("$label $method $url got $code (expected $allowed_codes)")
+    fi
+}
+
+echo "=== Agent A attacking Agent B's tenant ($B_TARGET_GROUP) ==="
+for p in "${PROBES[@]}"; do
+    method=$(echo "$p" | awk '{print $1}')
+    path=$(echo "$p" | awk '{print $2}' | sed "s|{group}|$B_TARGET_GROUP|g")
+    expected=$(echo "$p" | awk '{print $3}')
+    probe "A→B" "$A_TOKEN" "$method" "$TARGET$path" "$expected"
+done
+echo
+echo "=== Agent B attacking Agent A's tenant ($A_TARGET_GROUP) ==="
+for p in "${PROBES[@]}"; do
+    method=$(echo "$p" | awk '{print $1}')
+    path=$(echo "$p" | awk '{print $2}' | sed "s|{group}|$A_TARGET_GROUP|g")
+    expected=$(echo "$p" | awk '{print $3}')
+    probe "B→A" "$B_TOKEN" "$method" "$TARGET$path" "$expected"
+done
+
+echo
+echo "=== Summary ==="
+echo "  PASS: $PASS"
+echo "  FAIL: $FAIL"
+if [[ $FAIL -gt 0 ]]; then
+    echo
+    echo "FAILED PROBES (these are real BOLA findings — investigate immediately):"
+    printf '  - %s\n' "${FAIL_LINES[@]}"
+    exit 1
+fi
+echo "All probes blocked — cross-tenant access control holds."

websec_validator/templates/probes/bola-write-verbs.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""
+Extended BOLA probe — covers PATCH, PUT, DELETE, POST verbs across
+tenant-scoped endpoints. The shell `bola-cross-tenant.sh` only tests GET +
+one POST; write verbs miss authz checks more often than GETs.
+
+Strategy:
+  - As Agent A (Tenant A), attempt every mutating verb against Agent B's
+    real resources in Tenant B.
+  - Expected: 403 or 404.
+  - If 200/204: BOLA — log the finding (no auto-rollback; some mutations
+    can't be cleanly reverted from a black-box position).
+
+DELETE-against-real-resource is SKIPPED. Instead we test the auth gate by
+sending DELETE to a fabricated UUID — expect 403 BEFORE the 404 lookup.
+"""
+import json, subprocess, sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2].parent
+fixture = json.loads((ROOT / 'security/pentest-prep/fixtures/test-context.json').read_text())
+TARGET = fixture['target']
+
+A = fixture['agent_a']
+B = fixture['agent_b']
+
+ENV = {}
+for line in (ROOT / 'security/zap/.env').read_text().splitlines():
+    if '=' in line and not line.lstrip().startswith('#'):
+        k, v = line.split('=', 1); ENV[k.strip()] = v.strip()
+
+# TODO: adjust login URL and response parsing to your API.
+def login(u, p):
+    r = subprocess.run(['curl','-fsS','-X','POST',f"{TARGET}/api/auth/login",
+                        '-H','Content-Type: application/json',
+                        '-d',json.dumps({'email':u,'password':p})],
+                       capture_output=True, text=True)
+    return json.loads(r.stdout)['tokens']['accessToken']
+
+A_TOK = login(ENV['ZAP_AGENT_USER'], ENV['ZAP_AGENT_PASS'])
+B_TOK = login(ENV['ZAP_AGENT2_USER'], ENV['ZAP_AGENT2_PASS'])
+
+# Pick a real resource ID from B's tenant as the cross-tenant target (Agent A attacks)
+B_CONV = B['conversation_ids'][0] if B['conversation_ids'] else None
+B_GROUP = B['group_id']
+A_CONV = A['conversation_ids'][0] if A['conversation_ids'] else None
+A_GROUP = A['group_id']
+FABRICATED_CONV = '00000000-0000-0000-0000-000000000000'
+
+if not B_CONV:
+    print("ERROR: agent_b has no resource ids in the fixture. Aborting.", file=sys.stderr)
+    sys.exit(2)
+
+findings = []
+
+def probe(label, method, path_template, body=None, target_group=B_GROUP, target_conv=B_CONV, tok=A_TOK, fab=False):
+    path = path_template.format(g=target_group, id=target_conv if not fab else FABRICATED_CONV)
+    cmd = ['curl','-s','-X',method,f"{TARGET}{path}",'-H',f'Authorization: Bearer {tok}',
+           '-w','\nHTTP_CODE:%{http_code}']
+    if body is not None:
+        cmd += ['-H','Content-Type: application/json','-d',json.dumps(body)]
+    r = subprocess.run(cmd, capture_output=True, text=True)
+    out = r.stdout
+    code = int(out.split('HTTP_CODE:')[-1].strip()) if 'HTTP_CODE:' in out else 0
+    body_text = out.split('\nHTTP_CODE:')[0]
+    if code in (403, 404):
+        sev, mark = 'PASS', 'OK'
+    elif code in (200, 201, 204):
+        sev, mark = 'CRITICAL', '!!'
+    else:
+        sev, mark = 'INVESTIGATE', '??'
+    finding = {'label': label, 'method': method, 'path': path, 'status': code,
+               'severity': sev, 'response_preview': body_text[:150]}
+    findings.append(finding)
+    print(f"  [{mark}] [{sev:11s}] {method:6s} {path}  -> {code}")
+    return code, body_text
+
+print(f"=== Extended BOLA write-verb tests ===")
+print(f"  Attacker (A): {A['email']}  tenant={A_GROUP}")
+print(f"  Target (B):   {B['email']}  tenant={B_GROUP}  resource={B_CONV}")
+print()
+
+# PROJECT-SPECIFIC START
+# TODO: replace the path templates with mutating endpoints from your project.
+# Look at your routes for any path with /:groupId or /:tenantId + a mutating verb.
+
+# 1. PATCH/PUT primary tenant resource
+print("--- Resource mutation (B's resource, attempted as A) ---")
+probe('patch-conv-as-A', 'PATCH', '/api/groups/{g}/conversations/{id}', {'status': 'CLOSED'})
+probe('put-conv-as-A',   'PUT',   '/api/groups/{g}/conversations/{id}', {'status': 'CLOSED'})
+
+# 2. Workflow actions (assign, snooze, status flip — whatever your project has)
+print()
+print("--- Workflow actions on B's resource as A ---")
+probe('assign-as-A',   'POST', '/api/groups/{g}/conversations/{id}/assign',   {'agentId': A['email']})
+probe('unassign-as-A', 'POST', '/api/groups/{g}/conversations/{id}/unassign', {})
+probe('snooze-as-A',   'POST', '/api/groups/{g}/conversations/{id}/snooze',   {'snoozeUntil': '2026-12-31T00:00:00Z'})
+probe('spam-as-A',     'POST', '/api/groups/{g}/conversations/{id}/spam',     {})
+
+# 3. Sub-resource operations (tags, labels, attachments — adapt to your model)
+print()
+print("--- Sub-resource operations on B's resource ---")
+probe('tag-add-as-A',  'POST',   '/api/groups/{g}/conversations/{id}/tags', {'tagId': 'some-tag-id'})
+probe('tag-del-as-A',  'DELETE', '/api/groups/{g}/conversations/{id}/tags/fake-tag-id')
+
+# 4. Tenant-level mutations (modify or delete the tenant itself)
+print()
+print("--- Tenant-level mutations (B's tenant as A) ---")
+probe('grp-put-as-A', 'PUT',    '/api/admin/groups/{g}', {'name': 'pwn'}, target_conv='')
+probe('grp-del-as-A', 'DELETE', '/api/admin/groups/{g}', target_conv='')
+
+# 5. DELETE with fabricated UUID — auth gate only (no real deletion since target doesn't exist)
+print()
+print("--- DELETE auth-gate check (fabricated UUID, no mutation possible) ---")
+probe('delete-conv-fab', 'DELETE', '/api/groups/{g}/conversations/{id}', fab=True)
+# PROJECT-SPECIFIC END
+
+# 6. Same probes as B against A (verify symmetry)
+print()
+print(f"=== Reverse direction: B attacks A's tenant ===")
+print(f"  Attacker (B): {B['email']}")
+print(f"  Target (A):   {A['email']}  tenant={A_GROUP}  resource={A_CONV}")
+print()
+
+if A_CONV:
+    probe('B->A: patch-conv',   'PATCH', '/api/groups/{g}/conversations/{id}', {'status':'CLOSED'},
+          target_group=A_GROUP, target_conv=A_CONV, tok=B_TOK)
+    probe('B->A: assign',       'POST',  '/api/groups/{g}/conversations/{id}/assign', {'agentId': B['email']},
+          target_group=A_GROUP, target_conv=A_CONV, tok=B_TOK)
+    probe('B->A: snooze',       'POST',  '/api/groups/{g}/conversations/{id}/snooze', {'snoozeUntil':'2026-12-31T00:00:00Z'},
+          target_group=A_GROUP, target_conv=A_CONV, tok=B_TOK)
+
+# Save
+out = ROOT / 'security/pentest-prep/reports/custom-bola/write-verb-findings.json'
+out.parent.mkdir(parents=True, exist_ok=True)
+out.write_text(json.dumps(findings, indent=2))
+
+crit = sum(1 for f in findings if f['severity'] == 'CRITICAL')
+inv = sum(1 for f in findings if f['severity'] == 'INVESTIGATE')
+ok = sum(1 for f in findings if f['severity'] == 'PASS')
+print()
+print("=== Summary ===")
+print(f"  CRITICAL (BOLA confirmed):  {crit}")
+print(f"  INVESTIGATE (odd status):   {inv}")
+print(f"  PASS (403/404):             {ok}")
+print(f"  Saved to: {out}")
+sys.exit(1 if crit > 0 else 0)

websec_validator/templates/probes/compare-roles.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# compare-roles.sh — diff two ZAP role-scoped SARIF reports.
+#
+# Usage:
+#   ./run.sh agent          # produces zap-report-sarif-agent.json
+#   ./run.sh admin          # produces zap-report-sarif-admin.json
+#   ./compare-roles.sh      # prints the access-control delta
+#
+# What it shows:
+#   - Routes ADMIN can reach that AGENT cannot      → expected; verifies authz
+#   - Routes AGENT can reach that ADMIN cannot      → almost always wrong; investigate
+#   - Routes both can reach                         → no role distinction (may be intentional public)
+#
+# This is the "two-role diff" step. Without it, the active scan only proves what one
+# role can see; the diff is what proves cross-role access control actually works.
+set -euo pipefail
+cd "$(dirname "$0")"
+
+AGENT="zap-report-sarif-agent.json"
+ADMIN="zap-report-sarif-admin.json"
+
+[[ -f "$AGENT" ]] || { echo "missing $AGENT — run ./run.sh agent first" >&2; exit 1; }
+[[ -f "$ADMIN" ]] || { echo "missing $ADMIN — run ./run.sh admin first" >&2; exit 1; }
+
+python3 - <<PY
+import json, re
+from collections import defaultdict
+
+def load_urls(path):
+    """Return {normalized_path: set(method)} of every URL ZAP touched."""
+    with open(path) as f:
+        sarif = json.load(f)
+    out = defaultdict(set)
+    for r in sarif["runs"][0]["results"]:
+        for loc in r.get("locations", []):
+            uri = loc.get("physicalLocation", {}).get("artifactLocation", {}).get("uri", "")
+            if not uri.startswith("http"): continue
+            # strip host + querystring, normalize ids/uuids/slugs
+            path = re.sub(r"https?://[^/]+", "", uri).split("?")[0]
+            path = re.sub(r"/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f-]{20,}", "/{uuid}", path)
+            path = re.sub(r"/[0-9a-f]{20,}", "/{id}", path)
+            path = re.sub(r"/\d+(?=/|\$)", "/{n}", path)
+            out[path].add(r.get("properties", {}).get("method", "?"))
+    return out
+
+agent = load_urls("$AGENT")
+admin = load_urls("$ADMIN")
+
+agent_only = set(agent) - set(admin)
+admin_only = set(admin) - set(agent)
+both       = set(agent) & set(admin)
+
+print(f"=== AGENT touched {len(agent)} distinct path patterns ===")
+print(f"=== ADMIN touched {len(admin)} distinct path patterns ===")
+print()
+print(f"--- Paths AGENT reached that ADMIN did not ({len(agent_only)}) ---")
+print("    These are SUSPICIOUS — admin should see everything agent sees.")
+for p in sorted(agent_only): print(f"  AGENT-ONLY  {p}")
+print()
+print(f"--- Paths ADMIN reached that AGENT did not ({len(admin_only)}) ---")
+print("    These should match the access-control matrix (admin-only routes).")
+for p in sorted(admin_only): print(f"  ADMIN-ONLY  {p}")
+print()
+print(f"--- Paths both reached ({len(both)}) ---")
+print("    These are routes neither blocked at the auth/authz layer for either role.")
+print("    Verify against access-control-matrix.md — anything here that should be")
+print("    admin-only is a real access-control gap.")
+for p in sorted(both): print(f"  BOTH        {p}")
+PY