fase(18): cli and cicd integration
This commit is contained in:
debian
302
README.md
302
README.md
@@ -1,6 +1,23 @@
|
||||
# ABE — Autonomous Bug Explorer
|
||||
|
||||
An open-source framework that autonomously explores web applications, provokes failures, and generates reproducible bug reports for developers and AI coding assistants.
|
||||
[](https://github.com/your-org/abe/actions)
|
||||
[](LICENSE)
|
||||
[](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
|
||||
|
||||
@@ -11,116 +28,229 @@ npm install
|
||||
# Install Playwright browser
|
||||
npx playwright install chromium
|
||||
|
||||
# Run ABE against your app
|
||||
npm run explore -- --url http://localhost:3000 --output ./reports
|
||||
# Explore your app (inline mode — no server needed)
|
||||
npm run abe -- explore --url http://localhost:3000
|
||||
|
||||
# Replay a discovered bug
|
||||
npm run replay -- --report reports/<anomaly-id>/report.json
|
||||
# Start the full dashboard (API server + React frontend)
|
||||
npm run dev:all
|
||||
# Then open http://localhost:5173
|
||||
```
|
||||
|
||||
## What ABE Does
|
||||
## CLI Reference
|
||||
|
||||
1. Launches a headless browser and navigates to the target URL
|
||||
2. Discovers interactive elements (links, buttons, inputs)
|
||||
3. Executes actions deterministically using a seed
|
||||
4. Observes HTTP responses, JS exceptions, and console errors
|
||||
5. Detects anomalies using heuristic rules
|
||||
6. Captures screenshots and DOM snapshots at anomaly moments
|
||||
7. Generates a JSON + Markdown bug report with exact reproduction steps
|
||||
|
||||
## Project Structure
|
||||
### `abe explore` — Run an exploration
|
||||
|
||||
```bash
|
||||
npm run abe -- explore [options]
|
||||
```
|
||||
src/
|
||||
├── core/ # Interfaces, StateGraph, ExplorationEngine, AnomalyDetector
|
||||
└── plugins/
|
||||
├── agents/ # PlaywrightAgent
|
||||
├── collectors/ # Screenshot, Network, DOMSnapshot
|
||||
├── exporters/ # JSON, Markdown
|
||||
└── reproducers/ # PlaywrightReproducer
|
||||
|
||||
tests/ # Unit and integration tests (mirrors src/)
|
||||
reports/ # Generated bug reports (runtime)
|
||||
logs/ # Session logs in .jsonl format (runtime)
|
||||
```
|
||||
|
||||
## CLI Options
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `--url` | `http://localhost:3000` | Target URL |
|
||||
| `--output` | `./reports` | Output directory |
|
||||
| `--seed` | `42` | Random seed for determinism |
|
||||
| `--max-steps` | `100` | Maximum exploration steps |
|
||||
| `--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 |
|
||||
|
||||
## Web UI (API Server + Dashboard)
|
||||
**Exit codes:** `0` = clean, `1` = findings over threshold, `2` = error
|
||||
|
||||
ABE also ships a web dashboard for launching explorations and watching results in real time.
|
||||
#### Examples
|
||||
|
||||
```bash
|
||||
# Start both the API server (port 3001) and the React frontend (port 5173)
|
||||
# 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
|
||||
```
|
||||
|
||||
Then open `http://localhost:5173` in your browser.
|
||||
|
||||
### API Server only
|
||||
|
||||
```bash
|
||||
npm run server
|
||||
```
|
||||
|
||||
REST endpoints available at `http://localhost:3001/api/`:
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| `POST` | `/sessions` | Start a new exploration |
|
||||
| `GET` | `/sessions` | List all sessions |
|
||||
| `GET` | `/sessions/:id` | Session detail |
|
||||
| `DELETE` | `/sessions/:id` | Stop a running session |
|
||||
| `GET` | `/anomalies` | List all anomalies |
|
||||
| `GET` | `/anomalies/:id` | Anomaly detail |
|
||||
| `GET` | `/anomalies/:id/screenshot` | Bug screenshot (PNG) |
|
||||
| `POST` | `/anomalies/:id/replay` | Trigger anomaly replay |
|
||||
|
||||
WebSocket events are emitted via socket.io (connect to `http://localhost:3001`).
|
||||
Open `http://localhost:5173`. First run prompts you to create an admin account and organization.
|
||||
|
||||
## Docker
|
||||
|
||||
Run the full stack (backend + frontend) with a single command:
|
||||
|
||||
```bash
|
||||
docker-compose up --build
|
||||
docker compose up --build
|
||||
```
|
||||
|
||||
| Service | Host port | Description |
|
||||
|---------|-----------|-------------|
|
||||
| Backend | `3001` | Express API + socket.io |
|
||||
| Frontend | `5173` | React dashboard (nginx) |
|
||||
|
||||
Then open `http://localhost:5173` in your browser.
|
||||
|
||||
Reports and logs are persisted via Docker volumes (`./reports`, `./logs`).
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
npm run build # Compile TypeScript
|
||||
npm test # Run all tests
|
||||
npm run typecheck # Type-check without compiling
|
||||
```
|
||||
| Service | Port | Description |
|
||||
|---------|------|-------------|
|
||||
| Backend | 3001 | Express API + socket.io |
|
||||
| Frontend | 5173 | React dashboard (nginx) |
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
frontend/ (React + Vite, port 5173)
|
||||
↕ HTTP REST + WebSocket
|
||||
src/server/ (Express + socket.io, port 3001)
|
||||
↕ imports
|
||||
src/core/ + src/plugins/ (ABE engine)
|
||||
Domain (pure TypeScript — no infrastructure dependencies)
|
||||
↑
|
||||
Application (use cases, commands, queries, event handlers)
|
||||
↑
|
||||
Infrastructure (Kysely/SQLite, Playwright, Express controllers)
|
||||
```
|
||||
|
||||
Core principles:
|
||||
- **Deterministic**: all random choices are seeded and logged
|
||||
- **Plugin-oriented**: core engine never imports concrete plugin classes
|
||||
- **Reproducible**: every anomaly includes an exact action trace and replay script
|
||||
**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.
|
||||
|
||||
Reference in New Issue
Block a user