How cuckoosandbox/cuckoo works
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.