Contributor Guide

Who is this guide for? This guide is for users interested in creating their own scenario or getting more familiarity with scenario creation so that they can modify an existing one more thoroughly. Users only interested in running previously made scenarios should refer to the UserGuide and the ScenarioPackage's documentation.

Getting Started

Before trying to create a scenario one should be familiar with the general structure of a ScenarioPackage and a ScenarioFile. Next, one should understand what a Base VM is and how the Administrative VM and OccpAdmin program can use ContentPacks and other specifications in the scenario file to produce the VSN with ConfigurationPhases. A ReferenceVSN has been created as a starting point to get familiar with this process.

Note If you name your ScenarioFile "instance.xml" it will be over written! The OccpAdmin program transforms your scenario file into an instance file which it names instance.xml.

Though highly discouraged, creating your VSN by hand is still an option. We discourage it because it makes reuse by yourself and others much more difficult. For those we haven't discouraged see this section.

Roadmap

  1. Checkout the ReferenceVSN to see if it is a suitable starting point or reference for your goals.
  2. Map out what machines you want in the VSN. Decide what exploits, services, content, configurations, etc. that you require on each machine. Also determine what players will need to accomplish and what tools should be available to them. Then for each machine:
    1. Download and install a suitable Base VM in to your hypervisor(s) that you will be using to develop your scenario. Create the host tag and set the basevm attribute in the ScenarioFile. If a suitable Base VM does not exist you have three options, but we'd prefer you choose the first
      • Visit the Base VM page and create a generic one for your needs leaving additional configurations to be handled by content packs, then contribute it back.
      • Following the steps to create a Base VM but perform additional configurations leaving only Phase 2 configuration to ContentPacks. This is creating a Phase 1 VM by hand. See building by hand info
      • (Discouraged) Create the VM entirely by hand and specify it as a Phase 2 VM. See building by hand info
    2. Find ContentPacks that can install the software, exploits, or other content you require and add them to your host tag's content. If no suitable ContentPacks exist, you have several options.
      • Create a content pack and contribute it back.
      • Create a content pack to wrap an existing puppet module (for puppet content packs)
      • (Discouraged) Do the work of the content pack by hand. See building by hand info
    3. Write a content pack to configure the remaining details specific to your scenario, such as users, passwords, SSH keys, and so on. Please see Generators to see how these things can be generated for use with your content pack.
  3. If Player VMs were not created in the previous step you should follow similar steps to produce them now. The ReferenceVSN has Lubuntu Desktop and Kali Player VM Content Packs.
  4. With your VSN machines configured you will now need to configure the GameServer. A generic GameServer content pack is probably sufficient for most but if your scenario needs to extend the GameServer you should extend the content pack to accomplish that.
  5. Now add the GameServer's actions to your scenario file.
  6. Before attempting to export and share your scenario you should run the scenario and test that everything works as expected.
  7. You can add report tags to your ScenarioFile which will generate the documentation with the Variables or generated content from Generators. Ideally there would be documentation for the administrator and participants with the former containing a solution or more detailed description of the scenario itself.
  8. When you are convinced everything is order run the OccpAdmin program in export mode and it will package your scenario.
  9. Please contribute your scenario to the community

Contributing a Scenario

Contributing logistics are still in development, please contact us for details.

Creating VMs by hand

Again we hope to discourage this in favor of expanding the number of ContentPacks available to the community but here is what you'd need to know if you wanted to create VMs by hand.

The OccpAdmin program was designed such that it would not harm VMs that were not part of your OCCP deployment. The program identifies OCCP VMs by the existence of phase snapshots, grouping, or other hypervisor specific attributes. The group will be "occp-YourScenarioName". For example, if my scenario name was "NetworkDefense", my group would be "occp-NetworkDefense". For VMware you must also add a configuration parameter called "occp.group" whose value is the group name.

  • If you fully build the VM by hand and do not ever intend to use ContentPacks then you must take a snapshot called "phase2", add your VM to the scenario's group, and declare the host to be phase2 in the ScenarioFile.
  • If you create or extend a Base VM but do not intend to use ContentPacks to configure phase 1 then you must take a snapshot named "phase1", add your VM to the scenario's group, and declare the host to be phase1 in the ScenarioFile.