From 71b31b7c285207dcd391ac3115395e26cbf276ab Mon Sep 17 00:00:00 2001 From: administrator Date: Wed, 29 Apr 2026 07:56:00 +0000 Subject: [PATCH] docs: restructure README into aasd/, add sample configs, update gitignore - Move README.md and AGENT.md into aasd/ (app-specific docs) - Create root README.md as lightweight repo overview (GITEX 2026 apps) - Add aasd/sample.config.yaml with placeholder values for deployment - Add aasd/sample.env with documented environment variables - Update .gitignore to exclude config.yaml, binaries, reports/ and logs/ --- .gitignore | 11 +++ README.md | 170 +++----------------------------------- AGENT.md => aasd/AGENT.md | 0 aasd/README.md | 165 ++++++++++++++++++++++++++++++++++++ aasd/sample.config.yaml | 18 ++++ aasd/sample.env | 16 ++++ 6 files changed, 222 insertions(+), 158 deletions(-) rename AGENT.md => aasd/AGENT.md (100%) create mode 100644 aasd/README.md create mode 100644 aasd/sample.config.yaml create mode 100644 aasd/sample.env diff --git a/.gitignore b/.gitignore index 905bda0..a14a341 100644 --- a/.gitignore +++ b/.gitignore @@ -10,3 +10,14 @@ Thumbs.db .idea/ *.swp *.swo + +# Binaries +*.exe +*.bin + +# Config — never commit real credentials +**/config.yaml + +# Runtime directories (deployment-only) +reports/ +logs/ diff --git a/README.md b/README.md index 7f36bc0..dfa8f02 100644 --- a/README.md +++ b/README.md @@ -1,168 +1,22 @@ -# AASD — API Attack Surface Discovery +# GITEX 2026 — Booth Applications -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. +This repository contains the applications developed for the **Sechpoint Aftica** booth at **GITEX 2026**. -``` -Enter domain → Discover subdomains → Pick target → GoTestWAF scan → AI report → QR code -``` +## Applications + +| App | Directory | Description | +|-----|-----------|-------------| +| **AASD** | [`aasd/`](aasd/) | API Attack Surface Discovery — interactive booth demo | ## 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 - -### config.yaml - -Edit `/opt/aasd/config.yaml`: - -```yaml -ai: - api_key: "sk-..." # DeepSeek API key for AI narratives -server: - base_url: "https://aasd.sechpoint.app" # Public URL for QR codes & email -admin: - username: "sechpoint" - password: "Git3x2o26" # Admin dashboard password -``` - -### 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 +Each application has its own `README.md` with build and deploy instructions. ```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" +# AASD +cd aasd/ +# Build: cd src && go build -o /opt/aasd/aasd ./cmd/aasd/ +# Deploy: sudo systemctl restart aasd ``` ## License diff --git a/AGENT.md b/aasd/AGENT.md similarity index 100% rename from AGENT.md rename to aasd/AGENT.md diff --git a/aasd/README.md b/aasd/README.md new file mode 100644 index 0000000..e1c48bf --- /dev/null +++ b/aasd/README.md @@ -0,0 +1,165 @@ +# 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. diff --git a/aasd/sample.config.yaml b/aasd/sample.config.yaml new file mode 100644 index 0000000..e9bd3ae --- /dev/null +++ b/aasd/sample.config.yaml @@ -0,0 +1,18 @@ +# AASD — Sample Configuration +# +# Copy this file to config.yaml in your deployment directory +# (e.g. /opt/aasd/config.yaml) and fill in your values. +# +# All values can also be set via environment variables — see sample.env. + +ai: + provider_url: "https://api.deepseek.com" + api_key: "sk-your-deepseek-api-key-here" # DeepSeek API key for AI narratives + model: "deepseek-chat" + +server: + base_url: "https://aasd.example.com" # Public URL for QR codes & email links + +admin: + username: "admin" # Admin dashboard username + password: "your-secure-password-here" # Admin dashboard password diff --git a/aasd/sample.env b/aasd/sample.env new file mode 100644 index 0000000..b503e26 --- /dev/null +++ b/aasd/sample.env @@ -0,0 +1,16 @@ +# AASD — Environment Variables +# +# All configuration can be set via environment variables. +# These override values in config.yaml when both are present. +# +# Source this file after editing: source sample.env + +# Server +export AASD_BASE_URL="https://aasd.example.com" + +# SMTP (for email report delivery) +export SMTP_HOST="smtp.example.com" +export SMTP_PORT="587" +export SMTP_USERNAME="user@example.com" +export SMTP_PASSWORD="your-smtp-password" +export SMTP_FROM="user@example.com"