mirror of
https://github.com/CERT-Polska/drakvuf-sandbox.git
synced 2026-10-12 02:01:43 +00:00
Add basic Sphinx docs setup (#255)
This commit is contained in:
Hubert Jasudowicz
+19
@@ -147,3 +147,22 @@ trigger:
|
||||
event:
|
||||
exclude:
|
||||
- pull_request
|
||||
|
||||
---
|
||||
kind: pipeline
|
||||
type: docker
|
||||
name: build-docs
|
||||
|
||||
steps:
|
||||
- name: build-docs
|
||||
image: python:3.8-buster
|
||||
commands:
|
||||
- cd docs
|
||||
- pip install -r requirements.txt
|
||||
- make html
|
||||
node:
|
||||
purpose: generic
|
||||
trigger:
|
||||
event:
|
||||
exclude:
|
||||
- pull_request
|
||||
|
||||
@@ -0,0 +1,24 @@
|
||||
# .readthedocs.yml
|
||||
# Read the Docs configuration file
|
||||
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
|
||||
|
||||
# Required
|
||||
version: 2
|
||||
|
||||
# Build documentation in the docs/ directory with Sphinx
|
||||
sphinx:
|
||||
configuration: docs/conf.py
|
||||
|
||||
# Build documentation with MkDocs
|
||||
#mkdocs:
|
||||
# configuration: mkdocs.yml
|
||||
|
||||
# Optionally build your docs in additional formats such as PDF
|
||||
formats:
|
||||
- pdf
|
||||
|
||||
# Optionally set the version of Python and requirements required to build your docs
|
||||
python:
|
||||
version: 3.7
|
||||
install:
|
||||
- requirements: docs/requirements.txt
|
||||
@@ -1,5 +1,5 @@
|
||||
# DRAKVUF Sandbox
|
||||
[](https://kvm-vmi.slack.com) [](https://drone.icedev.pl/CERT-Polska/drakvuf-sandbox)
|
||||
[](https://kvm-vmi.slack.com) [](https://drone.icedev.pl/CERT-Polska/drakvuf-sandbox) [](https://drakvuf-sandbox.readthedocs.io/en/latest/?badge=latest)
|
||||
|
||||
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.
|
||||
|
||||
@@ -9,157 +9,27 @@ Because it is usually pretty hard to set up a malware sandbox, this project also
|
||||
|
||||
|
||||
|
||||
## Getting started
|
||||
|
||||
### Supported hardware&software
|
||||
## Supported hardware & software
|
||||
|
||||
In order to run DRAKVUF Sandbox, your setup must fullfill all of the listed requirements:
|
||||
|
||||
* Processor: Intel processor with VT-x and EPT features
|
||||
* Host system: Debian 10 Buster/Ubuntu 18.04 Bionic/Ubuntu 20.04 Focal with at least 2 core CPU and 5 GB RAM
|
||||
* Processor: Intel processor with VT-x and EPT features.
|
||||
* Host system: Debian 10 Buster/Ubuntu 18.04 Bionic/Ubuntu 20.04 Focal with at least 2 core CPU and 5 GB RAM, running GRUB as bootloader.
|
||||
* Guest system: Windows 7 (x64), Windows 10 (x64; experimental support)
|
||||
|
||||
Nested virtualization:
|
||||
|
||||
* KVM **does** work, however it is considered experimental. If you experience any bugs, please report them to us for further investigation.
|
||||
* Due to lack of exposed CPU features, hosting drakvuf-sandbox in cloud is **not** supported (although it might change in the future)
|
||||
* Hyper-V does **not** work
|
||||
* Xen **does** work out of the box
|
||||
* VMware Workstation Player **does** work, but you need to check Virtualize EPT option for a VM; Intel processor with EPT still required
|
||||
|
||||
### Basic installation
|
||||
|
||||
This instruction assumes that you want to create a single-node installation with the default components, which is recommended for beginners.
|
||||
|
||||
1. Download [latest release packages](https://github.com/CERT-Polska/drakvuf-sandbox/releases).
|
||||
2. Install DRAKVUF:
|
||||
```
|
||||
# apt update
|
||||
# apt install ./drakvuf-bundle*.deb
|
||||
# reboot
|
||||
```
|
||||
3. Install DRAKVUF Sandbox stack:
|
||||
```
|
||||
# apt install redis-server
|
||||
# apt install ./drakcore*.deb
|
||||
# apt install ./drakrun*.deb
|
||||
```
|
||||
4. Execute:
|
||||
```
|
||||
# draksetup install /opt/path_to_windows.iso
|
||||
```
|
||||
carefully read the command's output. This command would run a Virtual Machine with Windows system installation process.
|
||||
|
||||
**Unattended installation:** If you have `autounattend.xml` matching your Windows ISO, you can request unattended installation by adding `--unattended-xml /path/to/autounattend.xml`. Unattended install configuration could be generated with [Windows Answer File Generator](https://www.windowsafg.com/win10x86_x64.html).
|
||||
|
||||
**Storage backend:** By default, DRAKVUF Sandbox is storing virtual machine's HDD in a `qcow2` file. If you want to use ZFS instead, please check the "Optional features" section below.
|
||||
5. Use VNC to connect to the installation process:
|
||||
```
|
||||
$ vncviewer localhost:5900
|
||||
```
|
||||
6. Perform Windows installation until you are booted to the desktop.
|
||||
7. **Extra software:** At this point you might optionally install additional software. You can execute:
|
||||
```
|
||||
draksetup mount /path/to/some-cd.iso
|
||||
```
|
||||
which would mount a virtual CD disk containing additional software into your VM.
|
||||
8. In order to finalize the VM setup process, execute:
|
||||
```
|
||||
# draksetup postinstall
|
||||
```
|
||||
**Note:** Add `--no-report` if you don't want `draksetup` to send [basic usage report](https://github.com/CERT-Polska/drakvuf-sandbox/blob/master/USAGE_STATISTICS.md).
|
||||
9. Test your installation by navigating to the web interface ( http://localhost:6300/ ) and uploading some samples. The default analysis time is 10 minutes.
|
||||
|
||||
## Optional features
|
||||
|
||||
This sections contains various information about optional features that may be enabled when setting up DRAKVUF Sandbox.
|
||||
|
||||
### ZFS Storage backend
|
||||
If you want to install DRAKVUF Sandbox with a ZFS storage backend, you should perform the following extra steps before executing `draksetup install` command:
|
||||
|
||||
1. Install ZFS on your machine (guide for: [Debian Buster](https://github.com/openzfs/zfs/wiki/Debian), [Ubuntu 18.04](https://ubuntu.com/tutorials/setup-zfs-storage-pool#2-installing-zfs))
|
||||
2. Create a ZFS pool on a free partition:
|
||||
```
|
||||
# zpool create tank <partition_name>
|
||||
```
|
||||
where `<partiton_name>` is e.g. `/dev/sda3`. Be aware that all data stored on the selected partition may be erased.
|
||||
3. Create a dataset for DRAKVUF Sandbox:
|
||||
```
|
||||
# zfs create tank/vms
|
||||
```
|
||||
4. Execute `draksetup install` as in "Basic installation" section, but remembering to provide additional command line switches:
|
||||
```
|
||||
--storage-backend zfs --zfs-tank-name tank/vms
|
||||
```
|
||||
|
||||
### ProcDOT integration
|
||||
DRAKVUF Sandbox may optionally draw a behavioral graph using [ProcDOT](https://www.procdot.com/), if `drakcore` will find it's binary installed at `/opt/procdot/procmon2dot`.
|
||||
|
||||
1. [Download ProcDOT](https://www.procdot.com/downloadprocdotbinaries.htm) (Linux version).
|
||||
2. With your downloaded `procdot*_linux.zip` archive, execute the following commands:
|
||||
```
|
||||
# unzip -o procdot*_linux.zip lin64/* -d /tmp/procdot
|
||||
# mv /tmp/procdot/lin64 /opt/procdot
|
||||
# chmod +x /opt/procdot/procmon2dot
|
||||
```
|
||||
3. Your new analysis reports will also contain behavioral graphs.
|
||||
|
||||
### Networking (optional)
|
||||
|
||||
**Note:** Even though that the guest Internet connectivity is an optional feature, `drakrun` would always make some changes to your host system's network configuration:
|
||||
|
||||
Always:
|
||||
|
||||
* Each instance of `drakrun@<vm_id>` will create a bridge `drak<vm_id>`, assign `10.13.<vm_id>.1/24` IP address/subnet to it and bring the interface up.
|
||||
* `drakrun` will drop any INPUT traffic originating from `drak<vm_id>` bridge, except DHCP traffic (UDP ports: 67, 68).
|
||||
|
||||
Only with `net_enable=1`:
|
||||
|
||||
* `drakrun` will enable IPv4 forwarding.
|
||||
* `drakrun` will configure MASQUERADE through `out_interface` for packets originating from `10.13.<vm_id>.0/24`.
|
||||
* `drakrun` will DROP traffic between `drak<X>` and `drak<Y>` bridges for `X != Y`.
|
||||
|
||||
In order to find out the exact details of the network configuration, search for `_add_iptable_rule` function usages in `drakrun/drakrun/main.py` file.
|
||||
|
||||
#### Basic networking
|
||||
If you want your guest VMs to access Internet, you can enable networking by editing `[drakrun]`
|
||||
section in `/etc/drakrun/config.ini`:
|
||||
|
||||
* Set `net_enable=1` in order to enable guest Internet access.
|
||||
* Check if `out_interface` was detected properly (e.g. `ens33`) and if not, correct this setting.
|
||||
|
||||
After making changes to `/etc/drakrun`, you need to restart all `drakrun` services that are running
|
||||
in your system:
|
||||
|
||||
```
|
||||
# systemctl restart 'drakrun@*'
|
||||
```
|
||||
|
||||
Be aware that if your sandbox instance is already running some analyses, the above command will gracefully
|
||||
wait up to a few minutes until these are completed.
|
||||
|
||||
#### Using dnschef
|
||||
You may optionally configure your guests to use
|
||||
|
||||
1. Setup [dnschef](https://github.com/iphelix/dnschef) tool.
|
||||
2. Start `dnschef` in such way to make it listen on all `drak*` interfaces that belong to DRAKVUF Sandbox.
|
||||
3. Set `dns_server=use-gateway-address` in `/etc/drakrun/config.ini`.
|
||||
4. Restart your drakrun instances: `systemctl restart 'drakrun@*`
|
||||
* Due to lack of exposed CPU features, hosting DRAKVUF Sandbox in the cloud is **not** supported (although it might change in the future).
|
||||
* Hyper-V does **not** work.
|
||||
* Xen **does** work out of the box.
|
||||
* VMware Workstation Player **does** work, but you need to check Virtualize EPT option for a VM; Intel processor with EPT still required.
|
||||
|
||||
|
||||
#### Office files
|
||||
There is an experimental support for analyzing word and excel samples. However this requires that you have Microsoft Office installed.
|
||||
## Installation
|
||||
[Here](https://github.com/CERT-Polska/drakvuf-sandbox/releases) you can find the latest releases.
|
||||
|
||||
The steps below should be completed on guest vm before creating the snapshot (e.g. before you run `draksetup postinstall`).
|
||||
1. Install Microsoft Office. You can use `draksetup mount /path/to/office.iso` command to insert Office installation media during VM setup. After installation, you should be able to start word/excel by running `start winword.exe`, `start excel.exe` from command line.
|
||||
2. Adjust the registry keys by adding 3 values (`DWORD VBAWarnings VALUE=1`, `DWORD AccessVBOM VALUE=1`, `DWORD ExtensionHardening VALUE=0`) both to `Computer\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\<version>\Word\Security` and to `Computer\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\<version>\Excel\Security` keys.
|
||||
|
||||
|
||||
## [Troubleshooting](https://github.com/CERT-Polska/drakvuf-sandbox/wiki/Troubleshooting)
|
||||
|
||||
## [Project contents](https://github.com/CERT-Polska/drakvuf-sandbox/wiki/Project-contents)
|
||||
|
||||
## [Building installation packages](https://github.com/CERT-Polska/drakvuf-sandbox/wiki/Building-installation-packages)
|
||||
See the docs for the [installation guide](https://drakvuf-sandbox.readthedocs.io/en/latest/usage/getting_started.html).
|
||||
|
||||
## Maintainers/authors
|
||||
|
||||
|
||||
@@ -0,0 +1 @@
|
||||
_build/
|
||||
@@ -0,0 +1,20 @@
|
||||
# Minimal makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
|
||||
.PHONY: help Makefile
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@@ -0,0 +1,32 @@
|
||||
Building installation packages
|
||||
##############################
|
||||
|
||||
In order to build installation packages on your own, you must first `install Docker <https://docs.docker.com/install/linux/docker-ce/debian/>`_ on your machine.
|
||||
|
||||
DRAKVUF Sandbox (drakcore, drakrun)
|
||||
===================================
|
||||
|
||||
|
||||
You may build your packages from source using following commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git clone https://github.com/CERT-Polska/drakvuf-sandbox.git
|
||||
$ cd drakvuf-sandbox
|
||||
$ sudo ./drakcore/package/build.sh
|
||||
$ sudo ./drakrun/package/build.sh
|
||||
|
||||
Afterwards, you should find your installation packages produced in `out/` directory.
|
||||
|
||||
DRAKVUF (drakvuf-bundle)
|
||||
========================
|
||||
|
||||
The build scripts for `drakvuf-bundle` are part of `tklengyel/drakvuf <https://github.com/tklengyel/drakvuf>`_ repository. You may build your package using the following commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git clone --recursive https://github.com/tklengyel/drakvuf
|
||||
$ cd drakvuf
|
||||
$ sudo ./package/build.sh
|
||||
|
||||
The resulting package will be produced to ``package/out/`` directory.
|
||||
@@ -0,0 +1,62 @@
|
||||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# This file only contains a selection of the most common options. For a full
|
||||
# list see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Path setup --------------------------------------------------------------
|
||||
|
||||
# If extensions (or modules to document with autodoc) are in another directory,
|
||||
# add these directories to sys.path here. If the directory is relative to the
|
||||
# documentation root, use os.path.abspath to make it absolute, like shown here.
|
||||
#
|
||||
# import os
|
||||
# import sys
|
||||
# sys.path.insert(0, os.path.abspath('.'))
|
||||
import sphinx_rtd_theme
|
||||
|
||||
import os
|
||||
import sys
|
||||
sys.path.insert(0, os.path.abspath('../drakcore'))
|
||||
sys.path.insert(0, os.path.abspath('../drakrun'))
|
||||
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
|
||||
project = 'DRAKVUF Sandbox'
|
||||
copyright = '2020, CERT Polska'
|
||||
author = 'CERT Polska'
|
||||
|
||||
# The full version, including alpha/beta/rc tags
|
||||
release = 'v0.11.0'
|
||||
|
||||
|
||||
# -- General configuration ---------------------------------------------------
|
||||
|
||||
# Add any Sphinx extension module names here, as strings. They can be
|
||||
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
|
||||
# ones.
|
||||
extensions = [
|
||||
"sphinx_rtd_theme",
|
||||
]
|
||||
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This pattern also affects html_static_path and html_extra_path.
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
@@ -0,0 +1,45 @@
|
||||
===================
|
||||
DRAKVUF Sandbox FAQ
|
||||
===================
|
||||
|
||||
Can I run DRAKVUF Sandbox in the cloud?
|
||||
---------------------------------------
|
||||
|
||||
We've done some research regarding the deployment of the sandbox in the cloud.
|
||||
Unfortunately, due to the nature of the project and extensive use of low level CPU features,
|
||||
none of the popular "instance" services were able to run DRAKVUF - bare metal access is required.
|
||||
If you're interested to learn more about underlying problems see `relevant issues on GitHub <https://github.com/CERT-Polska/drakvuf-sandbox/issues?q=label%3Anested>`_.
|
||||
|
||||
.. _check-cpu:
|
||||
|
||||
How can I verify if my CPU is supported?
|
||||
----------------------------------------
|
||||
|
||||
If you're running fairly recent Intel CPU, it's probably going to have all of the required features.
|
||||
|
||||
0. Make sure VT-x extensions are enabled in BIOS.
|
||||
1. Check virtualization extensions support.
|
||||
|
||||
.. code-block :: console
|
||||
|
||||
$ lscpu | grep vmx
|
||||
|
||||
2. Check EPT support.
|
||||
|
||||
.. code-block :: console
|
||||
|
||||
$ lscpu | grep ept
|
||||
|
||||
If both flags are present, you're good to go.
|
||||
|
||||
I have an AMD CPU which supports NPT. Can I run DRAKVUF Sandbox?
|
||||
----------------------------------------------------------------
|
||||
|
||||
DRAKVUF is tightly coupled with `alpt2m <https://xenproject.org/2016/04/13/stealthy-monitoring-with-xen-altp2m/>`_ feature, implemented
|
||||
only for Intel CPUs. Thus it's not possible to run it on a AMD CPU.
|
||||
|
||||
|
||||
I have some other question
|
||||
--------------------------
|
||||
|
||||
Feel free to `submit an issue <https://github.com/CERT-Polska/drakvuf-sandbox/issues/new/choose>`_, write us an email or contact in any other way.
|
||||
@@ -0,0 +1,34 @@
|
||||
=============================
|
||||
DRAKVUF Sandbox Documentation
|
||||
=============================
|
||||
|
||||
DRAKVUF Sandbox is an automated black-box malware analysis system with DRAKVUF engine under the hood, which does not require an agent on guest OS.
|
||||
|
||||
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 insight whether the file is truly malicious or not.
|
||||
|
||||
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.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: User guide
|
||||
|
||||
usage/getting_started
|
||||
usage/optional_features
|
||||
usage/troubleshooting
|
||||
|
||||
understanding_sandbox
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:caption: Developer guide
|
||||
|
||||
building_packages
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:caption: Misc
|
||||
|
||||
faq
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
Sphinx==3.2.1
|
||||
sphinx-rtd-theme==0.5.0
|
||||
@@ -0,0 +1,50 @@
|
||||
=========================
|
||||
Understanding the sandbox
|
||||
=========================
|
||||
|
||||
DRAKVUF Sandbox is divided into two packages:
|
||||
|
||||
* drakcore - system core, provides a web interface, an internal task queue and object storage
|
||||
* drakrun - sandbox worker, wrapper for DRAKVUF, responsible for managing VMs, running analyses and sending results for further postprocessing.
|
||||
|
||||
|
||||
.. note ::
|
||||
`DRAKVUF engine <https://github.com/tklengyel/drakvuf>`_ is a separate project authored by Tamas K Lengyel.
|
||||
|
||||
DRAKVUF Sandbox is built around *karton* -- microservice framework created at CERT Poland
|
||||
as a specialized tool for building flexible malware analysis pipelines. Its main goal
|
||||
is routing tasks between multiple services.
|
||||
|
||||
As of now, documentation for *karton* isn't publically available, however this will change
|
||||
in the future.
|
||||
|
||||
Daemons
|
||||
-------
|
||||
|
||||
* drakcore package
|
||||
|
||||
* ``drak-web`` - web interface that allows user to interact with the sandbox with either REST API or GUI
|
||||
* ``drak-system`` - internal task management system, using for dispatching jobs between workers
|
||||
* ``drak-minio`` - builtin object storage in which analysis results are stored
|
||||
* ``drak-postprocess`` - responsible for processing raw analysis logs into more usable form
|
||||
|
||||
* drakrun package
|
||||
|
||||
* ``drakrun 1..n`` - fetches incoming samples for analysis, runs VMs, and sends back results of analysis; each daemon handles one concurrent VM
|
||||
|
||||
Lifecycle of a analysis
|
||||
-----------------------
|
||||
|
||||
1. User submits new analysis with a browser or programatically using *karton* API.
|
||||
2. ``drak-system`` dispatches the job to one of the ``drakrun`` instances.
|
||||
3. ``drakrun`` runs the analysis:
|
||||
|
||||
- preconfigured virtual machine image is restored
|
||||
- sample is uploaded to the VM using DRAKVUF's ``injector``
|
||||
- sample is executed
|
||||
- after a chosen timeout, virtual machine is destroyed
|
||||
|
||||
4. Raw results (dumps, logs, pcaps) are sent back to ``drak-system`` as a *karton* task.
|
||||
5. ``drak-system`` dispatches a task to ``drak-postprocess`` which extracts interesting data for the user
|
||||
|
||||
|
||||
@@ -0,0 +1,80 @@
|
||||
===============
|
||||
Getting started
|
||||
===============
|
||||
|
||||
Supported hardware & software
|
||||
=============================
|
||||
|
||||
In order to run DRAKVUF Sandbox, your setup must fullfill all of the listed requirements:
|
||||
|
||||
* Processor: Intel processor with VT-x and EPT features (:ref:`how to check <check-cpu>`).
|
||||
* Host system: Debian 10 Buster/Ubuntu 18.04 Bionic/Ubuntu 20.04 Focal with at least 2 core CPU and 5 GB RAM, running GRUB as bootloader.
|
||||
* Guest system: Windows 7 (x64), Windows 10 (x64; experimental support)
|
||||
|
||||
Nested virtualization:
|
||||
|
||||
* KVM **does** work, however it is considered experimental. If you experience any bugs, please report them to us for further investigation.
|
||||
* Due to lack of exposed CPU features, hosting DRAKVUF Sandbox in the cloud is **not** supported (although it might change in the future).
|
||||
* Hyper-V does **not** work.
|
||||
* Xen **does** work out of the box.
|
||||
* VMware Workstation Player **does** work, but you need to check Virtualize EPT option for a VM; Intel processor with EPT still required.
|
||||
|
||||
Basic installation
|
||||
==================
|
||||
|
||||
This instruction assumes that you want to create a single-node installation with the default components, which is recommended for beginners.
|
||||
|
||||
1. Download `latest release packages <https://github.com/CERT-Polska/drakvuf-sandbox/releases>`_.
|
||||
2. Install DRAKVUF:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# apt update
|
||||
# apt install ./drakvuf-bundle*.deb
|
||||
# reboot
|
||||
3. Install DRAKVUF Sandbox stack:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# apt install redis-server
|
||||
# apt install ./drakcore*.deb
|
||||
# apt install ./drakrun*.deb
|
||||
4. Execute:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# draksetup install /opt/path_to_windows.iso
|
||||
|
||||
Read the command's output carefully. This command will run a virtual machine with Windows system installation process.
|
||||
|
||||
**Unattended installation:** If you have ``autounattend.xml`` matching your Windows ISO, you can request unattended installation by adding ``--unattended-xml /path/to/autounattend.xml``. Unattended install configuration can be generated with `Windows Answer File Generator <https://www.windowsafg.com/win10x86_x64.html>`_.
|
||||
|
||||
.. note::
|
||||
By default, DRAKVUF Sandbox will store virtual machine's HDD in a ``qcow2`` file. If you want to use ZFS instead, please check the :ref:`ZFS storage backend<zfs-backend>` docs.
|
||||
|
||||
5. Use VNC to connect to the installation process:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ vncviewer localhost:5900
|
||||
|
||||
6. Perform Windows installation until you are booted to the desktop.
|
||||
|
||||
7. **Extra software:** At this point you might optionally install additional software. You can execute:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# draksetup mount /path/to/some-cd.iso
|
||||
|
||||
which would mount a virtual CD disk containing additional software into your VM.
|
||||
|
||||
8. In order to finalize the VM setup process, execute:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# draksetup postinstall
|
||||
|
||||
.. note ::
|
||||
Add ``--no-report`` if you don't want ``draksetup`` to send `basic usage report <https://github.com/CERT-Polska/drakvuf-sandbox/blob/master/USAGE_STATISTICS.md>`_.
|
||||
|
||||
9. Test your installation by navigating to the web interface ( http://localhost:6300/ ) and uploading some samples. The default analysis time is 10 minutes.
|
||||
@@ -0,0 +1,112 @@
|
||||
|
||||
=================
|
||||
Optional features
|
||||
=================
|
||||
|
||||
|
||||
This sections contains various information about optional features that may be enabled when setting up DRAKVUF Sandbox.
|
||||
|
||||
|
||||
.. _zfs-backend:
|
||||
|
||||
ZFS storage backend
|
||||
-------------------
|
||||
If you want to install DRAKVUF Sandbox with a ZFS storage backend, you should perform the following extra steps before executing ``draksetup install`` command:
|
||||
|
||||
1. Install ZFS on your machine (guide for: `Debian Buster <https://github.com/openzfs/zfs/wiki/Debian>`_, `Ubuntu 18.04 <https://ubuntu.com/tutorials/setup-zfs-storage-pool#2-installing-zfs>`_)
|
||||
2. Create a ZFS pool on a free partition:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# zpool create tank <partition_name>
|
||||
|
||||
where ``<partiton_name>`` is e.g. ``/dev/sda3``. Be aware that all data stored on the selected partition may be erased.
|
||||
|
||||
3. Create a dataset for DRAKVUF Sandbox:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# zfs create tank/vms
|
||||
|
||||
4. Execute ``draksetup install`` as in "Basic installation" section, but remembering to provide additional command line switches:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
--storage-backend zfs --zfs-tank-name tank/vms
|
||||
|
||||
|
||||
|
||||
Networking
|
||||
----------
|
||||
|
||||
.. note ::
|
||||
Even though that the guest Internet connectivity is an optional feature, ``drakrun`` would always make some changes to your host system's network configuration:
|
||||
|
||||
Always:
|
||||
|
||||
* Each instance of ``drakrun@<vm_id>`` will create a bridge ``drak<vm_id>``, assign ``10.13.<vm_id>.1/24`` IP address/subnet to it and bring the interface up.
|
||||
* ``drakrun`` will drop any INPUT traffic originating from ``drak<vm_id>`` bridge, except DHCP traffic (UDP ports: 67, 68).
|
||||
|
||||
Only with ``net_enable=1``:
|
||||
|
||||
* ``drakrun`` will enable IPv4 forwarding.
|
||||
* ``drakrun`` will configure MASQUERADE through ``out_interface`` for packets originating from ``10.13.<vm_id>.0/24``.
|
||||
* ``drakrun`` will DROP traffic between ``drak<X>`` and ``drak<Y>`` bridges for ``X != Y``.
|
||||
|
||||
In order to find out the exact details of the network configuration, search for ``_add_iptable_rule`` function usages in ``drakrun/drakrun/main.py`` file.
|
||||
|
||||
Basic networking
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
If you want your guest VMs to access Internet, you can enable networking by editing ``[drakrun]``
|
||||
section in ``/etc/drakrun/config.ini``:
|
||||
|
||||
* Set ``net_enable=1`` in order to enable guest Internet access.
|
||||
* Check if ``out_interface`` was detected properly (e.g. ``ens33``) and if not, correct this setting.
|
||||
|
||||
After making changes to ``/etc/drakrun``, you need to restart all ``drakrun`` services that are running
|
||||
in your system:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# systemctl restart 'drakrun@*'
|
||||
|
||||
Be aware that if your sandbox instance is already running some analyses, the above command will gracefully
|
||||
wait up to a few minutes until these are completed.
|
||||
|
||||
Using dnschef
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
You may optionally configure your guests to use dnschef.
|
||||
|
||||
1. Setup `dnschef <https://github.com/iphelix/dnschef>`_ tool.
|
||||
2. Start ``dnschef`` in such way to make it listen on all ``drak*`` interfaces that belong to DRAKVUF Sandbox.
|
||||
3. Set ``dns_server=use-gateway-address`` in ``/etc/drakrun/config.ini``.
|
||||
4. Restart your drakrun instances: ``systemctl restart 'drakrun@*``.
|
||||
|
||||
MS Office file support
|
||||
----------------------
|
||||
|
||||
There is an experimental support for analyzing word and excel samples. However this requires that you have Microsoft Office installed.
|
||||
|
||||
The steps below should be completed on guest vm before creating the snapshot (e.g. before you run ``draksetup postinstall``).
|
||||
|
||||
1. Install Microsoft Office. You can use ``draksetup mount /path/to/office.iso`` command to insert Office installation media during VM setup.
|
||||
After installation, you should be able to start word/excel by running ``start winword.exe``, ``start excel.exe`` from command line.
|
||||
2. Adjust the registry keys by adding 3 values (``DWORD VBAWarnings VALUE=1``, ``DWORD AccessVBOM VALUE=1``, ``DWORD ExtensionHardening VALUE=0``) both to ``Computer\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\<version>\Word\Security`` and to ``Computer\HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\<version>\Excel\Security`` keys.
|
||||
|
||||
|
||||
ProcDOT integration
|
||||
-------------------
|
||||
DRAKVUF Sandbox may optionally draw a behavioral graph using `ProcDOT <https://www.procdot.com/>`_, if ``drakcore`` will find it's binary installed at ``/opt/procdot/procmon2dot``.
|
||||
|
||||
1. `Download ProcDOT <https://www.procdot.com/downloadprocdotbinaries.htm>`_ (Linux version).
|
||||
2. With your downloaded ``procdot*_linux.zip`` archive, execute the following commands:
|
||||
|
||||
.. code-block :: console
|
||||
|
||||
# unzip -o procdot*_linux.zip lin64/* -d /tmp/procdot
|
||||
# mv /tmp/procdot/lin64 /opt/procdot
|
||||
# chmod +x /opt/procdot/procmon2dot
|
||||
|
||||
3. Your new analysis reports will also contain behavioral graphs.
|
||||
@@ -0,0 +1,51 @@
|
||||
Troubleshooting
|
||||
===============
|
||||
|
||||
Checking service status
|
||||
-----------------------
|
||||
|
||||
If your DRAKVUF Sandbox installation seems to work improperly, here are some commands that would help to troubleshoot the infrastructure.
|
||||
|
||||
Check service status:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# drak-healthcheck
|
||||
|
||||
Check service logs:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# journalctl -e -u drak-web
|
||||
# journalctl -e -u drak-system
|
||||
# journalctl -e -u drak-minio
|
||||
# journalctl -e -u drakrun@1
|
||||
|
||||
Debug ``device model did not start``
|
||||
------------------------------------
|
||||
|
||||
You may encounter the following error with ``draksetup`` command or ``drakrun@*`` service, which will prevent the VM from starting properly.
|
||||
|
||||
::
|
||||
|
||||
libxl: error: libxl_create.c:1676:domcreate_devmodel_started: Domain 4:device model did not start: -3
|
||||
...
|
||||
subprocess.CalledProcessError: Command 'xl create /etc/drakrun/configs/vm-0.cfg' returned non-zero exit status 3.
|
||||
|
||||
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.
|
||||
|
||||
Debug ``can't allocate low memory for domain``
|
||||
----------------------------------------------
|
||||
|
||||
The following error with ``draksetup`` command or ``drakrun@*`` service means that your machine is missing memory resources:
|
||||
|
||||
::
|
||||
|
||||
xc: error: panic: xc_dom_boot.c:122: xc_dom_boot_mem_init: can't allocate low memory for domain: Out of memory
|
||||
...
|
||||
subprocess.CalledProcessError: Command 'xl create /etc/drakrun/configs/vm-0.cfg' returned non-zero exit status 3.
|
||||
|
||||
Resolutions:
|
||||
|
||||
* 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``
|
||||
* adjust the amount of memory dedicated to the DomU (guest systems) in ``/etc/drakrun/scripts/cfg.template`` (``maxmem`` and ``memory`` keys)
|
||||
Reference in New Issue
Block a user