# ABE — Autonomous Bug Explorer

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

[![Build](https://img.shields.io/github/actions/workflow/status/your-org/abe/ci.yml?branch=main)](https://github.com/your-org/abe/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
[![Node.js](https://img.shields.io/badge/Node.js-20-green)](https://nodejs.org/)

ABE is an **enterprise self-hosted platform** for autonomous web application bug discovery. It explores apps like a real user, injects invalid inputs (fuzzing), detects anomalies, and generates reproducible bug reports.

---

## Features

- **Autonomous Exploration** — BFS-based state graph exploration with deterministic seeds
- **Smart Fuzzing** — 5 strategies: empty, oversized, special characters, type mismatch, boundary values
- **Visual Regression** — pixel-level screenshot comparison with Playwright + pixelmatch
- **Accessibility Auditing** — WCAG violations via axe-core
- **Reproducible Reports** — generates Playwright test scripts, Markdown, JSON, PDF reports
- **Real-time Dashboard** — live WebSocket feed with severity charts and KPI cards
- **Auth & RBAC** — multi-user, organizations, roles (owner/admin/member/viewer), API keys
- **Integrations** — Slack, GitHub Issues, Jira, custom webhooks
- **Scheduling** — cron-based automated explorations
- **CLI + CI/CD** — JUnit XML output, GitHub Actions integration
- **API Documentation** — OpenAPI 3.1 + Scalar UI at `/api-docs`
- **Licensing** — RSA-signed license keys with feature gating (Free/Pro/Enterprise)

---

## Quick Start

### Prerequisites

- Node.js 20+
- npm 10+

### Development

```bash
# Install dependencies
npm install
cd frontend && npm install && cd ..

# Start development servers
npm run dev          # Backend on :3001
cd frontend && npm run dev  # Frontend on :5173

# Database migrations
npm run db:migrate

# Run tests
npm run test

# Build
npm run build
cd frontend && npm run build
```

### Docker

```bash
# Start all services
docker compose up -d --build

# Production
docker compose -f docker-compose.prod.yml up -d --build
```

The app will be available at `http://localhost:5173`.

---

## CLI Usage

```bash
# Run an exploration
node dist/cli/abe.js explore --url https://example.com \
  --output json \
  --fail-on-severity high

# Generate a report
node dist/cli/abe.js report --session SESSION_ID

# Check server status
node dist/cli/abe.js status
```

### CI/CD Integration

```yaml
# .github/workflows/abe.yml
- uses: ./.github/actions/abe-explore
  with:
    url: https://staging.example.com
    fail-on-severity: high
    api-key: ${{ secrets.ABE_API_KEY }}
```

---

## Architecture

ABE uses a **modular monolith hexagonal architecture** with bounded contexts:

```
src/
├── shared/          → Domain building blocks (Entity, ValueObject, Result, EventBus)
├── modules/
│   ├── crawling/    → Session management + Playwright crawler
│   ├── fuzzing/     → Input fuzzing strategies
│   ├── findings/    → Bug report lifecycle
│   ├── auth/        → Users, organizations, RBAC
│   ├── reporting/   → PDF/HTML/JSON report generation
│   ├── integrations/→ Slack, GitHub, Jira, webhooks
│   ├── scheduling/  → Cron-based automation
│   ├── licensing/   → RSA license validation
│   └── visual-regression/ → Screenshot comparison
├── api/             → Express server + OpenAPI docs
├── realtime/        → Socket.io gateway
├── jobs/            → SQLite-backed job queue
└── cli/             → Commander CLI
```

**Architectural rules:**
1. Domain never imports infrastructure
2. Cross-module communication only via EventBus
3. Use cases return `Result<T, E>`, never throw
4. Controllers are thin — delegate to use cases

---

## API Documentation

Once running, visit `http://localhost:3001/api-docs` for the interactive Scalar API reference.

Endpoints:
- `POST /api/auth/register` — Register
- `POST /api/auth/login` — Login
- `GET /api/sessions` — List explorations
- `POST /api/sessions` — Start exploration
- `GET /api/findings` — List findings
- `POST /api/reports` — Generate report
- `GET /api/schedules` — List schedules
- `GET /api/visual/comparisons` — Visual regression review

---

## License

ABE core is open-source under the [MIT License](LICENSE).

Enterprise features (SSO, LDAP, advanced audit logs) require a commercial license. See [LICENSE-ENTERPRISE](LICENSE-ENTERPRISE).