gitex2026/aasd/AGENT.md

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 ../bin/aasd ./cmd/aasd/ (outputs to bin/)
• 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_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROM env vars override YAML and defaults
• Gin web framework — all HTTP routing via router.POST/GET
• Comments in Go code — use // not /* */ per project style

Testing

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

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