LOKI

Autonomous AI Testing & Synthetic Chaos Agent

⚡ Overview

LOKI is an autonomous CLI testing agent designed to break, explore, and verify modern web applications before your users do. Operating as a standalone developer tool (similar to docker, terraform, or gh), LOKI combines synthetic chaos personas, automated visual recording, AI business rule verification, and forensic network analysis into an end-to-end quality gate.

Unlike traditional testing frameworks that test for "happy paths", LOKI deliberately injects chaos: race conditions, input fuzzing, network drops, and security tampering. When a failure is detected, LOKI packages the incident into a deterministic reproduction script, video replay, and standalone HTML scorecard.

🌟 Key Capabilities

🐝 1. Swarm Mode & 4 Chaos Personas

LOKI simulates realistic, erratic human behaviors through specialized personas:

• RageClicker: Targets interactive buttons with rapid burst clicks to provoke double-submissions and race conditions.
• NoviceChaotic: Fuzzes inputs with massive unicode strings, negative values, and erratic keyboard strokes.
• NetworkTormentor: Dynamically throttles network conditions (Slow 3G, 1200ms latency) and simulates abrupt offline connection drops mid-flight.
• Adversary: Bypasses client-side UI protections (strips disabled and aria-disabled attributes), tampers with hidden form fields, and probes with security payloads.
• Swarm (--swarm): Coordinates all personas in multi-vector assault waves.

📋 2. AI Business Rules Verification (rules.md)

Define human-readable business invariants in .loki/rules.md:

- "Double clicking payment button must never trigger duplicate charges or unhandled errors."
- "Invalid coupon codes must display an error message and keep checkout button disabled."

At the end of an assault session, LOKI's AI Brain (model set in .loki/config.yaml under ai.model, via LiteLLM) observes the live DOM snapshot, console logs, and network events to evaluate each rule as PASSED or VIOLATED with detailed evidence.

🌐 3. Forensic Network Capture & Privacy Scrubber (network.har)

• Automatically captures full HTTP network traffic in standard .har format.
• Network Scrubber: Automatically redacts sensitive tokens, bearer headers (Authorization), session cookies (Cookie, Set-Cookie), API keys, and passwords before storing archives.

📹 4. Standalone Visual HTML Reports & Replay Videos

• Generates interactive, standalone HTML dashboards with embedded <video> replays, business rule scorecards, network archives, and chronological timelines.
• Review incidents offline or share reports across your engineering team.

⚡ 5. Deterministic Playwright Reproduction (repro_test.py)

• When an unhandled crash or HTTP 500 error occurs, LOKI automatically synthesizes a standalone Playwright script that replays the exact recorded action trace (real selectors, payloads, network drops, and device emulation) — not a generic click simulation — to deterministically reproduce the incident.

🔀 6. Multi-Tab Concurrency Probe (--concurrency)

• Opens N independent, synchronized browser lanes that fire the same action at the same instant, hunting for server-side race conditions (double charges, oversold inventory) that a single tab's sequential click bursts cannot trigger.
• Flags evidence like multiple lanes both getting a successful response for a one-time action, and ships its own dedicated repro_test.py that replays the synchronized race deterministically.

💬 7. Conversational QA Terminal Assistant (loki chat) — the default screen

• Running bare loki (no subcommand) drops you straight into this REPL — it's the central control surface for the whole agent, not just a Q&A window.
• Chat about recent runs, analyze crash traces, inspect rules, and receive actionable refactoring suggestions directly in your console.
• /model lists, switches, and adds AI model profiles on the fly (e.g. /model add local ollama/llama3) — the choice applies immediately, in that same session, to every LOKI AI feature (chat, rules evaluation, fix, auto-heal), not just chat, since it's saved to .loki/models.json and read from there first.
• /run [url] [flags], /fix [run_id] [--apply], and /report [run_id] drive the exact same code as their standalone CLI commands — launch an attack, diagnose or patch an incident, or open a report, all without leaving the chat.

💣 8. Infrastructure Chaos (loki infra)

• Goes past the browser to fault-inject the real local process (or Docker container) backing your app: loki infra kill --port 5432 kills whatever's listening there outright (a crashed/OOM-killed dependency), loki infra pause --port 5432 -d 10 hangs it for 10s then resumes it (an unresponsive dependency instead of a hard crash), loki infra cpu-stress/memory-stress saturate every core or hold megabytes resident to simulate a noisy neighbor.
• Scoped to your own machine (or local Docker daemon) — same trust boundary as localhost for loki run: if you can already signal it without extra credentials, it's yours to break.
• kill/cpu-stress/memory-stress are verified against real processes; pause uses the standard OS suspend/resume mechanism but couldn't be confirmed to actually halt execution in every environment — test it against your own target before relying on it.

🛡️ 9. Strict CI/CD Quality Gate

• Seamlessly integrates into GitHub Actions, GitLab CI, or pre-commit pipelines (--ci, --strict).
• Automatically formats and publishes test summaries to $GITHUB_STEP_SUMMARY and enforces deterministic exit codes (0 on pass, 1 on failure).

🚑 10. Autonomous Code Self-Healing (loki fix --apply & loki run --auto-heal)

• Synthesizes precise, minimal surgical code patches to permanently eliminate the root cause of crashes.
• Safely creates automatic backups (.loki.bak), applies the patch to your source code, and runs a closed-loop reproduction verification test.
• If the crash still reproduces, LOKI automatically restores your code safely from backup.

🚀 Quickstart

1. Installation

Option A: Standalone Precompiled Binaries (Zero Python Required)

Download the standalone executable directly from GitHub Releases:

• Windows: loki-windows-amd64.exe
• Linux: loki-linux-amd64
• macOS (Apple Silicon): loki-macos-arm64

Option B: Global Isolated Install with uv (Recommended for developers)

# Install globally as a standalone command (fastest):
uv tool install git+https://github.com/Elabsurdo984/loki-agent.git

# Or run instantly without installing (like npx):
uvx --from git+https://github.com/Elabsurdo984/loki-agent.git loki run http://localhost:8000 --swarm

Option C: Global Install with pipx

pipx install git+https://github.com/Elabsurdo984/loki-agent.git

Option D: Local Development from Source

git clone https://github.com/Elabsurdo984/loki-agent.git
cd loki-agent

python -m venv .venv
# Activate: .\.venv\Scripts\Activate.ps1 (Windows) or source .venv/bin/activate (Linux/macOS)
pip install -e .

2. Configure AI Brain (Optional for AI features)

LOKI's AI Brain runs on LiteLLM, so it can talk to any LiteLLM-compatible provider — not just Gemini, OpenAI, or Anthropic. For the bundled default, export a Gemini key:

# Windows PowerShell
$env:GEMINI_API_KEY="your-gemini-api-key"

# Linux / macOS
export GEMINI_API_KEY="your-gemini-api-key"

To use a different provider (Mistral, Groq, Cohere, Azure, Bedrock, a local Ollama/vLLM/LM Studio server, or any other OpenAI-compatible endpoint), set ai: in .loki/config.yaml:

ai:
  provider: mistral                # optional: prefixes `model` when it has no "/"
  model: mistral-large-latest      # any LiteLLM model id ("provider/model"), or a
                                    # bare name when pointing at a custom api_base
  api_base: https://my-host/v1     # optional: a self-hosted or OpenAI-compatible
                                    # server (Ollama, vLLM, LM Studio, an internal
                                    # gateway...) — needs no public API key at all
  api_key_env: MY_PROVIDER_KEY     # optional: the env var holding the key, when it
                                    # doesn't match the provider's usual name

Once ai: (or --model) points anywhere other than the bundled Gemini default, LOKI tries exactly that connection — it never silently falls back to a different provider.

loki init scaffolds .loki/config.yaml with these examples already written in as comments (including a local Ollama one-liner), so you never have to come back here to look up the syntax.

3. Initialize Workspace

Analyze your target project and generate .loki/ configuration:

loki init

4. Unleash Chaos

Execute an exploratory chaos attack on your local or remote application:

# Run 6-second Swarm assault and open visual HTML report
loki run http://localhost:8000 --swarm --duration 6 --open

# Emulate mobile viewport & audit responsive overflows (iPhone 15, Pixel 7, iPad Pro)
loki run http://localhost:8000 --device iphone-15 --orientation portrait

# Run specific persona in visible browser
loki run http://localhost:8000 -p adversary --headed

📖 CLI Commands Reference

🛑 Authorization Guardrail

loki run/loki record against localhost need nothing extra. Against anything else, LOKI refuses until you confirm, once per host, that you own it or have explicit permission to test it — type the hostname back when prompted, or pass --authorized for scripted/CI use. The confirmation is remembered in .loki/authorized_targets.json; revoke it anytime with loki auth remove <host>.

This exists because LOKI runs real attacks (input fuzzing, security payloads, forced clicks, concurrent requests) against whatever URL you give it — there's nothing technical stopping you from pointing it at a site you don't control, so the tool itself asks. Valid reasons to proceed: you own the host, you have the target's explicit written authorization, it's in a bug bounty program's documented scope, or it's a dedicated practice target (OWASP Juice Shop, a CTF box, ...). "It's probably fine" isn't one of them.

📁 Repository Structure

loki-agent/
├── assets/                     # Brand assets and transparent logos
│   └── logo.png                # Official LOKI flat vector brandmark
├── .github/
│   └── workflows/
│       ├── loki.yml            # Automated CI/CD quality gate workflow
│       └── release.yml         # Cross-platform binary compilation & releases
├── .loki/                      # Local configuration and captured artifacts
│   ├── config.yaml             # Target URL, timeouts, model settings
│   ├── rules.md                # Human-readable business rules evaluated by AI
│   ├── knowledge.json          # Architectural fingerprint of the target app
│   ├── journeys/               # Recorded user workflow blueprints
│   └── runs/                   # Captured incident bundles
│       └── run_YYYYMMDD_HHMMSS/
│           ├── incident.json   # Full incident metadata, crashes, and logs
│           ├── replay.webm     # Video recording of the failure session
│           ├── network.har     # Sanitized HTTP archive (tokens scrubbed)
│           ├── report.html     # Standalone visual HTML dashboard
│           └── repro_test.py   # Standalone Playwright reproduction script
├── playground/                 # Local testbed with intentional edge-case bugs
│   └── index.html              # Interactive e-commerce checkout vulnerability playground
├── src/
│   └── loki/
│       ├── cli.py              # Typer CLI application entry point
│       ├── ai/
│       │   ├── brain.py        # LiteLLM integration, diagnosis, rules reasoning
│       │   └── chat.py         # LokiChatSession: Interactive terminal REPL
│       ├── engine/
│       │   ├── sandbox.py      # ChaosSandbox: Isolated Playwright browser & sniffer
│       │   ├── reporter.py     # Incident packaging and bundle persistence
│       │   ├── html_reporter.py # Standalone visual HTML dashboard renderer
│       │   ├── scrubber.py     # NetworkScrubber: Sanitizes HAR traces & cookies
│       │   ├── recorder.py     # JourneyRecorder: Interactive DOM event recorder
│       │   ├── replayer.py     # IncidentReplayer: Deterministic reproduction
│       │   ├── healer.py       # CodeHealer: Autonomous patch synthesizer & verification
│       │   ├── ci.py           # CIGate: CI environment detection & Step Summary
│       │   └── scanner.py      # ProjectScanner: Tech stack detector
│       └── personas/
│           ├── base.py         # BasePersona abstract class
│           ├── rage_clicker.py # Burst clicks and concurrency racing
│           ├── novice_chaotic.py # Input fuzzing and erratic navigation
│           ├── network_tormentor.py # Latency throttling and offline drops
│           ├── adversary.py    # UI locks bypass and security probes
│           └── swarm.py        # Multi-vector assault orchestrator
├── requirements.txt            # Core dependencies
└── AGENTS.md                   # Canonical operating manual for AI coding agents

🤝 Contributing & Pull Requests

Contributions are warmly welcomed! You do not need to wait for or find an open issue to contribute.

If you have an idea for a new feature, a new chaos persona, an engine optimization, security hardening, or extra tooling, feel free to submit a Pull Request directly.

• Check out CONTRIBUTING.md for local environment setup, architecture guidelines, and test instructions.
• Read SECURITY.md for our vulnerability disclosure policy and contributor security guardrails.
• All PRs are verified against our unit test suite (pytest) and must adhere to the 100% English repository policy.
• For newcomer-scoped tasks, browse our good first issue list.

📄 License

This project is licensed under the MIT License.