The adorable AI agent that knocks things off your API tables

Quick Start • Features • How It Works • Installation • Contributing • Contributors

---

🎯 What is Chaos Kitten?

Chaos Kitten is an agentic AI security testing tool that acts like a mischievous cat—it explores your API, understands the business logic, and systematically tries to "break" things before malicious actors do. Unlike traditional fuzzers (ZAP, Burp) that spray random payloads, Chaos Kitten reasons about your API structure and crafts intelligent attacks.

� Agent thinks... "This is a login endpoint. I should test for: - SQL injection in username - User enumeration - Brute force protection"

---

🤔 The Problem

AI-powered "vibe coding" tools (Claude, Cursor, Windsurf) generate backend APIs at incredible speed, but they often skip critical security measures:

❌ Missing Auth No authentication on critical endpoints

❌ No Validation Input fields accept anything

❌ SQL Injection Queries built with string concatenation

❌ Logic Flaws IDOR, privilege escalation

Real Story: While building Bondhu (Digital Twin for mental wellness), we discovered our AI vibe coded frontend had ZERO authentication on critical endpoints. Anyone could exploit this to access user data.

Chaos Kitten finds these issues before attackers do. 🔒

---

✨ Features

🧠 The Brain (AI Orchestrator) Parses OpenAPI/Swagger specs Understands endpoint semantics Plans intelligent multi-step attacks Uses Chain-of-Thought reasoning � The Paws (Executor) Async HTTP with httpx Playwright browser automation Rate limiting & politeness controls Multiple auth methods

🧶 The Toy Box (Attack Library) SQL Injection profiles XSS payloads (reflected, stored) IDOR detection strategies Naughty strings collection Easy to contribute! 📦 The Litterbox (Reporter) Beautiful HTML reports Markdown export PoC curl commands Remediation guidance

---

�🚀 Quick Start

# Install
pip install chaos-kitten

# Initialize config
chaos-kitten init

# Run against your API
chaos-kitten scan --config chaos-kitten.yaml

Example Output

🐱 Chaos Kitten v1.0.0
📋 Parsing OpenAPI spec...
🎯 Found 12 endpoints
🧠 Planning attack strategies...

🐾 Testing /api/login
   ⚠️  I knocked this vase over! (SQL Injection found)

🐾 Testing /api/users/{id}
   ⚠️  I played with this string! (IDOR vulnerability)

📊 Report saved to ./reports/chaos-kitten-2026-01-20.html

---

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        🐱 Chaos Kitten                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌────────────────┐           ┌────────────────┐               │
│   │   🧠 Brain     │───────────│   🐾 Paws      │               │
│   │  Orchestrator  │           │   Executor     │               │
│   │                │           │                │               │
│   │  • OpenAPI     │           │  • httpx       │               │
│   │  • LLM Agent   │           │  • Playwright  │               │
│   │  • Planner     │           │  • Async       │               │
│   └───────┬────────┘           └───────┬────────┘               │
│           │                            │                         │
│           └────────────┬───────────────┘                         │
│                        │                                         │
│              ┌─────────▼─────────┐                               │
│              │   🧶 Toy Box      │                               │
│              │  Attack Profiles  │                               │
│              │                   │                               │
│              │  • SQL Injection  │                               │
│              │  • XSS Payloads   │                               │
│              │  • IDOR Tests     │                               │
│              └─────────┬─────────┘                               │
│                        │                                         │
│              ┌─────────▼─────────┐                               │
│              │   📦 Litterbox    │                               │
│              │    Reporter       │                               │
│              │                   │                               │
│              │  • HTML Reports   │                               │
│              │  • PoC Scripts    │                               │
│              │  • Remediation    │                               │
│              └───────────────────┘                               │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

---

📦 Installation

From PyPI (Recommended)

pip install chaos-kitten

From Source

git clone https://github.com/mdhaarishussain/chaos-kitten.git
cd chaos-kitten
pip install -e .

With Development Dependencies

pip install -e ".[dev]"

---

⚙️ Configuration

Create a chaos-kitten.yaml file:

target:
  base_url: "http://localhost:3000"
  openapi_spec: "./openapi.json"
  auth:
    type: "bearer"
    token: "${API_TOKEN}"

agent:
  llm_provider: "anthropic"
  model: "claude-3-5-sonnet-20241022"
  temperature: 0.7

executor:
  concurrent_requests: 5
  timeout: 30
  rate_limit: 10
  retry:
    max_retries: 3           # Max attempts for rate-limited (429) requests
    base_backoff: 1.0        # Initial wait time in seconds
    max_backoff: 60.0        # Maximum wait time
    jitter: true             # Add randomization to backoff

safety:
  allowed_domains:
    - "localhost"
    - "*.test.com"
  destructive_mode: false

📄 See chaos-kitten.yaml for all configuration options.

---

🎮 Usage

Basic Scan

chaos-kitten scan --target http://localhost:3000

With OpenAPI Spec

chaos-kitten scan --spec openapi.json --target http://localhost:3000

CI/CD Integration

# .github/workflows/security-test.yml
name: 🐱 Chaos Kitten Security Scan

on: [pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Chaos Kitten
        run: |
          pip install chaos-kitten
          chaos-kitten scan --fail-on-critical

---

🎁 Contributing

We love contributions! Chaos Kitten is designed to be beginner-friendly.

🐣 First-Timers No coding required! Add payloads to toys/ Fix typos in docs Add naughty strings

🐥 Beginners Basic Python Write unit tests Create YAML attack profiles Add CLI features

🐔 Advanced Core Features New attack strategies GraphQL support LLM optimization

See CONTRIBUTING.md and docs/contributing_guide.md for details.

---

🔒 Safety & Ethics

⚖️ LEGAL NOTICE

Chaos Kitten is intended for testing YOUR OWN applications or systems where you have explicit permission. Unauthorized access to computer systems is illegal. Users are responsible for compliance with applicable laws. The developers assume no liability for misuse.

Built-in Safeguards

Feature	Description
✅ Allowlist-Only	Won't scan domains not in allowed_domains
✅ Rate Limiting	Respects server resources
✅ Non-Destructive	Prevents DROP/DELETE by default
✅ Audit Logging	All actions logged

---

🗺️ Roadmap

Phase 1 (MVP) ✅ OpenAPI parsing SQL injection detection XSS & IDOR detection HTML/Markdown reports CLI tool

Phase 2 🔄 GraphQL support gRPC/Protobuf WebSocket testing GitHub Action

Phase 3 🚀 Kubernetes Operator Service Mesh integration Real-time dashboard OPA integration

---

🏆 Built For

Aperture 3.0 by Resourcio Community

---

📄 License

MIT License - see LICENSE for details.

---

🤝 Contributors

Thanks to all the amazing people who have contributed to Chaos Kitten! 🐱

Want to contribute? Check out our Contributing Guide and join the fun!

---

Chaos Kitten
"Breaking your code before hackers do"

Made with 💜 by the Chaos Kitten Team
A project under the Last Neuron Umbrella
(By the makers of Bondhu)

⭐ Star us on GitHub