System Design Overview
RedactedWorld is a cybersecurity pentesting platform that enables authorized security assessments of domains you own or have explicit permission to test. This section covers the architectural decisions, service layout, data stores, infrastructure, and workflows that power the platform.
Key Design Principles
Authorization-First
Every scan begins with DNS TXT record verification. Users must prove domain ownership before any tool is executed. There is no direct IP scanning -- all targets are resolved from verified domains. This ensures the platform is never used to attack infrastructure you do not control.
Microservice Architecture
The platform is composed of 12 NestJS services, each owning a bounded context. Services communicate via gRPC for synchronous calls, NATS for asynchronous events, and WebSocket for real-time client updates.
Real-Time and Scheduled Scanning
Users can launch on-demand scans and receive live terminal output streamed through WebSocket. They can also configure scheduled scans that run automatically on a cron cadence, with results stored for historical comparison.
Fine-Grained Permissions with SpiceDB
Access control is enforced through SpiceDB, a Zanzibar-inspired authorization system. Every API call checks permissions against a relationship graph -- not simple role strings. This enables nuanced policies such as "members of organization X can scan domain Y, but only user Z can delete scan results."
Subdomain-Routed Gateway
All traffic enters through Traefik, which routes requests to seven subdomains (app, api, keycloak, grafana, gitlab, wazuh, doc), each backed by distinct services or infrastructure components.
Documentation Map
| Page | Description |
|---|---|
| Architecture Overview | High-level diagrams of subdomain routing and service topology |
| Services | Port mappings and responsibilities for all 12 services |
| Data Stores | PostgreSQL schemas, SpiceDB schema, ClickHouse, and Elasticsearch |
| Infrastructure | RKE2 cluster, node IPs, and platform components |
| Domain Verification | DNS TXT verification flow and security rules |
| Pentesting Tools | MVP tool catalog (nmap, ZAP, sslyze, subfinder) |
| Job Execution | On-demand and scheduled scan execution pipelines |
| Theming | Three visual themes and CSS custom property system |
| Authentication | Keycloak OIDC and SpiceDB authorization model |