SecGen creates vulnerable virtual machines, lab environments, and hacking challenges, so students can learn security penetration testing techniques.
Boxes like Metasploitable2 are always the same, this project uses Vagrant, Puppet, and Ruby to create randomly vulnerable virtual machines that can be used for learning or for hosting CTF events.
The latest version is available at: http://github.com/cliffe/SecGen/
Please complete a short survey to tell us how you are using SecGen.
For a hosted solution visit: https://hacktivity.co.uk/
Computer security students benefit from engaging in hacking challenges. Practical lab work and pre-configured hacking challenges are common practice both in security education and also as a pastime for security-minded individuals. Competitive hacking challenges, such as capture the flag (CTF) competitions have become a mainstay at industry conferences and are the focus of large online communities. Virtual machines (VMs) provide an effective way of sharing targets for hacking, and can be designed in order to test the skills of the attacker. Websites such as Vulnhub host pre-configured hacking challenge VMs and are a valuable resource for those learning and advancing their skills in computer security. However, developing these hacking challenges is time consuming, and once created, essentially static. That is, once the challenge has been "solved" there is no remaining challenge for the student, and if the challenge is created for a competition or assessment, the challenge cannot be reused without risking plagiarism, and collusion.
Security Scenario Generator (SecGen) generates randomised vulnerable systems. VMs are created based on a scenario specification, which describes the constraints and properties of the VMs to be created. For example, a scenario could specify the creation of a system with a remotely exploitable vulnerability that would result in user-level compromise, and a locally exploitable flaw that would result in root-level compromise. This would require the attacker to discover and exploit both randomly selected vulnerabilities in order to obtain root access to the system. Alternatively, the scenario that is defined can be more specific, specifying certain kinds of services (such as FTP or SMB) or even exact vulnerabilities (by CVE).
SecGen is a Ruby application, with an XML configuration language. SecGen reads its configuration, including the available vulnerabilities, services, networks, users, and content, reads the definition of the requested scenario, applies logic for randomising the scenario, and leverages Puppet and Vagrant to provision the required VMs.
SecGen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
SecGen contains modules, which install various software packages. Each SecGen module may contain or remotely source software, and each module defines its own license in the accompanying secgen_metadata.xml file.
SecGen is developed and tested on Ubuntu Linux. In theory, SecGen should run on Mac or Windows, if you have all the required software installed.
SecGen needs:
- Ruby 2.7 to 4.0, with development headers, and the Ruby gems in the Gemfile (including Nokogiri and Librarian-puppet)
- Vagrant: https://developer.hashicorp.com/vagrant
- VirtualBox: https://www.virtualbox.org/ (or Proxmox / oVirt / ESXi, see below)
- ImageMagick, ExifTool, Graphviz and a few libraries for native gems
- Packer, only for the Windows bases: https://www.packer.io/
There are two ways to install it. Both have been tested from a fresh Ubuntu install.
Install Docker and VirtualBox on the host, then let docker/secgen-docker.sh build a container with everything else. VirtualBox is still needed on the host for its kernel driver. See docker/README.md.
git clone https://github.com/cliffe/SecGen.git
cd SecGen
docker/secgen-docker.sh run -s scenarios/default_scenario.xmlInstall VirtualBox from Oracle's repository. The virtualbox package in Ubuntu 24.04 (7.0.16) cannot build its kernel driver for the current HWE kernels, and Linux 7.0 needs VirtualBox 7.2.8 or later:
sudo apt-get update
sudo apt-get install -y wget gpg lsb-release
wget -qO- https://www.virtualbox.org/download/oracle_vbox_2016.asc \
| sudo gpg --yes --dearmor -o /usr/share/keyrings/oracle-virtualbox-2016.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/oracle-virtualbox-2016.gpg] https://download.virtualbox.org/virtualbox/debian $(lsb_release -cs) contrib" \
| sudo tee /etc/apt/sources.list.d/virtualbox.list
sudo apt-get update
sudo apt-get install -y virtualbox-7.2If KVM is loaded, VirtualBox can't start VMs while KVM holds VT-x (VERR_VMX_IN_VMX_ROOT_MODE). On kernels 6.12 and later you can let them coexist:
echo "options kvm enable_virt_at_load=0" | sudo tee /etc/modprobe.d/kvm-virtualbox.conf
sudo modprobe -r kvm_intel kvm_amd kvm; sudo modprobe kvm_intel || sudo modprobe kvm_amdSecGen scenarios use host-only network ranges outside VirtualBox's default 192.168.56.0/21, so allow any range:
sudo mkdir -p /etc/vbox
echo '* 0.0.0.0/0 ::/0' | sudo tee /etc/vbox/networks.confInstall Vagrant from HashiCorp's repository (Ubuntu 26.04 no longer packages it, and older Vagrant releases can't download boxes from Vagrant Cloud any more):
wget -qO- https://apt.releases.hashicorp.com/gpg | sudo gpg --yes --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" \
| sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt-get update
sudo apt-get install -y vagrantInstall Ruby and the other required packages:
sudo apt-get install -y git ruby-full ruby-dev build-essential patch pkg-config zlib1g-dev liblzma-dev \
imagemagick exiftool libpq-dev libcurl4-openssl-dev libxml2-dev libxslt1-dev graphviz libgraphviz-dev \
libpcap-dev libsqlite3-dev libgpgme-dev libyaml-dev libffi-dev libssl-devClone SecGen and install the gems. Use bundle install, not bundle update: Gemfile.lock pins versions that work on every supported Ruby, and bundle update replaces them with the newest releases, which may not.
git clone https://github.com/cliffe/SecGen.git
cd SecGen
sudo gem install bundler -v '~> 2.4'
sudo bundle installThen try the default scenario (it downloads the base box from hacktivity.co.uk the first time):
ruby secgen.rb runNotes:
- Ubuntu 20.04 (Ruby 2.7): HashiCorp's apt repository no longer verifies on 20.04; install Vagrant from the
.debon https://releases.hashicorp.com/vagrant/ instead. Don't install theruby-bundlerpackage. It brings a Debian-packagedthorgem, andbundle installthen fails with "Could not find thor-0.19.4.gem". Usesudo gem install bundler -v 2.4.22as above (2.4 is the last Bundler release that supports Ruby 2.7). - Ruby 4.0:
bundle installre-resolves a few gems (librarian-puppet and its dependencies) and rewrites Gemfile.lock locally, because the versions pinned for Ruby 2.7 don't allow Ruby 4. - Already using SecGen on an older system? After pulling, run
sudo bundle installagain. - Memory: on VirtualBox, VMs built on desktop bases (Kali, Debian KDE) get 3000 MB each, other VMs 1024 MB, so a CTF with an attack VM and a desktop target (such as
scenarios/ctf/nosferatu.xml) needs about 6 GB of free RAM. Override with--memory-per-vmor--total-memory.
To use the Windows basesboxes you will need to install Packer. Use the following command:
curl -SL https://releases.hashicorp.com/packer/1.3.2/packer_1.3.2_linux_amd64.zip -o packer_1.3.2_linux_amd64.zip
unzip packer_1.3.2_linux_amd64.zip
sudo mv packer /usr/local/
sudo bash -c 'echo "export PATH=\"\$PATH:/usr/local/\"" >> /etc/environment'
sudo vagrant plugin install winrm
sudo vagrant plugin install winrm-fsBasic usage:
ruby secgen.rb run
SecGen accepts arguments to change the way that it behaves, the currently implemented arguments are:
ruby secgen.rb [--options] <command>
OPTIONS:
--scenario [xml file], -s [xml file]: Set the scenario to use
(defaults to /home/secgen/SecGen/scenarios/default_scenario.xml)
--project [output dir], -p [output dir]: Directory for the generated project
(output will default to /home/secgen/SecGen/projects/SecGen20200313_094915)
--shutdown: Shutdown VMs after provisioning (vagrant halt)
--network-ranges: Override network ranges within the scenario, use a comma-separated list
--forensic-image-type [image type]: Forensic image format of generated image (raw, ewf)
--read-options [conf path]: Reads options stored in file as arguments (see example.conf)
--memory-per-vm: Allocate generated VMs memory in MB (e.g. --memory-per-vm 1024)
--total-memory: Allocate total VM memory for the scenario, split evenly across all VMs.
--cpu-cores: Number of virtual CPUs for generated VMs
--help, -h: Shows this usage information
--system, -y [system_name]: Only build this system_name from the scenario
--snapshot: Creates a snapshot of VMs once built
--no-tests: Prevent post-provisioning tests from running.
VIRTUALBOX OPTIONS:
--gui-output, -g: Show the running VM (not headless)
--nopae: Disable PAE support
--hwvirtex: Enable HW virtex support
--vtxvpid: Enable VTX support
--max-cpu-usage [1-100]: Controls how much cpu time a virtual CPU can use
(e.g. 50 implies a single virtual CPU can use up to 50% of a single host CPU)
OVIRT OPTIONS:
--ovirtuser [ovirt_username]
--ovirtpass [ovirt_password]
--ovirt-url [ovirt_api_url]
--ovirtauthz [ovirt authz]
--ovirt-cluster [ovirt_cluster]
--ovirt-network [ovirt_network_name]
--ovirt-affinity-group [ovirt_affinity_group_name]
ESXI OPTIONS:
--esxiuser [esxi_username]
--esxipass [esxi_password]
--esxi-hostname [esxi_api_url]
(ESXi hostname/IP)
--esxi-datastore [esxi_datastore]
--esxi-disktype [esxi_disktype]: 'thin', 'thick', or 'eagerzeroedthick'
(If unspecified, it will be set to 'thin')
--esxi-network [esxi_network_name]
(If its not specified, the default is to use the first found)
--esxi-guest-nictype [esxi_nictype]: 'e1000', 'e1000e', 'vmxnet', 'vmxnet2', 'vmxnet3', 'Vlance', or 'Flexible'
(RISKY - Can cause VM to not respond)
--esxi-no-hostname
(Setting the hostname on some boxes can cause vagrant up to fail if the network configuration was not previously cleaned up.)
PROXMOX OPTIONS:
--proxmoxuser [username]
--proxmoxpass [password]
--proxmox-url [api_url]
--proxmox-node [node]
--proxmox-network [proxmox network name]
--proxmox-vlan [vlan number]
COMMANDS:
run, r: Builds project and then builds the VMs
build-project, p: Builds project (vagrant and puppet config), but does not build VMs
build-vms, v: Builds VMs from a previously generated project
(use in combination with --project [dir])
ovirt-post-build: only performs the ovirt actions that normally follow a successful vm build
(snapshots and networking)
create-forensic-image: Builds forensic images from a previously generated project
(can be used in combination with --project [dir])
list-scenarios: Lists all scenarios that can be used with the --scenario option
list-projects: Lists all projects that can be used with the --project option
delete-all-projects: Deletes all current projects in the projects directoryIf SecGen experiences errors installing packages, the template VMs (base boxes) we publish on Vagrant cloud may need updating (especially Kali, which is a rolling-release). After you have built some VMs, browse in your home directory .vagrant.d/boxes/, from here you can manually launch the VMs that are used as templates, and apply software updates sudo apt-get update; sudo apt-get upgrade. Then power down the VM, and try SecGen again.
For Proxmox, use this Vagrant plugin: https://github.com/cliffe/vagrant-proxmox/, and make this fix to Vagrant: https://github.com/hashicorp/vagrant/pull/12463/files.
You will typically need to create a Debian Buster base VM, broadly following these instructions: https://github.com/cliffe/SecGen/blob/master/README-Creating-Bases.md
SecGen generates VMs based on a scenario specification, which describes the constraints and properties of the VMs to be created.
Existing scenarios make SecGen's barrier for entry low: when invoking SecGen, a scenario can be specified as a command argument, and SecGen will then read the appropriate scenario definition and go about randomisation and VM generation. This removes the requirement for end users of the framework to understand SecGen's configuration specification.
Scenarios can be found in the scenarios/ directory. For example, to spin up a VM that has a random remotly exploitable vulnerability that results in user-level compromise:
ruby secgen.rb --scenario scenarios/examples/remotely_exploitable_user_vulnerability.xml run
To generate a set of VMs for a randomly generated fictional organisation, with a desktop system, webserver, and intranet server:
ruby secgen.rb --scenario scenarios/security_audit/team_project.xml runNote that the intranet server has a security remit, with instructions on performing a security audit of these systems. The desktop system can access the intranet to access the remit, but the attacker VM (for example, Kali) can be connected to the NIC only shared by the Web server to simulate the need to pivot attacks through the Web server, as they can't connect to the intranet system directly. The "marking guide" is in the form of the output scenario.xml in the project directory, which provides the details of the systems generated.
To generate a set of VMs for a CTF competition:
ruby secgen.rb --scenario scenarios/ctf/flawed_fortress_1.xml runNote that a 'CTFd_importable.zip' file is also generated, containing all the flags and hints, which you can import into the CTFd scoreboard frontend. This is compatible with CTFd v2.0.2 and newer.
Default admin account: Username: adminusername Password: adminpassword
Writing your own scenarios enables you to define a VM or set of VMs with a configuration as specific or general as desired.
SecGen's scenario specification is a powerful interface for specifying the constraints of the vulnerable systems to generate. Scenarios are defined in XML configuration files that specify systems in terms of a base, services/utilities, vulnerabilities, and networks.
For details please see the Creating Scenarios guide.
SecGen is designed to be easily extendable with modules that define vulnerabilities and other kinds of software, configuration, and content changes.
The types of modules supported in SecGen are:
- base: a SecGen module that defines the OS platform (VM template) used to build the VM
- vulnerability: a SecGen module that adds an insecure, hackable, state (including realistic software vulnerabilities known to be in the wild or fabricated hacking challenges)
- service: a SecGen module that adds a (relatively secure) network service
- utility: a SecGen module that adds (relatively secure) software or configuration changes
- network: a virtual network card
- generator: generates output, such as random text
- encoder: receives input, such as text, performs operations on that to produce output (such as, encoding/encryption/selection)
Each vulnerability module is contained within the modules/vulnerabilies directory tree, which is organised to match the Metasploit Framework (MSF) modules directory structure. For example, the distcc_exec vulnerability module is contained within: modules/vulnerabilities/unix/misc/distcc_exec/.
The root of the module directory always contains a secgen_metadata.xml file and also contains puppet files, which are used to make a system vulnerable.
For details please see the Modules Metadata guide.
Encoders and generators have code that is evaluated at project build time, such as encoding text, and generating flags and other potentially randomised content. In each case, this is a ruby script located within the module directory in local/secgen_local.rb. Although normally called by SecGen, secgen_local.rb scripts can be executed directly, and accept all the parameter inputs as command line arguments, and returns the output in JSON format to stdout. Other human readable output is written to stderr.
#ruby modules/encoders/string/base64/secgen_local/local.rb --strings_to_encode "encode this" --strings_to_encode "and this"
BASE64 Encoder
Encoding '["encode this", "and this"]'
Encoded: ["ZW5jb2RlIHRoaXM=", "YW5kIHRoaXM="]
["ZW5jb2RlIHRoaXM=","YW5kIHRoaXM="]
Each vulnerability, service, and utility module contains Puppet files which are used to provision the software and configuration changes onto the VMs. By the time Puppet is executed to provision VMs, all randomisation has previously taken place at build time.
For details please see the Modules Puppet guide.
By default output is to 'projects/SecGen_[CurrentTime]/'
The project output includes:
- A Vagrant configuration for spinning up the boxes.
- A directory containing all the required puppet modules for the above. A Librarian-Puppet file is created to manage modules, and some required modules may be obtained via PuppetForge, and therefore an Internet connection is required when building the project.
- A de-randomised scenario XML file. Using SecGen you can use this 'scenario.xml' file to recreate the above Vagrant config and puppet files. Any randomisation that has been applied should be un-randomised in this output (compared to the original scenario file). This file contains all the details of the systems created, and can also be used later for grading, scoring, or giving hints.
- A 'flag_hints.xml' file, containing all the flags along with multiple hints per flag.
- A 'CTFd_importable.zip' file useful for CTF events, for import into the CTFd scoreboard frontend.
If you start SecGen with the "build-project" (or "p") command it creates the above files and then stops. The "run" (or "r") command creates the project files then uses Vagrant to build the VM(s).
It is possible to copy the project directory to any compatible system with Vagrant, and simply run "vagrant up" to create the VMs.
The default root password for the base-boxes is 'puppet', but this may be modified by SecGen depending on the scenario used.
Generating multiple VMs in a batch is now possible through the use of batch_secgen, which manages a job queue to mass-create VMs with SecGen. There are helper commands available to add jobs, list jobs in the table, remove jobs, and reset the status of jobs from 'running' or 'error' to 'todo'.
For details please see the Batch Creation of VMs guide.
The Cyber Security Body of Knowledge (CyBOK) is a body of knowledge that aims to encapsulate the various knowledge areas present within cyber security. Scenarios within SecGen now contain XML elements linking them to CyBOK knowledge areas and specific topics within those knowledge areas. Additionally, video content for scenarios are tagged with CyBOK associations.
For an index of lab scenarios in SecGen organised by CyBOK Knowledge Areas please see the Lab Scenarios and CyBOK. Likewise, for CTF scenarios.
For a list of lecture and demo videos with CyBOK metadata please see the Lecture Videos and CyBOK.
The table below is a key for the abbreviations you will find within the CyBOK XML elements within the scenarios:
| Abbreviation | Knowledge Area (KA) | Chapter | Knowledge Tree |
|---|---|---|---|
| IC | Introduction to CyBOK | link | link |
| FM | Formal Methods | n/a | link |
| RMG | Risk Management & Governance | link | link |
| LR | Law & Regulation | link | link |
| HF | Human Factors | link | link |
| POR | Privacy & Online Rights | link | link |
| MAT | Malware & Attack Technologies | link | link |
| AB | Adversarial Behaviours | link | link |
| SOIM | Security Operations & Incident Management | link | link |
| F | Forensics | link | link |
| C | Cryptography | link | link |
| AC | Applied Cryptography | link | link |
| OSV | Operating Systems & Virtualisation Security | link | link |
| DSS | Distributed Systems Security | link | link |
| AAA | Authentication, Authorisation and Accountability | link | link |
| SS | Software Security | link | link |
| WAM | Web & Mobile Security | link | link |
| SSL | Secure Software Lifecycle | link | link |
| NS | Network Security | link | link |
| HS | Hardware Security | link | link |
| CPS | Cyber Physical Systems | link | link |
| PLT | Physical Layer and Telecommunications Security | link | link |
For a hosted solution visit: https://hacktivity.leedsbeckett.ac.uk/
Hacktivity is powered by SecGen, and provides a fully-hosted lab environment for cyber security education. Track your progress with CyBOK insights.
Development team:
- Dr Z. Cliffe Schreuders http://z.cliffe.schreuders.org
- Tom Shaw
- Alix Hiscock
- Rosie Fletcher
- James Davis
- Sofia Markusfeld
- Harry Hall
- Jack Biggs
- Tom Harrison
- Jason Keighley
- Lewis Ardern -- author of the first proof-of-concept release of SecGen
- Connor Wilson
Many thanks to everyone who has contributed to the project. The above list is not complete or exhaustive, please refer to the GitHub history.
Grant support:
- This project is supported by a Higher Education Academy (HEA) learning and teaching in cyber security grant (2015-2017).
- This project is supported by a Leeds Beckett University Teaching Excellence Fund grant (2018-2019).
- This project is supported by a Cyber Security Body of Knowledge (CyBOK) resources around CyBOK 1.0 grant (2021).
- This project is supported by a Cyber Security Body of Knowledge (CyBOK) resources around CyBOK 1.1 grant (2021-2022).
- This project is supported by a Cyber Security Body of Knowledge (CyBOK) resources around CyBOK 1.1 grant (2022-2023).
- This project is supported by a CyberASAP (Cyber Security Academic Startup Accelerator Programme) Innovate UK grant (2022-2023).
- This project is supported by a Leeds Beckett University Teaching Excellence Fund grant (2023).
- This project is supported by a Cyber Security Body of Knowledge (CyBOK) resources around CyBOK 1.1 grant (2023-2024).
- This project is supported by a Cyber Security Body of Knowledge (CyBOK) resources around CyBOK 1.1 grant (2024-2025).
- This project is supported by a Cyber Security Body of Knowledge (CyBOK) resources around Security-Informed Safety grant (2025-2026).
We encourage contributions to the project.
Briefly, please fork from http://github.com/cliffe/SecGen/, create a branch, make and commit your changes, then create a pull request.
Paper: Z.C. Schreuders, T. Shaw, A. Mac Muireadhaigh, and P. Staniforth, “Hackerbot: Attacker Chatbots for Randomised and Interactive Security Labs, Using SecGen and oVirt,” USENIX Workshop on Advances in Security Education (ASE'18), Baltimore, MD, USA. USENIX Association, 2018. (This paper describes Hackerbot and how we use SecGen with oVirt.)
Paper: Z.C. Schreuders, T. Shaw, M. Shan-A-Khuda, G. Ravichandran, J. Keighley, and M. Ordean, “Security Scenario Generator (SecGen): A Framework for Generating Randomly Vulnerable Rich-scenario VMs for Learning Computer Security and Hosting CTF Events,” USENIX Workshop on Advances in Security Education (ASE'17), Vancouver, BC, Canada. USENIX Association, 2017. (This paper provides a good overview of SecGen.)
Paper: Z.C. Schreuders, and L. Ardern, "Generating randomised virtualised scenarios for ethical hacking and computer security education: SecGen implementation and deployment," in The first UK Workshop on Cybersecurity Training & Education (Vibrant Workshop 2015) Liverpool, UK, 2015. (This paper describes the first prototype.)
Podcast interview: Purple Squad Security Episode 011 – Security Scenario Generator with Dr. Z. Cliffe Schreuders