Skip to content

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

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

4.2 Scanning Flow (High Level)

  1. User triggers scan from UI or External API.
  2. Backend creates a scan job and queues async tasks.
  3. A module container runs tools/scripts and writes findings.
  4. Results are normalized and stored in Postgres under the tenant schema.
  5. UI receives progress updates via WebSockets (Django Channels).
  6. 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)]

--

14. Use Case Catalog

14.1 Authentication & Authorization

Use Case ID Use Case Name Actor Description
UC-AUTH-01 Register New Account Guest User signs up for AttackEye service
UC-AUTH-02 Login to System Admin, Scan Operator, Observer User logs in with credentials
UC-AUTH-03 Logout from System Admin, Scan Operator, Observer User logs out
UC-AUTH-04 Reset Password Admin, Scan Operator, Observer User requests password reset
UC-AUTH-05 Obtain JWT Token External API Client Client obtains access token for API usage
UC-AUTH-06 Refresh JWT Token External API Client Client refreshes expired token
UC-AUTH-07 Manage User Roles Admin Admin assigns/modifies user roles

14.2 Payment & Subscription Management

Use Case ID Use Case Name Actor Description
UC-PAY-01 Select Subscription Plan Guest User selects pricing tier
UC-PAY-02 Process Payment Guest, Payment Gateway Payment is processed and verified
UC-PAY-03 Create Tenant After Payment System Automated tenant creation post-payment
UC-PAY-04 Upgrade Subscription Admin Admin upgrades to higher tier
UC-PAY-05 Cancel Subscription Admin Admin cancels subscription
UC-PAY-06 View Billing History Admin Admin reviews payment history

14.3 Tenant & Organization Management

Use Case ID Use Case Name Actor Description
UC-TENANT-01 Create Tenant Schema System Create isolated database schema
UC-TENANT-02 Configure Tenant Settings Admin Admin customizes tenant configuration
UC-TENANT-03 Invite Team Members Admin Admin add users to tenant
UC-TENANT-04 Manage User Permissions Admin Admin assigns role-based permissions
UC-TENANT-05 Remove User from Tenant Admin Admin removes user access
UC-TENANT-06 View Tenant Dashboard Admin, Scan Operator, Observer Users access tenant-specific dashboard

14.4 Domain Management

Use Case ID Use Case Name Actor Description
UC-DOM-01 Register Domain Admin Add domain to monitoring list
UC-DOM-02 Verify Domain Ownership Admin, System Verify domain via meta tag verification
UC-DOM-03 View Domain Status Admin, Scan Operator, Observer Check domain verification status
UC-DOM-04 Edit Domain Details Admin Modify domain metadata
UC-DOM-05 Remove Domain Admin Delete domain from system
UC-DOM-06 List All Domains Admin, Scan Operator, Observer View all registered domains

14.5 Spyglass Module (Subdomain Discovery)

Use Case ID Use Case Name Actor Description
UC-SPY-01 Start Spyglass Scan Admin, Scan Operator Initiate subdomain enumeration
UC-SPY-02 Configure Spyglass Parameters Admin, Scan Operator Set scan depth, tools, wordlists
UC-SPY-03 View Spyglass Progress Admin, Scan Operator, Observer Monitor real-time scan progress via WebSocket
UC-SPY-04 View Discovered Subdomains Admin, Scan Operator, Observer Review enumerated subdomains
UC-SPY-05 Export Spyglass Results Admin, Scan Operator Export subdomain list (excel sheet)

14.6 PortScan Module

Use Case ID Use Case Name Actor Description
UC-PORT-01 Start Port Scan Admin, Scan Operator Scan ports on target domains/IPs
UC-PORT-02 Configure Port Range Admin, Scan Operator Specify ports to scan
UC-PORT-03 View Open Ports Admin, Scan Operator, Observer See discovered open ports
UC-PORT-04 Identify Running Services Admin, Scan Operator, Observer View service detection results

14.7 EIFP Module (Email & Impersonation)

Use Case ID Use Case Name Actor Description
UC-EIFP-01 Start EIFP Scan Admin, Scan Operator Check for look-alike domains
UC-EIFP-02 Detect Email Spoofing Admin, Scan Operator Analyze SPF/DKIM/DMARC records
UC-EIFP-03 Find Similar Domains Admin, Scan Operator, Observer Identify typosquatting domains
UC-EIFP-04 View EIFP Alerts Admin, Scan Operator, Observer See flagged impersonation attempts
UC-EIFP-05 Monitor New Registrations System Automated monitoring of new similar domains

14.8 VulScan Module (Vulnerability Scanning)

Use Case ID Use Case Name Actor Description
UC-VUL-01 Start Vulnerability Scan Admin, Scan Operator Launch ZAP-based web vulnerability scan
UC-VUL-02 Configure Scan Profile Admin, Scan Operator Select scan depth
UC-VUL-03 View Vulnerability Findings Admin, Scan Operator, Observer Review discovered vulnerabilities

14.9 Dark Web & Social Media Monitoring

Use Case ID Use Case Name Actor Description
UC-DARK-01 Monitor Dark Web Mentions System Automated scanning of dark web sources
UC-DARK-02 View Dark Web Alerts Admin, Scan Operator, Observer See mentions of organization
UC-DARK-03 Analyze Leaked Credentials Admin, Scan Operator Review compromised credentials
UC-DARK-04 Monitor Social Media System Track brand mentions on social platforms
UC-DARK-05 View Social Media Insights Admin, Scan Operator, Observer See social media analysis
UC-DARK-06 Export Dark Web Report Admin, Scan Operator Generate comprehensive report

14.10 Reporting & Analytics

Use Case ID Use Case Name Actor Description
UC-REP-01 Generate Comprehensive Report Admin, Scan Operator Create full security assessment report
UC-REP-02 Export Report (PDF/HTML) Admin, Scan Operator Download report in various formats
UC-REP-03 Share Report with Stakeholders Admin, Scan Operator Email or share report links

14.11 External API (SaaS)

Use Case ID Use Case Name Actor Description
UC-API-01 Authenticate via API External API Client Obtain JWT token
UC-API-02 Trigger Scan via API External API Client Programmatically start any module scan
UC-API-03 Query Scan Status via API External API Client Check scan progress
UC-API-04 Retrieve Scan Results via API External API Client Fetch findings programmatically
UC-API-05 List Domains via API External API Client Get list of monitored domains

15. Use Case Diagrams

15.1 High-Level System Use Cases

graph TB
    Guest[Guest User]
    Admin[Admin User]
    ScanOp[Scan Operator]
    Observer[Observer User]
    APIClient[External API Client]
    PayGW[Payment Gateway]
    System[System/Scheduler]

    Guest --> UC_Register[Register Account]
    Guest --> UC_SelectPlan[Select Plan]
    Guest --> UC_Payment[Process Payment]

    Admin --> UC_Login[Login]
    Admin --> UC_ManageTenant[Manage Tenant]
    Admin --> UC_ManageDomain[Manage Domains]
    Admin --> UC_RunScans[Execute Scans]
    Admin --> UC_ViewReports[View Reports]
    Admin --> UC_ConfigAlerts[Configure Alerts]
    Admin --> UC_ManageUsers[Manage Users]
    Admin --> UC_Schedule[Schedule Tasks]

    ScanOp --> UC_Login
    ScanOp --> UC_RunScans
    ScanOp --> UC_ViewReports
    ScanOp --> UC_ViewDashboard[View Dashboard]

    Observer --> UC_Login
    Observer --> UC_ViewReports
    Observer --> UC_ViewDashboard

    APIClient --> UC_APIAuth[API Authentication]
    APIClient --> UC_APIScans[Trigger Scans via API]
    APIClient --> UC_APIResults[Retrieve Results via API]



    PayGW --> UC_Payment

15.2 Scanning Workflow Use Cases

graph LR
    User[Admin/Scan Operator]

    User --> SelectModule[Select Scan Module]

    SelectModule --> Spyglass[Spyglass Scan]
    SelectModule --> PortScan[Port Scan]
    SelectModule --> EIFP[EIFP Scan]
    SelectModule --> VulScan[Vulnerability Scan]
    SelectModule --> Drakweb&Socialinsights[Drakweb & Social insights]
    SelectModule --> DomSec[Domain Security Scan]

    Spyglass --> Configure[Configure Parameters]
    PortScan --> Configure
    EIFP --> Configure
    VulScan --> Configure
    Drakweb&Socialinsights --> Configure
    DomSec --> Configure

    Configure --> StartScan[Start Scan]
    StartScan --> MonitorProgress[Monitor Progress]
    MonitorProgress --> ViewResults[View Results]
    ViewResults --> ExportReport[Export Report]

15.3 Domain Management Use Cases

graph TB
    Admin[Admin User]

    Admin --> RegisterDomain[Register New Domain]
    RegisterDomain --> VerifyDomain[Verify Domain Ownership]

    VerifyDomain --> DNS_Verify[Meta tag verification]


    DNS_Verify --> Verified{Verified?}


    Verified -->|Yes| EnableScanning[Enable Scanning]
    Verified -->|No| RetryVerification[Retry Verification]

    EnableScanning --> ManageDomain[Manage Domain Settings]
    ManageDomain --> EditDomain[Edit Domain]
    ManageDomain --> DeleteDomain[Remove Domain]
    ManageDomain --> ViewStatus[View Status]

15.4 Reporting Use Cases

graph LR
    User[Admin/Scan Operator]

    User --> GenerateReport[Generate Report]

    GenerateReport --> SelectModules[Select Modules to Include]
    SelectModules -->  GeneratePDF[Generate PDF/HTML]

    GeneratePDF --> ViewReport[View Report]
    GeneratePDF --> DownloadReport[Download Report]
    GeneratePDF --> ShareReport[Share Report]

15.5 External API Use Cases

graph TB
    APIClient[External API Client]

    APIClient --> Authenticate[Obtain JWT Token]
    Authenticate --> APICall{API Operations}

    APICall --> ListDomains[List Domains]
    APICall --> TriggerScan[Trigger Scan]
    APICall --> CheckStatus[Check Scan Status]
    APICall --> GetResults[Retrieve Results]


    TriggerScan --> SelectModule[Specify Module]
    SelectModule --> SpyglassAPI[Spyglass via API]
    SelectModule --> PortScanAPI[PortScan via API]
    SelectModule --> EIFPAPI[EIFP via API]
    SelectModule --> VulScanAPI[VulScan via API]
    SelectModule --> Drakweb&Socialinsights[Drakweb & Social insights]

15.6 Onboarding Flow Use Case

sequenceDiagram
    participant Guest as Guest User
    participant Web as Web Application
    participant PayGW as Payment Gateway
    participant System as System
    participant DB as Database
    participant Admin as New Admin User

    Guest->>Web: Browse Pricing Plans
    Guest->>Web: Select Plan & Sign Up
    Web->>Guest: Collect User Information
    Guest->>Web: Submit Registration
    Web->>PayGW: Process Payment
    PayGW-->>Web: Payment Confirmed

    Web->>System: Trigger Tenant Creation
    System->>DB: Create Tenant Schema
    System->>DB: Create Domain Entry
    System->>DB: Create Admin User
    System-->>Web: Tenant Created

    Web->>Admin: Send Welcome Email
    Admin->>Web: Login with Credentials
    Web->>Admin: Display Empty Dashboard

    Admin->>Web: Register Domain
    Web->>Admin: Provide Verification Instructions
    Admin->>Web: Complete Verification
    Web-->>Admin: Domain Verified

    Admin->>Web: Start First Scan
    Web-->>Admin: Scan Running

16. Future Use Cases (Roadmap)

Planned Features

  • UC-FUTURE-01: AI-Powered Threat Prediction
  • UC-FUTURE-02: Automated Remediation Workflows
  • UC-FUTURE-03: Mobile App Access
  • UC-FUTURE-04: Compliance Reporting (SOC2, ISO27001)
  • UC-FUTURE-05: Integration Marketplace