c09d266f02
- Add aasd/bin/ with compiled aasd binary and gotestwaf binary - Fix .gitignore: remove blanket *.exe/*.bin rules - Update install.sh to support local bin/ deployment (dev workflow) - Update README and AGENT.md docs to reference bin/ directory
119 lines
5 KiB
Markdown
119 lines
5 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# 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
|