# cert-polska/drakvuf-sandbox architecture

> Architecture diagram of the GitHub repository cert-polska/drakvuf-sandbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cert-polska/drakvuf-sandbox
- Repository: https://github.com/cert-polska/drakvuf-sandbox

## Overview

DRAKVUF Sandbox accepts suspicious files through its web interface, queues analysis jobs, runs them in an agentless virtual machine, post-processes the captured behavior, and presents reports and artifacts. The graph also includes documented installation and optional S3 storage capabilities. API and VM wiring is shown at the subsystem level because those implementations were not sampled; uncertain internal calls are omitted.

Main entry points: [`drakrun/analyzer/worker.py`](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/analyzer/worker.py) (Analysis worker), [`drakrun/web/api.py`](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/web/api.py) (Web API), [`drakrun/web/frontend/src/App.jsx`](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/web/frontend/src/App.jsx) (Web frontend), [`drakrun/web/storage.py`](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/web/storage.py) (Artifact access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web interface"]
  node_frontend["Web frontend<br/>[App.jsx]"]
  node_api["Web API<br/>[api.py]"]
  node_web_storage["Artifact access<br/>[storage.py]"]
end

subgraph group_jobs["Analysis jobs"]
  node_job_queue["RQ queue<br/>[worker.py]"]
  node_worker["Analysis worker<br/>[worker.py]"]
end

subgraph group_execution["Sandbox execution"]
  node_analyzer["File analyzer<br/>[analyzer.py]"]
  node_vm["VM management<br/>[vm.py]"]
end

subgraph group_results["Results and storage"]
  node_postprocess["Post-processing<br/>[postprocess.py]"]
  node_plugins["Analysis plugins"]
  node_local_artifacts[("Local analysis files<br/>[paths.py]")]
end

subgraph group_operations["System operations"]
  node_installer["System installer<br/>[install.py]"]
end

node_user(("Analyst"))
node_hypervisor["Virtualization host"]
node_drakvuf["DRAKVUF engine"]
node_s3[("S3 object storage")]

node_user -->|"uploads sample"| node_frontend
node_frontend -->|"calls API"| node_api
node_api -->|"enqueues job"| node_job_queue
node_job_queue -->|"dispatches job"| node_worker
node_worker -->|"runs analysis"| node_analyzer
node_analyzer -->|"uses VM"| node_vm
node_vm -->|"manages guest"| node_hypervisor
node_analyzer -->|"captures behavior"| node_drakvuf
node_worker -->|"processes output"| node_postprocess
node_postprocess -->|"runs plugins"| node_plugins
node_worker -->|"writes artifacts"| node_local_artifacts
node_postprocess -->|"writes results"| node_local_artifacts
node_frontend -->|"requests results"| node_api
node_api -->|"serves artifacts"| node_web_storage
node_web_storage -->|"reads files"| node_local_artifacts
node_worker -.->|"uploads analysis"| node_s3
node_web_storage -.->|"reads objects"| node_s3
node_installer -->|"configures host"| node_hypervisor

click node_frontend "https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/web/frontend/src/App.jsx"
click node_api "https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/web/api.py"
click node_web_storage "https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/web/storage.py"
click node_job_queue "https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/analyzer/worker.py"
click node_worker "https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/analyzer/worker.py"
click node_analyzer "https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/analyzer/analyzer.py"
click node_vm "https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/lib/vm.py"
click node_postprocess "https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/analyzer/postprocessing/postprocess.py"
click node_plugins "https://github.com/cert-polska/drakvuf-sandbox/tree/master/drakrun/analyzer/postprocessing/plugins"
click node_local_artifacts "https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/lib/paths.py"
click node_installer "https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/cli/install.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_api,node_web_storage toneBlue
class node_job_queue,node_worker,node_s3 toneAmber
class node_analyzer,node_vm toneMint
class node_postprocess,node_plugins,node_local_artifacts toneRose
class node_installer,node_user,node_hypervisor,node_drakvuf toneIndigo
```

## Components

### Web interface

- [Web frontend](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/web/frontend/src/App.jsx): `drakrun/web/frontend/src/App.jsx`
- [Web API](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/web/api.py): `drakrun/web/api.py`
- [Artifact access](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/web/storage.py): `drakrun/web/storage.py`

### Analysis jobs

- [RQ queue](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/analyzer/worker.py): `drakrun/analyzer/worker.py`
- [Analysis worker](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/analyzer/worker.py): `drakrun/analyzer/worker.py`

### Sandbox execution

- [File analyzer](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/analyzer/analyzer.py): `drakrun/analyzer/analyzer.py`
- [VM management](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/lib/vm.py): `drakrun/lib/vm.py`

### Results and storage

- [Post-processing](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/analyzer/postprocessing/postprocess.py): `drakrun/analyzer/postprocessing/postprocess.py`
- [Analysis plugins](https://github.com/cert-polska/drakvuf-sandbox/tree/master/drakrun/analyzer/postprocessing/plugins): `drakrun/analyzer/postprocessing/plugins`
- [Local analysis files](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/lib/paths.py): `drakrun/lib/paths.py`

### System operations

- [System installer](https://github.com/cert-polska/drakvuf-sandbox/blob/master/drakrun/cli/install.py): `drakrun/cli/install.py`

### Other components

- **Analyst**
- **Virtualization host**
- **DRAKVUF engine**
- **S3 object storage**

## Connections

- Analyst → Web frontend: uploads sample
- Web frontend → Web API: calls API
- Web API → RQ queue: enqueues job
- RQ queue → Analysis worker: dispatches job
- Analysis worker → File analyzer: runs analysis
- File analyzer → VM management: uses VM
- VM management → Virtualization host: manages guest
- File analyzer → DRAKVUF engine: captures behavior
- Analysis worker → Post-processing: processes output
- Post-processing → Analysis plugins: runs plugins
- Analysis worker → Local analysis files: writes artifacts
- Post-processing → Local analysis files: writes results
- Web frontend → Web API: requests results
- Web API → Artifact access: serves artifacts
- Artifact access → Local analysis files: reads files
- Analysis worker → S3 object storage: uploads analysis
- Artifact access → S3 object storage: reads objects
- System installer → Virtualization host: configures host
