Heretic (n.) — one who breaks the sacred rules. This tool breaks the rules an application assumes but never enforces.

HERETIC is a CLI tool (in the spirit of nmap, sqlmap, nuclei) that reasons about an app's business intent, then systematically tries to violate it: IDOR/BOLA, broken function-level auth, excessive data exposure, price tampering, workflow bypass, mass assignment, race conditions.

It is not another signature scanner. Signature scanners find XSS / SQLi / CVEs. HERETIC finds the ~70% of critical web bugs that have no signature — where the code did exactly what it was told, but what it was told violated the business rules. It reasons about intent with an LLM, but never trusts the LLM to confirm a bug — a deterministic Oracle proves every finding, which is why the false-positive rate is ~0%.

heretic scan -u https://target.local --roe roe.yaml --accounts accounts.yaml

👀 See it work — real output, live OWASP Juice Shop

Real recording — offline FP-gate, then live Juice Shop and VAmPI. Reproduce with scripts/demo.sh · replay the raw cast with asciinema play docs/demo/heretic-demo.cast.

Not a mock-up. This is HERETIC against a live bkimminich/juice-shop container — model auto-detected, basket id harvested from the login response, attack surface discovered from the SPA's JS bundle.

  CONFIRM excessive_data_exposure — basketitem list leaks all users' records
  CONFIRM bfla — admin function /rest/admin/application-configuration is exposed to unauthenticated users
  CONFIRM mass_assignment — registration at /api/Users accepts privileged field 'role'
  CONFIRM price_tamper — /api/BasketItems accepts a negative quantity (-100)
  CONFIRM workflow_bypass — order finalized at /rest/basket/6/checkout without a payment step
────────────────── 7 confirmed · 17 dropped (false positives) ───────────────────

Five business-logic classes confirmed on a live app in one command — with 0 false positives. The 17 "dropped" are candidates the Oracle refused to confirm (SPA catch-alls, public catalogs, the LLM's wrong guesses). Every confirmation is deterministic and reproducible.

It even catches itself hallucinating — when the LLM invents an endpoint that isn't on the target, HERETIC detects it and regenerates grounded on the real surface:

Phase 3b hypotheses — logic classes (LLM + knowledge)
  ⚠ hallucination detected — 1/3 test(s) referenced endpoints not on the real surface (33%); regenerating grounded
  ✓ self-corrected — added 3 grounded test(s)

✅ Validation

Two independent proofs — one you can run right now, one you can reproduce against real targets.

Offline — every build, no key, no network (heretic bench, wired into CI):

Live — reproducible with heretic livecheck (the read-only classes need no LLM key):

Coverage today: 9 business-logic classes — 7 fully mechanical + coupon_abuse (deterministic) + auth_flow (LLM-driven). Login auto-detection spans JSON/JWT · session-cookie · CSRF-guarded · form-encoded flows.

Offline metrics are checked on every commit. The live numbers reproduce from the profiles in targets/ — see docs/09-LIVE-VALIDATION.md. Real-world FP on hardened production apps is not yet independently measured; ~0% reflects the three deliberately-vulnerable targets above.

🏆 Why HERETIC wins

The one-liner: signature scanners find bugs that have a pattern; the ~70% of critical web bugs that don't — the logic flaws — need reasoning about intent. HERETIC reasons with an LLM but proves with deterministic code, so it gets the logic coverage of a human without the false positives of an AI toy.

📋 Table of contents

• Validation
• Why HERETIC wins
• Install
• Quickstart (60 seconds)
• The three ways to run it
• Command reference
• Choosing an AI model
• Configuration
• What it finds (bug classes)
• How it works
• Output & reporting
• Run it in CI
• Safety & legal
• FAQ
• Docs

📦 Install

Requirements: Python 3.11+. An AI key is optional (see models) — HERETIC runs the deterministic classes with no key at all.

Optional extras (install only what you need):

pip install -e ".[browser]"    # headless-browser XHR capture (Playwright) — for JS-heavy SPAs
pip install -e ".[gemini]"     # the gemini-flash backend
pip install -e ".[rag]"        # swap keyword knowledge store for embeddings (ChromaDB)

Verify the install:

heretic version
heretic bench      # offline self-test — no network, no API key. Should report FP-rate 0%.

🖥️ Platform setup — Windows / macOS / Linux

Step-by-step for each OS. Pick your tab.

# 1. Install Python 3.11+ (skip if you have it)
winget install Python.Python.3.12

# 2. Install HERETIC in an isolated environment
py -m pip install --user pipx
py -m pipx ensurepath           # then reopen PowerShell
pipx install heretic-agent

# 3. (optional) Give it an AI key — this shell only
$env:NVIDIA_API_KEY = "nvapi-xxxxxxxx"
#    …or persist across shells (reopen the terminal after):
setx NVIDIA_API_KEY "nvapi-xxxxxxxx"

# 4. Confirm the setup (does the key actually work?)
heretic doctor --ping

# 5. Run it
heretic connect

git clone https://github.com/SYCO7/heretic.git
cd heretic
py -m venv .venv
.\.venv\Scripts\Activate.ps1     # if blocked: Set-ExecutionPolicy -Scope Process RemoteSigned
pip install -e ".[dev]"
heretic version

# 1. Install Python 3.11+ and pipx via Homebrew
brew install python@3.12 pipx
pipx ensurepath                 # then reopen Terminal

# 2. Install HERETIC
pipx install heretic-agent

# 3. (optional) AI key — add the export line to ~/.zshrc to persist
export NVIDIA_API_KEY="nvapi-xxxxxxxx"

# 4. Run it
heretic connect

git clone https://github.com/SYCO7/heretic.git && cd heretic
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
heretic version

brew install ollama
ollama serve &                  # start the daemon
ollama pull qwen2.5:7b          # HERETIC auto-selects it — nothing leaves your Mac

# 1. Python 3.11+ (Debian/Ubuntu shown; use your package manager)
sudo apt install -y python3 python3-venv python3-pip pipx
pipx ensurepath

# 2. Install HERETIC
pipx install heretic-agent

# 3. (optional) AI key — add to ~/.bashrc to persist
export NVIDIA_API_KEY="nvapi-xxxxxxxx"

# 4. Run it
heretic connect

git clone https://github.com/SYCO7/heretic.git && cd heretic
python3 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
# or: docker build -t heretic . && docker run --rm heretic --help

Using --browser (SPA XHR capture)? After installing the browser extra, fetch the engine once: playwright install chromium (works the same on all three OSes).

Prefer a .env file over shell exports? Drop a .env in your working directory — HERETIC auto-loads it on every command, on every OS:

NVIDIA_API_KEY=nvapi-xxxxxxxx

⚡ Quickstart (60 seconds)

The easy path — no config files to write. Point it at your app, give it two logins, done:

heretic connect

connect will:

1. Ask for the target URL and two test accounts.
2. Auto-detect the login endpoint and where the token lives in the response (handles OTP / MFA / SSO — just paste a bearer token when prompted).
3. Auto-detect your AI model — a hosted key or a local Ollama model, whichever is best available.
4. Discover the attack surface, run the scan, and print confirmed findings.

Or launch the full interactive menu:

heretic          # menu: Connect · Auto · Doctor · Scan · Models · Keys …

💡 No AI key and no Ollama? It still runs — the deterministic classes (BOLA, BFLA, data-exposure) need no LLM and never change state. You get real findings offline.

🚀 The three ways to run it

Pick the entry point that matches how much control you want:

1. Guided — heretic connect / heretic auto

Zero config. Best for a first run or a quick look at an app.

heretic auto -u https://target.local --profile targets/crapi

Runs the whole assessment end-to-end (every class + chaining) and writes an HTML report.

2. Full control — heretic scan

The scriptable workhorse. You supply roe.yaml + accounts.yaml and choose exactly what runs.

heretic scan -u https://target.local --roe roe.yaml --accounts accounts.yaml \
  --discover --chain --iterate 3 --report findings.html

3. Score it — heretic livecheck

Run against a known target and grade precision / recall / FP vs ground truth. This is how you prove the tool works.

heretic livecheck --profile targets/juiceshop -u http://localhost:3000

🧭 Command reference

Every command. Run heretic <command> --help for the full flag list.

heretic scan — every flag

heretic scan -u <URL> --roe <roe.yaml> --accounts <accounts.yaml> [options]

# First run against an app you have no config for — let it discover everything
heretic scan -u https://app.local --roe roe.yaml --accounts accounts.yaml --discover

# Only the read-only classes (safe on production, no LLM key needed)
heretic scan -u https://app.local --roe roe.yaml --accounts accounts.yaml \
  --classes bola,bfla,excessive_data_exposure

# Full assessment with chaining, retries, resumable checkpoint + HTML report
heretic scan -u https://app.local --roe roe.yaml --accounts accounts.yaml \
  --discover --chain --iterate 3 --save run.db --report findings.html

# JS-heavy Angular/React SPA — capture the runtime XHRs a static scrape misses
heretic scan -u https://spa.local --roe roe.yaml --accounts accounts.yaml --browser

# Resume after an interruption
heretic resume --engagement run.db --report findings.html

# CI gate — fail the build on any HIGH+ finding, emit SARIF
heretic scan -u https://staging.local --roe roe.yaml --accounts accounts.yaml \
  --classes bola,bfla,excessive_data_exposure --sarif heretic.sarif --fail-on high

🤖 Choosing an AI model

HERETIC talks to any OpenAI-compatible endpoint over plain HTTP (no vendor SDK). It auto-detects the best model available — a hosted key or a local Ollama model — so you usually don't pass --model at all.

Set a key (any one is enough) via env var or a .env file in the working directory:

# .env  (auto-loaded, gitignored — never commit keys)
NVIDIA_API_KEY=nvapi-xxxxxxxx

Go fully offline / private with a local model:

ollama pull qwen2.5:7b      # or any model; HERETIC auto-selects the largest local one
heretic scan ...            # --model omitted → uses your local model, no data leaves the host

Check what's wired up before a run:

heretic doctor -u https://target.local

⚙️ Configuration

You need two files. Generate starters with heretic init, then edit.

1. roe.yaml — Rules of Engagement (the authorization gate)

HERETIC refuses to run without a valid, signed RoE. This is a hard security boundary — the LLM cannot override it.

engagement:    "my lab engagement"        # free-text label
authorized_by: "you@example.com"          # REQUIRED — who authorized this test
signed:        true                        # REQUIRED — must be true or it refuses to run

scope:
  allow:                                   # every request target MUST match one of these
    - "*.target.local"
    - "127.0.0.1"
    - "10.0.0.0/8"                         # CIDR ranges supported
  exclude:                                 # never touch these, even if in allow
    - "*/admin/delete*"

mode:          dry-run                      # dry-run (read-only) | live (allows state changes)
max_rate_rps:  5                            # request rate cap — don't DoS the target
max_parallel:  3                            # concurrency cap for race-condition tests

destructive_allowed: []                     # e.g. ["price_tamper"] or ["*"] to fire state-changing tests
classes: [bola, bfla, excessive_data_exposure]   # omit for all classes

# Optional: a header sent on EVERY request (e.g. bug-bounty program attribution)
# headers:
#   X-Bug-Bounty: "your-handle"

# Objects to harvest ids from + test for BOLA (omit entirely to auto-discover):
objects:
  - name:      order
    list_url:  "/api/orders"               # each role fetches its OWN orders (harvest ids)
    item_url:  "/api/orders/{id}"          # non-owners are tested against this (cross-role BOLA)
    id_field:  "id"                         # the id key inside each list item
    # list_path: "data"                     # dotted path to the array, if nested

# When the owned id comes from the LOGIN response, not a list endpoint
# (e.g. Juice Shop hands you your basket id at login):
login_objects:
  - name:     basket
    item_url: "/rest/basket/{id}"
    id_from:  "authentication.bid"          # dotted path in the login JSON

# Race / TOCTOU probes — fire N identical requests, confirm no more than
# `expect_max_success` succeed (e.g. a single-use coupon applied twice):
races:
  - name:     coupon_double_apply
    url:      "/api/coupon/apply"
    method:   POST
    body:     { code: "SAVE10" }
    as_role:  userA
    parallel: 10
    expect_max_success: 1

# Coupon abuse — redeem a single-use code repeatedly IN SERIES (not concurrent;
# that's `races:`). Confirmed if the server accepts it more than `max_uses` times:
coupons:
  - name:       welcome10
    url:        "/api/coupon/apply"
    code:       "WELCOME10"
    code_field: "code"                      # body field carrying the code
    as_role:    userA
    max_uses:   1                           # single-use
    success_field: "applied"                # optional: dotted field marking a redemption

# Per-phase model routing (only used with `--model auto`):
models:
  intent:     nemotron-super
  hypothesis: ollama:nemotron-nano
  judge:      nemotron-super
  refute:     openrouter-r1

2. accounts.yaml — test identities (operator-owned only)

HERETIC uses multiple roles at once for differential (cross-session) testing — that's how it proves BOLA.

login:
  url:         "/api/auth/login"
  method:      "POST"
  token_field: "token"                       # json field · dotted "data.token" · or "cookie:session"
  auth_header: "Authorization: Bearer {token}"

roles:
  - { name: guest, creds: null }                                               # unauth baseline
  - { name: userA, creds: { email: "userA@test.local", password: "Pass123!" } }
  - { name: userB, creds: { email: "userB@test.local", password: "Pass123!" } }  # the "victim" for BOLA
  - { name: admin, creds: { email: "admin@test.local", password: "Admin123!" } }

🔎 heretic connect auto-detects all of this — including session-cookie logins (Django / Rails / PHP / Express → token_field: "cookie:NAME"), CSRF-guarded logins (Laravel / Angular / Rails — it pre-fetches and replays the token via a csrf: block), and form-encoded logins (content_type: "form"). You rarely write this file by hand.

🔑 OTP / MFA / SSO? You can't script those logins — so paste a token instead. Give the role a token: field with a bearer token grabbed from your browser, and HERETIC skips login for that identity:

  - { name: userA, token: "eyJhbGciOi..." }

login:
  url:          "/api/login"
  method:       "POST"
  content_type: "form"                 # or "json"
  token_field:  "cookie:session"       # auth lives in a Set-Cookie, not a JSON token
  auth_header:  "Cookie: session={token}"
  csrf:                                # pre-fetch a CSRF token and replay it on login
    fetch_url:  "/login"               # GET this first (seeds the token)
    source:     "cookie:XSRF-TOKEN"    # cookie:NAME | meta:NAME | input:NAME | json:dotted
    header:     "X-XSRF-TOKEN"         # send the token in this header …
    # field:    "_csrf"                # … and/or this body field

roles:
  - { name: guest, creds: null }
  - { name: userA, creds: { username: "userA", password: "Pass123!" } }
  - { name: userB, creds: { username: "userB", password: "Pass123!" } }

⚠️ accounts.yaml holds credentials — it's gitignored by default. Never commit it, never use real end-user data.

🎯 What it finds

✅ read-only classes are safe to run against production — no LLM key required, no state changed. ⚠️ state-changing classes are gated: they only fire in --mode live and when listed in the RoE's destructive_allowed. In dry-run they're skipped and the tool tells you why.

coupon_abuse runs deterministically from a coupons: RoE block (see below); auth_flow is LLM-driven (needs a model). The rest of the state-changing set is fully mechanical.

🧠 How it works

The LLM proposes; deterministic code enforces and confirms. That split is the whole design — an LLM is great at guessing where a logic bug might be, and terrible at being trusted that one happened.

flowchart LR
    A[1. Recon<br/>multi-role login<br/>+ id harvest] --> B[1b. Discovery<br/>OpenAPI · JS · browser<br/>· wordlist · list→detail]
    B --> C[2. Intent model<br/>LLM extracts<br/>business invariants]
    C --> D[3. Hypotheses<br/>invariant-violation<br/>tests + knowledge]
    D --> E[4. Execute<br/>scope-gated,<br/>rate-limited]
    E --> F[5. ORACLE<br/>prove it or drop it<br/>= the moat]
    F --> G[6. Chain<br/>compose primitives<br/>into higher impact]
    G --> H[Report<br/>table · html · json · SARIF]

• Recon logs in as every role and harvests the ids each one owns.
• Discovery finds the attack surface itself — parses OpenAPI/Swagger, extracts API routes from SPA JS bundles, optionally drives a headless browser to capture runtime XHRs, and follows list endpoints to real item endpoints (/thing/{id}) — so you don't hand-write objects:.
• Intent model (LLM) reads the observed API and writes down the business rules it should enforce.
• Hypotheses turn each invariant into a concrete test. Invented endpoints are detected and regenerated against the real surface (anti-hallucination).
• Oracle is the moat: a business-logic bug throws no error and returns 200 OK, so the Oracle proves an invariant was violated — deterministically where possible, and with an adversarial 3-skeptic refuter panel for the LLM-judged classes. An LLM can never veto a deterministic proof.
• Chain composes confirmed primitives (e.g. two BOLA reads → bulk exfiltration).

Full detail: docs/01-ARCHITECTURE.md · docs/03-ORACLE.md · docs/02-WORKFLOWS.md.

📤 Output & reporting

Every finding carries a proof bundle: the oracle used, the evidence (status codes, body similarity, distinct owners, …), a reproducible PoC request sequence, a confidence score, and a remediation.

🔁 Run it in CI

Because every finding is Oracle-proven (~0 FP), a failing build is a real bug, not AI noise — the property that makes a security gate developers keep switched on.

# .github/workflows/heretic.yml
- uses: SYCO7/heretic@v1.0.0
  with:
    url: https://staging.example.com
    roe: roe.yaml
    accounts: accounts.yaml
    classes: bola,bfla,excessive_data_exposure   # read-only set — safe on every PR, no LLM key
    fail-on: high
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: heretic.sarif }

The read-only classes need no LLM key and never change state, so they're safe on every PR. Run the state-changing classes on a schedule against staging. See docs/CI.md.

🛡️ Safety & legal

HERETIC is built for authorized testing only and enforces it in code:

• Authorization gate — refuses to run without a signed RoE naming who authorized the test.
• Scope allowlist — every request is checked against scope.allow (host globs + CIDR) before it leaves the process; anything out of scope or matching exclude is hard-blocked. The LLM cannot bypass this.
• Read-only by default — dry-run mode does no state changes. State-changing classes fire only in live mode and when explicitly listed in destructive_allowed.
• Rate limited — max_rate_rps / max_parallel throttle every identity so you don't stress the target.

Only test systems you own or are explicitly authorized to assess. See docs/07-GUARDRAILS.md.

❓ FAQ

📚 Full documentation

🤝 Contributing & license

Issues and PRs welcome. Run the suite before pushing:

make test      # pytest
make bench     # offline FP-gate
make lint      # ruff

License: Apache-2.0. Lab-first — authorized testing only.