Most API scanners run through a fixed list of known patterns — SQLi payloads, OWASP wordlists, common headers. They're decent at catching what they already know about. What they miss is the logic that's specific to your API: the checkout flow that accepts a negative quantity, the admin endpoint that blocks GET but not POST, the WebSocket handler that falls over on a prototype pollution payload.

Entropy hands your API schema to an LLM and asks it to think like an attacker. It generates multi-step attack sequences based on your actual endpoints and data models, runs them, diffs the responses against a clean baseline, and only surfaces the ones that look like real issues.

Works with OpenAPI specs, GraphQL schemas, or nothing at all — it can crawl the target and figure out the endpoints itself.

---

Install

pip install entropy-chaos

Python 3.10+ required. Only hard dependency is PyYAML.

---

⚠️ --live flag — read this first

By default, entropy runs in dry-run / simulation mode. No HTTP requests are sent to your target. All findings are simulated.

To actually scan something, you need --live:

# This does nothing real — simulated output only
entropy run --target https://api.example.com --discover

# This actually scans
entropy run --target https://api.example.com --discover --live

The terminal output says Mode : DRY RUN (simulation) when live is off. If you see that line, your target has not been touched.

---

Basic usage

# Dry run — safe to run anywhere, no requests sent
entropy run --spec openapi.yaml --target http://localhost:8000

# Live scan — actually sends requests
entropy run --spec openapi.yaml --target http://localhost:8000 --live

# No spec — discover endpoints automatically, then scan
entropy run --target https://api.example.com --discover --live

# Full scan with a real LLM backend
entropy run --spec api.yaml --llm anthropic --profile full --live
# ANTHROPIC_API_KEY is read from the environment

---

How it works

Attack generation. Entropy parses your schema, maps out the data model and auth structure, then sends it to an LLM with the instruction to think adversarially. The output isn't just a list of payloads — it's multi-step attack chains like "authenticate as user A, grab the session token, then try to pull user B's data with it."

Personas. Five attacker archetypes run in parallel:

Persona	What it tests
malicious_insider	Authenticated abuse — IDOR, mass assignment, privilege escalation
impatient_consumer	Timing issues — race conditions, double-spend, retry loops
bot_swarm	Volume-based issues — rate limiting, resource exhaustion
confused_user	Edge cases — type confusion, state machine bypasses, unexpected inputs
penetration_tester	Classic vulns — injection, auth bypass, SSRF, XXE

Baseline diffing. Before each attack, entropy sends a normal request to the same endpoint and records the response. A finding only gets flagged if the attack response meaningfully differs — different status code, new fields, latency spike. This cuts the noise from endpoints that were already broken before you touched them.

History. Every run writes to ~/.entropy/history.db. In CI, entropy exits non-zero when it finds issues that weren't there in the last run — useful as a regression gate.

---

LLM backends

Set the relevant env var, pass --llm <backend>:

Backend	Env var
anthropic	ANTHROPIC_API_KEY
openai	OPENAI_API_KEY
gemini	GEMINI_API_KEY
mistral	MISTRAL_API_KEY
groq	GROQ_API_KEY
ollama	(runs locally, no key)
huggingface	HF_API_KEY
mock	(no key — deterministic output, good for CI/pipeline testing)

mock generates plausible-looking attack scenarios without hitting any API. The test suite uses it. It's enough to verify your pipeline works before plugging in a real backend.

Note on --llm mock: Mock still sends real HTTP requests when --live is set — it just uses pre-generated attack payloads instead of LLM-generated ones. Results are less targeted but the scan is real.

---

v0.4 features

SSRF detection

Looks for parameters that take URLs (url, callback, redirect, webhook, src, etc.) and injects internal addresses — AWS EC2 metadata endpoint (169.254.169.254), GCP metadata, Azure IMDS, RFC1918 gateway ranges. Confirms when the server actually returns cloud metadata in the response.

SSTI detection

Tests string parameters with arithmetic probes across nine template engine dialects. {{7*7}} returning 49 confirms Jinja2 or Twig. ${7*7} confirms FreeMarker or Spring EL. FreeMarker RCE chains get escalated to CRITICAL automatically.

XXE detection

Sends <!ENTITY xxe SYSTEM "file:///etc/passwd"> payloads to any endpoint taking POST/PUT/PATCH. Covers standard XML bodies, SVG upload vectors, and parameter entity variants. Detects file content leaking into responses.

JWT security testing

Pulls JWT tokens out of scan responses and throws a few things at them: alg:none bypass, weak HMAC secret brute-force (30 common secrets), claim tampering for privilege escalation, expired token acceptance, missing exp checks. If a secret cracks, it shows up verbatim in the finding.

HTTP Request Smuggling

Timing-based CL.TE and TE.CL detection. Sends ambiguous requests and watches for latency delta vs a clean baseline. A gap over 4 seconds suggests the backend is stalling on a smuggled prefix. Needs --live and --smuggling:

entropy run --target https://api.example.com --smuggling --live

Parameter mining

Probes 80+ undocumented parameter names concurrently and flags anything that changes the response status, body size, or adds new fields. High-value targets get priority: admin, debug, is_admin, bypass, role, eval.

Multi-step IDOR chain testing

Finds endpoints with numeric path segments and walks sequential ID ranges. Flags responses that return sensitive fields (email, balance, token, medical records) for IDs the caller shouldn't be able to access.

Adaptive LLM false-positive filtering

After the scan finishes, each finding goes back to the LLM with the full request/response context. The LLM decides whether the evidence actually supports the finding or not. Filtered count shows up in the summary. Turn it off with --no-adaptive.

---

v0.3 features

Endpoint discovery

No spec file? Pass --discover:

entropy run --target https://api.example.com --discover --live

Checks robots.txt, crawls linked JS for fetch() and axios calls, probes 180+ common API paths (PHP apps, Spring Boot actuators, Django debug views), and sniffs for OpenAPI/Swagger specs at the usual locations. Runs concurrently.

# Discovery only, no fuzzing
entropy discover --target https://api.example.com

Rate limit detection

entropy ratelimit --url https://api.example.com/login --max-probes 60

Fires requests until it hits a 429 or runs out of budget, then tests bypass techniques: X-Forwarded-For rotation, X-Real-IP, trailing slash path variants. Missing rate limits come out as HIGH; bypassable ones as CRITICAL. Also runs automatically during a full scan.

Differential testing

entropy compare \
  --spec openapi.yaml \
  --target-a https://api.example.com/v1 \
  --target-b https://api.example.com/v2

Finds where two targets diverge — status code changes, dropped response fields, latency regressions. Good for checking staging against prod or catching breaking changes before a release.

Custom personas

entropy persona template > finance-insider.yaml
# edit it
entropy persona validate finance-insider.yaml
entropy run --spec api.yaml --custom-persona finance-insider.yaml --live

name: finance-insider
auth_level: read_write
attack_focus:
  - privilege_escalation
  - idor
endpoints_whitelist:
  - /api/reports
  - /api/export
payload_overrides:
  role: admin
  is_admin: true

Dashboard

entropy run --spec api.yaml --dashboard --live
# http://localhost:8080

Live findings feed over Server-Sent Events. No external JS dependencies.

WebSocket fuzzing

entropy run --spec api.yaml --ws wss://api.example.com/ws --live

15 payloads across injection, prototype pollution, oversized messages, and type confusion. Uses stdlib ssl/socket — no extra packages needed.

Proxy integration

# Send traffic through Burp Suite
entropy run --spec api.yaml --proxy http://127.0.0.1:8080 --no-verify-ssl --live

# Run entropy itself as an intercepting proxy
entropy proxy --port 8888

Watch mode

entropy run --spec api.yaml --watch --watch-interval 300 --live
entropy run --spec api.yaml --watch --watch-file api.yaml --live

---

Output formats

entropy run --spec api.yaml --live                        # Markdown + JSON + HTML
entropy run --spec api.yaml --sarif results.sarif --live  # SARIF for GitHub Code Scanning

Every run writes a Markdown summary, a JSON report, and an HTML report with severity breakdowns. JSON schema is stable across versions.

---

Scan profiles

entropy run --spec api.yaml --profile quick --live   # ~2min, critical findings only
entropy run --spec api.yaml --profile full  --live   # everything, all personas

Profile	Personas	Fail threshold	Use case
quick	2	critical	Pre-commit / fast feedback
standard	3	high	PR gate (default)
full	5	high	Nightly / pre-release
stealth	2	critical	Low-noise prod testing
ci	3	high	CI pipelines

---

CI integration

GitHub Actions

- name: Install entropy
  run: pip install entropy-chaos

- name: Run scan
  run: |
    entropy run \
      --spec openapi.yaml \
      --target ${{ env.API_URL }} \
      --llm anthropic \
      --profile ci \
      --sarif results.sarif \
      --live
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

- name: Upload to Code Scanning
  uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: results.sarif

GitLab CI

entropy:
  image: python:3.11
  script:
    - pip install entropy-chaos
    - entropy run --spec openapi.yaml --target $API_URL --llm groq --profile ci --live
  artifacts:
    reports:
      junit: entropy-report/junit.xml

---

Configuration file

Drop an entropy.yml in your project root instead of passing flags every time:

entropy run                         # picks up entropy.yml automatically
entropy run --config path/to/entropy.yml

target: http://localhost:8000
spec: openapi.yaml

llm:
  backend: anthropic

scan:
  live: true
  profile: standard
  baseline_diff: true
  rate_limit_check: true

output:
  dir: entropy-report
  sarif: results.sarif
  fail_on: high

# alerts:
#   slack_webhook: https://hooks.slack.com/...

Generate a commented template:

entropy report config-template > entropy.yml

---

Commands

entropy run        Run a scan
entropy compare    Compare two targets (v1 vs v2, prod vs staging)
entropy discover   Probe a target for endpoints without a spec
entropy ratelimit  Test rate limiting on a specific URL
entropy history    Browse previous runs (list / trend / compare)
entropy persona    Manage custom personas (template / validate)
entropy shell      Interactive REPL
entropy proxy      HTTP interception proxy
entropy backends   List available LLM backends
entropy profiles   List scan profiles
entropy owasp      List OWASP Top 10 scenarios

Full flag reference: entropy run --help

---

License

MIT — see LICENSE.

Contributing

CONTRIBUTING.md

Security

Report vulnerabilities privately — see SECURITY.md.