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:

Modularity is key. Each component of the installation and configuration process should be modular. This allows for individuals to tailor their packer image in the most flexible way.

Builds must be atomic. A packer build should either complete all configuration and installation tasks without errors, or it should fail. A packer image with missing tools is a failure scenario.

Hardened out of the box. To the extent that it will not interfere with investigative workflows, all settings related to proactive hardening and security controls should be enabled. Further information on DARKSURGEON security can be found later in this post.

Instrumented out of the box. To the extent that it will not interfere with investigative workflows, Microsoft Sysmon, Windows Event Logging, and osquery will provide detailed telemetry on host behavior without further configuration.

Private out of the box. To the extent that it will not interfere with investigative workflows, all settings related to privacy, Windows telemetry, and error reporting should minimize collection.

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:

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:

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:

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

Packer creates a new virtual machine using the DARKSURGEON JSON file and your hypervisor of choice (e.g. Hyper-V, Virtualbox, VMWare).

The answers.iso file is mounted inside the DARKSURGEON VM along with the Windows ISO. The answers.iso file contains the unattend.xml needed for a touchless installation of windows, as well as a powershell script to configure Windows Remote Management (winrm).

Packer connects to the DARKSURGEON VM using WinRM and copies over all files in the helper-scripts and configuration-files directory to the host.

Packer performs serial installations of each of the configured powershell scripts, performing occasional reboots as needed.

When complete, packer performs a sysprep, shuts down the virtual machine, and creates a vagrant box file. Additional outputs may be specified in the post-processors section of the JSON file.

Setup

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

Install packer, vagrant, and your preferred hypervisor on your host.

Download the repository contents to your host.

Download a Windows 10 Enterprise Evaluation ISO (1803).

Move the ISO file to your local DARKSURGEON repository.

Update DARKSURGEON.json with the ISO SHA1 hash and file name.

(Optional) Execute the powershell script New-DARKSURGEONISO.ps1 to generate a new answers.iso file. There is an answers ISO file included in the repository but you may re-build this if you don't trust it, or you would like to modify the unattend files: powershell.exe New-DARKSURGEONISO.ps1

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.

Install vagrant and your preferred hypervisor on your host.

Navigate to the DARKSURGEON repository (or the location where you've saved the DARKSURGEON box file).

Perform a vagrant up: vagrant up

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.

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.

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.