fase(25): polish and quality improvements
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
debian
315
README.md
315
README.md
@@ -1,256 +1,153 @@
|
||||
# ABE — Autonomous Bug Explorer
|
||||
|
||||
[](https://github.com/your-org/abe/actions)
|
||||
[](LICENSE)
|
||||
[](package.json)
|
||||
> "Playwright discovers what you test. ABE discovers what you miss."
|
||||
|
||||
> **"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/)
|
||||
|
||||
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.
|
||||
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** — 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
|
||||
- **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 ..
|
||||
|
||||
# Install Playwright browser
|
||||
npx playwright install chromium
|
||||
# Start development servers
|
||||
npm run dev # Backend on :3001
|
||||
cd frontend && npm run dev # Frontend on :5173
|
||||
|
||||
# Explore your app (inline mode — no server needed)
|
||||
npm run abe -- explore --url http://localhost:3000
|
||||
# Database migrations
|
||||
npm run db:migrate
|
||||
|
||||
# Start the full dashboard (API server + React frontend)
|
||||
npm run dev:all
|
||||
# Then open http://localhost:5173
|
||||
# Run tests
|
||||
npm run test
|
||||
|
||||
# Build
|
||||
npm run build
|
||||
cd frontend && npm run build
|
||||
```
|
||||
|
||||
## CLI Reference
|
||||
|
||||
### `abe explore` — Run an exploration
|
||||
### Docker
|
||||
|
||||
```bash
|
||||
npm run abe -- explore [options]
|
||||
# Start all services
|
||||
docker compose up -d --build
|
||||
|
||||
# Production
|
||||
docker compose -f docker-compose.prod.yml up -d --build
|
||||
```
|
||||
|
||||
| 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 |
|
||||
The app will be available at `http://localhost:5173`.
|
||||
|
||||
**Exit codes:** `0` = clean, `1` = findings over threshold, `2` = error
|
||||
---
|
||||
|
||||
#### Examples
|
||||
## CLI Usage
|
||||
|
||||
```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 \
|
||||
# Run an exploration
|
||||
node dist/cli/abe.js explore --url https://example.com \
|
||||
--output json \
|
||||
--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
|
||||
# Generate a report
|
||||
node dist/cli/abe.js report --session SESSION_ID
|
||||
|
||||
# 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
|
||||
# Check server status
|
||||
node dist/cli/abe.js status
|
||||
```
|
||||
|
||||
#### 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
|
||||
### CI/CD Integration
|
||||
|
||||
```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/workflows/abe.yml
|
||||
- uses: ./.github/actions/abe-explore
|
||||
with:
|
||||
url: https://staging.example.com
|
||||
fail-on-severity: high
|
||||
api-key: ${{ secrets.ABE_API_KEY }}
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
ABE uses a **modular monolith hexagonal architecture** with bounded contexts:
|
||||
|
||||
```
|
||||
Domain (pure TypeScript — no infrastructure dependencies)
|
||||
↑
|
||||
Application (use cases, commands, queries, event handlers)
|
||||
↑
|
||||
Infrastructure (Kysely/SQLite, Playwright, Express controllers)
|
||||
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
|
||||
```
|
||||
|
||||
**Modules:** `crawling` · `findings` · `fuzzing` · `auth` · `reporting` · `integrations` · `licensing`
|
||||
**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
|
||||
|
||||
Cross-module communication via `EventBus` only — bounded contexts never import each other directly.
|
||||
---
|
||||
|
||||
## Development
|
||||
## API Documentation
|
||||
|
||||
```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
|
||||
```
|
||||
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
|
||||
|
||||
Core: [MIT](LICENSE) · Enterprise features require a valid license key.
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user