v0.1.0 Alpha – Getting Started

Unleash Chaos on your
API onboarding.

Spin up Chaos Kitten locally or in CI, wire it to your API, and let the agentic scanner go hunting for logic flaws, auth gaps, and crash‑only bugs.

chaos-kitten-clizsh

$ chaos-kitten scan --target http://api.localINFO 🧠 Brain initializing...INFO 📄 Parsing OpenAPI spec... 12 endpoints found.WARN 🧪 Planning attack strategies...VULN 💥 Reflected XSS found at GET /usersVULN 💣 SQL Injection found at POST /loginINFO 📊 Report generated: reports/audit.html

Prerequisitesbefore you start

Python 3.10 or higher
An API to test (ideally a local dev server)
An LLM API key (Anthropic or OpenAI)

Install Chaos Kittenstep 1

Pick the install that matches your workflow.

Option 1 – pip (recommended)

pip install chaos-kitten

Option 2 – From source

git clone https://github.com/mdhaarishussain/chaos-kitten.git cd chaos-kitten pip install -e .        # standard install (no browser) # optional: browser exploit validation pip install -e .[browser] playwright install chromium

Option 3 – Docker (isolated)

# docker compose – spins up demo API + scanner export ANTHROPIC_API_KEY=your_key_here # or: export OPENAI_API_KEY=your_key_here docker-compose up -d demo-api docker-compose run chaos-kitten scan --demo

# standalone docker docker build -t chaos-kitten . docker run --rm \ -v $(pwd)/chaos-kitten.yaml:/app/chaos-kitten.yaml \ -v $(pwd)/reports:/app/reports \ -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \ chaos-kitten scan

Authentication & MFAoptional hardening

Test MFA‑protected APIs by letting Chaos Kitten auto‑generate TOTP codes.

# install MFA extra pip install 'chaos-kitten[mfa]' # or directly # pip install pyotp

auth: totp_secret: "YOUR_BASE32_SECRET_HERE" totp_endpoint: "/api/mfa" totp_field: "code"

Quickstart workflowstep 2

step 1

Initialize config

Bootstrap a fresh chaos-kitten.yaml.

chaos-kitten init

step 2

Wire your API

target: base_url: "http://localhost:3000" openapi_spec: "./openapi.json" agent: llm_provider: "anthropic" model: "claude-3-5-sonnet-20241022"

step 3

Set API key

export ANTHROPIC_API_KEY=your_key_here

step 4

Run a scan

chaos-kitten scan

Chaos Modenegative testing

Turn on chaos to hammer your API with type flips, extreme boundaries, nulls, and Unicode edge cases.

# payment / crash‑hunting chaos-kitten scan --chaos --target http://localhost:5000 # access control chaos-kitten scan --goal \ "I want to check if admin endpoints are accessible to regular users" # authentication takeover chaos-kitten scan --goal \ "test the authentication system for account takeover risks" # maximum carnage chaos-kitten scan --chaos --chaos-level 5 --target http://localhost:5000

Chaos levels

Level	Mode	What it does
1	Gentle	Basic type mismatches
2	Moderate	Boundary values and nulls
3	Aggressive	Unicode, control chars, and large payloads
4	Destructive	Overflow, injections, nested attacks
5	Maximum carnage	All of the above combined

Reading resultsseverity model

Level	Icon	Meaning
INFO	🔵	Informational finding / context signal
CRITICAL	🔴	Immediate action required
HIGH	🟠	Should be fixed soon
MEDIUM	🟡	Should be addressed
LOW	🟢	Minor issues

Sample CLI output

🐱 Chaos Kitten v1.0.0 📋 Parsing OpenAPI spec... 🎯 Found 12 endpoints 🐾 Testing /api/login ⚠️  I knocked this vase over! (SQL Injection) Severity: CRITICAL

CI / CD wiringpipelines

Use JUnit or SARIF in GitHub / GitLab so security findings fail builds automatically.

# GitLab example security_scan: image: python:3.12 script: - pip install chaos-kitten - chaos-kitten scan --target $STAGING_URL \ --format junit --output reports \ --fail-on high --silent artifacts: reports: junit: reports/*.xml

# Useful CLI flags --format sarif   # GitHub Advanced Security --format junit   # CI test parsers --fail-on high   # exit 1 on high+ vulns --silent         # quiet mode for logs

Need help? Open anIssueor jump intoDiscussions.