Autonomous-Bug-Explorer/README.md

ABE — Autonomous Bug Explorer

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

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

# 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

# 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

# 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

# .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.

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