AttackEye — Architecture Documentation

1. Overview

AttackEye is a web-based cybersecurity platform built with Django and Docker, designed as a multi-tenant SaaS for External Attack Surface Management (EASM) and continuous security monitoring.

AttackEye provides: - Spyglass (subdomain discovery / recon) - PortScan (open ports, services) - EIFP (email & impersonation / look-alike domain checks) - VulScan (web vulnerability scanning via containerized scanner) - Darkweb & Social Media Insights - Threat Feeds / Threat Intelligence - Alerts & Reporting (beautiful detailed reports)

The system offers: - GUI for interactive use (web portal) - External API (SaaS) via a dedicated Django app (external_api) for authenticated customers to trigger scans programmatically.

2. Goals & Non-Goals

2.1 Goals

Provide a scalable multi-tenant architecture with strong isolation.
Support both UI-driven and API-driven workflows.
Run scanning modules in isolated containers for security and portability.
Asynchronous processing for long-running scans via Celery.
Real-time updates (scan progress/alerts) via WebSockets.
Generate rich, detailed, exportable reports.

2.2 Non-Goals (Current)

Fully automated auto-remediation (block IP, patching) out of scope unless added later.
On-prem “air-gapped” hardening and compliance packaging (future roadmap).

3. Users, Roles, and Tenant Model

AttackEye uses multi-tenant architecture with schema-based tenancy using django_tenants.

3.1 Tenant Types

Public: entry website, onboarding, payment, marketing/landing, tenant registration.
Master: administrative control (system-level admin, global settings).
Tenant: customer environment containing organizations, domains, scans, reports.

3.2 Roles inside a Tenant

Admin: manage tenant, users, billing, domains, full scan control.
Scan Operator: run scans, view results, generate reports (limited admin).
Observer: view-only access to dashboards and reports.

4. Key Workflows

4.1 Onboarding & Payment Flow

User selects plan and completes payment.
System creates a Tenant and primary Domain entry.
System creates the first Admin user for that tenant.
Tenant admin logs in → dashboard is initially empty.
Admin registers a domain → domain verification occurs.
Once verified, scanning modules can be executed and reports generated.

4.2 Scanning Flow (High Level)

User triggers scan from UI or External API.
Backend creates a scan job and queues async tasks.
A module container runs tools/scripts and writes findings.
Results are normalized and stored in Postgres under the tenant schema.
UI receives progress updates via WebSockets (Django Channels).
User generates a consolidated report.

5. System Architecture (Containers + Services)

AttackEye is deployed using Docker Compose and consists of:

5.1 Core Services

web (Django application)
celery (Celery workers for async tasks)
celery beat (scheduled tasks; DB-backed scheduler)
db (PostgreSQL 16, tenant-aware backend via django_tenants)
rabbitmq (Celery broker)
redis (channels layer + caching)
ollama (LLM service used for enrichment/analysis - optional feature)

5.2 Module Containers (Microservices)

Each module runs as a separate container with its own lightweight API (Flask), for example: - spyglass (Flask) - portscan (Flask) - eifp (Flask) - vulscan (scanner container) - reporting (Node-based report generation) - domain_sec_scanner (domain security checks)

Modules are orchestrated by Django/Celery and communicate through: - HTTP API calls (Django → module Flask apps) - Shared volumes (where required; e.g., output folders) - Database writes via Django ingestion pipeline

6. Component Responsibilities

6.1 Django Web App (`web`)

Responsibilities: - UI pages, dashboards, tenant routing, session-based auth - Domain registration + verification workflow - Job creation + orchestration logic - Aggregation of module findings - Report generation triggers - External API app (external_api) for SaaS consumption (JWT auth)

6.2 Celery Worker (`celery`)

Responsibilities: - Long-running scan execution orchestration - Parallelization (fan-out to modules, fan-in results) - Retrying failed tasks with backoff - Sending notifications / progress updates - Scheduled jobs (via Celery beat): periodic scans, threat feed pulls, housekeeping

6.3 RabbitMQ

Message broker for Celery tasks.

6.4 Redis

Django Channels layer for WebSockets.
Caching for common read-heavy objects.

6.5 PostgreSQL

Primary data store for tenants.
Schema-per-tenant isolation (public/master/tenant schemas).

6.6 Reporting Service (Node)

Generates the “beautiful detailed report” artifacts (PDF/HTML).
Pulls data from Django API or DB (depending on implementation).

7. Authentication & Authorization

7.1 UI Authentication

Django session-based authentication.
Role-based access control for views and actions.

7.2 External API Authentication

JWT authentication via rest_framework_simplejwt.
Tokens issued to tenant users / API clients.
Throttling applied via DRF throttles (anon/user).

8. Real-Time Updates

AttackEye uses: - Django Channels + WebSockets - channels_redis for channel layer backend

Use cases: - Scan progress updates - Alert notifications - Live dashboards

9. Scheduling & Automation

Celery beat with django_celery_beat scheduler stored in DB.
Tenant-aware periodic scheduling supported via django_tenants_celery_beat.

Scheduled jobs can include: - Nightly scans - Threat feed sync every X hours - Cleanup / retention enforcement - Report regeneration and summaries

10. Deployment Topology (Docker Compose)

10.1 Networks

default: general internal traffic
attackeye_net: specific connectivity (e.g., web ↔ ollama)

10.2 Volumes

postgres_data_1 (DB persistence)
spyglass_output (shared output)
vulscan_data_1, vulscan_session_data_1 (scanner workspace)
ollama-data (ollama model storage)

11. Data Model (High-Level)

Typical tenant objects: - Tenant / Domain - Organization (optional grouping) - Target Domain(s) - Scan Jobs - Module Findings (normalized entities) - Alerts - Reports

Recommended approach: - Store raw module outputs + normalized findings - Add deduplication keys and timestamps for trending analytics

12. Observability (Logging + Health)

Tenant-aware logging using TenantContextFilter format: [schema:domain] LEVEL timestamp message
Docker healthchecks for DB and Ollama (already present).
Recommend adding health endpoints for:
Django /health/
Module containers /health/

13. Diagrams

13.1 C1 — GUI System Context

flowchart LR
  User[End User / SOC Analyst] --> UI[AttackEye Web UI]
  UI --> Core[AttackEye Core Platform]
  Core --> Templates[Templates]
  Templates --> Urls[Urls]  
  Urls --> Views[Views]
  Views --> RabbitMQ[(RabbitMQ)]
  RabbitMQ --> Celeryworker[Celeryworker]
  Celeryworker --> FlaskAPI[FlaskAPI]
  FlaskAPI --> Container[Container]
  Container --> DB[(PostgreSQL)]
  DB --> DjangoChannels[DjangoChannels]  
  DjangoChannels --> Core[AttackEye Core Platform]

13.2 C1 — External Api System Context

flowchart LR

  APIClient[External API Client] --> ExternalAPI[AttackEye External API]
  ExternalAPI --> Views[Views]
  Views --> RabbitMQ[(RabbitMQ)]
  RabbitMQ --> Celeryworker[Celeryworker]
  Celeryworker --> FlaskAPI[FlaskAPI]
  FlaskAPI --> Container[Container]
  Container --> DB[(PostgreSQL)]

13.3 C1 — Database Diagram

flowchart LR

  DB[(ATTACKEYE)] --> public[(Public Schema)]
  DB[(ATTACKEYE)] --> Tenant[(Tenant Schema)]
  DB[(ATTACKEYE)] --> Master[(Master Schema)]