Autonomous-Bug-Explorer/README.md

# ABE — Autonomous Bug Explorer

[![Build](https://img.shields.io/github/actions/workflow/status/your-org/abe/abe-example.yml?branch=main&label=build)](https://github.com/your-org/abe/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.1.0-blue)](package.json)

> **"Playwright discovers what you test. ABE discovers what you miss."**

An enterprise-grade, self-hosted platform for autonomous bug discovery in web applications. ABE explores your app like a real user, injects invalid inputs (fuzzing), detects anomalies, and generates reproducible bug reports — all without writing a single test.

## Features

- **Autonomous exploration** — navigates your app using a seeded, deterministic algorithm
- **Smart fuzzing** — injects empty values, oversized strings, special chars, type mismatches and boundary values into every input
- **Anomaly detection** — catches HTTP errors, JS exceptions, console errors, and accessibility violations
- **Reproducible reports** — every finding includes an exact action trace + generated Playwright test
- **Real-time dashboard** — watch explorations live with severity heatmaps and trend charts
- **CI/CD integration** — JUnit XML output, GitHub Action, exit codes for threshold-based gating
- **Auth support** — cookies, headers, or login flow for authenticated app exploration
- **Enterprise licensing** — RSA-signed license keys, RBAC, API keys, Slack/GitHub/Jira integrations

## Quick Start

```bash
# Install dependencies
npm install

# Install Playwright browser
npx playwright install chromium

# Explore your app (inline mode — no server needed)
npm run abe -- explore --url http://localhost:3000

# Start the full dashboard (API server + React frontend)
npm run dev:all
# Then open http://localhost:5173
```

## CLI Reference

### `abe explore` — Run an exploration

```bash
npm run abe -- explore [options]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--url <url>` | *(required)* | Target URL to explore |
| `--config <file>` | — | JSON config file (merged with flags) |
| `--seed <n>` | `42` | Deterministic seed |
| `--max-states <n>` | `50` | Max states to visit |
| `--max-depth <n>` | `5` | Max click depth |
| `--allowed-domains <d>` | *(from URL)* | Comma-separated allowed domains |
| `--excluded-paths <p>` | — | Comma-separated paths to skip |
| `--auth-type <type>` | — | `cookies` \| `headers` \| `login_flow` |
| `--output <format>` | `human` | `human` \| `json` \| `junit` \| `markdown` |
| `--reports-dir <dir>` | `./reports` | Output directory |
| `--fail-on-severity <s>` | — | Exit 1 if finding at `low`/`medium`/`high`/`critical` or above |
| `--fail-on-anomaly` | — | Exit 1 if any finding found |
| `--server <url>` | — | Remote ABE server URL (skips inline engine) |
| `--api-key <key>` | — | API key for remote server |

**Exit codes:** `0` = clean, `1` = findings over threshold, `2` = error

#### Examples

```bash
# Basic exploration
npm run abe -- explore --url https://staging.myapp.com

# CI mode — fail on high/critical findings, output JUnit
npm run abe -- explore \
  --url https://staging.myapp.com \
  --max-states 100 \
  --output junit \
  --fail-on-severity high

# Authenticated exploration (login flow)
npm run abe -- explore \
  --url https://staging.myapp.com \
  --auth-type login_flow \
  --login-url https://staging.myapp.com/login \
  --username ci@example.com \
  --password secret

# Load config from JSON file
npm run abe -- explore --url https://staging.myapp.com --config abe.config.json

# Remote server mode (delegates to ABE server)
npm run abe -- explore \
  --url https://staging.myapp.com \
  --server https://abe.internal.company.com \
  --api-key $ABE_API_KEY
```

#### Config File Format (`abe.config.json`)

```json
{
  "maxStates": 100,
  "maxDepth": 8,
  "seed": 1337,
  "allowedDomains": ["staging.myapp.com"],
  "excludedPaths": ["/logout", "/admin"]
}
```

### `abe report` — Generate a report

```bash
npm run abe -- report --session <id> [options]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--session <id>` | *(required)* | Session ID to report on |
| `--server <url>` | `http://localhost:3001` | ABE server URL |
| `--api-key <key>` | — | API key |
| `--format <fmt>` | `pdf` | `pdf` \| `html` \| `json` |
| `--output <file>` | `./abe-report-<id>.<fmt>` | Output file path |

```bash
npm run abe -- report \
  --session abc123 \
  --server https://abe.internal.company.com \
  --api-key $ABE_API_KEY \
  --format pdf \
  --output ./security-report.pdf
```

### `abe status` — Check server health

```bash
npm run abe -- status [options]
```

| Option | Default | Description |
|--------|---------|-------------|
| `--server <url>` | `http://localhost:3001` | ABE server URL |
| `--api-key <key>` | — | API key |
| `--json` | — | JSON output |

```bash
npm run abe -- status --server https://abe.internal.company.com
# ✓ ABE server is ready at https://abe.internal.company.com
#   2 active session(s):
#     [abc123] https://staging.myapp.com — 42 states explored
```

## CI/CD Integration

### GitHub Actions — Composite Action

```yaml
steps:
  - uses: actions/checkout@v4

  - name: Run ABE
    uses: ./.github/actions/abe-explore
    with:
      url: https://staging.myapp.com
      max-states: '50'
      fail-on-severity: high
      output: junit

  - name: Publish results
    if: always()
    uses: EnricoMi/publish-unit-test-result-action@v2
    with:
      files: abe-results.xml
```

### GitHub Actions — Inline

```yaml
- name: Run ABE
  run: |
    npm run abe -- explore \
      --url https://staging.myapp.com \
      --max-states 50 \
      --output junit \
      --fail-on-severity high
```

### Docker CI Image

```bash
# Build the CI image (includes Playwright/Chromium)
docker build -f Dockerfile.ci -t abe-ci .

# Run exploration in Docker
docker run --rm \
  -v $(pwd)/abe-reports:/reports \
  abe-ci explore \
    --url http://host.docker.internal:3000 \
    --output junit \
    --fail-on-severity high
```

### JUnit XML Output

With `--output junit`, ABE writes `abe-results.xml`:
- Each **state visited** = a passing test case
- Each **finding** = a failing test case with severity and description

Integrates with GitHub Actions, Jenkins, GitLab CI, CircleCI, and any JUnit-compatible reporter.

## Web Dashboard

```bash
# Start both backend (port 3001) and frontend (port 5173)
npm run dev:all
```

Open `http://localhost:5173`. First run prompts you to create an admin account and organization.

## Docker

```bash
docker compose up --build
```

| Service | Port | Description |
|---------|------|-------------|
| Backend | 3001 | Express API + socket.io |
| Frontend | 5173 | React dashboard (nginx) |

## Architecture

```
Domain       (pure TypeScript — no infrastructure dependencies)
    ↑
Application  (use cases, commands, queries, event handlers)
    ↑
Infrastructure (Kysely/SQLite, Playwright, Express controllers)
```

**Modules:** `crawling` · `findings` · `fuzzing` · `auth` · `reporting` · `integrations` · `licensing`

Cross-module communication via `EventBus` only — bounded contexts never import each other directly.

## Development

```bash
npm run build                        # Compile TypeScript
npm run test                         # Run tests (Vitest)
npm run lint                         # ESLint
npm run db:migrate                   # Apply database migrations
cd frontend && npm run build         # Build frontend
docker compose up -d --build         # Full stack with Docker
```

## License

Core: [MIT](LICENSE) · Enterprise features require a valid license key.