customer-engineering/gitex2026

administrator b91406ada4 fix: email report URL, duplicate case; feat: Home button, email UI, scan timer; test: 44 unit tests; refactor: IsIP to pkg/netutil; docs: SMTP env vars

- Fix email report URL: /{token}.html → /visitor_{token}.html
- Remove duplicate case 'generating' in simulation.html polling
- Add defensive guard against empty Subdomains in SelectAndScan
- Add Home link and Start New Scan button to visitor report
- Replace QR code injection with email-send form in consultant report
- Add scan timer animation (barberpole + elapsed counter) to frontend
- Move IsIP() from scanner/probe.go to pkg/netutil for reuse
- Add 44 unit tests across scanner, report, and netutil packages
- Create Makefile with build/vet/test/deploy targets
- Document SMTP environment variables in README and AGENT.md

2026-04-29 07:30:42 +00:00

4.9 KiB

Raw Blame History

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_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 /opt/aasd/aasd ./cmd/aasd/
sudo systemctl restart aasd

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

4.9 KiB Raw Blame History Unescape Escape