# cuckoosandbox/cuckoo architecture

> Architecture diagram of the GitHub repository cuckoosandbox/cuckoo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cuckoosandbox/cuckoo
- Repository: https://github.com/cuckoosandbox/cuckoo

## Overview

##### Project type and purpose
- This is Cuckoo Sandbox: an open-source, full-stack, automated malware analysis system.
- It provides both a CLI/API-driven core to run analyses (scheduling, VM orchestration, result collection, processing, reporting) and optional distributed cluster support, plus a web UI for users.

##### High-level architectural components
a. Submission & API Layer
- CLI entrypoint (main.py) and REST/API endpoints (cuckoo/apps/api.py, cuckoo/web/controllers/*) receive files or URLs.
b. Core Orchestration
- Scheduler (cuckoo/core/scheduler.py) queues tasks.
- Guest Controller (cuckoo/core/guest.py) launches analysis inside a chosen VM or physical host via “machinery” drivers (cuckoo/machinery/*).
- Result Server (cuckoo/core/resultserver.py) listens for callbacks (agent connections, dumped data).
c. Virtualization / Guest Environments
- “machinery” drivers for KVM, QEMU, VirtualBox, VMware, Xen, ESX, AVD, physical.
- Guest agents (cuckoo/data/agent/agent.py) communicate analysis data back to the host.
- Network services: DNS stub (cuckoo/apps/dnsserve.py), MITM proxy/sniffer (cuckoo/auxiliary/mitm.py, sniffer.py).
d. Processing Pipeline
- Extraction (cuckoo/core/extract.py) of dropped files, memory, network traces.
- Multiple processing modules (cuckoo/processing/*) analyze memory dumps, network PCAP, sandboxed behavior, static properties, signatures, YARA.
e. Storage & Persistence
- Local file storage tree (cuckoo/data/storage).
- SQL database (cuckoo/core/database.py via SQLAlchemy), migrations under private/db_migration.
- Optional: MongoDB, Elasticsearch, Moloch support via reporting modules.
f. Reporting & Export
- JSON, single-file HTML, Mattermost, MISP, VirusTotal, email, etc. (cuckoo/reporting/*).
g. Web UI & Distributed Dashboard
- Django-style controllers/views/templates in cuckoo/web and cuckoo/distributed for cluster metrics.
- Front-end assets built with Gulp, Handlebars, SCSS, JS in web/src and distributed/src.
- REST API backing the web UI (cuckoo/web/controllers/*, cuckoo/distributed/api.py).

##### Relationships & Data Flows
- Submission → Scheduler → Virtualization Driver → Guest VM → Agent → Result Server → Processing → Storage/DB → Reporting & Web UI
- Distributed mode: Scheduler can push tasks to remote workers; workers report back status to a central DB; cluster UI polls a “distributed” API.
- Web UI reads from the same DB (and optionally Elasticsearch) via API controllers.

##### Architectural patterns & design principles
- Modular, plugin-based core: new analyzers, services, reporting backends can be dropped into designated directories.
- MVC for the web component (separate controllers, views, templates).
- Layered pipeline: orchestration → execution → data capture → processing → reporting.
- Adapter pattern in machinery drivers to unify heterogeneous VM/host interfaces.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: Ingestion/API
    subgraph "1. Ingestion/API Layer"
        CLI["CLI Entrypoint\n(main.py)"]:::orchestration
        RESTAPI["REST/API Endpoints\n(api.py)"]:::orchestration
        WebSub["Web Submission Controllers"]:::orchestration
    end

    %% Layer 2: Core Orchestration & Scheduler
    subgraph "2. Core Orchestration & Scheduler"
        Scheduler["Scheduler\n(scheduler.py)"]:::orchestration
        SubmitLogic["Submission Logic\n(submit.py)"]:::orchestration
        Feedback["Feedback & Root Privileges\n(feedback.py, rooter.py)"]:::orchestration
        CoreInit["Core Init & Startup\n(init.py, startup.py)"]:::orchestration
        GuestCtrl["Guest Controller\n(guest.py)"]:::orchestration
        ResultSrv["Result Server\n(resultserver.py)"]:::orchestration
    end

    %% Layer 3: Virtualization & Network Services
    subgraph "3. Virtualization / Guest Environments"
        Machinery["Machinery Drivers"]:::orchestration
        Agent["Guest Agent\n(agent.py)"]:::orchestration
        DNSStub["DNS Stub Service\n(dnsserve.py)"]:::orchestration
        MITM["MITM Proxy / Sniffer"]:::orchestration
    end

    %% Layer 4: Guest VMs & Agents
    subgraph "4. Guest VMs & Agents"
        VM["Guest VM / Host"]:::orchestration
    end

    %% Layer 5: Result Server & Processing
    subgraph "5. Result Server & Processing Pipeline"
        Extract["Extraction Module\n(extract.py)"]:::orchestration
        Processing["Processing Modules\n(processing/)"]:::orchestration
    end

    %% Layer 6: Storage & Persistence
    subgraph "6. Storage & Persistence"
        StorageFS["Local File Storage\n(data/storage)"]:::storage
        SQLDB["SQL Database\n(SQLAlchemy)"]:::storage
        Migrations["DB Migrations\n(db_migration/)"]:::storage
    end

    %% Layer 7: Reporting & Web UI / Distributed Dashboard
    subgraph "7. Reporting & Web UI & Distributed"
        Reporting["Reporting Backends\n(reporting/)"]:::external
        WebUI["Web UI MVC & Assets"]:::ui
        DistributedAPI["Distributed Cluster API & UI"]:::ui
    end

    %% Connections
    CLI -->|submits| Scheduler
    RESTAPI -->|submits| Scheduler
    WebSub -->|submits| Scheduler

    Scheduler --> SubmitLogic
    SubmitLogic --> GuestCtrl
    GuestCtrl --> Machinery
    Machinery --> VM
    VM --> Agent
    Agent --> ResultSrv

    ResultSrv --> Extract
    Extract --> Processing
    Processing --> StorageFS
    Processing --> SQLDB

    StorageFS -->|reads/writes| WebUI
    SQLDB -->|reads/writes| WebUI
    SQLDB -->|reads/writes| Reporting
    StorageFS -->|optional reads| Reporting

    Scheduler <-->|tasks/status| DistributedAPI

    %% Click Events
    click CLI "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/main.py"
    click RESTAPI "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/apps/api.py"
    click WebSub "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/web/controllers/submission/api.py"
    click WebSub "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/web/controllers/submission/routes.py"
    click Scheduler "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/core/scheduler.py"
    click GuestCtrl "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/core/guest.py"
    click ResultSrv "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/core/resultserver.py"
    click SubmitLogic "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/core/submit.py"
    click Feedback "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/core/feedback.py"
    click Rooter "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/core/rooter.py"
    click CoreInit "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/core/init.py"
    click CoreInit "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/core/startup.py"
    click Machinery "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/machinery/kvm.py"
    click Machinery "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/machinery/qemu.py"
    click Machinery "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/machinery/virtualbox.py"
    click Machinery "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/machinery/vmware.py"
    click Machinery "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/machinery/esx.py"
    click Machinery "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/machinery/xenserver.py"
    click Machinery "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/machinery/avd.py"
    click Machinery "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/machinery/physical.py"
    click Machinery "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/machinery/vsphere.py"
    click Agent "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/data/agent/agent.py"
    click DNSStub "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/apps/dnsserve.py"
    click MITM "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/auxiliary/mitm.py"
    click MITM "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/auxiliary/sniffer.py"
    click Extract "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/core/extract.py"
    click Processing "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/processing/"
    click StorageFS "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/data/storage"
    click SQLDB "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/core/database.py"
    click Migrations "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/private/db_migration/"
    click Reporting "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/reporting/"
    click WebUI "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/web/controllers/"
    click WebUI "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/web/templates/"
    click WebUI "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/web/dashboard/"
    click WebUI "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/web/src/"
    click WebUI "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/web/static/"
    click DistributedAPI "https://github.com/cuckoosandbox/cuckoo/blob/master/cuckoo/distributed/api.py"
    click DistributedAPI "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/distributed/views/"
    click DistributedAPI "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/distributed/templates/"
    click DistributedAPI "https://github.com/cuckoosandbox/cuckoo/tree/master/cuckoo/distributed/src/"

    %% Styling
    classDef orchestration fill:#bee3f8,stroke:#3182ce,stroke-width:1px
    classDef storage fill:#c6f6d5,stroke:#38a169,stroke-width:1px
    classDef ui fill:#fefcbf,stroke:#d69e2e,stroke-width:1px
    classDef external fill:#fed7d7,stroke:#e53e3e,stroke-width:1px
```
