11 | {status}
12 | {substatus ? ` (${substatus})` : ""}
13 |
14 | );
15 | }
16 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/bug_report.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Bug report
3 | about: Create a report to help us improve
4 | title: ''
5 | labels: bug
6 | assignees: ''
7 |
8 | ---
9 |
10 | **Describe the bug**
11 |
12 | A clear and concise description of what the bug is.
13 |
14 | **How to reproduce**
15 |
16 | Steps to reproduce the behavior:
17 | 1. Install drakcore and drakrun
18 | 2. Execute `draksetup ...`
19 | 3. Execute (what commands?)...
20 |
21 | **Output of the [status checking commands](https://github.com/CERT-Polska/drakvuf-sandbox#checking-service-status)**
22 |
23 | If applicable (optional).
24 |
--------------------------------------------------------------------------------
/requirements.txt:
--------------------------------------------------------------------------------
1 | dataclasses-json==0.5.6
2 | click==8.1.7
3 | flare-capa==7.4.0
4 | orjson==3.9.15
5 | mslex==1.1.0
6 | pydantic==2.10.6
7 | pathvalidate==3.2.0
8 | drakpdb==0.2.2
9 | tomli==2.2.1
10 | # Web analyzer dependencies
11 | rq==2.3.1
12 | Flask==3.0.3
13 | flask-openapi3[swagger]==4.1.0
14 | python-magic==0.4.27
15 | rq-dashboard==0.8.2.2
16 | # Screenshotter dependencies
17 | asyncvnc==1.3.0
18 | Pillow==10.4.0
19 | Perception==0.6.8
20 | # Perception missing peer dependency
21 | opencv-contrib-python-headless==4.11.0.86
22 | # Also peer vivisect dependency, but we use it directly
23 | msgpack==1.0.8
24 | boto3==1.38.15
25 |
--------------------------------------------------------------------------------
/drakrun/cli/postprocess.py:
--------------------------------------------------------------------------------
1 | import pathlib
2 |
3 | import click
4 |
5 | from drakrun.lib.config import load_config
6 |
7 |
8 | @click.command("postprocess")
9 | @click.argument(
10 | "output_dir",
11 | type=click.Path(exists=True),
12 | )
13 | def postprocess(output_dir):
14 | """
15 | Run postprocessing on analysis output
16 | """
17 | from drakrun.analyzer.postprocessing import (
18 | append_metadata_to_analysis,
19 | postprocess_analysis_dir,
20 | )
21 |
22 | config = load_config()
23 | output_dir = pathlib.Path(output_dir)
24 | extra_metadata = postprocess_analysis_dir(output_dir, config)
25 | append_metadata_to_analysis(output_dir, extra_metadata)
26 |
--------------------------------------------------------------------------------
/docs/Makefile:
--------------------------------------------------------------------------------
1 | # Minimal makefile for Sphinx documentation
2 | #
3 |
4 | # You can set these variables from the command line, and also
5 | # from the environment for the first two.
6 | SPHINXOPTS ?=
7 | SPHINXBUILD ?= sphinx-build
8 | SOURCEDIR = .
9 | BUILDDIR = _build
10 |
11 | # Put it first so that "make" without argument is like "make help".
12 | help:
13 | @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14 |
15 | .PHONY: help Makefile
16 |
17 | # Catch-all target: route all unknown targets to Sphinx using the new
18 | # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19 | %: Makefile
20 | @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
21 |
--------------------------------------------------------------------------------
/test/vm-runner-client/vm_runner_client/socks.py:
--------------------------------------------------------------------------------
1 | import requests
2 | from python_socks.sync import Proxy
3 |
4 |
5 | def create_connection(
6 | host,
7 | port,
8 | proxy_username=None,
9 | proxy_password=None,
10 | proxy_host=None,
11 | proxy_port=None
12 | ):
13 | """
14 | Establishes TCP connection with host via SOCKS5
15 | """
16 | proxy = Proxy.from_url(f'socks5://{proxy_username}:{proxy_password}@{proxy_host}:{proxy_port}')
17 | return proxy.connect(host, port)
18 |
19 |
20 | def make_session(socks5_uri):
21 | session = requests.Session()
22 | session.proxies.update({
23 | 'http': socks5_uri,
24 | 'https': socks5_uri
25 | })
26 | return session
27 |
--------------------------------------------------------------------------------
/dev/config.example.toml:
--------------------------------------------------------------------------------
1 | # Copy this file to config.toml
2 | #
3 | # If you want to connect it to the remote worker instance:
4 | # - change [redis] so it points to the Redis host shared with worker
5 | # - uncomment and change [s3] section so it points to the S3 host shared with worker
6 |
7 | [redis]
8 | host = "redis."
9 | port = 6379
10 |
11 | # [s3]
12 | # address = "https://"
13 | # access_key = "
14 |
31 | );
32 | }
33 |
--------------------------------------------------------------------------------
/drakrun/web/app.py:
--------------------------------------------------------------------------------
1 | import os
2 |
3 | import rq_dashboard
4 | from flask import jsonify, send_file
5 | from flask_openapi3 import Info, OpenAPI
6 |
7 | from drakrun.lib.config import load_config
8 | from drakrun.version import __version__
9 |
10 | from .api import api
11 |
12 | info = Info(title="Drakvuf Sandbox", version=__version__)
13 | app = OpenAPI(__name__, info=info, static_folder="frontend/dist/assets")
14 | config = load_config()
15 | app.config.update(
16 | {
17 | "RQ_DASHBOARD_REDIS_URL": config.redis.make_url(),
18 | }
19 | )
20 | rq_dashboard.web.setup_rq_connection(app)
21 | app.register_blueprint(rq_dashboard.blueprint, url_prefix="/rq")
22 | app.register_api(api)
23 |
24 |
25 | @app.errorhandler(404)
26 | def resource_not_found(e):
27 | return jsonify(error="Object not found"), 404
28 |
29 |
30 | if os.environ.get("DRAKRUN_CORS_ALL"):
31 |
32 | @app.after_request
33 | def add_header(response):
34 | response.headers["Access-Control-Allow-Origin"] = "*"
35 | response.headers["Access-Control-Allow-Headers"] = "Range"
36 | return response
37 |
38 |
39 | @app.route("/")
40 | def index():
41 | return send_file("frontend/dist/index.html")
42 |
43 |
44 | @app.route("/
15 | {Array.from(Array(analysis.screenshots).keys()).map(
16 | (_, idx) => (
17 |
30 |
18 |
19 | 
25 |
26 |
27 | ),
28 | )}
29 |
30 |
38 | );
39 | }
40 |
--------------------------------------------------------------------------------
/drakrun/cli/main.py:
--------------------------------------------------------------------------------
1 | import logging
2 |
3 | import click
4 |
5 | from .analyze import analyze
6 | from .drakshell import drakshell
7 | from .drakvuf_cmdline import drakvuf_cmdline
8 | from .injector import injector
9 | from .install import install
10 | from .make_profile import make_profile
11 | from .modify_vm0 import modify_vm0
12 | from .mount import mount
13 | from .postinstall import postinstall
14 | from .postprocess import postprocess
15 | from .s3_storage import s3_storage
16 | from .snapshot import snapshot
17 | from .vm_start import vm_start
18 | from .vm_stop import vm_stop
19 | from .worker import worker
20 |
21 |
22 | @click.group()
23 | def main():
24 | logging.basicConfig(
25 | level=logging.INFO,
26 | format="[%(asctime)s][%(levelname)s] %(message)s",
27 | handlers=[logging.StreamHandler()],
28 | )
29 | logging.getLogger("drakrun").setLevel(logging.DEBUG)
30 |
31 |
32 | main.add_command(analyze)
33 | main.add_command(postprocess)
34 | main.add_command(install)
35 | main.add_command(postinstall)
36 | main.add_command(vm_start)
37 | main.add_command(vm_stop)
38 | main.add_command(worker)
39 | main.add_command(modify_vm0)
40 | main.add_command(injector)
41 | main.add_command(drakshell)
42 | main.add_command(drakvuf_cmdline)
43 | main.add_command(mount)
44 | main.add_command(make_profile)
45 | main.add_command(s3_storage)
46 | main.add_command(snapshot)
47 |
--------------------------------------------------------------------------------
/drakrun/web/frontend/package.json:
--------------------------------------------------------------------------------
1 | {
2 | "name": "@drakvuf-sandbox/web",
3 | "private": true,
4 | "version": "0.20.0",
5 | "type": "module",
6 | "scripts": {
7 | "dev": "vite",
8 | "build": "vite build",
9 | "lint": "eslint .",
10 | "preview": "vite preview"
11 | },
12 | "dependencies": {
13 | "@fortawesome/fontawesome-svg-core": "^6.7.2",
14 | "@fortawesome/free-regular-svg-icons": "^6.7.2",
15 | "@fortawesome/free-solid-svg-icons": "^6.7.2",
16 | "@fortawesome/react-fontawesome": "^0.2.2",
17 | "@melloware/react-logviewer": "^6.2.0",
18 | "@novnc/novnc": "^1.5.0",
19 | "axios": "^1.12.0",
20 | "bootstrap": "^5.3.5",
21 | "jszip": "^3.10.1",
22 | "jszip-utils": "^0.1.0",
23 | "prettier": "^3.5.3",
24 | "react": "^19.0.0",
25 | "react-dom": "^19.0.0",
26 | "react-medium-image-zoom": "^5.2.14",
27 | "react-modal": "^3.16.3",
28 | "react-router-dom": "^6.30.0",
29 | "react-select": "^5.10.1",
30 | "startbootstrap-sb-admin": "^7.0.7"
31 | },
32 | "devDependencies": {
33 | "@eslint/js": "^9.22.0",
34 | "@types/react": "^19.0.10",
35 | "@types/react-dom": "^19.0.4",
36 | "@vitejs/plugin-react": "^4.3.4",
37 | "eslint": "^9.22.0",
38 | "eslint-plugin-react-hooks": "^5.2.0",
39 | "eslint-plugin-react-refresh": "^0.4.19",
40 | "globals": "^16.0.0",
41 | "vite": "^6.4.1"
42 | },
43 | "prettier": {
44 | "tabWidth": 4
45 | }
46 | }
47 |
--------------------------------------------------------------------------------
/drakrun/analyzer/postprocessing/plugins/build_process_tree.py:
--------------------------------------------------------------------------------
1 | import json
2 | import logging
3 |
4 | from ..process_tree import tree_from_log
5 | from .plugin_base import PostprocessContext
6 |
7 | logger = logging.getLogger(__name__)
8 |
9 |
10 | def build_process_tree(context: PostprocessContext) -> None:
11 | analysis_dir = context.analysis_dir
12 | procmon_log_path = analysis_dir / "procmon.log"
13 | process_tree_path = analysis_dir / "process_tree.json"
14 |
15 | with procmon_log_path.open("r") as procmon_log:
16 | process_tree = tree_from_log(procmon_log)
17 |
18 | data = json.dumps(process_tree.as_dict())
19 | process_tree_path.write_text(data)
20 |
21 | context.process_tree = process_tree
22 | context.update_report(
23 | {
24 | "processes": [
25 | {
26 | "seqid": process.seqid,
27 | "pid": process.pid,
28 | "parent_seqid": process.parent.seqid if process.parent else None,
29 | "name": process.procname,
30 | "args": process.args,
31 | "started_at": process.ts_from,
32 | "exited_at": process.ts_to,
33 | "exit_code": process.exit_code,
34 | "exit_code_str": process.exit_code_str,
35 | "killed_by": process.killed_by,
36 | }
37 | for process in process_tree.processes
38 | ]
39 | }
40 | )
41 |
--------------------------------------------------------------------------------
/drakrun/cli/sanity_check.py:
--------------------------------------------------------------------------------
1 | import logging
2 | import subprocess
3 |
4 | log = logging.getLogger(__name__)
5 |
6 |
7 | def sanity_check():
8 | log.info("Checking xen-detect...")
9 | proc = subprocess.run("xen-detect -N", shell=True)
10 |
11 | if proc.returncode != 1:
12 | log.error(
13 | "It looks like the system is not running on Xen. Please reboot your machine into Xen hypervisor."
14 | )
15 | return False
16 |
17 | log.info("Testing if xl tool is sane...")
18 |
19 | try:
20 | subprocess.run(
21 | "xl info",
22 | shell=True,
23 | stdout=subprocess.DEVNULL,
24 | stderr=subprocess.DEVNULL,
25 | check=True,
26 | )
27 | except subprocess.CalledProcessError:
28 | log.exception(
29 | "Failed to test xl info command. There might be some dependency problem (please execute 'xl info' manually to find out)."
30 | )
31 | return False
32 |
33 | try:
34 | subprocess.run(
35 | "xl list",
36 | shell=True,
37 | stdout=subprocess.DEVNULL,
38 | stderr=subprocess.DEVNULL,
39 | check=True,
40 | timeout=10,
41 | )
42 | except subprocess.SubprocessError:
43 | log.exception(
44 | "Failed to test xl list command. There might be a problem with xen services (check 'systemctl status xenstored', 'systemctl status xenconsoled')."
45 | )
46 | return False
47 |
48 | return True
49 |
--------------------------------------------------------------------------------
/docs/usage/troubleshooting.rst:
--------------------------------------------------------------------------------
1 | Troubleshooting
2 | ===============
3 |
4 | Debug ``device model did not start``
5 | ------------------------------------
6 |
7 | You may encounter the following error with ``draksetup`` command or ``drakrun-worker@*`` service, which will prevent the VM from starting properly.
8 |
9 | ::
10 |
11 | libxl: error: libxl_create.c:1676:domcreate_devmodel_started: Domain 4:device model did not start: -3
12 | ...
13 | subprocess.CalledProcessError: Command 'xl create /etc/drakrun/configs/vm-0.cfg' returned non-zero exit status 3.
14 |
15 | In such a case, you should inspect ``/var/log/xen/qemu*.log`` in order to determine the actual reason why the VM is refusing to start.
16 |
17 | Debug ``can't allocate low memory for domain``
18 | ----------------------------------------------
19 |
20 | The following error with ``drakrun`` command or ``drakrun-worker@*`` service means that your machine is missing memory resources:
21 |
22 | ::
23 |
24 | xc: error: panic: xc_dom_boot.c:122: xc_dom_boot_mem_init: can't allocate low memory for domain: Out of memory
25 | ...
26 | subprocess.CalledProcessError: Command 'xl create /var/lib/drakrun/configs/vm-0.cfg' returned non-zero exit status 3.
27 |
28 | Resolutions:
29 |
30 | * adjust the amount of memory dedicated to the Dom0 (host system) in ``/etc/default/grub.d/xen.cfg`` (look for ``dom0_mem=2048M,max:2048M``) and run ``update-grub && reboot``
31 | * adjust the amount of memory dedicated to the DomU (guest systems) in ``/etc/drakrun/install.json`` or ``/etc/drakrun/cfg.template`` ( ``memory`` and ``maxmem`` keys)
32 |
--------------------------------------------------------------------------------
/drakrun/web/frontend/src/App.css:
--------------------------------------------------------------------------------
1 | .App {
2 | text-align: left;
3 | }
4 |
5 | .App-logo {
6 | height: 40vmin;
7 | }
8 |
9 | .App-header {
10 | background-color: #282c34;
11 | min-height: 100vh;
12 | display: flex;
13 | flex-direction: column;
14 | align-items: center;
15 | justify-content: center;
16 | font-size: calc(10px + 2vmin);
17 | color: white;
18 | }
19 |
20 | .App-link {
21 | color: #09d3ac;
22 | }
23 |
24 | .text-hash {
25 | font-family:
26 | SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono",
27 | "Courier New", monospace;
28 | word-break: break-all;
29 | }
30 |
31 | .apicallTable td {
32 | padding: 0.5rem;
33 | }
34 |
35 | .plugin-badge {
36 | border-radius: 2px;
37 | margin: 2px;
38 | font-size: 85%;
39 | padding: 3px 8px;
40 | text-overflow: ellipsis;
41 | overflow: hidden;
42 | white-space: nowrap;
43 | }
44 |
45 | .tooltip-inner {
46 | max-width: none !important;
47 | white-space: nowrap;
48 | }
49 |
50 | .btn.btn-inline-link {
51 | padding: 0;
52 | margin: 0;
53 | }
54 |
55 | .btn.btn-inline-link:hover {
56 | color: rgb(0, 82, 204);
57 | }
58 |
59 | li.selected {
60 | background-color: rgba(0, 82, 204, 0.1);
61 | border: 1px rgb(0, 82, 204) solid;
62 | padding: 2px 4px;
63 | }
64 |
65 | /* Overriding element hover */
66 | .optionListContainer > .optionContainer li:hover,
67 | .optionContainer .highlight {
68 | background: #e9ecef;
69 | color: #6c757d;
70 | }
71 | /* Ends overriding */
72 |
73 | .ReactModalPortal {
74 | z-index: 10000;
75 | position: absolute;
76 | }
77 |
--------------------------------------------------------------------------------
/drakrun/analyzer/postprocessing/plugins/plugin_base.py:
--------------------------------------------------------------------------------
1 | import pathlib
2 | from typing import Any, Dict, List, NamedTuple, Optional, Protocol
3 |
4 | from drakrun.lib.config import DrakrunConfig
5 |
6 | from ..process_tree import ProcessTree
7 |
8 |
9 | class PostprocessContext:
10 | def __init__(self, analysis_dir: pathlib.Path, config: DrakrunConfig) -> None:
11 | self.analysis_dir = analysis_dir
12 | self.config = config
13 | self._process_tree: Optional[ProcessTree] = None
14 | # Quick metadata fetched along with analysis status
15 | self.metadata = {}
16 | # More verbose data to be placed in report.json
17 | self.report = {}
18 |
19 | @property
20 | def process_tree(self) -> ProcessTree:
21 | if self._process_tree is None:
22 | raise RuntimeError("Process tree not initialized")
23 | return self._process_tree
24 |
25 | @process_tree.setter
26 | def process_tree(self, value: ProcessTree) -> None:
27 | self._process_tree = value
28 |
29 | def update_metadata(self, metadata: Dict[str, Any]) -> None:
30 | self.metadata.update(metadata)
31 |
32 | def update_report(self, report: Dict[str, Any]) -> None:
33 | self.report.update(report)
34 |
35 |
36 | class PostprocessFunction(Protocol):
37 | def __call__(self, context: PostprocessContext) -> None: ...
38 |
39 |
40 | class PostprocessPlugin(NamedTuple):
41 | function: PostprocessFunction
42 | # Paths that are required by plugin to run
43 | requires: List[str]
44 | # Paths that are products of processing and plugin is not run when they exist
45 | generates: List[str]
46 |
--------------------------------------------------------------------------------
/drakrun/lib/paths.py:
--------------------------------------------------------------------------------
1 | import pathlib
2 | import shutil
3 |
4 | ETC_DIR = pathlib.Path("/etc/drakrun")
5 | INSTALL_INFO_PATH = ETC_DIR / "install.json"
6 | XL_CFG_TEMPLATE_PATH = ETC_DIR / "cfg.template"
7 | CONFIG_PATH = ETC_DIR / "config.toml"
8 |
9 | LIB_DIR = pathlib.Path("/var/lib/drakrun")
10 | SNAPSHOT_DIR = LIB_DIR / "volumes"
11 | CONFIGS_DIR = LIB_DIR / "configs"
12 | VMI_PROFILES_DIR = LIB_DIR / "profiles"
13 | PDB_CACHE_DIR = LIB_DIR / "pdb_cache"
14 | ANALYSES_DIR = LIB_DIR / "analyses"
15 | UPLOADS_DIR = LIB_DIR / "uploads"
16 |
17 | VMI_INFO_PATH = VMI_PROFILES_DIR / "runtime.json"
18 | VMI_KERNEL_PROFILE_PATH = VMI_PROFILES_DIR / "kernel.json"
19 |
20 | PACKAGE_DIR = pathlib.Path(__file__).parent.parent.absolute()
21 | PACKAGE_DATA_PATH = PACKAGE_DIR / "data"
22 | PACKAGE_TOOLS_PATH = PACKAGE_DIR / "tools"
23 |
24 | RUN_DIR = pathlib.Path("/var/run/drakrun")
25 |
26 | DUMPS_DIR = "dumps"
27 | DUMPS_ZIP = "dumps.zip"
28 | IPT_DIR = "ipt"
29 | IPT_ZIP = "ipt.zip"
30 |
31 |
32 | def make_dirs():
33 | pathlib.Path(ETC_DIR).mkdir(exist_ok=True)
34 | pathlib.Path(LIB_DIR).mkdir(exist_ok=True)
35 | SNAPSHOT_DIR.mkdir(exist_ok=True)
36 | CONFIGS_DIR.mkdir(exist_ok=True)
37 | ANALYSES_DIR.mkdir(exist_ok=True)
38 | VMI_PROFILES_DIR.mkdir(exist_ok=True)
39 | PDB_CACHE_DIR.mkdir(exist_ok=True)
40 |
41 |
42 | def initialize_config_files():
43 | if not XL_CFG_TEMPLATE_PATH.exists():
44 | source_file = PACKAGE_DATA_PATH / "cfg.template"
45 | shutil.copy(source_file, XL_CFG_TEMPLATE_PATH)
46 | if not CONFIG_PATH.exists():
47 | source_file = PACKAGE_DATA_PATH / "config.toml"
48 | shutil.copy(source_file, CONFIG_PATH)
49 |
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | rwildcard = $(foreach d,$(wildcard $1*),\
2 | $(call rwildcard,$d/,$2) \
3 | $(filter $(subst *,%,$2),$d))
4 | WEB_SOURCE_FILES := $(call rwildcard,drakrun/web/frontend/src/,*.js) $(call rwildcard,drakrun/web/frontend/src/,*.jsx) $(call rwildcard,drakrun/web/frontend/src/,*.css)
5 | PYTHON_SOURCE_FILES := $(call rwildcard,drakrun/,*.py) drakrun/data pyproject.toml MANIFEST.in requirements.txt setup.py
6 |
7 | .PHONY: all
8 | all: dist/*.whl
9 |
10 | dist/*.whl: $(PYTHON_SOURCE_FILES) drakrun/web/frontend/dist drakrun/tools/get-explorer-pid drakrun/tools/drakshell/drakshell
11 | rm -f dist/*.whl
12 | ifndef DIST
13 | DRAKRUN_VERSION_TAG=$(shell git rev-parse --short HEAD) python3 setup.py bdist_wheel
14 | else
15 | python3 setup.py bdist_wheel
16 | endif
17 |
18 | drakrun/web/frontend/dist: drakrun/web/frontend/node_modules $(WEB_SOURCE_FILES) drakrun/web/frontend/vite.config.js drakrun/web/frontend/index.html
19 | cd drakrun/web/frontend ; npm run build
20 |
21 | drakrun/web/frontend/node_modules: drakrun/web/frontend/package.json drakrun/web/frontend/package-lock.json
22 | cd drakrun/web/frontend ; npm ci
23 |
24 | drakrun/tools/get-explorer-pid: drakrun/tools/get-explorer-pid.c
25 | gcc $< -o $@ -lvmi `pkg-config --cflags --libs glib-2.0`
26 |
27 | drakrun/tools/drakshell/drakshell:
28 | $(MAKE) -C drakrun/tools/drakshell
29 |
30 | .PHONY: clean
31 | clean:
32 | rm -rf dist drakvuf_sandbox.egg-info build
33 | rm -rf drakrun/web/frontend/dist drakrun/web/frontend/node_modules
34 | rm -f drakrun/tools/get-explorer-pid drakrun/tools/test-altp2m
35 | rm -f drakrun/tools/drakshell/drakshell
36 |
37 | .PHONY: install
38 | install: all
39 | pip install dist/*.whl
40 |
--------------------------------------------------------------------------------
/test/utils.py:
--------------------------------------------------------------------------------
1 | import io
2 | import logging
3 |
4 |
5 | def apt_install(c, packages):
6 | deps = " ".join(packages)
7 | logging.info(f"Installing {packages} with apt")
8 | c.run(f"DEBIAN_FRONTEND=noninteractive apt-get install -y {deps}", in_stream=False)
9 |
10 |
11 | def dpkg_install(c, deb_file):
12 | logging.info(f"Installing {deb_file} with dpkg")
13 | c.run(f"DEBIAN_FRONTEND=noninteractive dpkg -i {deb_file}", in_stream=False)
14 |
15 |
16 | def get_file(c, path):
17 | tmp = io.BytesIO()
18 | c.get(path, tmp)
19 | return tmp.getvalue()
20 |
21 |
22 | def get_hypervisor_type(c):
23 | return get_file(c, "/sys/hypervisor/type").strip().decode()
24 |
25 |
26 | def get_service_info(c, service):
27 | lines = c.run(f"systemctl show {service}", hide="out").stdout.splitlines()
28 | return dict(map(lambda l: l.split("=", maxsplit=1), lines))
29 |
30 |
31 | class Drakcore:
32 | def __init__(self, drakvuf_vm):
33 | self.host = f"http://{drakvuf_vm.vm_ip}:6300/"
34 | self.session = drakvuf_vm.http_session()
35 |
36 | def get(self, endpoint, *args, **kwargs):
37 | return self.session.get(f"{self.host}{endpoint}", *args, **kwargs)
38 |
39 | def post(self, endpoint, *args, **kwargs):
40 | return self.session.post(f"{self.host}{endpoint}", *args, **kwargs)
41 |
42 | def upload(self, sample, timeout):
43 | response = self.post(f"upload", files={"file": sample}, data={"timeout": timeout})
44 | response.raise_for_status()
45 | return response.json()["task_uid"]
46 |
47 | def check_status(self, task_uuid):
48 | response = self.get(f"status/{task_uuid}")
49 | response.raise_for_status()
50 | return response.json()
51 |
52 | def analysis_log(self, task_uuid, log_name):
53 | response = self.get(f"logs/{task_uuid}/{log_name}", stream=True)
54 | response.raise_for_status()
55 | return response
56 |
--------------------------------------------------------------------------------
/test/test_sanity.py:
--------------------------------------------------------------------------------
1 | import time
2 | import json
3 | import pytest
4 |
5 | from utils import get_hypervisor_type, get_service_info, Drakcore
6 | from conftest import DRAKMON_SERVICES
7 |
8 |
9 | @pytest.fixture
10 | def drakcore(drakmon_vm):
11 | return Drakcore(drakmon_vm)
12 |
13 |
14 | def test_running_on_xen(drakmon_ssh):
15 | assert get_hypervisor_type(drakmon_ssh) == "xen"
16 |
17 |
18 | def test_services_running(drakmon_ssh):
19 | def check_status():
20 | infos = [get_service_info(drakmon_ssh, service) for service in DRAKMON_SERVICES]
21 |
22 | for info in infos:
23 | assert info["LoadState"] == "loaded"
24 | assert info["ActiveState"] == "active"
25 | assert info["SubState"] == "running"
26 |
27 | # Wait up to 5 seconds for the services to be up
28 | for _ in range(5):
29 | try:
30 | check_status()
31 | break
32 | except AssertionError:
33 | pass
34 | time.sleep(1.0)
35 | else:
36 | raise Exception("Services down")
37 |
38 |
39 | def test_web_ui_reachable(drakcore):
40 | response = drakcore.get("/")
41 | response.raise_for_status()
42 |
43 |
44 | def test_sample_analysis(drakcore):
45 | task_uuid = drakcore.upload(open("test.exe", "rb"), timeout=120)
46 |
47 | # wait until end of analysis
48 | while True:
49 | r = drakcore.check_status(task_uuid)
50 | if r["status"] != "pending":
51 | break
52 | time.sleep(10.0)
53 |
54 | # give it a bit more time?
55 | time.sleep(10.0)
56 |
57 | # check logs if our binary was ran
58 | response = drakcore.analysis_log(task_uuid, "filetracer")
59 | for line in response.iter_lines():
60 | d = json.loads(line)
61 | # our sample tried to create a file
62 | if d.get("Method") == "NtCreateFile" and "test.txt" in d.get("FileName"):
63 | break
64 | else:
65 | raise Exception("No matching entry found")
66 |
--------------------------------------------------------------------------------
/drakrun/lib/libvmi/vmi_info.py:
--------------------------------------------------------------------------------
1 | import logging
2 | import re
3 | from dataclasses import dataclass, field
4 | from typing import Optional
5 |
6 | from dataclasses_json import DataClassJsonMixin, config
7 |
8 | log = logging.getLogger(__name__)
9 |
10 | hexstring = config(
11 | encoder=lambda v: hex(v),
12 | decoder=lambda v: int(v, 16),
13 | )
14 |
15 |
16 | @dataclass
17 | class VmiOffsets(DataClassJsonMixin):
18 | # Fields correspond to output defined in
19 | # https://github.com/libvmi/libvmi/blob/master/examples/win-offsets.c
20 |
21 | win_ntoskrnl: int = field(metadata=hexstring)
22 | win_ntoskrnl_va: int = field(metadata=hexstring)
23 |
24 | win_tasks: int = field(metadata=hexstring)
25 | win_pdbase: int = field(metadata=hexstring)
26 | win_pid: int = field(metadata=hexstring)
27 | win_pname: int = field(metadata=hexstring)
28 | win_kdvb: int = field(metadata=hexstring)
29 | win_sysproc: int = field(metadata=hexstring)
30 | win_kpcr: int = field(metadata=hexstring)
31 | win_kdbg: int = field(metadata=hexstring)
32 |
33 | kpgd: int = field(metadata=hexstring)
34 |
35 | @staticmethod
36 | def from_tool_output(output: str) -> "VmiOffsets":
37 | """
38 | Parse vmi-win-offsets tool output and return VmiOffsets.
39 | If any of the fields is missing, throw TypeError
40 | """
41 | offsets = re.findall(r"^([a-z_]+):(0x[0-9a-f]+)$", output, re.MULTILINE)
42 | vals = {k: int(v, 16) for k, v in offsets}
43 | return VmiOffsets(**vals)
44 |
45 |
46 | @dataclass
47 | class VmiInfo(DataClassJsonMixin):
48 | vmi_offsets: VmiOffsets
49 | inject_pid: int
50 | inject_tid: Optional[int] = None
51 |
52 | @staticmethod
53 | def load(file_path: str) -> "VmiInfo":
54 | with open(file_path) as file_obj:
55 | return VmiInfo.from_json(file_obj.read())
56 |
57 |
58 | @dataclass
59 | class VmiGuidInfo:
60 | version: str
61 | guid: str
62 | filename: str
63 |
--------------------------------------------------------------------------------
/drakrun/lib/drakvuf_cmdline.py:
--------------------------------------------------------------------------------
1 | from typing import List, Optional
2 |
3 | from .libvmi import VmiInfo, get_dll_cmdline_args
4 |
5 |
6 | def get_base_drakvuf_cmdline(
7 | vm_name: str,
8 | kernel_profile_path: str,
9 | vmi_info: VmiInfo,
10 | exec_cmd: Optional[str] = None,
11 | extra_args: Optional[List[str]] = None,
12 | ) -> List[str]:
13 | args = [
14 | "drakvuf",
15 | "-o",
16 | "json",
17 | # be aware of https://github.com/tklengyel/drakvuf/pull/951
18 | "-F", # enable fast singlestep
19 | "-k",
20 | hex(vmi_info.vmi_offsets.kpgd),
21 | "-r",
22 | kernel_profile_path,
23 | "-d",
24 | vm_name,
25 | ]
26 | args.extend(get_dll_cmdline_args())
27 | if exec_cmd is not None:
28 | args.extend(
29 | [
30 | "-j",
31 | "60",
32 | "-i",
33 | str(vmi_info.inject_pid),
34 | "-e",
35 | exec_cmd,
36 | *(
37 | ["-I", str(vmi_info.inject_tid), "--exit-injection-thread"]
38 | if vmi_info.inject_tid is not None
39 | else []
40 | ),
41 | ]
42 | )
43 | if extra_args:
44 | args.extend(extra_args)
45 | return args
46 |
47 |
48 | def get_base_injector_cmdline(
49 | vm_name: str,
50 | kernel_profile_path: str,
51 | vmi_info: VmiInfo,
52 | method: str,
53 | args: Optional[List[str]] = None,
54 | ) -> List[str]:
55 | args = args or []
56 | return [
57 | "injector",
58 | "-o",
59 | "json",
60 | "-d",
61 | vm_name,
62 | "-r",
63 | kernel_profile_path,
64 | "-i",
65 | str(vmi_info.inject_pid),
66 | "-k",
67 | hex(vmi_info.vmi_offsets.kpgd),
68 | "-m",
69 | method,
70 | *(["-I", str(vmi_info.inject_tid)] if vmi_info.inject_tid is not None else []),
71 | *args,
72 | ]
73 |
--------------------------------------------------------------------------------
/drakrun/web/frontend/src/AnalysisMetadataTable.jsx:
--------------------------------------------------------------------------------
1 | import { PluginList } from "./PluginPicker.jsx";
2 |
3 | export function AnalysisMetadataTable({ analysis }) {
4 | const startCommand = analysis.options["start_command"] || "-";
5 | return (
6 | | File name | 10 |{analysis.file.name} | 11 |
|---|---|
| SHA256 | 14 |{analysis.file.sha256} | 15 |
| Type | 18 |{analysis.file.type} | 19 |
| Start command | 22 |23 | {Array.isArray(startCommand) 24 | ? startCommand.join(" ") 25 | : startCommand} 26 | | 27 |
| Analysis time | 30 |{analysis.options["timeout"]} seconds | 31 |
| Job started at | 34 |{analysis["time_started"] || "-"} | 35 |
| Execution started at | 38 |{analysis["time_execution_started"] || "-"} | 39 |
| Job finished at | 42 |{analysis["time_finished"] || "-"} | 43 |
| Plugins | 46 |
47 | |
49 |
| Process name | 11 |{processInfo.procname} | 12 |
|---|---|
| PID | 15 |{processInfo.pid} | 16 |
| PPID | 19 |{processInfo.ppid} | 20 |
| Arguments | 23 |24 | {Array.isArray(processInfo.args) 25 | ? processInfo.args.join(" ") 26 | : processInfo.args} 27 | | 28 |
| Started at | 31 |32 | {processInfo.ts_from ? ( 33 | epochToTimestamp(processInfo.ts_from) 34 | ) : ( 35 | (running from the beginning of analysis) 36 | )} 37 | | 38 |
| Finished at | 41 |42 | {processInfo.ts_to ? ( 43 | epochToTimestamp(processInfo.ts_to) 44 | ) : ( 45 | (never) 46 | )} 47 | | 48 |
| Exit code | 52 |53 | {processInfo.exit_code_str} (0x 54 | {processInfo.exit_code.toString(16)}) 55 | | 56 |
Error: {error.toString()}
;
63 | }
64 |
65 | if (typeof analysisInfo === "undefined") {
66 | return (
67 |
68 |
74 | );
75 | }
76 | if (isStatusPending(analysisInfo?.status)) {
77 | return
69 |
70 | Fetching analysis status...
71 |
72 |
73 |
86 |
89 | );
90 | }
91 |
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | Contribute to DRAKVUF Sandbox
2 | =============================
3 |
4 | ## Setup development environment
5 |
6 | ### Prerequisites
7 |
8 | Very first thing to consider is to setup and configure your local instance of DRAKVUF Sandbox. There are two basic options in that matter:
9 |
10 | * Develop on local machine: Install Debian Buster in [VMware Workstation 15 Player](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html).
11 | * Develop on a remote server: Just get some bare-metal or rent a dedicated server (e.g. [Kimsufi](https://www.kimsufi.com/us/en/servers.xml)) with Debian Buster.
12 |
13 | **Caution!** Your host machine must be an Intel processor with VT-x and EPT support, even when using VMware or other nested virtualization. You can check it by executing the following command on your native system (i.e. host system and without hypervisor loaded):
14 |
15 | ```
16 | # should return non-empty output and exit code 0
17 | lscpu | grep -i flags | grep -w ept
18 | ```
19 |
20 | DRAKVUF will not run on incompatible processors, as it directly relies on particular hardware virtualization extensions.
21 |
22 |
23 | ### Clone the repository
24 |
25 | In order to obtain the source code of DRAKVUF Sandbox, you need to execute the following commands:
26 |
27 | ```
28 | git clone --recurse-submodules https://github.com/CERT-Polska/drakvuf-sandbox.git
29 | cd drakvuf-sandbox
30 | ```
31 |
32 | ### Build Debian packages
33 |
34 | #### On local computer
35 |
36 | The DRAKVUF Sandbox distribution packages are built using Docker, in order to make them more reproducible. In order to build the packages by yourself, perform the following steps:
37 |
38 | 1. Obtain and install [Docker](https://docs.docker.com/engine/install/debian/).
39 | 2. Execute:
40 | ```
41 | sh drakcore/package/build.sh
42 | ```
43 | 3. The Debian packages will be produced to the `out/` directory. You can install them similarly as you would install the released packages. See ["Basic installation" section of README.md](https://github.com/CERT-Polska/drakvuf-sandbox/blob/icedevml-patch-1/README.md#basic-installation).
44 |
45 | #### On the Drone CI server
46 |
47 | When you open a pull request to this project, Drone CI will run some tests on your code and Debian packages will be also built during the process. The artifacts produced by the CI are available in S3 bucket at [minio.drakvuf.cert.pl/debs](https://minio.drakvuf.cert.pl/debs).
48 |
49 | Packages are numbered according to the Drone CI job numbers. You can figure out the job number by inspecting the [status checks](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-status-checks) related to your commit and clicking on `Details` link near `continuous-integration/drone/push` label. The build ID is in the URL and also in the breadcrumb, e.g.: `Repositories -> CERT-Polska/drakvuf-sandbox -> #200`.
50 |
51 |
52 | ### Install editable Python packages
53 |
54 | Now you can re-install Python packages from sources, using:
55 |
56 | ```
57 | /opt/venvs/drakcore/bin/pip3 install --editable ./drakcore/
58 | /opt/venvs/drakrun/bin/pip3 install --editable ./drakrun/
59 | ```
60 |
61 | your changes to the DRAKVUF Sandbox services will be immediately visible after you restart them.
62 |
63 | ### Test local changes
64 |
65 | 1. Open `drakcore/drakcore/app.py`
66 | 2. Add these lines before `def main()`:
67 | ```python
68 | @app.route("/hello-world")
69 | def hello_world():
70 | return 'hello'
71 | ```
72 | 3. Save the file and execute `systemctl restart drak-web`
73 | 4. Navigate to `http://localhost:6300/hello-world`, your new subpage should appear.
74 |
--------------------------------------------------------------------------------
/drakrun/web/frontend/src/AnalysisList.jsx:
--------------------------------------------------------------------------------
1 | import { Link } from "react-router-dom";
2 | import { useEffect, useState } from "react";
3 | import { getAnalysisList } from "./api";
4 | import { CanceledError } from "axios";
5 | import { AnalysisStatusBadge } from "./AnalysisStatusBadge.jsx";
6 |
7 | function AnalysisListRow({ analysis }) {
8 | return (
9 | Analysis report
87 |
16 |
19 | SHA256:
17 | {analysis.file.sha256}
18 |
20 |
23 | Name:
21 | {analysis.file.name}
22 |
24 |
27 | Type:
25 | {analysis.file.type}
26 | Error: {error.toString()}
;
57 | }
58 |
59 | if (typeof analysisList === "undefined") {
60 | return Loading...
;
61 | }
62 |
63 | if (analysisList.length === 0) {
64 | return (
65 | There are no analyses. Upload sample to create a new one.
66 | );
67 | }
68 |
69 | return (
70 |
71 |
72 |
73 |
89 |
90 | );
91 | }
92 |
93 | export default function AnalysisList() {
94 | return (
95 | | Analysis ID | 75 |Sample info | 76 |Started | 77 |Finished | 78 |
|---|
96 |
99 | );
100 | }
101 |
--------------------------------------------------------------------------------
/drakrun/web/frontend/src/PluginPicker.jsx:
--------------------------------------------------------------------------------
1 | import { useCallback, useState } from "react";
2 | import CreatableSelect from "react-select/creatable";
3 |
4 | const createOption = (option) => ({ label: option, value: option });
5 |
6 | const plugins = [
7 | createOption("apimon"),
8 | createOption("bsodmon"),
9 | createOption("clipboardmon"),
10 | createOption("codemon"),
11 | createOption("delaymon"),
12 | createOption("exmon"),
13 | createOption("fileextractor"),
14 | createOption("filetracer"),
15 | createOption("hidevm"),
16 | createOption("hidsim"),
17 | createOption("ipt"),
18 | createOption("memdump"),
19 | createOption("objmon"),
20 | createOption("procmon"),
21 | createOption("regmon"),
22 | createOption("socketmon"),
23 | createOption("syscalls"),
24 | createOption("tlsmon"),
25 | createOption("windowmon"),
26 | ];
27 |
28 | const defaultPlugins = [
29 | createOption("apimon"),
30 | createOption("filetracer"),
31 | createOption("memdump"),
32 | createOption("procmon"),
33 | createOption("socketmon"),
34 | createOption("tlsmon"),
35 | ];
36 |
37 | const pluginPickerStyles = {
38 | multiValue: (styles, { data }) => {
39 | if (!data.__isNew__)
40 | return { ...styles, backgroundColor: "rgba(0, 82, 204, 0.1)" };
41 | else return { ...styles, backgroundColor: "rgba(255, 86, 48, 0.1)" };
42 | },
43 | multiValueLabel: (styles, { data }) => {
44 | if (!data.__isNew__) return { ...styles, color: "rgb(0, 82, 204)" };
45 | else return { ...styles, color: "rgb(255, 86, 48)" };
46 | },
47 | };
48 |
49 | export function PluginList({ plugins }) {
50 | return (
51 | Analyses
97 |
52 | {plugins.map((plugin) => (
53 |
65 | );
66 | }
67 |
68 | export function PluginPicker({ onChange, name }) {
69 | const [warning, setWarning] = useState(undefined);
70 | const onSelectChange = useCallback(
71 | (currentValue) => {
72 | if (currentValue.some((data) => data.__isNew__)) {
73 | setWarning(
74 | "Picked custom plugin which may be not supported by Drakvuf Sandbox",
75 | );
76 | } else if (
77 | currentValue.length > 0 &&
78 | !currentValue.some((data) => data.value === "procmon")
79 | ) {
80 | setWarning(
81 | "It's recommended to include 'procmon' plugin for complete process information",
82 | );
83 | } else {
84 | setWarning(undefined);
85 | }
86 | if (onChange) onChange(currentValue);
87 | },
88 | [onChange],
89 | );
90 | return (
91 |
61 | {plugin}
62 |
63 | ))}
64 |
92 |
102 | );
103 | }
104 |
--------------------------------------------------------------------------------
/docs/ipt.rst:
--------------------------------------------------------------------------------
1 | ===================================================
2 | Using Intel Processor Trace Features (Experimental)
3 | ===================================================
4 |
5 | Enable IPT plugin in drakrun
6 | ----------------------------
7 |
8 | 1. In ``/etc/drakrun/scripts/cfg.template`` add a new entry: ``vmtrace_buf_kb = 8192``
9 | 2. Execute ``systemctl restart drakrun-worker@1`` (repeat for each drakrun instance if you have scaled them up).
10 | 3. Use ``ipt`` and ``codemon`` Drakvuf plugins while submitting your analysis.
11 |
12 |
13 |
14 | Install required extra dependencies
15 | -----------------------------------
16 |
17 | In order to analyze IPT data streams, you need to install ``libipt``, ``xed``, ``ptdump`` (modified), ``ptxed`` and ``drak-ipt-blocks`` tools.
18 |
19 | .. code-block :: console
20 |
21 | rm -rf /tmp/iptbuild
22 | mkdir /tmp/iptbuild
23 | cd /tmp/iptbuild
24 |
25 | git clone https://github.com/icedevml/libipt.git
26 | git clone https://github.com/intelxed/xed.git
27 | git clone https://github.com/intelxed/mbuild.git
28 | git clone https://github.com/gabime/spdlog.git
29 | git clone https://github.com/p-ranav/argparse.git -b v2.9
30 | git clone https://github.com/CERT-Polska/drakvuf-sandbox.git
31 |
32 | cd xed
33 | ./mfile.py --share
34 | ./mfile.py --prefix=/usr/local install
35 | ldconfig
36 |
37 | cd ../libipt
38 | git checkout
39 | cmake -D PTDUMP=On -D PTXED=On .
40 | make install
41 |
42 | cd ../spdlog
43 | cmake .
44 | make -j$(nproc) install
45 |
46 | cd ../argparse
47 | cmake .
48 | make -j$(nproc) install
49 |
50 | cd ../drakvuf-sandbox/drakrun/drakrun/tools/ipt
51 | cmake .
52 | make install
53 |
54 |
55 | Generate trace disassembly
56 | --------------------------
57 |
58 | 1. Perform an analysis with IPT plugin enabled
59 | 2. Download the completed analysis from MinIO to your local hard drive
60 | 3. Find CR3 of the target process you want to disassemble (hint: `syscall.log` will contain CR3 values)
61 | 4. Execute ``drak-ipt-disasm --analysis . --cr3 {warning}
: []}
101 | -
66 | {processTree.map((element) => {
67 | const leaf = element.children.length === 0;
68 | const collapsed = !uncollapsedSeqid.has(element.seqid);
69 | const isSelected = element.seqid === selected;
70 | return (
71 | <>
72 |
-
73 | {!leaf ? (
74 |
{ 81 | ev.preventDefault(); 82 | setCollapse(element.seqid); 83 | }} 84 | /> 85 | ) : ( 86 | 91 | )} 92 | onSelect(element.seqid)} 95 | /> 96 |
97 | {!leaf && !collapsed ? (
98 |
79 |
118 | );
119 | }
120 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # DRAKVUF Sandbox
2 |
3 | > [!WARNING]
4 | > Here be dragons 🐉. Maintaining your own sandbox is a difficult task and this project uses technology that is not user-friendly.
5 | > Be prepared to brush up on your debugging skills as bugs may be reproducible only on your configuration.
6 | > On the other hand, it's not purely an R&D project and it is used in production! Source code and issues section on both
7 | > DRAKVUF Sandbox and [DRAKVUF engine](https://github.com/tklengyel/drakvuf) projects are your best friend.
8 |
9 | DRAKVUF Sandbox is an automated black-box malware analysis system with [DRAKVUF](https://drakvuf.com/) engine under the hood, which does not require an agent on guest OS.
10 |
11 | This project provides you with a friendly web interface that allows you to upload suspicious files to be analyzed. Once the sandboxing job is finished, you can explore the analysis result through the mentioned interface and get an insight on whether the file is truly malicious or not.
12 |
13 | Because it is usually pretty hard to set up a malware sandbox, this project also provides you with an installer app that would guide you through the necessary steps and configure your system using settings that are recommended for beginners. At the same time, experienced users can tweak some settings or even replace some infrastructure parts to better suit their needs.
14 |
15 | ## Quick start
16 | * **[👋 Getting started](https://drakvuf-sandbox.readthedocs.io/en/latest/usage/getting_started.html)**
17 | * [Latest releases](https://github.com/CERT-Polska/drakvuf-sandbox/releases)
18 | * [Latest docs](https://drakvuf-sandbox.readthedocs.io/en/latest/)
19 |
20 | 
21 |
22 | ## Recommended hardware & software
23 |
24 | In order to run DRAKVUF Sandbox, your setup should fulfill all the listed requirements.
25 |
26 | * Processor:
27 | * ✔️ Required Intel processor with Intel Virtualization Technology (VT-x) and Extended Page Tables (EPT) features
28 | * Host system with at least 2 core CPU and 5 GB RAM, running GRUB as bootloader, one of:
29 | * ✔️ Debian 12 Bookworm
30 | * ✔️ Ubuntu 22.04 Jammy
31 | * Guest system, one of:
32 | * ✔️ Windows 10 build at least 2004 (x64), recommended 22H2
33 | * ✔️ Windows 7 (x64)
34 |
35 | Nested virtualization:
36 |
37 | * ✔️ Xen - works out of the box.
38 | * ✔️ KVM - works, we often use it for development purposes. If you experience any bugs, please report them to us for further investigation.
39 | * ✔️ VMware Workstation Player - works, but you need to check Virtualize EPT option for a VM; Intel processor with EPT still required.
40 | * ❌ AWS, GCP, Azure - due to lack of exposed CPU features, hosting DRAKVUF Sandbox in the cloud is **not** supported (although it might change in the future).
41 | * ❌ Hyper-V - doesn't work.
42 | * ❌ VMWare Fusion (Mac) - doesn't work.
43 |
44 | ## Maintainers/authors
45 |
46 | Feel free to contact us if you have any questions or comments.
47 |
48 | **General contact email: info@cert.pl** (fastest response)
49 |
50 | You can also chat with us about this project on Discord: [https://discord.gg/Q7eTsHnpn4](https://discord.gg/Q7eTsHnpn4)
51 |
52 | This project is authored by:
53 |
54 | * Michał Leszczyński ([@icedevml](https://github.com/icedevml))
55 | * Adam Kliś ([@BonusPlay](https://github.com/BonusPlay))
56 | * Hubert Jasudowicz ([@chivay](https://github.com/chivay))
57 | * Paweł Srokosz ([@psrok1](https://github.com/psrok1))
58 | * Konstanty Cieśliński ([@kscieslinski](https://github.com/kscieslinski))
59 | * Arkadiusz Wróbel ([@catsuryuu](https://github.com/catsuryuu))
60 | * Jarosław Jedynak ([@msm-cert](https://github.com/msm-cert))
61 |
62 | If you have any questions about [DRAKVUF](https://drakvuf.com/) engine itself, contact tamas@tklengyel.com
63 |
64 | ## Acknowledgements
65 |
66 | This project was created and/or upgraded thanks to the following organizations and initiatives:
67 |
68 | ### Connecting Europe Facility of the European Union
69 |
70 |
80 | {typeof processTree === "undefined" ? (
81 | Loading process tree...
82 | ) : (
83 | []
84 | )}
85 | {typeof error !== "undefined" ? (
86 |
87 | Unable to load process tree
88 |
89 | ) : (
90 | []
91 | )}
92 | {typeof processTree !== "undefined" ? (
93 | {
97 | const collapse = uncollapsed.has(seqid);
98 | setUncollapsed((currentValue) => {
99 | let newSet = new Set(currentValue);
100 | if (!collapse) {
101 | newSet.add(seqid);
102 | } else {
103 | newSet.delete(seqid);
104 | }
105 | return newSet;
106 | });
107 | }}
108 | selected={selectedProcess}
109 | onSelect={(seqid) => {
110 | onProcessSelect(seqid);
111 | }}
112 | />
113 | ) : (
114 | []
115 | )}
116 |
117 | 
71 |
72 | ### The Honeynet Project
73 |
74 | 
75 |
76 | ### CERT Polska
77 |
78 | 
79 |
--------------------------------------------------------------------------------
/drakrun/web/frontend/src/AnalysisPendingView.jsx:
--------------------------------------------------------------------------------
1 | import { AnalysisLiveInteraction } from "./AnalysisLiveInteraction.jsx";
2 | import { AnalysisStatusBadge } from "./AnalysisStatusBadge.jsx";
3 | import { AnalysisMetadataTable } from "./AnalysisMetadataTable.jsx";
4 | import { useState } from "react";
5 | import { Tab, TabSwitcher } from "./TabSwitcher.jsx";
6 |
7 | export function AnalysisPendingStatusBox({ children }) {
8 | return (
9 |
10 |
24 | );
25 | }
26 |
27 | function AnalysisPendingTabs({ analysis }) {
28 | const [activeTab, setActiveTab] = useState("metadata");
29 | const enableLiveInteraction =
30 | analysis["vm_id"] &&
31 | analysis["status"] === "started" &&
32 | analysis["substatus"] !== "starting_vm";
33 | return (
34 |
11 |
23 | {children}
12 |
13 |
21 |
22 |
70 | Remaining time: {formatTime(remainingTime)}
71 |
72 | );
73 | }
74 |
75 | export function AnalysisPendingView({ analysis }) {
76 | return (
77 | <>
78 |
79 |
103 |
80 |
81 |
101 |
102 | Please wait until analysis is completed...
82 |
83 |
100 |
84 | Current status:
85 |
86 |
104 |
112 |
113 | );
114 | }
115 |
--------------------------------------------------------------------------------
/drakrun/lib/vmi_profile.py:
--------------------------------------------------------------------------------
1 | import json
2 | import logging
3 | import pathlib
4 | import tempfile
5 | import time
6 |
7 | from drakpdb import make_pdb_profile, pe_codeview_data
8 |
9 | from drakrun.lib.drakshell import get_drakshell
10 | from drakrun.lib.fetch_pdb import vmi_fetch_pdb
11 | from drakrun.lib.injector import Injector
12 | from drakrun.lib.libvmi.dlls import DLL, optional_dll_file_list, required_dll_file_list
13 | from drakrun.lib.libvmi.vmi_info import VmiInfo
14 | from drakrun.lib.paths import VMI_INFO_PATH, VMI_KERNEL_PROFILE_PATH, VMI_PROFILES_DIR
15 | from drakrun.lib.vm import VirtualMachine
16 |
17 | from .libvmi import extract_explorer_pid, extract_vmi_offsets, get_vmi_kernel_guid
18 |
19 | log = logging.getLogger(__name__)
20 |
21 |
22 | def extract_dll_profile(injector: Injector, dll: DLL):
23 | tempdir = pathlib.Path(tempfile.gettempdir())
24 | local_dll_path = (tempdir / dll.dest).as_posix()
25 | guest_dll_path = str(pathlib.PureWindowsPath("C:/", dll.path))
26 |
27 | log.info("Generating VMI profile for %s", local_dll_path)
28 |
29 | proc = injector.read_file(guest_dll_path, local_dll_path)
30 | out = json.loads(proc.stdout.decode())
31 | if out["Status"] == "Error" and out["Error"] in [
32 | "ERROR_FILE_NOT_FOUND",
33 | "ERROR_PATH_NOT_FOUND",
34 | ]:
35 | raise FileNotFoundError
36 | if out["Status"] != "Success":
37 | raise RuntimeError(f"Injector failed with {proc.stderr}")
38 |
39 | codeview_data = pe_codeview_data(local_dll_path)
40 | pdb_filepath = vmi_fetch_pdb(
41 | codeview_data["filename"], codeview_data["symstore_hash"]
42 | )
43 | profile = make_pdb_profile(
44 | pdb_filepath,
45 | dll_origin_path=guest_dll_path,
46 | dll_path=local_dll_path,
47 | dll_symstore_hash=codeview_data["symstore_hash"],
48 | )
49 | profile_path = VMI_PROFILES_DIR / f"{dll.dest}.json"
50 | profile_path.write_text(json.dumps(profile, indent=4))
51 |
52 |
53 | def create_vmi_info(vm: VirtualMachine, with_drakshell: bool = True) -> VmiInfo:
54 | if not vm.is_running:
55 | raise RuntimeError("VM is not running")
56 | kernel_info = get_vmi_kernel_guid(vm.vm_name)
57 | log.info(f"Determined PDB GUID: {kernel_info.guid}")
58 | log.info(f"Determined kernel filename: {kernel_info.filename}")
59 |
60 | pdb_file = vmi_fetch_pdb(kernel_info.filename, kernel_info.guid)
61 | kernel_profile = make_pdb_profile(pdb_file.as_posix())
62 | VMI_KERNEL_PROFILE_PATH.write_text(json.dumps(kernel_profile, indent=4))
63 |
64 | vmi_offsets = extract_vmi_offsets(vm.vm_name, VMI_KERNEL_PROFILE_PATH)
65 | explorer_pid = extract_explorer_pid(
66 | vm.vm_name, VMI_KERNEL_PROFILE_PATH, vmi_offsets
67 | )
68 | vmi_info = VmiInfo(vmi_offsets, inject_pid=explorer_pid)
69 | if with_drakshell:
70 | injector = Injector(vm.vm_name, vmi_info, VMI_KERNEL_PROFILE_PATH.as_posix())
71 | for try_no in range(5):
72 | try:
73 | _, drakshell_info = get_drakshell(vm, injector)
74 | vmi_info.inject_pid = drakshell_info["pid"]
75 | vmi_info.inject_tid = drakshell_info["tid"]
76 | break
77 | except Exception as e:
78 | log.warning("Failed to install drakshell on the VM", exc_info=e)
79 | if try_no < 4:
80 | log.warning(
81 | f"Another try ({try_no+2}/5) in 5 seconds... You can try connecting to the VM using VNC and moving "
82 | f"mouse over the desktop while we're trying to setup the drakshell."
83 | )
84 | time.sleep(5)
85 | else:
86 | log.warning(
87 | "I surrender, drakshell will be inactive. I hope you won't have problems with profile generation."
88 | )
89 |
90 | VMI_INFO_PATH.write_text(vmi_info.to_json(indent=4))
91 | return vmi_info
92 |
93 |
94 | def create_vmi_json_profile(vm: VirtualMachine, vmi_info: VmiInfo):
95 | if not vm.is_running:
96 | raise RuntimeError("VM is not running")
97 |
98 | injector = Injector(vm.vm_name, vmi_info, VMI_KERNEL_PROFILE_PATH.as_posix())
99 | for dll in required_dll_file_list:
100 | extract_dll_profile(injector, dll)
101 |
102 | for dll in optional_dll_file_list:
103 | try:
104 | extract_dll_profile(injector, dll)
105 | except Exception:
106 | logging.exception(f"Failed to get profile for {dll.path}")
107 |
--------------------------------------------------------------------------------
/drakrun/web/frontend/src/api.js:
--------------------------------------------------------------------------------
1 | import axios from "axios";
2 |
3 | if (import.meta.env.VITE_API_SERVER) {
4 | axios.defaults.baseURL = import.meta.env.VITE_API_SERVER;
5 | } else {
6 | axios.defaults.baseURL = "/api";
7 | }
8 |
9 | export async function getAnalysisList({ abortController }) {
10 | const listRequest = await axios.get("/list", {
11 | signal: abortController.signal,
12 | });
13 | return listRequest.data;
14 | }
15 |
16 | export async function getAnalysisStatus({
17 | analysisId,
18 | abortController = undefined,
19 | }) {
20 | const listRequest = await axios.get(
21 | `/status/${analysisId}`,
22 | abortController
23 | ? {
24 | signal: abortController.signal,
25 | }
26 | : {},
27 | );
28 | return listRequest.data;
29 | }
30 |
31 | export async function getAnalysisSummary({
32 | analysisId,
33 | abortController = undefined,
34 | }) {
35 | const reportRequest = await axios.get(
36 | `/report/${analysisId}`,
37 | abortController
38 | ? {
39 | signal: abortController.signal,
40 | }
41 | : {},
42 | );
43 | return reportRequest.data;
44 | }
45 |
46 | export async function getAnalysisProcessTree({
47 | analysisId,
48 | abortController = undefined,
49 | }) {
50 | const listRequest = await axios.get(
51 | `/processed/${analysisId}/process_tree`,
52 | abortController
53 | ? {
54 | signal: abortController.signal,
55 | }
56 | : {},
57 | );
58 | return listRequest.data;
59 | }
60 |
61 | export async function getLog({ analysisId, logType, rangeStart, rangeEnd }) {
62 | const logRequest = await axios.get(`/logs/${analysisId}/${logType}`, {
63 | responseType: "text",
64 | headers: {
65 | Range: `bytes=${rangeStart}-${rangeEnd}`,
66 | },
67 | });
68 | return logRequest.data;
69 | }
70 |
71 | export async function getLogList({ analysisId }) {
72 | const logRequest = await axios.get(`/logs/${analysisId}`);
73 | return logRequest.data;
74 | }
75 |
76 | export async function getProcessInfo({ analysisId, processSeqId }) {
77 | const logRequest = await axios.get(
78 | `/process_info/${analysisId}/${processSeqId}`,
79 | );
80 | return logRequest.data;
81 | }
82 |
83 | export async function getProcessLog({
84 | analysisId,
85 | logType,
86 | selectedProcess,
87 | rangeStart,
88 | rangeEnd,
89 | methodsFilter = [],
90 | }) {
91 | const logRequest = await axios.get(
92 | `/logs/${analysisId}/${logType}/process/${selectedProcess}`,
93 | {
94 | responseType: "text",
95 | headers: {
96 | Range: `bytes=${rangeStart}-${rangeEnd}`,
97 | },
98 | params: {
99 | filter: methodsFilter,
100 | },
101 | },
102 | );
103 | return logRequest.data;
104 | }
105 |
106 | export async function getAnalysisFileList({
107 | analysisId,
108 | abortController = undefined,
109 | }) {
110 | const listRequest = await axios.get(
111 | `/files/${analysisId}`,
112 | abortController
113 | ? {
114 | signal: abortController.signal,
115 | }
116 | : {},
117 | );
118 | return listRequest.data;
119 | }
120 |
121 | export async function uploadSample({
122 | file,
123 | timeout,
124 | file_name,
125 | file_path,
126 | plugins,
127 | start_command,
128 | no_internet,
129 | no_screenshots,
130 | extract_archive,
131 | archive_password,
132 | }) {
133 | const formData = new FormData();
134 | formData.append("file", file);
135 | formData.append("timeout", timeout);
136 | formData.append("plugins", JSON.stringify(plugins));
137 | if (file_name) formData.append("file_name", file_name);
138 | if (file_path) formData.append("file_path", file_path);
139 | if (start_command) formData.append("start_command", start_command);
140 | if (no_internet) formData.append("no_internet", "1");
141 | if (no_screenshots) formData.append("no_screenshots", "1");
142 | if (extract_archive) formData.append("extract_archive", "1");
143 | if (archive_password) formData.append("archive_password", archive_password);
144 | const request = await axios.post("/upload", formData, {
145 | headers: {
146 | "Content-Type": "multipart/form-data",
147 | },
148 | });
149 | return request.data;
150 | }
151 |
--------------------------------------------------------------------------------
/drakrun/analyzer/screenshotter.py:
--------------------------------------------------------------------------------
1 | import asyncio
2 | import json
3 | import logging
4 | import threading
5 | import time
6 | from pathlib import Path
7 |
8 | import asyncvnc
9 | from perception import hashers
10 | from PIL import Image
11 |
12 | logger = logging.getLogger(__name__)
13 |
14 |
15 | class Screenshotter:
16 | def __init__(
17 | self,
18 | output_dir: Path,
19 | vnc_host: str,
20 | vnc_port: int,
21 | vnc_password: str,
22 | loop_interval=5,
23 | max_screenshots=30,
24 | diff_threshold=0.05,
25 | ):
26 | self._aioloop = None
27 | self._thread = None
28 | self._task = None
29 |
30 | self.output_dir = output_dir
31 | self.vnc_host = vnc_host
32 | self.vnc_port = vnc_port
33 | self.vnc_password = vnc_password
34 | self.loop_interval = loop_interval
35 | self.max_screenshots = max_screenshots
36 | self.diff_threshold = diff_threshold
37 |
38 | async def perform(self):
39 | hasher = hashers.PHash()
40 | prev_image_hash = None
41 | screenshot_no = 0
42 | screenshot_log_path = self.output_dir / "screenshots.json"
43 | screenshot_dir = self.output_dir / "screenshots"
44 | screenshot_dir.mkdir()
45 | try:
46 | with screenshot_log_path.open("w") as screenshot_log:
47 | async with asyncvnc.connect(
48 | host=self.vnc_host, port=self.vnc_port, password=self.vnc_password
49 | ) as client:
50 | logger.info(f"Connected to VNC {self.vnc_host}:{self.vnc_port}")
51 | while screenshot_no < self.max_screenshots:
52 | pixels = await asyncio.wait_for(client.screenshot(), timeout=30)
53 | timestamp = time.time()
54 | image = Image.fromarray(pixels)
55 | image_hash = hasher.compute(image)
56 | if (
57 | not prev_image_hash
58 | or hasher.compute_distance(image_hash, prev_image_hash)
59 | > self.diff_threshold
60 | ):
61 | prev_image_hash = image_hash
62 | screenshot_no += 1
63 | screenshot_name = (
64 | screenshot_dir / f"screenshot_{screenshot_no}.png"
65 | )
66 | image.save(screenshot_name)
67 | screenshot_log.write(
68 | json.dumps(
69 | {
70 | "timestamp": timestamp,
71 | "image_hash": image_hash,
72 | "index": screenshot_no,
73 | }
74 | )
75 | + "\n"
76 | )
77 | logger.info(f"Got screenshot {screenshot_no}: {image_hash}")
78 | await asyncio.sleep(self.loop_interval)
79 | except asyncio.CancelledError:
80 | logger.info("Screenshot task was cancelled.")
81 | # This exception is raised when stop() cancels the task.
82 | except Exception as e:
83 | logger.exception(f"Error in screenshotter task: {e}")
84 | finally:
85 | logger.info("Screenshot task finished.")
86 |
87 | def perform_loop(self):
88 | asyncio.set_event_loop(self._aioloop)
89 | try:
90 | self._task = self._aioloop.create_task(self.perform())
91 | self._aioloop.run_until_complete(self._task)
92 | finally:
93 | if not self._aioloop.is_closed():
94 | self._aioloop.close()
95 | logger.info("Screenshotter event loop closed.")
96 |
97 | def start(self):
98 | self._aioloop = asyncio.new_event_loop()
99 | self._thread = threading.Thread(target=self.perform_loop)
100 | self._thread.start()
101 |
102 | def stop(self):
103 | if not self._thread:
104 | return
105 |
106 | if self._aioloop and not self._aioloop.is_closed() and self._task:
107 | logger.info("Stopping screenshotter...")
108 | self._aioloop.call_soon_threadsafe(self._task.cancel)
109 |
110 | self._thread.join(timeout=15)
111 |
112 | if self._thread.is_alive():
113 | logger.error("Screenshotter thread did not stop in time!")
114 |
115 | logger.info("Screenshotter stopped.")
116 |
--------------------------------------------------------------------------------
/drakrun/lib/s3_storage.py:
--------------------------------------------------------------------------------
1 | import logging
2 | import pathlib
3 | from typing import BinaryIO, Optional
4 |
5 | import boto3
6 | from botocore.client import BaseClient
7 | from botocore.credentials import (
8 | ContainerProvider,
9 | InstanceMetadataFetcher,
10 | InstanceMetadataProvider,
11 | )
12 | from botocore.exceptions import ClientError
13 | from botocore.session import get_session
14 |
15 | from .config import S3StorageConfigSection
16 |
17 | logger = logging.getLogger(__name__)
18 |
19 |
20 | def is_s3_enabled(s3_config: Optional[S3StorageConfigSection]) -> bool:
21 | return bool(s3_config is not None and s3_config.enabled)
22 |
23 |
24 | def get_s3_client(s3_config: S3StorageConfigSection) -> BaseClient:
25 | if s3_config.iam_auth:
26 | boto_session = get_session()
27 | iam_providers = [
28 | ContainerProvider(),
29 | InstanceMetadataProvider(
30 | iam_role_fetcher=InstanceMetadataFetcher(timeout=1000, num_attempts=2)
31 | ),
32 | ]
33 | for provider in iam_providers:
34 | creds = provider.load()
35 | if creds:
36 | boto_session._credentials = creds # type: ignore
37 | return boto3.Session(botocore_session=boto_session).client(
38 | "s3",
39 | endpoint_url=s3_config.address,
40 | )
41 | else:
42 | raise RuntimeError("Unable to fetch IAM credentials")
43 | else:
44 | return boto3.client(
45 | "s3",
46 | endpoint_url=s3_config.address,
47 | aws_access_key_id=s3_config.access_key,
48 | aws_secret_access_key=s3_config.secret_key,
49 | )
50 |
51 |
52 | def upload_sample_to_s3(
53 | analysis_id: str, sample_stream: BinaryIO, s3_client: BaseClient, s3_bucket: str
54 | ) -> None:
55 | sample_s3_name = "/".join([*analysis_id[0:4], analysis_id + ".sample"])
56 | logger.info("Uploading sample for analysis %s...", analysis_id)
57 | s3_client.put_object(Bucket=s3_bucket, Key=sample_s3_name, Body=sample_stream)
58 | logger.info("Sample for %s uploaded successfully", analysis_id)
59 |
60 |
61 | def download_sample_from_s3(
62 | analysis_id: str, target_path: pathlib.Path, s3_client: BaseClient, s3_bucket: str
63 | ) -> None:
64 | sample_s3_name = "/".join([*analysis_id[0:4], analysis_id + ".sample"])
65 | logger.info("Downloading sample for analysis %s...", analysis_id)
66 | s3_client.download_file(Bucket=s3_bucket, Key=sample_s3_name, Filename=target_path)
67 | logger.info("Sample for %s downloaded successfully", analysis_id)
68 |
69 |
70 | def upload_analysis(
71 | analysis_id: str, analysis_path: pathlib.Path, s3_client: BaseClient, s3_bucket: str
72 | ) -> None:
73 | s3_name_prefix = "/".join([*analysis_id[0:4], analysis_id])
74 |
75 | logger.info("Uploading analysis %s...", analysis_id)
76 | for analysis_file in analysis_path.rglob("*"):
77 | if not analysis_file.is_file():
78 | continue
79 | relative_path = analysis_file.relative_to(analysis_path).as_posix()
80 | s3_name = s3_name_prefix + "/" + relative_path
81 | logger.info("Uploading %s/%s...", analysis_id, relative_path)
82 | with analysis_file.open("rb") as f:
83 | s3_client.put_object(Bucket=s3_bucket, Key=s3_name, Body=f)
84 | logger.info("Analysis %s uploaded successfully", analysis_id)
85 |
86 |
87 | def download_analysis(
88 | analysis_id: str, target_path: pathlib.Path, s3_client: BaseClient, s3_bucket: str
89 | ) -> None:
90 | s3_name_prefix = "/".join([*analysis_id[0:4], analysis_id])
91 | logger.info("Downloading analysis %s...", analysis_id)
92 | objects = s3_client.list_objects_v2(Bucket=s3_bucket, Prefix=s3_name_prefix + "/")
93 | for object in objects:
94 | object_key = object["Key"]
95 | relative_path = object_key[len(s3_name_prefix + "/") :]
96 | logger.info("Downloading %s/%s...", analysis_id, relative_path)
97 | target_file_path = target_path / relative_path
98 | s3_client.download_file(
99 | Bucket=s3_bucket, Key=object_key, Filename=target_file_path
100 | )
101 | logger.info("Analysis %s downloaded successfully", analysis_id)
102 |
103 |
104 | def is_analysis_on_s3(analysis_id: str, s3_client: BaseClient, s3_bucket: str) -> bool:
105 | s3_name = "/".join([*analysis_id[:4], analysis_id, "metadata.json"])
106 |
107 | try:
108 | s3_client.head_object(Bucket=s3_bucket, Key=s3_name)
109 | return True
110 | except ClientError as e:
111 | if e.response["Error"]["Code"] == "NoSuchKey":
112 | return False
113 | else:
114 | raise
115 |
--------------------------------------------------------------------------------
105 |
111 |
106 |
110 |
107 |
109 |