DARKSURGEON is a Windows packer project to empower incident response, digital forensics, malware analysis, and network defense.

DARKSURGEON has three stated goals:

If you haven't worked with packer before, this project has a simple premise:

Provide all the tools you need to have a productive, secure, and private Windows virtual machine so you can spend less time tweaking your environment and more time fighting bad guys.

Please note this is an alpha project and it will be subject to continual development, updates, and package breakage.

Development Principles

DARKSURGEON is based on a few key development principles:

Hardening

DARKSURGEON is hardened out of the box, and comes with scripts to enable High or Low security modes.

All default installations of DARKSURGEON have the following security features enabled:

Additionally, the user may specify a Low or High security mode by using the appropriate scripts. The default setting is to build an image in Low Security mode.

Low Security mode is primarily used for virtual machines intended for reverse engineering, malware analysis, or systems that cannot support VBS security controls.

In Low Security mode, the following hardening features are configured:

Note: High Security mode is still in development.

High Security mode is primarily used for production deployment of sensitive systems (e.g. Privileged Access Workstations) and may require additional tailoring or configuration.

In High Security mode, the following hardening features are configured:

Telemetry

Whether analyzing unknown binaries or working on sensitive projects, endpoint telemetry powers detection and response operations. DARKSURGEON comes pre-configured with the following telemetry sources available for analysis:

Privacy

Your operational environment contains some of the most sensitive data from your network, and it's important to safeguard that from prying eyes. DARKSURGEON implements the following strategies to maximize privacy without hindering workflows:

Packages

Out of the box, DARKSURGEON comes equipped with tools, scripts, and binaries to make your life as a defender easier.

Android Analysis:

Tools, scripts, and binaries focused on android analysis and reverse engineering.

Blue Team:

Tools, scripts, and binaries focused on blue team, network defense, and alerting/detection development.

Debuggers:

Tools, scripts, and binaries for debugging binary artifacts.

Disassemblers:

Tools, scripts, and binaries for disassembling binary artifacts.

Document Analysis: Tools, scripts, and binaries for performing analysis of documents.

DotNet Analysis:

Tools, scripts, and binaries for performing analysis of DotNet artifacts.

Flash Analysis:

Tools, scripts, and binaries for performing analysis of flash artifacts.

Forensic Analysis:

Tools, scripts, and binaries for performing forensic analysis on application and operating system artifacts.

Hex Editors:

Java Analysis:

Network Analysis:

PE Analysis:

Powershell Modules:

Python Libraries:

Red Team:

Remote Management:

Utilities:

Visual Basic Analysis:

Building DARKSURGEON

Build Process

DARKSURGEON is built using the HashiCorp application packer. The total build time for a new instance of DARKSURGEON is around 2–3 hours.

Setup

Note: Hyper-V is currently the only supported hypervisor in this alpha release. VirtualBox and VMWare support are forthcoming.

Configuring DARKSURGEON

DARKSURGEON is designed to be modular and easy to configure. An example configuration is provided in the DARKSURGEON.json file, but you may add, remove, or tweak any of the underlying scripts.

Have a custom CA you need to add? Need to add a license file for IDA? No problem. You can throw any files you need in the configuration-files directory and they'll be copied over to the host for you.

Want to install a custom package, or need some specific OS tweaks? No worries. Simply make a new powershell script (or modify an existing one) in the configuration-scripts directory and add it as a build step in the packer JSON file.

Using DARKSURGEON

Note: Hyper-V is currently the only supported hypervisor in this alpha release. VirtualBox and VMWare support are forthcoming.

Once DARKSURGEON has successfully built, you'll receive an output vagrant box file. The box file contains the virtual machine image and vagrant metadata, allowing you to quickly spin up a virtual machine as needed.

Vagrant will now extract the virtual machine image from the box file, read the metadata, and create a new VM for you. Want to kill this VM and get a new one?

Easy, just perform the following: vagrant destroy && vagrant up

Once the DARKSURGEON virtual machine is running, you can login using one of the two local accounts:

Note: These are default accounts with default credentials. You may want to consider changing the credentials in your packer build.

Administrator Account:

Username: Darksurgeon

Password: darksurgeon

Local User Account:

Username: Unprivileged

Password: unprivileged

If you'd rather not use vagrant, you can either import the VM image manually, or look at one of the many other post-processor options provided by packer.

Downloading DARKSURGEON

If you'd rather skip the process of building DARKSURGEON and want to trust the box file I've built, you can simply download it here.

Contributing

Contributions, fixes, and improvements can be submitted directly against this project as a GitHub issue or pull request. Tools will be reviewed and added on a case-by-case basis.

Frequently Asked Questions

Why is Hyper-V the preferred hypervisor?

I strongly believe in the value of Windows Defender Device Guard and Virtualization Based Security, which require the usage of Hyper-V for optimal effectiveness. As a result, other Hypervisors are not recommended on the host machine. I will do my best to accomodate other mainline hypervisors, but I would encourage all users to try using Hyper-V.

Why does the entire packer build fail on a chocolatey package error?

This was a design decision that was made to guarantee that all packages which were expected made it into the final packer build. The upside of this decision is that it guarantees all expected tools will be available in the finalized product. The downside is that additional complexity and fragility are inserted the build pipeline, as transient or chocolatey errors may cause a build to fail.

If you wish to ignore this functionality, you are free to modify the underlying script to ignore errors on package installation.

Does this project support using a Chocolatey Professional/Business/Consultant license?

Yes. If you add your license file (named chocolatey.license.xml) to the configuration-files directory when performing a packer build, it will automatically be imported by the Set-ChocolateySettings.ps1 script. Please ensure that your usage of a chocolatey license adheres to their End-User License Agreement.

Why are the build functions broken into dozens of individual powershell scripts

Flexibility is key. You may opt to use -- or not use -- any of these scripts, and in any order. Having individual files, while increasing project complexity, ensures that the project can be completely customized without issue.

I want to debug the build. How do I do so?

Add the Set-Breakpoint.ps1 script into the provisioner process at the desired point. This will cause the packer build to halt for 4 hours as it waits for the script to complete.

Troubleshooting

The packer build process never starts and hangs on the UEFI screen.

This is most likely a timing issue caused by the emulated key presses not causing the image to boot from the mounted Windows ISO. Restart your VM and hit any button a few times until the build process starts.

Packer timed out during the build. I didn't receive an error.

Due to the size of the packages that are downloaded and installed, you may have exceeded the default packer build time limit.

My VM is running, but packer doesn't seem to connect via WinRM.

Connect to the guest and check the following:

I keep getting anti-virus, checksum, or other issues with Chocolatey. What gives?

Unfortunately these packages can be a moving target. New updates can render the static checksum in the chocolatey package incorrect, anti-virus may mistakenly flag binaries, etc. Global chocolatey options can be specified to prevent these errors from occurring, but I will do my best to respond to bug reports filed as issues on underlying chocolatey packages.

Download DARKSURGEON