154 lines
4.6 KiB
Markdown
154 lines
4.6 KiB
Markdown
# ABE — Autonomous Bug Explorer
|
|
|
|
> "Playwright discovers what you test. ABE discovers what you miss."
|
|
|
|
[](https://github.com/your-org/abe/actions)
|
|
[](LICENSE)
|
|
[](https://www.typescriptlang.org/)
|
|
[](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).
|