gitex2026/aasd/README.md

# AASD — API Attack Surface Discovery

Interactive booth application for **GITEX 2026**. Visitors enter a domain, the app discovers live subdomains via HTTPS/TLS probing, and they select one to scan with GoTestWAF against a Wallarm WAF endpoint.

```
Enter domain → Discover subdomains → Pick target → GoTestWAF scan → AI report → QR code
```

## Quick Start

```bash
# Build
cd ~/gitex2026/aasd/src
go build -o /opt/aasd/aasd ./cmd/aasd/

# Deploy
sudo systemctl restart aasd

# Monitor
sudo journalctl -u aasd -f
```

## Booth Flow

1. **Visitor enters a domain** (e.g. `example.com`) or an IP address
2. **Discovery runs** — probes 5000 common subdomain names via HTTPS/TLS (`Checking 142 / 5000 subdomains…`)
3. **Live progress** — frontend shows real-time counter with pulsing indicator
4. **Subdomains displayed** — only those with valid TLS certificates (filters wildcard DNS noise)
5. **Visitor picks one** — selects a subdomain to scan
6. **GoTestWAF scans** — tests the selected subdomain against the Wallarm WAF endpoint
7. **AI report generated** — resilience narrative (or fallback if AI unavailable)
8. **QR code shown** — visitor shares with booth team for full consultant report

## Deployment

### Structure

```
/opt/aasd/
├── aasd                      # Compiled binary (31M)
├── config.yaml               # Server URL, admin credentials, AI key
├── prompt.txt                # DeepSeek system prompt
├── subdomains.txt            # 5000 common subdomain names (SecLists)
├── gotestwaf                 # WAF scanner binary (27M)
├── gotestwaf-config.yaml     # HTTP headers for scans
├── testcases/                # GoTestWAF attack payloads
├── static/                   # Frontend files
│   ├── index.html            # Landing page
│   └── simulation.html       # Selection + progress page
├── templates/
│   └── admin.html            # Consultant dashboard
├── reports/                  # Generated scan reports
└── logs/                     # Server logs
```

### Configuration

Sample configuration files are provided in the project root:

| File | Purpose |
|------|---------|
| [`sample.config.yaml`](sample.config.yaml) | Full config template with placeholder values (copy to `/opt/aasd/config.yaml`) |
| [`sample.env`](sample.env) | Environment variable template (source with `source sample.env`) |

**Important:** The `install.sh` script prompts for credentials at deploy time and generates `config.yaml` automatically. Sample files are for reference only — never commit real credentials.

### Environment Variables

All config values can be overridden via environment variables:

| Variable | Overrides | Description |
|----------|-----------|-------------|
| `AASD_BASE_URL` | `server.base_url` | Public base URL for report links & QR codes |
| `SMTP_HOST` | — | SMTP server hostname (default: `smtp.openxchange.eu`) |
| `SMTP_PORT` | — | SMTP server port (default: `587`) |
| `SMTP_USERNAME` | — | SMTP auth username (default: `post@sechpoint.app`) |
| `SMTP_PASSWORD` | — | SMTP auth password |
| `SMTP_FROM` | — | Sender email address (default: `post@sechpoint.app`) |

### Service Management

```bash
sudo systemctl start   aasd       # Start
sudo systemctl stop    aasd       # Stop
sudo systemctl restart aasd       # Restart
sudo systemctl status  aasd       # Status
sudo journalctl -u aasd -f        # Follow logs
```

### Credentials

| Interface | Username | Password |
|-----------|----------|----------|
| Admin Dashboard | `sechpoint` | `Git3x2o26` |

## API Endpoints

| Endpoint | Auth | Description |
|----------|------|-------------|
| `GET /` | Public | Landing page |
| `POST /start` | Public | Submit domain, start discovery |
| `GET /select-subdomain?token=` | Public | Subdomain selection page |
| `POST /select-subdomain` | Public | Select subdomain, start scan |
| `GET /analysing?token=` | Public | Scan progress page |
| `GET /scan-status/:token` | Public | Poll status (JSON) |
| `GET /admin-dashboard` | Basic Auth | Consultant dashboard |
| `GET /api/scans` | Public | Scan list (JSON) |
| `POST /email-report` | Public | Send report via email (`{"token":"...","email":"..."}`) |
| `GET /reports/visitor_*.html` | Public | Visitor-facing report (with Home button) |
| `GET /reports/consultant_*.html` | Public | GoTestWAF consultant report (with email-send form) |
| `GET /qrcode?text=` | Public | QR code generator |

## Report Types

| File | Content | Size |
|------|---------|------|
| `visitor_{token}.html` | AI resilience narrative or fallback | ~4KB |
| `consultant_{token}.html` | Raw GoTestWAF output (if scan succeeded) | ~59KB |

## Architecture

```
src/
├── cmd/aasd/main.go          # HTTP server, routes, lifecycle
├── internal/
│   ├── scanner/
│   │   ├── scanner.go        # Orchestrator, pipeline, scan results
│   │   ├── probe.go          # Wordlist-based HTTPS/TLS subdomain discovery
│   │   └── gotestwaf.go      # GoTestWAF binary execution
│   ├── report/report.go      # Static HTML report generation
│   ├── ai/deepseek.go        # DeepSeek API integration
│   └── mailer/smtp.go        # SMTP email delivery
└── static/                   # Frontend source files
```

## Key Design Decisions

- **No email collection** — domain is the only input, avoiding data-mining appearance
- **TLS cert validation** as subdomain filter — reliable signal vs wildcard DNS noise
- **Interactive selection** — visitor participates by choosing the scan target
- **5000-name wordlist** from SecLists — comprehensive but fast (~2 min probe)
- **In-memory scan state** — volatile (restart clears), reports are files on disk (persist)
- **IP fast-path** — skips discovery when an IP address is entered

## Development

```bash
# Repository
cd ~/gitex2026
# aasd/src/  — Go source
# aasd/docs/ — Documentation

# Build
cd ~/gitex2026/aasd/src
go build -o /opt/aasd/aasd ./cmd/aasd/
go vet ./...

# Update wordlist (optional, defaults to built-in 40 names)
curl -sL -o /opt/aasd/subdomains.txt \
  "https://raw.githubusercontent.com/danielmiessler/SecLists/master/Discovery/DNS/subdomains-top1million-5000.txt"
```

## License

Proprietary — For internal event use at GITEX 2026.