websec-validator 0.2.0__py3-none-any.whl

websec_validator/templates/probes/webhook-forgery.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""
+Webhook forgery probe — signature verification for inbound webhooks.
+
+A correct webhook verifier uses:
+  - crypto.timingSafeEqual (or HMAC compare_digest) — not raw == comparison
+  - fail-closed — reject if ANY required header is missing or malformed
+  - timestamp-age check — reject signatures older than ~5 minutes to prevent
+    captured-and-replayed-later forgeries
+
+This probe tests:
+  1. No signature header               -> expect 401
+  2. Invalid signature (random b64)    -> expect 401
+  3. Garbage signature (non-b64)       -> expect 401
+  4. Missing timestamp                 -> expect 401
+  5. Far-future timestamp              -> expect 401 ideally (replay-window check)
+  6. Far-past timestamp                -> same
+  7. Truncated signature               -> expect 401
+  8. Empty body                        -> expect 401
+  9. Wrong content-type                -> expect 401
+"""
+import json, subprocess, time, sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2].parent
+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()
+
+TARGET = ENV['ZAP_TARGET']
+
+# PROJECT-SPECIFIC START
+# TODO: replace with your project's inbound-webhook path, signature header
+# name, and timestamp header name. Examples:
+#   Bird / MessageBird: /webhooks/messagebird, messagebird-signature, messagebird-timestamp
+#   Stripe:             /webhooks/stripe,      Stripe-Signature  (combined ts+sig)
+#   Twilio:             /webhooks/twilio,      X-Twilio-Signature
+#   GitHub:             /webhooks/github,      X-Hub-Signature-256
+#   Custom:             /webhooks/<provider>,  X-Signature, X-Timestamp
+WEBHOOK_PATH = "/webhooks/<provider>"
+SIG_HEADER = "x-signature"
+TS_HEADER  = "x-timestamp"
+
+URL = f"{TARGET}{WEBHOOK_PATH}"
+
+# TODO: realistic payload shape for your provider.
+PAYLOAD = json.dumps({
+    "event": "message.received",
+    "type": "message",
+    "channelId": "channel-id-xxx",
+    "message": {
+        "id": "fake-msg-id",
+        "from": "+15551234567",
+        "content": "hello from attacker",
+    }
+})
+# PROJECT-SPECIFIC END
+
+probes = [
+    # (name, headers, body, expected_code, expected_reason)
+    ('no-signature',           {},                                                                             PAYLOAD, 401, 'no sig'),
+    ('invalid-signature-b64',  {SIG_HEADER: 'aW52YWxpZA=='},                                                   PAYLOAD, 401, 'bad sig'),
+    ('garbage-signature',      {SIG_HEADER: 'not-base64-!'},                                                   PAYLOAD, 401, 'malformed sig'),
+    ('missing-timestamp',      {SIG_HEADER: 'aW52YWxpZA=='},                                                   PAYLOAD, 401, 'no timestamp'),
+    ('zero-timestamp',         {SIG_HEADER: 'aW52YWxpZA==', TS_HEADER: '0'},                                   PAYLOAD, 401, 'timestamp epoch 0'),
+    ('far-future-timestamp',   {SIG_HEADER: 'aW52YWxpZA==', TS_HEADER: '4070908800'},                          PAYLOAD, 401, 'timestamp year 2099'),
+    ('far-past-timestamp',     {SIG_HEADER: 'aW52YWxpZA==', TS_HEADER: '1000000000'},                          PAYLOAD, 401, 'timestamp year 2001'),
+    ('truncated-signature',    {SIG_HEADER: 'a'},                                                              PAYLOAD, 401, 'too short'),
+    ('empty-body',             {SIG_HEADER: 'aW52YWxpZA==', TS_HEADER: str(int(time.time()))},                 '',      401, 'empty body'),
+    ('wrong-content-type',     {SIG_HEADER: 'aW52YWxpZA==', TS_HEADER: str(int(time.time())), 'Content-Type': 'text/plain'}, PAYLOAD, 401, 'wrong ct'),
+]
+
+findings = []
+print(f"=== Webhook forgery probes against {URL} ===\n")
+
+for name, headers, body, expected, reason in probes:
+    cmd = ['curl', '-s', '-X', 'POST', URL, '-w', '\nHTTP_CODE:%{http_code}']
+    for h, v in headers.items():
+        cmd += ['-H', f'{h}: {v}']
+    if 'Content-Type' not in headers:
+        cmd += ['-H', 'Content-Type: application/json']
+    cmd += ['-d', 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]
+    expected_ok = code == expected
+    mark = 'OK' if expected_ok else '!!'
+    sev = 'PASS' if expected_ok else 'FAIL'
+    print(f"  [{mark}] [{sev}] {name:30s} expected={expected} actual={code} ({reason})")
+    findings.append({
+        'name': name, 'expected': expected, 'actual': code, 'pass': expected_ok,
+        'body_preview': body_text[:120],
+    })
+
+out_p = ROOT / 'security/pentest-prep/reports/webhook-forgery/findings.json'
+out_p.parent.mkdir(parents=True, exist_ok=True)
+out_p.write_text(json.dumps(findings, indent=2))
+
+passed = sum(1 for f in findings if f['pass'])
+print(f"\n=== Summary ===")
+print(f"  {passed}/{len(findings)} probes returned expected 401")
+print(f"  Saved: {out_p}")
+
+# Replay-window note
+print()
+print("=== Note on timestamp-age / replay window ===")
+print("  Even if the HMAC is correct, captured webhooks should not replay forever.")
+print("  Look in your handler for code like:")
+print("    const age = Math.abs(Date.now()/1000 - parseInt(timestamp));")
+print("    if (age > 300) return res.status(401).json({error:'webhook timestamp out of window'});")
+print("  If that check is missing, log it as a finding (low severity, easy fix).")

websec_validator/templates/reports/FINDINGS-SUMMARY.md.template

@@ -0,0 +1,75 @@
+# Security tooling pass — findings summary
+
+> Date: <YYYY-MM-DD>. Tools run locally; **zero repo footprint added**.
+> All outputs in `security/<tool>/` (gitignored).
+
+## Tools run
+
+| Tool | Status | Outputs |
+|---|---|---|
+| **Prowler** <ver> | ☐ | `security/prowler/` |
+| **Nuclei** <ver> | ☐ | `security/nuclei/` |
+| **Semgrep** <ver> | ☐ | `security/semgrep/` |
+| **Gitleaks** <ver> | ☐ | `security/gitleaks/` |
+| **Trivy** <ver> | ☐ | `security/trivy/` |
+| **ZAP** <ver> + manual probes | ☐ | `security/zap/`, `security/pentest-prep/` |
+
+## Most important finding
+
+> The single highest-priority item, with action and owner.
+
+## Real findings
+
+| Tool | Finding | Severity | Action |
+|---|---|---|---|
+| <tool> | <finding> | <CRIT/HIGH/MED/LOW> | <action + file:line> |
+
+## What's clean
+
+| Surface | Tool | Result |
+|---|---|---|
+| <Surface 1> | <Tool> | <e.g. 0 CRITICAL + 0 HIGH> |
+| <Surface 2> | <Tool> | <Result> |
+
+## Recommended order of fixes
+
+1. <P0 item>
+2. <P1 item>
+3. <P2 item>
+
+## What's NOT in this report
+
+- <Surfaces not covered + why>
+- <Tools skipped + why>
+
+## Reproducing this scan pass
+
+```bash
+# Prowler
+prowler aws --region us-east-1 \
+  --compliance cis_2.0_aws aws_foundational_security_best_practices_aws \
+  --output-formats html json-asff csv \
+  --output-directory security/prowler/
+
+# Nuclei
+TOKEN=$(./security/zap/run.sh --print-token)
+nuclei -target "$ZAP_TARGET" -H "Authorization: Bearer $TOKEN" \
+  -tags "jwt,ssrf,sqli,lfi,redirect,rce,exposure,misconfig,cve" \
+  -severity medium,high,critical -rate-limit 30 -concurrency 5 \
+  -json-export security/nuclei/nuclei-baseline.json \
+  -output security/nuclei/nuclei-baseline.txt
+
+# Semgrep
+semgrep --config auto --config p/typescript --config p/javascript \
+  --config p/security-audit --severity WARNING --severity ERROR \
+  --json -o security/semgrep/semgrep-backend.json backend/src
+
+# Gitleaks
+gitleaks detect --source . --report-format json --report-path security/gitleaks/current.json
+gitleaks git --report-format json --report-path security/gitleaks/history.json
+
+# Trivy
+trivy fs --scanners vuln,secret,misconfig --severity HIGH,CRITICAL \
+  --skip-dirs node_modules --skip-dirs security \
+  --format json --output security/trivy/trivy-fs.json .
+```

websec_validator/templates/reports/access-control-matrix.md.template

@@ -0,0 +1,65 @@
+# Access-Control Matrix — <PROJECT_NAME> API
+
+> Source of truth: `backend/src/routes/*`, `backend/src/server.ts`,
+> the auth/permission middleware files, and the role seed.
+>
+> This is the map of *what each role SHOULD be able to reach*. The ZAP
+> Access Control test compares it against what each role *actually* can reach.
+>
+> **Last refreshed:** <YYYY-MM-DD>
+
+## How auth is enforced
+
+- `<requireAuth middleware mount line>` applies to every `/api/*` route mounted *after* it.
+- A handful of `/api/*` routes are registered **before** that line and are therefore **public**:
+  list them here (e.g. `/api/auth/*`, `/api/health`, `/api/settings` if public).
+- Routes outside `/api/*` bypass `requireAuth` entirely: webhooks (HMAC-verified),
+  SCIM endpoints (own bearer), `/docs`, etc.
+- **Token mechanism:** describe how tokens are minted, sent, and refreshed.
+- **Authorization styles seen on routes:**
+  - Permission strings (CASL / cancan / custom) — describe.
+  - Tenant-scoped middleware (`requireGroupAccess` / `requireOrgAccess`) — describe.
+  - Manual in-handler checks — list which routes still rely on these.
+
+## Roles
+
+| Role label | roleId | Key permissions |
+|---|---|---|
+| <Highest privilege> | `role-...` | `*` (all) |
+| <Mid privilege> | `role-...` | ... |
+| <Low privilege> | `role-...` | ... |
+
+## Legend
+
+- ✅ allowed · ❌ denied (403) · 🔒 = denied unless caller is in the target tenant · 🟡 = self-only (IDOR-guarded)
+- "Auth" column = `requireAuth` enforced (any authenticated user reaches the guard).
+
+## Matrix (representative endpoints, grouped)
+
+| Method + Path | Guard | admin | low-privilege role |
+|---|---|---|---|
+| **Auth / public** | | | |
+| POST /api/auth/login | public | ✅ | ✅ |
+| POST /api/auth/refresh | public | ✅ | ✅ |
+| GET /api/auth/me | requireAuth | ✅ | ✅ |
+| POST /api/auth/logout | requireAuth | ✅ | ✅ |
+| **Admin: users** | | | |
+| GET /api/admin/users | requirePermission('users:view') | ✅ | ❌ |
+| POST /api/admin/users | requirePermission('users:manage') | ✅ | ❌ |
+| ... | ... | ... | ... |
+
+> Continue this table for every route. Group by `**Section**` rows.
+> The completeness of this matrix is the single highest-value deliverable —
+> the pentest team loads it into ZAP's Access Control tab and uses it as the
+> map for role-vs-role testing.
+
+## Known gaps / TODOs
+
+- List any routes you know don't yet conform (e.g. still use legacy `requireRole('admin')`).
+- List any routes whose authz lives in-handler instead of in middleware — these are
+  the easiest to forget when adding a new role.
+
+## Audit history
+
+- YYYY-MM-DD — initial matrix
+- YYYY-MM-DD — added `*` after PR #N

websec_validator/templates/reports/findings-triage.md.template

@@ -0,0 +1,28 @@
+# ZAP findings triage — API scan
+
+> Triaged against the actual codebase. Document every false positive with
+> evidence so future-you (and the pentest team) doesn't re-investigate them.
+
+| Alert | Count | Risk | Verdict | Why |
+|---|---|---|---|---|
+| <e.g. SQL Injection> | <N> | High | **False positive** | <Reason — link to file:line proof> |
+| <e.g. NoSQL Injection> | <N> | High | **False positive** | <Stack uses parameterized expressions, not strings> |
+| <e.g. PII Disclosure> | <N> | High | <Real / FP> | <Evidence trail> |
+| <e.g. Path Traversal> | <N> | High | **False positive** | <IDs are DB keys, no filesystem reads> |
+| <e.g. Application Error Disclosure> | <N> | Low | Minor | <Confirm error responses are generic> |
+
+## So what's actually worth doing?
+
+> List the real, actionable items that came from elsewhere in the engagement
+> (infra checks, source review, role-comparison diff).
+
+1. <Real item 1>
+2. <Real item 2>
+3. <Real item 3>
+
+## Lesson for next runs
+
+> A 2-3 sentence note about which ZAP rules systematically misfire on this stack
+> and what the real signal source was. Examples:
+>  - DynamoDB JSON API -> SQLi/NoSQLi alerts are noise; signal is in two-role diff.
+>  - GraphQL endpoint -> rule 10202 misfires on every alias; signal is in graphql-cop.

websec_validator/templates/reports/pentest-handover-brief.md.template

@@ -0,0 +1,121 @@
+# <PROJECT_NAME> — Pentest Handover Brief
+
+**Audience:** <client>'s security engineering (pentester)
+**Prepared by:** <your name>
+**Engagement type:** Gray-box authenticated pentest
+**Test window:** <fill in dates>
+**Primary contact:** <name> — <email / phone>
+**Backup contact:** <name> — <email / phone>
+
+---
+
+## 1. What this app is (one paragraph)
+
+<2-3 sentence app description in plain English. What does it do, who uses it,
+what kind of data does it hold, what's it integrated with.>
+
+## 2. Architecture (give freely)
+
+| Layer | Tech | Notes |
+|---|---|---|
+| Frontend | <e.g. Next.js + React> | <SPA / server-rendered / etc.> |
+| API | <e.g. Express + TS on App Runner> | <auth model summary> |
+| Datastore | <e.g. DynamoDB single-table> | <indexing model> |
+| Object storage | <e.g. S3 bucket name> | <public access posture> |
+| Ingress (webhooks) | <e.g. /webhooks/provider> | <signature scheme> |
+| Outbound | <e.g. third-party REST API> | <auth model> |
+| Hosting | <e.g. AWS CDK-managed> | <test env stack name> |
+
+**Auth model (important):** <e.g. Bearer JWT + localStorage. No cookies, no CSRF token.>
+
+**Tenancy / isolation:** <Describe the tenancy boundary — group/org/workspace —
+and which boundary the pentester should attack.>
+
+## 3. URLs
+
+| Env | URL | Notes |
+|---|---|---|
+| Dev / test | <https://...> | Pentest target |
+| Prod | <https://...> | **OUT OF SCOPE** unless separately authorized in writing |
+
+Webhook endpoint: `POST <WEBHOOK_PATH>` — <signature scheme description>.
+**Do not skip the signature check during your own replay tests** — the server
+returns 401 fast and you'll think the endpoint is dead.
+
+## 4. Roles & authorization matrix
+
+| Role | Should access |
+|---|---|
+| `<role-1>` | <what they can do> |
+| `<role-2>` | <what they can do> |
+| `<role-3>` | <what they can do> |
+
+**Known intent (please verify by attack):**
+- An agent in Tenant A should get **403/404** on Tenant B's resources across every group-scoped endpoint.
+- <Other intent statements>
+
+## 5. Test accounts (provisioned in dev env)
+
+> **Real values stored in <vault name>** — share via Bitwarden/1Password link, **not** via email/Slack.
+
+| Username | Role | Tenant | Purpose |
+|---|---|---|---|
+| `pentest-agent-a1@...` | agent | Tenant A | Baseline agent |
+| `pentest-agent-a2@...` | agent | Tenant A | Same-tenant collision tests |
+| `pentest-agent-b1@...` | agent | **Tenant B** | Cross-tenant isolation tests ← primary IDOR target |
+| `pentest-manager-a@...` | manager | Tenant A | Manager privilege boundary |
+| `pentest-manager-b@...` | manager | Tenant B | Cross-tenant manager boundary |
+| `pentest-admin@...` | admin | (tenant-wide) | Privilege-escalation baseline |
+
+**Pre-seeded data:**
+- ~N resources across Tenants A and B
+- A few with attached media — good for media-ACL tests
+- Notifications (read + unread) for each test agent
+
+## 6. Out of scope (rules of engagement)
+
+- **Third-party infrastructure** (their API, their webhook origin). Test our handling, not their service.
+- **Cloud control plane** — IAM probing, account enumeration, bucket bruteforcing across the org.
+- **DoS / volumetric** — no load attacks, no fork bombs, no concurrency exhaustion.
+- **Social engineering** of <client> staff or customers.
+- **Production** environment — dev/test URLs only.
+- **Real customer data** — even if you find a path to it, do not exfiltrate beyond a single proof sample, and notify <contact> immediately.
+
+## 7. Things to focus on (without telling you the answers)
+
+In rough order of where I'd spend time if I were you:
+
+1. **Cross-tenant authorization.** Every `/api/...` route that takes a resource ID — does it verify the resource belongs to a tenant the caller can see?
+2. **Token exposure.** Token lifetime, refresh, revocation on logout, XSS sinks.
+3. **Media proxy.** Can an agent in Tenant A fetch a media key belonging to Tenant B? Are object-storage keys guessable / sequential?
+4. **Webhook endpoint.** Signature bypass, replay window, oversized payloads, malformed JSON, source spoofing.
+5. <Other focus areas>
+
+## 8. What you will NOT receive (and why)
+
+- My internal findings, ZAP/Semgrep/Prowler output, suspected weak spots. These would bias your testing and reduce the value of comparing your results against mine afterward.
+- Source code. If <client> wants a code review as part of this engagement, that's a separate ask and I'll provide a read-only repo link.
+- Prod credentials.
+
+After your report is in, I'll share my findings and we'll diff them — the **overlap** validates tooling, the **delta in both directions** is the real signal.
+
+## 9. Communication
+
+- **Real-time questions:** <chat handle>
+- **Findings:** Final report + raw evidence to <sponsor email>
+- **Suspected high/critical mid-test:** Page <contact> immediately.
+- **If you accidentally hit prod:** Stop, ping <contact>, do not delete logs.
+
+## 10. Reporting format we'd like
+
+Per finding:
+- Title
+- Severity (CVSS 3.1 vector + score)
+- Affected endpoint(s) / component
+- Reproduction steps (curl or HTTP request preferred over screenshots)
+- Impact (what an attacker actually gets)
+- Suggested remediation (optional but appreciated)
+
+---
+
+_Last updated: <YYYY-MM-DD>_

websec_validator/templates/reports/per-tool-FINDINGS.md.template

@@ -0,0 +1,37 @@
+# <Tool> findings — <YYYY-MM-DD>
+
+> Hand-written triage of `<tool>` output. Raw evidence in this folder
+> (e.g. `<tool>-baseline.json`, `<tool>-current.json`).
+
+## Run command
+
+```bash
+<the exact command, so anyone can re-run it>
+```
+
+## Summary
+
+- Raw alerts: <N>
+- Real findings: <N>
+- False positives triaged: <N>
+
+## Real findings
+
+### 1. <Title> — <severity>
+
+- **What:** <1-2 sentences>
+- **Where:** `<file:line>` or `<endpoint>`
+- **Evidence:** <log excerpt / response body / commit hash>
+- **Action:** <what to do, who owns it>
+
+### 2. ...
+
+## False positives (do not "fix")
+
+| Alert | Cause | Why FP |
+|---|---|---|
+| <alert name> | <what the tool detected> | <why it's a FP — link to file:line or test that proves it> |
+
+## Notes for next run
+
+- <Anything that surprised you, anything to investigate further next time>

websec_validator-0.2.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: websec-validator
+Version: 0.2.0
+Summary: Local-first security recon that briefs your AI coding agent: facts + tailored probe scripts, code-in / artifacts-out. No LLM, no server, no running app.
+Author: Ricardo Accioly
+License: MIT
+Keywords: security,pentest,sast,dast,bola,ai-agent,appsec
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# websec-validator
+
+> Local-first security recon that **briefs your AI coding agent**. It does the deterministic
+> half — read the repo, map the full attack surface, run + de-duplicate the static scanners, and
+> stage a probe library tailored to what it found — then hands your agent (Claude Code, Codex,
+> Gemini, Cursor) a marching-orders briefing. **Code in, artifacts out. No LLM in the tool, no
+> server, no running app required.**
+
+It is *not* an autonomous scanner and *not* a SaaS. It's the missing front-half: the thing that
+turns a repo into a precise, fact-grounded security brief an AI agent (with a human in the loop)
+can act on — an auto-filled, repo-aware version of a senior pentester's "here's what to test and
+how" handoff. Full landscape + why this niche is real: [`MARKET-ANALYSIS-AND-VERDICT.md`](MARKET-ANALYSIS-AND-VERDICT.md).
+
+## Quickstart — just point it at your repo
+
+**Simplest: tell your AI agent.** In Claude Code (or any coding agent), open your project and say:
+
+> *"Install and run the security tool at github.com/raccioly/websec-validator on this repo, then follow its briefing."*
+
+It installs, runs, and walks the findings with you. There's nothing to host and no website — it's
+local. The four ways to get there, all ending in the same `AGENT-BRIEFING.md` your agent acts on:
+
+| Path | One-time setup | Then |
+|---|---|---|
+| **Tell your agent** (simplest) | — | say the line above |
+| **CLI** (a terminal) | `pipx install websec-validator` | `websec run /path/to/your/app` |
+| **Claude Code plugin** (slash) | `/plugin marketplace add raccioly/websec-validator`  →  `/plugin install websec-validator@websec-plugins` | invoke the **security-pass** skill, or just ask |
+| **Docker** (no install) | `docker build -t websec-validator .` | `docker run --rm -v "$PWD:/scan" websec-validator run /scan --out /scan/websec-out` |
+
+➡️ **Want the reasoning behind every check?** Read **[docs/METHODOLOGY.md](docs/METHODOLOGY.md)** — what each test does and why.
+
+## Install
+
+```bash
+pipx install websec-validator   # from PyPI
+brew install noir               # OWASP Noir — the route engine (50+ frameworks); regex fallback if absent
+websec --version
+```
+
+_Until the first PyPI release publishes (or for bleeding-edge), install straight from source instead:_
+`pipx install git+https://github.com/raccioly/websec-validator` (or from a clone: `pipx install .`).
+
+Requires **Python 3.11+** (on stock macOS, `python3` is often 3.9 — use `pipx`, which picks a newer
+interpreter, or install via Homebrew/pyenv). Zero Python runtime dependencies: it shells out to
+scanners (Trivy, Gitleaks, Semgrep/OpenGrep, Checkov, Prowler) and Noir **when present**, reports
+what's missing, and never hard-fails if a tool is absent.
+
+### Or run via Docker (everything bundled, zero install)
+
+No need to install Noir or any scanner — the image bundles them all (arch-aware, amd64 + arm64):
+
+```bash
+docker build -t websec-validator .
+docker run --rm -v "$PWD:/scan" websec-validator run /scan --out /scan/websec-out
+```
+
+The image carries Noir + Trivy + Gitleaks + Semgrep + Checkov; mount your repo at `/scan` and the
+artifacts land in `/scan/websec-out`.
+
+## Use
+
+```bash
+websec run ./my-app           # ← the one command: recon + stage tailored probes + emit the briefing
+websec ./my-app               # same thing — a bare path defaults to `run`
+websec run ./my-app --scan    # …and also execute the available static scanners
+websec doctor ./my-app        # (optional) which scanners are installed?
+```
+
+Then point your agent at the output: **"Read `websec-out/AGENT-BRIEFING.md` and follow it."**
+
+> That's the whole user surface: **`run`** (plus the optional, advanced **`dynamic`** live-probing step below). `recon`/`proof`/`calibrate` exist for developing the tool itself and are hidden from `--help` — you never need them.
+
+## What it extracts (11 deterministic extractors, no LLM)
+
+| | Dimension | Notable output |
+|---|---|---|
+| stack | languages, frameworks, datastores | monorepo-aware (aggregates every manifest) |
+| routes | every endpoint via **OWASP Noir** | method · path · typed params · code path |
+| auth | scheme + login surface | multi-scheme (primary jwt > passport), PyJWT/NextAuth/session aware |
+| **authz** | access-control map | guard coverage + **write endpoints with no visible guard** + roles |
+| tenant | multi-tenancy key candidates | the BOLA boundary, by frequency |
+| surface | 12 user-input-gated sink classes | SSRF/SQLi/NoSQLi/traversal/SSTI/redirect/deser/XXE/proto-pollution/ReDoS/cmd/eval |
+| schemas | data models + **privileged fields** | Pydantic/SQLAlchemy/Django/Prisma/Mongoose/TypeORM/Zod → `role`/`isAdmin`/`groupId` for mass-assignment targeting |
+| iac_ci | IaC + CI/CD | GitHub Actions injection, unpinned actions, Dockerfile-root, tfstate |
+| client_exposure | browser leakage | `NEXT_PUBLIC_*` secrets, server-secret-in-client, source maps |
+| graphql | GraphQL surface | introspection / playground / missing depth-limit |
+| integrations | third-party + webhooks | webhooks missing signature verification |
+
+Plus **derived targeting** — IDOR / SSRF / open-redirect / upload / write / auth-endpoint
+candidates — so probes get pointed at the *exact* endpoints, not fired blindly.
+
+## What you get (`websec-out/`)
+
+| Artifact | What it is |
+|---|---|
+| `AGENT-BRIEFING.md` | **The product.** Marching orders: detected surface, the access-control map, targeting, findings, the method, and the staged probe list. |
+| `FACTS.json` | The full structured recon. |
+| `findings.json` | Static scanner results, **de-duplicated across tools** and severity-ranked (with `--scan`). |
+| `findings-ledger.json` / `REPORT.md` | The traceable ledger: each finding with an evidence chain, CWE/ASVS/OWASP-API citation, remediation, and a **calibrated `P(real)`** (measured real-vuln rate + 95% CI + sample size). |
+| `probes/` | The probe scripts selected + staged for *this* app (BOLA, JWT, SSRF, mass-assignment…). |
+
+## The flow
+
+```
+🔧 websec (deterministic)              🤖 your agent + 🧑 you
+─────────────────────────────────      ─────────────────────────────────
+1. recon → full attack surface     →   confirm the tenant boundary + auth model
+2. run + de-dup static scanners    →   triage real-vs-noise
+3. stage tailored probes           →   fill placeholders, run vs a TEST instance
+4. emit AGENT-BRIEFING.md           →   propose fixes, re-run to confirm, report back
+```
+
+Static recon + briefing need **only the code**. *Running* the probes needs a live test instance +
+test credentials (the human supplies them) — the tool itself never touches a running app.
+
+## Proof harness
+
+`websec proof` clones a vuln-app corpus (VAmPI, NodeGoat, DVGA) and scores whether recon surfaces
+each app's documented attack surface — a deterministic, CI-trackable proxy (currently **10/10**).
+The real kill-criterion (does the briefing lift an agent's bug-finding vs a generic prompt?) is the
+manual A/B in [`corpus/PROOF-PROTOCOL.md`](corpus/PROOF-PROTOCOL.md).
+
+## Calibrated confidence
+
+`websec calibrate` runs the ledger against the labeled corpus, measures how often each
+*(attack-class, confidence)* bucket is a **real** documented vuln, and writes `calibration.json`
+(shipped + applied at runtime). Each finding then carries `P(real)` with a **95% Wilson confidence
+interval** and the sample size `n` — so "MEDIUM" stops being a vibe and becomes "real ~57% of the
+time on the corpus (CI 43–70%, n=51)". A finding that matches no documented vuln counts as a false
+positive (the corpus is well-documented). **Honest caveats:** the corpus is *deliberately
+vulnerable*, so the rates skew **optimistic** for clean production code, and small samples mean
+**wide intervals** — the CI is the headline, not the point estimate, and both tighten as the corpus
+grows. With thin data a bucket falls back to the per-label aggregate, then to a clearly-flagged
+uncalibrated prior. No ML, no deps — binomial proportion + Wilson interval; the structure upgrades to
+isotonic regression if a large labeled set ever exists.
+
+**It self-improves.** `websec dynamic` is an *oracle*: a write that executes unauthenticated is a
+confirmed real vuln, and a recon-flagged endpoint that turns out auth-enforced is a confirmed false
+positive. Every dynamic run folds those confirmed labels into a **local overlay** (`~/.cache/websec-validator/`,
+gitignored, never shipped) that's merged on top of the public table — so the numbers **personalize to
+your apps** the more you run it, with no extra step and nothing leaving your machine. To label by hand
+instead, feed a `{attack_class, confidence, is_real}` file to `websec calibrate --ingest`.
+
+## Dynamic phase (v2 — read-only so far)
+
+When you have a *running TEST instance*, `websec dynamic` mints role tokens and runs the probes the
+static recon pointed at. v1 is **read-only**: authenticated **cross-tenant BOLA** on the group-scoped
+GET endpoints recon discovered.
+
+```bash
+cp dynamic-config.example.json dynamic-config.json    # TEST target + role creds (gitignored)
+websec run ./my-app                                    # static recon → websec-out/FACTS.json
+websec dynamic --config dynamic-config.json --facts websec-out/FACTS.json
+# → "14/14 cross-tenant GET reads blocked — all isolated"   (or 🚨 LEAK with the exact endpoint)
+```
+
+Never point it at production. Write-verb BOLA, JWT/auth attacks, and a ZAP/Nuclei two-role diff are
+the next dynamic probes (explicitly gated — they mutate).
+
+## Validated on
+
+HugoCross (Next.js), `wu-whatsappinbox` (106-service Express/AWS monorepo), VAmPI, NodeGoat, DVGA —
+independently reproducing a hand-done pentest's findings (tenant boundary, SSO-endpoint SSRF, media
+upload, conversation-BOLA routes, roles).
+
+## Tests
+
+```bash
+python3 -m unittest discover -s tests    # stdlib only, no Noir/network — 23 tests
+```
+
+## Releasing (maintainer)
+
+Published to PyPI via **Trusted Publishing** (OIDC — no API token in the repo). To cut a release:
+
+```bash
+# 1. bump the version in pyproject.toml (e.g. 0.2.0 → 0.2.1)
+# 2. tag it and push — the tag must match pyproject's version (CI verifies):
+git tag v0.2.1 && git push origin v0.2.1
+# → .github/workflows/publish.yml builds + publishes to PyPI
+```
+
+One-time PyPI setup (before the first release): on pypi.org → **Account → Publishing → Add a pending
+publisher** with project `websec-validator`, owner `raccioly`, repo `websec-validator`, workflow
+`publish.yml`, environment `pypi`. The project is created on the first successful publish.
+
+> Two independent channels, two update mechanisms: the **CLI** ships to **PyPI** (semver releases,
+> `pip install --upgrade`); the **Claude Code plugin** ships from **git** (tracks latest commit,
+> refreshed via `/plugin marketplace update`).
+
+## Status / roadmap
+
+**Done:** 11-extractor recon (incl. schema/entity → mass-assignment targeting), cross-tool de-dup,
+tailored probe staging, agent briefing, traceable findings ledger with **calibrated confidence
+(CJE — Wilson CIs)**, proof harness, test suite, **Docker bundle** (all scanners + Noir, arch-aware),
+**dynamic phase v1** (authenticated read-only cross-tenant BOLA — validated live, reproduced a
+hand-pentest's 14/14).
+**Next:** dynamic write-verb BOLA + JWT/auth probes + ZAP/Nuclei two-role diff (gated, they mutate),
+calibration on hand-labeled real repos (more representative base rate), ASVS index lookup, optional
+model-SDK adapters for no-agent fallback.
+
+## Using it as a Claude Code skill / plugin
+
+This repo **is** a Claude Code plugin. Install it once —
+
+```
+/plugin marketplace add raccioly/websec-validator
+/plugin install websec-validator@websec-plugins
+```
+
+— and the bundled **security-pass** skill ([`skills/security-pass/SKILL.md`](skills/security-pass/SKILL.md))
+lets you just ask, in plain English, for a security pass: it runs `websec`, reads the briefing, and
+works the findings with you. For other agents the universal interface is unchanged: run the CLI, read
+`AGENT-BRIEFING.md`.
+
+## Credits
+
+Methodology + probe library come from a real authenticated pentest pass
+([`base-research/REPLICATION-PLAYBOOK.md`](base-research/REPLICATION-PLAYBOOK.md), not committed).
+This tool productizes that hand-written pass into something an AI agent can run on any repo.