# AASD — Agent Guide

This file is for AI agents and developers working on the AASD (API Attack Surface Discovery) codebase.

## Project Overview

AASD is a GITEX 2026 booth demo application. Visitors enter a domain, the app discovers subdomains via HTTPS/TLS probing, and the visitor selects one to scan with GoTestWAF against a Wallarm WAF endpoint.

## Repository Structure

```
gitex2026/
├── aasd/
│   ├── src/                  # Go source code (module: aasd)
│   │   ├── cmd/aasd/main.go  # Entry point — HTTP routes, server lifecycle
│   │   ├── internal/
│   │   │   ├── scanner/      # Core pipeline (discovery, scan orchestration)
│   │   │   │   ├── scanner.go     # Orchestrator, pipeline phases, ScanResult
│   │   │   │   ├── probe.go       # Wordlist-based HTTPS/TLS subdomain probe
│   │   │   │   └── gotestwaf.go   # GoTestWAF binary execution
│   │   │   ├── report/report.go   # HTML report generation
│   │   │   ├── ai/deepseek.go     # DeepSeek AI narrative generation
│   │   │   └── mailer/smtp.go     # SMTP email delivery
│   │   ├── static/           # Frontend HTML/JS (served at runtime from /opt/aasd/static/)
│   │   ├── templates/        # Go HTML templates (admin dashboard)
│   │   ├── go.mod            # Module: aasd, Go 1.25
│   │   └── gotestwaf/        # Vendored GoTestWAF source (reference only)
│   ├── docs/
│   │   ├── CHANGELOG.md
│   │   └── STATE_OF_DEVELOPMENT.md
│   ├── install.sh
│   └── VERSION
├── README.md
└── AGENT.md                  # This file
```

## Deployment

- **Binary**: `/opt/aasd/aasd` (31M, compiled Go binary)
- **Config**: `/opt/aasd/config.yaml`
- **Wordlist**: `/opt/aasd/subdomains.txt` (5000 names from SecLists)
- **Frontend**: `/opt/aasd/static/`
- **Service**: `aasd.service` (systemd, runs as `engineer`, WorkingDir `/opt/aasd`)
- **Build**: `cd ~/gitex2026/aasd/src && go build -o /opt/aasd/aasd ./cmd/aasd/`
- **Restart**: `sudo systemctl restart aasd`

## Architecture — Pipeline Flow

```
Visitor enters domain (or IP)
         ↓
POST /start → orchestrator.StartPipeline()
         ↓
    ┌─────IP detected?─────┐
    │ YES                  │ NO
    ↓                      ↓
executeScanPhase()    discoverSubdomains()
    │                      │
    │              ProbeSubdomains()
    │              (5000 names × HTTPS/TLS)
    │                      │
    │              Status: awaiting_selection
    │                      │
    │              POST /select-subdomain
    │                      │
    └──────────┬───────────┘
               ↓
    executeScanPhase(selectedDomain)
         ↓
    GoTestWAF scan → AI narrative → Static HTML report
         ↓
    Status: completed → visitor + consultant reports
```

## Key Components

### ProbeSubdomains (`probe.go`)
- Loads wordlist from `projectRoot/subdomains.txt` (falls back to 40 built-in names)
- Probes each name with `https://{name}.{domain}`
- Go's `http.Client` validates TLS certificate by default — this is the **definitive signal**
- Filters out wildcard DNS catch-all (no valid cert for arbitrary names)
- Reports progress via `onProgress(checked, total)` callback
- Concurrency: 10 workers, 3s timeout per request

### Orchestrator (`scanner.go`)
- **`StartPipeline`**: Creates scan result, starts discovery or direct scan for IPs
- **`discoverSubdomains`**: Runs ProbeSubdomains, pauses for user selection
- **`executeScanPhase`**: Runs GoTestWAF, generates AI narrative, builds HTML report
- Thread-safe via `sync.RWMutex` on map operations

### GoTestWAF (`gotestwaf.go`)
- Executes GoTestWAF binary as subprocess
- Targets `https://{selectedDomain}`
- 120s timeout, produces `consultant_{token}.html` on success
- If GoTestWAF fails (target unreachable), status still completes with fallback report

### Report Naming
- Visitor report: `visitor_{token}.html` (always generated)
- Consultant report: `consultant_{token}.html` (only when GoTestWAF succeeds)

## Important Patterns

- **No persistent storage** — scan results are in-memory only (map), lost on restart
- **Reports are files** — persisted at `/opt/aasd/reports/`, survive restarts
- **Config via YAML** — `/opt/aasd/config.yaml` for server URL, admin credentials, AI key
- **Environment config** — AASD_BASE_URL, SMTP_* env vars override YAML
- **Gin web framework** — all HTTP routing via `router.POST/GET`
- **Comments in Go code** — use `//` not `/* */` per project style

## Testing

```bash
# Build and deploy
cd ~/gitex2026/aasd/src && go build -o /opt/aasd/aasd ./cmd/aasd/
sudo systemctl restart aasd

# Check service
sudo systemctl status aasd
sudo journalctl -u aasd -f