157 lines
5.1 KiB
Markdown
157 lines
5.1 KiB
Markdown
# AASD — API Attack Surface Discovery
|
|
|
|
Interactive booth application for GITEX 2026. Visitors enter a corporate email, and AASD runs a full attack surface discovery pipeline:
|
|
|
|
**Email → Domain Discovery → GoTestWAF Scan → AI Resilience Report**
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Visitor Email
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ /start (POST) │ Email validation + domain extraction
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ domain-scan │ Passive subdomain enumeration (15s timeout)
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ GoTestWAF │ WAF penetration test against Wallarm endpoint (120s)
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ DeepSeek AI │ Generate resilience narrative from scan results
|
|
└────────┬────────┘
|
|
│
|
|
▼
|
|
┌─────────────────┐
|
|
│ HTML Report │ Static report served at /reports/<token>.html
|
|
└─────────────────┘
|
|
```
|
|
|
|
## Tech Stack
|
|
|
|
| Component | Technology |
|
|
|-----------|-----------|
|
|
| Backend | Go 1.25 — Gin web framework |
|
|
| Frontend | HTML, JavaScript, Tailwind CSS (CDN) |
|
|
| WAF Scanner | GoTestWAF |
|
|
| Domain Discovery | domain-scan |
|
|
| AI Narrative | DeepSeek API |
|
|
| Email | SMTP (OpenXchange) |
|
|
|
|
## Quick Start (Development)
|
|
|
|
```bash
|
|
# Option 1: Deploy via install script
|
|
cd AttackSurface
|
|
sudo bash install.sh
|
|
|
|
# Option 2: Run from dist/ directly
|
|
cd AttackSurface/dist
|
|
./aasd
|
|
|
|
# Option 3: Build from source
|
|
cd AttackSurface/src
|
|
go build -o ../dist/aasd ./cmd/aasd/
|
|
cd ../dist
|
|
./aasd
|
|
```
|
|
|
|
## Endpoints
|
|
|
|
| Path | Description | Auth |
|
|
|------|-------------|------|
|
|
| `/` | Frontend landing page (email entry) | Public |
|
|
| `/start` (POST) | Submit email, trigger scan pipeline | Public |
|
|
| `/analysing` | Scan progress visualization | Public |
|
|
| `/simulation` | Legacy alias for `/analysing` | Public |
|
|
| `/scan-status/:token` | Poll scan status (JSON) | Public |
|
|
| `/qrcode?text=...` | QR code generator | Public |
|
|
| `/admin-dashboard` | Consultant dashboard | Basic Auth |
|
|
| `/email-report` (POST) | Send report via email | Public |
|
|
| `/reports/*` | Generated static reports | Public |
|
|
| `/report-data/:token` | Raw scan result JSON | Public |
|
|
| `/api/scans` | Scan summaries (JSON) | Public |
|
|
|
|
## Configuration
|
|
|
|
Edit `dist/config.yaml` (or `/opt/aasd/config.yaml` after install) with your values:
|
|
|
|
```yaml
|
|
ai:
|
|
api_key: "sk-..." # DeepSeek API key for AI narratives
|
|
server:
|
|
base_url: "https://..." # Public URL for QR codes & email links
|
|
admin:
|
|
password: "..." # Admin dashboard password
|
|
```
|
|
|
|
Alternatively, set these via environment variables:
|
|
- `AASD_BASE_URL` — public-facing URL
|
|
- `AASD_AI_API_KEY` — DeepSeek API key
|
|
- `AASD_ADMIN_PASSWORD` — admin dashboard password
|
|
- `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_FROM` — SMTP config
|
|
|
|
## Deployment (Production)
|
|
|
|
See `install.sh` for automated deployment. The script:
|
|
|
|
1. Creates an `app` system user if it doesn't exist
|
|
2. Downloads the pre-built release archive from GitHub
|
|
3. Extracts to `/opt/aasd`
|
|
4. Creates a systemd service (`aasd.service`) for auto-start on boot
|
|
5. Prompts for required configuration values
|
|
|
|
### Systemd Service Management
|
|
|
|
```bash
|
|
sudo systemctl start aasd # Start the server
|
|
sudo systemctl stop aasd # Stop the server
|
|
sudo systemctl restart aasd # Restart
|
|
sudo systemctl status aasd # Check status
|
|
sudo journalctl -u aasd -f # Follow logs
|
|
```
|
|
|
|
## Version
|
|
|
|
**2026-04.1** — See [CHANGELOG.md](docs/CHANGELOG.md) for full history.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
AttackSurface/
|
|
├── dist/ # Deployment directory (self-contained)
|
|
│ ├── aasd # Compiled Go binary
|
|
│ ├── config.yaml # Application configuration
|
|
│ ├── prompt.txt # DeepSeek AI system prompt
|
|
│ ├── gotestwaf # GoTestWAF binary
|
|
│ ├── domain-scan # Domain discovery tool
|
|
│ ├── testcases/ # GoTestWAF test cases
|
|
│ ├── static/ # Frontend HTML/JS
|
|
│ ├── templates/ # Go HTML templates
|
|
│ ├── reports/ # Generated scan reports
|
|
│ └── logs/ # Server logs
|
|
├── src/ # Go source code
|
|
│ ├── cmd/aasd/ # Main entry point
|
|
│ ├── internal/ # Core packages (scanner, ai, mailer, report)
|
|
│ ├── static/ # Frontend source files
|
|
│ ├── templates/ # Template source files
|
|
│ └── gotestwaf/ # Vendored GoTestWAF
|
|
├── docs/ # Documentation
|
|
│ ├── CHANGELOG.md
|
|
│ └── DEVELOPMENT_STATUS.md
|
|
├── install.sh # Automated deployment script
|
|
├── VERSION
|
|
└── README.md # This file
|
|
```
|
|
|
|
## License
|
|
|
|
Proprietary — For internal event use at GITEX 2026.
|