` elements. 27 | 28 | - Gameboard automatically inserts your content into a pre-existing, correctly formatted HTML document for display. 29 | - You can use the **Copy from:** feature to paste an example certificate HTML configuration into the **Template** field. In the **Copy from:** dropdown, select a template to copy from and then click **Copy**. 30 | - You can include ` 16 | -------------------------------------------------------------------------------- /docs/gameboard/support.md: -------------------------------------------------------------------------------- 1 | # Getting In-Game Support 2 | 3 | The Gameboard platform comes with a built-in customer support interface so that competition hosts and administrators can assist players and teams. Gameboard is a "one-stop shop" and no outside apps or systems are required to track and measure issues reported by participants. Users who have been granted a role with the appropriate permissions can use the support feature to manage tickets. 4 | 5 | ## Support from the Participant Point-of-View 6 | 7 | ### Creating New Support Ticket 8 | 9 | You can create tickets from two places: the Support screen and the challenge screen. If you are coming from the challenge screen, then the Support Code, player id, and challenge id are automatically generated; if you are not, then this information can be added later. 10 | 11 | From the Support screen: 12 | 13 | 1. In the top navigation, click **Support**. 14 | 2. Click **Create Ticket**. 15 | 3. In the **Summary**, enter a brief statement of the problem. 16 | 4. In the **Description**, enter a more detailed statement of your problem. Include error messages and other pertinent details. 17 | 5. Under **Attachments**, attach files (especially screen shots) here. 18 | 6. Click **Submit**. 19 | 20 | After submitting the ticket, you can always **add a comment** and attach another file. Updates to a ticket are tracked under Activity. View a status change or an assignment change here too. 21 | 22 | From a challenge screen: 23 | 24 | These instructions assume you have enrolled in a game, started a session, and started a challenge. 25 | 26 | 1. In the *started* challenge, scroll to the bottom of the challenge instructions. 27 | 2. Click **Create Ticket**. Notice that the challenge is automatically populated in the **Challenge** field. 28 | 3. In the **Summary**, enter a brief statement of the problem. 29 | 4. In the **Description**, enter a more detailed statement of your problem. Include error messages and other pertinent details. 30 | 5. Under **Attachments**, attach files (especially screen shots) here. 31 | 6. Click **Submit**. Because you are coming from the challenge screen, a link to the game lobby is generated and Support Code is provided. 32 | 33 | ### Finding an Existing Ticket 34 | 35 | From the Support page, use the dropdowns and the **Search** field to locate specific tickets from *all* of the tickets you have submitted. 36 | 37 | Filter tickets by status: 38 | 39 | - Any Status 40 | - Open 41 | - In Progress 42 | - Not Closed (*Open* plus *In Progress*) 43 | - Closed 44 | 45 | Search by entering terms. Search covers ticket description, label, user, challenge title, and player. 46 | 47 | ## Support from the Support Role Point-of-View 48 | 49 | This section is meant for "support staff" - the people who are tasked with resolving customer service and technical support issues during a game. When we say "support staff" in the documentation, we mean those users given the `Support` role or a role that permits them to edit support settings, manage tickets, and view tickets such as `Admin` and `Director`. 50 | 51 | ### Creating New support Ticket (Support Staff) 52 | 53 | The procedure for support staff to create a tickets is very similar to procedure for participants to create a ticket (see above). However, after a ticket has been created users with the `Support` role have more options to manage the tickets. 54 | 55 | ### Managing Support Tickets 56 | 57 | From the Ticket management side-bar: 58 | 59 | **Assigned to:** Assign the ticket to another support person. The dropdown is filtered by users who have been granted the support role. 60 | 61 | **Status:** Move the ticket through the support workflow. Tickets are `Open`, `In progress`, or `Closed`. 62 | 63 | - **Open:** Indicates that ticket has been reported, but not yet acted upon by support staff. The ticket is "waiting" on an action. 64 | - **In progress:** The ticket is actively being worked on. 65 | - **Closed:** - The ticket has been resolved and no longer requires action from support or participants. 66 | 67 | **Labels:** Labels are tags or keywords used to categorize the ticket. A label is like a hashtag (#) used on Twitter, Facebook, and other social apps. Labels help when searching for an issue; labels also help when reporting on metrics from your competition. 68 | 69 | **Challenge:** When a ticket is associated with a challenge - meaning that the ticket was created from within the specific challenge - the challenge support code is shown here. If the challenge field is blank, you can view the challenge(s) the player is a part of in the Challenge dropdown. Attach the correct challenge from here. 70 | 71 | **Player:** When a ticket is associated with a challenge it is also linked to a team or player. If the challenge is a team challenge, then all of the members of the team can view the ticket. 72 | 73 | Add a **comment** to communicate with the participant. 74 | 75 | ### Copy to Markdown 76 | 77 | The **Copy to markdown** icon allows you to copy support ticket content to Markdown. You can paste it anywhere, including into a messaging app or email, with nicely formatted text, avoiding the need for links or logins to the Gameboard. 78 | 79 | ## Support-Related Reporting 80 | 81 | Support-related reporting provides you with a way to manage workloads and track trends during your competition. In the main menu, select **Reports**. Then click **Support** in the Reports screen. 82 | 83 | See [Using Reports](reports.md) for help understanding the Support reports. 84 | -------------------------------------------------------------------------------- /docs/index.md.bak: -------------------------------------------------------------------------------- 1 | # Crucible Framework 2 | 3 | Developed by Carnegie Mellon University's Software Engineering Institute (SEI), Crucible is a modular framework for creating, deploying, and managing virtual environments to support training, education, and exercises. Within the Crucible framework are the following applications and plugins. 4 | 5 | ## Core Applications 6 | 7 | ### Alloy 8 | 9 | Alloy joins the other independent Crucible apps together to provide a complete Crucible experience (i.e. labs, on-demand exercises, exercises, etc.). To get started with Alloy, see: 10 | - [Alloy API Repository](https://github.com/cmu-sei/Alloy.Api) 11 | - [Alloy UI Repository](https://github.com/cmu-sei/Alloy.ui) 12 | 13 | ### Caster 14 | 15 | Caster is the primary deployment component of the Crucible framework. Caster is built upon [Terraform](https://www.terraform.io/), an open source "Infrastructure as Code" tool. Caster provides a web interface that gives exercise developers a way to create, share, and manage topology configurations. To get started with Caster, see: 16 | - [Caster API Repository](https://github.com/cmu-sei/Caster.Api) 17 | - [Caster UI Repository](https://github.com/cmu-sei/Caster.Ui) 18 | 19 | ### Player 20 | 21 | Player is the centralized interface where users, teams, and administrators go to participate in the cyber exercise. To get started with the various components of Player, see: 22 | 23 | - [Player API Repository](https://github.com/cmu-sei/Player.Api) 24 | - [Player Console UI Repository](https://github.com/cmu-sei/Console.Ui) 25 | - [Player UI Repository](https://github.com/cmu-sei/Player.Ui) 26 | - [Player VM API Repository](https://github.com/cmu-sei/Vm.Api) 27 | - [Player VM UI Repository](https://github.com/cmu-sei/Vm.Ui) 28 | 29 | ### Steamfitter 30 | 31 | Steamfitter gives exercise developers the ability to create scenarios consisting of a series of scheduled tasks, manual tasks, and injects which run against virtual machines in an exercise. To get started with Steamfitter, see: 32 | 33 | - [Steamfitter API Repository](https://github.com/cmu-sei/Steamfitter.Api) 34 | - [Steamfitter UI Repository](https://github.com/cmu-sei/Steamfitter.Ui) 35 | 36 | Steamfitter relies upon [StackStorm](https://stackstorm.com/), an open source event-driven platform used to automate workflows, to execute commands. 37 | 38 | ## Crucible Appliance 39 | 40 | The Crucible appliance is an environment that includes everything needed to install and configure the core applications of the Crucible framework. The appliance application stack consists of a single-node Docker swarm utilizing a Traefik reverse proxy. They are assembled using Docker Compose files on an Ubuntu 20.04 operating system. To get started with the Crucible appliance, see: 41 | 42 | - [Crucible Appliance Repository](https://github.com/cmu-sei/Crucible.Appliance) 43 | 44 | ## Plugins 45 | 46 | ### Crucible Common Modules 47 | 48 | Crucible common modules are a set of Angular modules that are common between Crucible apps. For more information, see: 49 | - [Crucible Common Modules Repository](https://github.com/cmu-sei/Crucible.Common.Ui) 50 | 51 | ### Crucible plugin for Moodle 52 | 53 | The Crucible plugin for Moodle is an activity plugin that allows Crucible labs and exercises to be accessed from the Moodle open-source learning management system. For more information, see: 54 | 55 | - [Crucible plugin for Moodle Repository](https://github.com/cmu-sei/moodle-mod_crucible) 56 | 57 | ### osTicket 58 | 59 | osTicket (https://osticket.com/) is a widely-used open source support ticket system that can be configured and deployed for an exercise. To get started with the Crucible plugin for osTicket, see: 60 | - [osTicket Repository](https://github.com/cmu-sei/osticket-crucible) 61 | 62 | ### Terraform Provider for Crucible 63 | 64 | This is the [Terraform](https://www.terraform.io/) Provider for Crucible which is used to create many Crucible resource types (e.g., Player Virtual Machines, Views, Applications, and others). For more information, see: 65 | 66 | - [Terraform Provider Crucible Repository](https://github.com/cmu-sei/terraform-provider-crucible) 67 | 68 | ### Terraform Provider for Identity 69 | 70 | This is the [Terraform](https://www.terraform.io/) Provider for [Identity](https://github.com/cmu-sei/Identity) that creates and manages user accounts and other resources using the Identity API. For additional information, see: 71 | 72 | - [Terraform Provider Identity Repository](https://github.com/cmu-sei/terraform-provider-identity) 73 | 74 | ### Welder 75 | 76 | Welder is a simple application that can be added to an exercise; Welder allows users to dynamically load a VM workstation. To get started with Welder, see: 77 | - [Welder Repository](https://github.com/cmu-sei/Welder) 78 | 79 | ## Documentation 80 | 81 | You can find documentation on Crucible and all of its components [here](https://cmu-sei.github.io/crucible/). 82 | 83 | ## Reporting bugs and requesting features 84 | 85 | Think you found a bug? Please report all Crucible bugs - including bugs for the individual Crucible apps - in the [cmu-sei/crucible issue tracker](https://github.com/cmu-sei/crucible/issues). 86 | 87 | Include as much detail as possible including steps to reproduce, specific app involved, and any error messages you may have received. 88 | 89 | Have a good idea for a new feature? Submit all new feature requests through the [cmu-sei/crucible issue tracker](https://github.com/cmu-sei/crucible/issues). 90 | 91 | Include the reasons why you're requesting the new feature and how it might benefit other Crucible users. 92 | 93 | ## License 94 | 95 | Copyright 2021 Carnegie Mellon University. See the [LICENSE.md](https://github.com/cmu-sei/crucible/blob/master/license.md) file for details. -------------------------------------------------------------------------------- /docs/index.md.htmlbak: -------------------------------------------------------------------------------- 1 | --- 2 | template: home.html 3 | title: Crucible Simulation Framework 4 | --- 5 | -------------------------------------------------------------------------------- /docs/integrations/index.md: -------------------------------------------------------------------------------- 1 | # Third-Party Applications 2 | 3 | The Crucible Framework provides users the necessary tools and resources for integrating open-source third-party applications with the platform's features and data. By leveraging open-source resources, users can save time and resources, and benefit from the expertise of the open-source community. 4 | 5 | Additionally, the platform can be tailored to the user's needs by allowing administrators to add applications that will leverage and integrated with the necessary features needed for an exercise. This enables administrators to provide a more personalized experience with the platform and to use applications that are specifically designed to meet their unique needs. 6 | 7 | By allowing customization, the platform can become more valuable to users, as it can adapt to their evolving needs and preferences. This can lead to a more engaged user base and a more successful platform overall. 8 | 9 | ## Third-Party Integration Guide 10 | 11 | To be able to add third-party applications to the Crucible Framework, the user must have a System Admin permission. 12 | 13 | To integrate a third-party application to the Crucible Framework, follow these next steps: 14 | 15 |  16 | 17 | 1. Click your username in the top right corner of the screen. 18 | 2. Select **Administration**. 19 | 3. Click **Application Templates**. 20 | 4. Click **Add Application Template**. 21 | 5. Add the **Name** for the application. 22 | 6. Add the **Url** of the application. 23 | 7. Add an **icon path** to add the logo of the application. 24 | 8. If desired to be **Embeddable**, check the box. 25 | 9. If desired to be **Loaded in the Background**, check the box. 26 | 27 | After these steps, administrators should follow the Crucible Admin Guide to add the application to the desired set of users and/or teams. 28 | 29 | ## Third-Party Applications 30 | 31 | The following are third-party applications that have already been tested and used within the Crucible Framework. 32 | 33 | ### Mattermost 34 | 35 | Mattermost is an open-source, self-hostable online chat service with file sharing, search, and integrations. It is designed as an internal chat for organizations and companies. 36 | 37 | To know more about the application: [Mattermost Documentation](https://docs.mattermost.com) 38 | 39 | For installation instructions: [Mattermost Installation](https://github.com/cmu-sei/helm-charts/tree/main/charts/mattermost-team-edition) 40 | 41 | ### Moodle 42 | 43 | Moodle is a free and open-source learning management system. Moodle is used for blended learning, distance education, flipped classroom and other online learning projects in schools, universities, workplaces and other sectors. 44 | 45 | To know more about the application: [Moodle Documentation](https://docs.moodle.org/401/en/Main_page) 46 | 47 | For installation instructions: [Moodle Installation](https://docs.moodle.org/401/en/Installation_quick_guide) 48 | 49 | #### Crucible Plugin for Moodle 50 | 51 | This activity plugin allows Crucible labs and exercises to be integrated into the Moodle LMS. The Moodle activity can either embed the Crucible VM app in an iframe or link to open the full Crucible lab player in a new tab or window. With this plugin, Crucible labs can be started, accessed, and stopped from a Moodle course. 52 | 53 | To know more about the plugin and installation instructions: [Moodle Crucible Plugin Documentation](https://github.com/cmu-sei/moodle-mod_crucible) 54 | 55 | ### osTicket 56 | 57 | osTicket is a widely-used open source support ticket system. It seamlessly integrates inquiries created via email, phone and web-based forms into a simple easy-to-use multi-user web interface. Manage, organize and archive all your support requests and responses in one place while providing your customers with accountability and responsiveness they deserve. 58 | 59 | To know more about the application: [osTicket Documentation](https://docs.osticket.com/en/latest/) 60 | 61 | For installation instructions: [osTicket Installation](https://docs.osticket.com/en/latest/Getting%20Started/Installation.html) 62 | 63 | #### Crucible Plugin for osTicket 64 | 65 | A plugin, developed by the Software Engineering Institute (SEI), that provides authentication against an OAuth2 Identity Server and posts ticket event notifications to the Crucible API. 66 | 67 | For installation and configuration instructions: [osTicket Crucible Plugin](https://github.com/cmu-sei/osticket-crucible) 68 | 69 | ### Rocket.Chat 70 | 71 | Rocket.Chat is a customizable open-source communications platform for organizations with high data protection standards. It enables real-time conversations between colleagues, other companies, or your customers across web, desktop, or mobile devices. 72 | 73 | To know more about the application: [Rocket.Chat Documentation](https://docs.rocket.chat) 74 | 75 | For installation instructions: [Rocket.Chat Installation](https://github.com/RocketChat/helm-charts) 76 | 77 | ### Roundcube 78 | 79 | Roundcube is a web-based IMAP email client. It provides full functionality you expect from an email client, including MIME support, address book, folder manipulation, message searching and spell checking. 80 | 81 | To know more about the application: [Roundcube Documentation](https://docs.roundcube.net/doc/help/1.1/en_US/) 82 | 83 | For installation instructions: [Roundcube Installation](https://github.com/sei-npacheco/webmail) 84 | -------------------------------------------------------------------------------- /docs/stylesheets/extra.css.bak: -------------------------------------------------------------------------------- 1 | :root > * { 2 | --md-primary-fg-color: #CC002B; 3 | } -------------------------------------------------------------------------------- /docs/topomojo/about.md: -------------------------------------------------------------------------------- 1 | # TopoMojo Docs 2 | 3 | This documentation introduces users to the TopoMojo environment and provides information necessary to launch existing labs and create new topologies. 4 | 5 | ## About TopoMojo 6 | 7 | TopoMojo is a web application used for creating and delivering cybersecurity training labs and exercises. With TopoMojo, users can build and deploy labs in an isolated and secure virtual-machine environment. 8 | 9 | TopoMojo allows for the same functionality and connectivity that users would experience with real, physical devices. Network topologies can utilize not only IP and Ethernet, but also custom protocol solutions like 802.11 wireless packet simulation. 10 | 11 | New topologies can be rapidly deployed using existing templates or built from the ground up with user-provided ISO's and VM specifications. 12 | 13 | **Go to the TopoMojo repository:** [github.com/cmu-sei/TopoMojo](https://github.com/cmu-sei/TopoMojo). 14 | 15 | ## TopoMojo Concepts 16 | 17 | ### Workspace and Gamespace 18 | 19 | You build your content in a *workspace*, but you "play" (complete the lab, do the activity) in a *gamespace*. In the workspace, engineers and lab developers add VMs, save updates, author a guide in Markdown, and configure questions/answers to turn the topology into a lab or *challenge*. 20 | 21 | A *gamespace* is where someone else plays through the lab. They get their own, isolated, read-only copies of all workspace resources. Players in a gamespace can interact with VMs and answer questions to complete a lab, but they can't save anything in the environment. 22 | 23 | In short: a *gamespace* is a read-only copy of a *workspace* where a player (user) interacts with the lab content. 24 | 25 | ### Isolation Tag 26 | 27 | A unique identifier TopoMojo uses to identify a workspace or gamespace. 28 | 29 | - For a workspace: the *isolation tag* is the workspace id visible above the Workspace Title when viewing the workspace. See screen print 1. 30 | - For a gamespace: the *isolation tag* is the gamespace id partially visible from the **Admin**, **Gamespaces** view (see screen print 2) and fully visible in the URL bar when viewing a VM console that belongs to a gamespace (highlighted in screen print 3). 31 | 32 | The id's used for isolation tags uniquely identify each workspace and gamespace in the TopoMojo database. Additionally, each resource (e.g., virtual machine, virtual network, etc.) associated with a workspace or gamespace will have the isolation tag appended to the resource name. 33 | 34 | For example: a VM named `challenge-sever` in the gamespace with id (isolation tag) `18048abc66f142e1804732082f4051d2`, has the name `challenge-server#18048abc66f142e1804732082f4051d2`. Appending the isolation tag to workspace/gamespace resources ensures environment isolation -- VMs and networks cannot have the same name, so there will never be accidental sharing of VM/network resources. 35 | 36 | Screen print 1 37 | 38 |  39 | 40 | Screen print 2 41 | 42 |  43 | 44 | Screen print 3 45 | 46 |  47 | 48 | ### Challenge 49 | 50 | The term *challenge* refers to when users integrate Gameboard and TopoMojo to execute a cyber competition. In this scenario, Gameboard is a consumer of content made in TopoMojo. More information on that is available elsewhere in the documentation. 51 | -------------------------------------------------------------------------------- /docs/topomojo/admin-dashboard.md: -------------------------------------------------------------------------------- 1 | # Admin Features 2 | 3 | TopoMojo has an admin interface called **Admin Dashboard**. To access the Admin Dashboard, you'll need the `admin` role. In the top-right corner, click the **Admin** button. TopoMojo provides the initial `admin` role to the first user who authenticates successfully. 4 | 5 | ## Hub Connections 6 | 7 | **Hub connections** informs TopoMojo admins about which users are currently logged into TopoMojo. 8 | 9 | ## Announcement 10 | 11 | The **Announcement** feature allows TopoMojo admins to broadcast important messages to everyone in TopoMojo. Announcements appear in the TopoMojo interface. In the Message field, enter the content of the announcement and click **Send**. 12 | 13 | ## Import/Export 14 | 15 | This is future functionality for the TopoMojo UI. The API equivalent of import/export is available for use. 16 | 17 | ## Janitor 18 | 19 | The **Janitor** service cleans up unused resources (e.g., a workspace VM that has been idle for a long time) in TopoMojo. 20 | 21 | **Cleanup Report:** Provides a log of the Janitor's activity. 22 | -------------------------------------------------------------------------------- /docs/topomojo/admin-gamespaces.md: -------------------------------------------------------------------------------- 1 | # Admin Gamespaces 2 | 3 | The **Gamespaces** tab is where the admin can search for, and filter by, **active** and **inactive** gamespaces. By default, the search is for *active* gamespaces. Green indicates *active* gamespaces and gray indicates *inactive* gamespaces. 4 | 5 | **Refresh:** Refreshes your search. 6 | 7 | **Delete Selected:** Check the box next to **All** to select all gamespaces for deletion or check a box next to individual gamespaces to select for deletion. 8 | 9 | Gamespaces in the table show the following information: 10 | 11 | - Gamespace id or support code in Gameboard (e.g. `e9416013`) 12 | - Time remaining (if active) 13 | - User who is interacting with (or *had* interacted with) the gamespace 14 | - Title of the *workspace* that deployed the *gamespace* 15 | 16 | The screen print below shows several active and inactive gamespaces (usernames redacted). 17 | 18 |  19 | 20 | ## View (Expanded) 21 | 22 | **View:** Selecting **View** expands the gamespace information where a list of all the VMs associated with the gamespace and their state. 23 | 24 | - **refresh:** Refreshes the VM instance. 25 | - **console:** Allows you to interact with the VM (a user's gamespace). 26 | - **stop:** Stops a powered on VM. 27 | - **revert:** Reverts to last saved state. 28 | - **delete:** Deletes a running VM instance. 29 | - **JSON:** Shows detailed information about the gamespace, including: answers to questions, variables associated with the challenge, submitted answers, challenge questions and expected answers, and if the participant answered questions correctly or incorrectly. 30 | - **Dispatcher:** Used to issue commands to a VM from TopoMojo provided that the TopoMojo agent program is running on that VM. The VM requires an internet connection which allows the agent program to establish a connection with TopoMojo. `target` is the hostname of the VM that you want to run the command on. `command` is any command you wish to run. See TopoMojo's [GitHub repository](https://github.com/cmu-sei/TopoMojo/tree/main/src/TopoMojo.Agent) for more information on TopoMojo's agent. 31 | 32 | ## Delete 33 | 34 | **Delete:** As you would expect, deletes the gamespace and associated VMs. 35 | -------------------------------------------------------------------------------- /docs/topomojo/admin-log.md: -------------------------------------------------------------------------------- 1 | # Admin Dashboard Log Tab 2 | 3 | The **Log** tab is useful from the admin point of view when trying to troubleshoot. The Log tab only shows errors here, not every log line. 4 | -------------------------------------------------------------------------------- /docs/topomojo/admin-machines.md: -------------------------------------------------------------------------------- 1 | # Admin Machines 2 | 3 | This tab lists all VMs TopoMojo is tracking and the gamespaces they belong to, without using the vSphere Client. 4 | 5 |  6 | 7 | - `gamespace` tells you this is a *gamespace* VM. 8 | - `pc5-ubuntu-server-2204-594` is the name of the VM. 9 | - `#d9b090c92728424781537c66b3ee2f4b` after the hash tag is the gamespace GUID. 10 | 11 | The **Machines** tab is helpful when you want to find all the VMs related to a gamespace (e.g., `PC6 Stock Topology v1` in the screen print above). You can copy the gamespace GUID and paste it into the **Search** field. Note that you cannot interact with the VMs from this tab. 12 | 13 | ## "Orphaned" VMs 14 | 15 | VMs tagged with `__orphaned` are VMs that still exist; however, they are not connected to anything. TopoMojo may have attached these VMs to an expired gamespace, and when it tried to remove them vSphere failed to respond. Orphaned VMs should be manually deleted in vSphere. 16 | 17 | To identify orphaned VMs, search for "orphaned" in the Search field, identify the VMs to clean up in vSphere, and delete them. Once deleted in vSphere, they won't appear on the **Machines** tab again. 18 | -------------------------------------------------------------------------------- /docs/topomojo/admin-templates.md: -------------------------------------------------------------------------------- 1 | # Admin Templates 2 | 3 | The **Templates** tab is where you can view all of the templates that exist in TopoMojo. 4 | 5 | **Search:** Search for templates by workspace. Notice that you can apply filters here to further narrow down your search. In the screen print below, the filter is for linked VMs with a parent template of a VM called `kali-201901`. 6 | 7 |  8 | 9 | You can filter for specific workspaces here too. Clicking the *name* of the of the workspace takes you directly to the workspace. 10 | 11 | !!! note "Linked and unlinked templates" 12 | 13 | The chain link icon next to a template name indicates the VM is *linked*. Use linked VMs when the prebuilt, stock templates included with TopoMojo meet your needs. Linked VMs save resources when VMs don't require custom configurations when deployed. Changes can't be saved to linked VMs when deployed. Changes can only be saved to *unlinked* VMs. 14 | 15 | ## Template Properties 16 | 17 | **Name:** The VM name can't contain spaces; TopoMojo will replace spaces in a name with a `-`. 18 | 19 | **Description:** Not visible to users; use the *Description* in a way that meets your needs. For example, include VM credentials here. 20 | 21 | **Networks:** A space delimited list of network names. When TopoMojo deploys a VM, it will have *one* network interface for each of the named networks. TopoMojo creates networks on the hypervisor at VM-deploy time if they don't already exist. 22 | 23 | TopoMojo appends the isolation tag of the workspace/gamespace to network names to ensure network isolation. 24 | 25 | TopoMojo does not append the isolation tag to persistent/shared networks listed here; the VM connects to the existing shared/persistent network. 26 | 27 | For more information on *isolation tags*, see "Isolation tags" in [TopoMojo concepts](about.md/#isolation-tag). 28 | 29 | **Guest Settings:** List key value pairs in the form of `key=value` to pass data into deployed VMs via VMware guestinfo Variables. The **Guest Settings** field uses VMware Guest Info Variables to inject content into virtual machines. Place key/value pairs here. The *key* is the name of the guest variable you want to define, and the *value* is value, information, setting, of the variable. For example, `var1=test` is a guest setting named "var1" with a value of "test". 30 | 31 | **Replicas:** *Replicas* indicates how many copies of the VM get deployed in a gamespace. This will vary according to your needs. You may need two copies of the VM per gamespace or you may need 10. E.g.: two users are working a TopoMojo lab together; we want to set Replicas to `2` to ensure that each user has their own VM to work with. If set to `1`, then the two users could encroach on each other's work on the single VM. 32 | 33 | When deciding how many replicas you need, keep resources in mind. If, as in our example above, we only need two copies of the VM at any given time don't set Replicas to `5`. TopoMojo will deploy five, two will get used, and the other three won't get used. 34 | 35 | `-1`: Setting Replicas to `-1` means TopoMojo will deploy one VM template copy per user. If there are two users, then TopoMojo deploys two copies; if there are 10 users, then 10 copies. TopoMojo does not deploy extra VMs. Use this setting in conjunction with the Gameboard app, where Gameboard informs TopoMojo on how many copies to make based upon the Gameboard team size. 36 | 37 | The value set in **Replicas** only applies to the template you are editing; not every template in the workspace. So, if you want the same number of copies deployed in a gamespace for each template, you'll have to edit each template individually. 38 | -------------------------------------------------------------------------------- /docs/topomojo/admin-users.md: -------------------------------------------------------------------------------- 1 | # Admin Users 2 | 3 | The **Users** tab shows all current TopoMojo users. You can create new users here and assign them permissions. The **Search** feature allows TopoMojo admins to search on the name of a TopoMojo user. To search for a user across all of TopoMojo, enter the term into the **Search** field or filter by *role* or *audience*. 4 | 5 | Recall from workspace Settings that "audience" is a list of clients who can launch the workspace as a gamespace. Selecting an audience filter results in users who are part of that audience. 6 | 7 | **View:** Select **View** to see the properties for the user. 8 | 9 | **Delete:** Deletes the user. 10 | 11 | ## Roles 12 | 13 | All permissions are *additive*; meaning a Creator can do everything a Builder can do and an Observer can do everything a Builder and Creator can do. 14 | 15 | - **Admin:** Highest level of permission in TopoMojo; can do everything the other roles can do. 16 | - **Observer:** Allows a user to view and use the Gamespaces tab. However, the *scope* of the user (see below) limits access too. An observer can deploy gamespaces with a matching *audience* and these are the only gamespaces the user can observe. 17 | - **Creator:** Can have as many workspaces and templates as wanted. 18 | - **Builder:** Can connect to bridge-net. 19 | - **User:** No extra permissions in TopoMojo. This is the TopoMojo default. 20 | - **Disabled:** No permissions in TopoMojo. 21 | 22 | ## Create a New User 23 | 24 | **Name:** Enter a new user name here. 25 | 26 | **Scope:** A space-delimited list of administrator-defined groups the user belongs to. Administrators can define a *scope* with any name here. A user's scope determines which workspaces they have permission to deploy gamespaces from. Users can only deploy a gamespace from a workspace if the user has a *scope* that matches an *audience* defined in the workspace. See also: [Building a new workspace](building-a-workspace.md). 27 | 28 | **Workspace Limit:** The maximum number of workspaces this user can manage. 29 | 30 | **Gamespace Limit:** The maximum number of concurrent gamespaces allowed for this user. 31 | 32 | **Gamespace Max Duration:** The maximum amount of minutes allowed for a gamespace. 33 | 34 | **Gamespace Cleanup Grace time:** The number of "grace" minutes between the time the gamespace expires and when TopoMojo tears it down. 35 | 36 | **Generate ApiKey:** Generate API keys here. This allows users to programmatically interact with the TopoMojo API without needing to log in. 37 | -------------------------------------------------------------------------------- /docs/topomojo/admin-workspaces.md: -------------------------------------------------------------------------------- 1 | # Admin Workspaces 2 | 3 | The **Workspaces** tab is where the admin can search for workspaces and perform limited actions. Workspaces are where you build challenges and labs. Here, an admin can view every workspace. 4 | 5 | !!! note 6 | 7 | Only users who are admins can view the list of workspaces on the Admin panel. Non-admin users will use the search feature on the left navigation pane. 8 | 9 | In the left navigation pane, you can use the **Search** field to locate a workspace. However, searching here only returns workspaces you created or workspaces others invited you to join. 10 | 11 | **Create:** Create a new workspace from the Admin Workspaces panel. For additional help, see [Building a new workspace](building-a-workspace.md). 12 | 13 | Selecting a workspace takes you the **Settings** tab of that particular workspace where you can edit it. For additional help on the **Settings** tab, see [Building a new workspace](building-a-workspace.md). 14 | 15 | The *workspace identifier* is present here too. The workspace identifier matches the directory name used to store workspace files like unlinked virtual machines, Markdown documents, images, etc. Copying it to the clipboard is useful if you need to use it in a terminal when navigating the filesystem. 16 | 17 |  18 | 19 | ## View (Expanded) 20 | 21 | **Template Limit:** Defines the number of VMs that can be in the workspace. 22 | 23 | **Template Scope:** Limits a workspace to using templates that have the given scope. 24 | 25 | **Audience:** Limits who can deploy a gamespace as a workspace. 26 | 27 | **VMs:** Refresh, deploy, view the console, start/stop, revert and delete from here. 28 | - **Refresh**: Queries the state of the VM from the hypervisor. 29 | - **Deploy**: Deploys that virtual machine into your workspace. 30 | - **Console:** Opens the console for the virtual machine. 31 | - **Stop/Start:** Power off/on the VM, but leaves the resource deployed on the hypervisor. Clicking **stop** results in the hypervisor showing a deployed VM in a powered-off state. Clicking **start** powers on the deployed VM. 32 | - **Revert:** Reverts the VM to its last saved state. You will lose all changes made since the last commit. 33 | - **Delete:** Deletes a running VM instance. 34 | -------------------------------------------------------------------------------- /docs/topomojo/challenge.md: -------------------------------------------------------------------------------- 1 | # Challenge Tab 2 | 3 | The *Challenge* tab in the TopoMojo workspace is where event organizers integrate Gameboard and TopoMojo to execute a cyber competition. Here, you create random key/values, embed them in a *gamespace* at deploy time, and ask questions and answers of competitors (players). 4 | 5 | ## Transforms 6 | 7 | **Transforms** allow you to define dynamic variables that TopoMojo generates based on certain criteria or types. Transforms are also a key/value pair definition –- the **key** is the name of your transform and the **value** is the type of the transform. The screen print below shows a transform named "token1" that will have a value of 8 random hexadecimal characters. 8 | 9 | *Screen print 1:* 10 | 11 |  12 | 13 | To access transforms, use the referenced "*double-pounder-key* (`##key##`)" notation. When TopoMojo deploys a gamespace, the engine generates the random values for all transforms, looks for double-pounder-keys, then replaces them with the randomly generated values for that deployment. 14 | 15 | Any of the sections on the Challenge tab (e.g., Transforms, Markdown, Questions, Answers) can contain *double-pounder-keys* that TopoMojo replaces with transform values at deploy time. You can also use transform *double-pounder-keys* in the *Guest Settings* field of a template to inject random variables into VM guest info variables when deploying a gamespace. (Transforms aren't generated when deploying workspace VMs, so the value of the variable will be the *double-pounder-key*.) 16 | 17 | The screen print below shows the Guest Settings of a VM template configured to use two guest info variables: `var1` and `token1`. `Var1` has a value of "test" and `token1` will have a random 8-character hexadecimal string assigned when TopoMojo deploys a gamespace. 18 | 19 | *Screen print 2:* 20 | 21 |  22 | 23 | Click [here](building-a-workspace.md/#template-field-definitions) to learn more about Guest Settings. 24 | 25 | ## Markdown 26 | 27 | The markdown you enter here gets appended to the gamespace document. 28 | 29 | ## Variants 30 | 31 | A *variant* describes a different version of a challenge. Variants can contain different ISO attachments, different virtual machines, and different questions and answers. Each time TopoMojo deploys a challenge, a variant is randomly selected for the deployment. For example, two competitors can attempt the same challenge, but one competitor may receive *variant #1* and the other competitor may receive *variant #2*. When creating a challenge using variants, make sure all variants test the same competitor skills at the same difficulty level. That is, variant #1 should test the same skills as variant #2 and one variant shouldn't be harder to solve than another variant. 32 | 33 | ## Question Set 34 | 35 | **Move Up, Move Down, Remove:** These functions are self-explanatory. Use them to position the question in the sequence of questions for that set or remove it. 36 | 37 | **Question:** Enter the question you expect the participant to answer here. Your question should be specific, so that there is only one correct answer. 38 | 39 | **Answer:** Enter the correct answer that the competitor must submit to earn a score. 40 | 41 | You will see these options when you select **Detail**. 42 | 43 | **Hidden:** Select **Hidden** to prevent the question from appearing when playing the challenge. Hidden questions do not appear when playing in TopoMojo or via Gameboard. 44 | 45 | **Grader:** Select the grading type here. The Grader determines if players submitted the correct answer to a question. Select one of four types: 46 | 47 | - `Match`: The submission must exactly match what is in the **Answer** field. Use this when there is exactly one possible answer to a question. 48 | - `MatchAny`: The submission must match one of the pipe-delimited answers in the **Answer** field. Use this when there is more than one possible answer to a question. 49 | - `MatchAll`: The submission must match all of the pipe-delimited answers in the **Answer** field. Use this for questions expecting a list of answers. 50 | - `MatchAlpha`: The submission must exactly match what is in the **Answer** field *after* the grader removes all non-alphanumeric characters. This is useful if the user might submit symbols that don't affect the validity of an answer. For example, `C:/Users` and `C:\Users` are both valid answers and the symbols (`/` vs `\`) don't matter. 51 | 52 | The Grader converts all answers and submissions to lowercase before comparing them to the expected answer. All four grader types are case-insensitive. 53 | 54 | ### Weight 55 | 56 | Weight is the percentage of total for this question. The value should be between `0 and 1` or `0 and 100`. The weights of all questions within the set must add up to 100% or one (1). TopoMojo calculates zero (`0`) values evenly. 57 | 58 | ### Example 59 | 60 | Providing an example answer helps players understand the required answer format. For instance, sometimes a file needs both the name and the extension, while other times only the name is necessary. 61 | -------------------------------------------------------------------------------- /docs/topomojo/copy-paste.md: -------------------------------------------------------------------------------- 1 | # Copy and Paste 2 | 3 | The procedures below show you how to: 4 | 5 | - Copy text from a local machine (an *out of game* computer) and paste it into an *in game* virtual machine 6 | - Copy text from a virtual machine and paste it into a local machine 7 | 8 | *The VM console cog icon:* 9 | 10 |  11 | 12 | ## From Local ("Out of Game") to "In Game" 13 | 14 | 1. On your local machine select, then copy, the content you want to place into a launched virtual machine. 15 | 2. In the VM console tab, select the cog icon (the **Tools**). Under **Clipboard** paste in the clip using right-click Paste or `ctrl+V`. 16 | 3. In the VM, select where you want the copied text to go (this can be a new file or an open application, etc.). 17 | 4. Under **Clipboard**, click **Paste**. This inserts the copied content into the virtual machine. 18 |  19 | 20 | ## From "In Game" to "Out of Game" 21 | 22 | 1. On the VM, select the content you would like to copy. Copy the content *first* to the VM's clipboard (right-click Copy or `ctrl+C`). 23 | 2. Once you've copied your text to the VM clipboard select the cog icon (the **Tools**), place your cursor in that clipboard, and click **Copy**. This transfers the VM clip to your local clipboard. 24 |  25 | 3. On your local machine, paste the copied text into an application using right-click Paste or `ctrl+V`. 26 | -------------------------------------------------------------------------------- /docs/topomojo/files.md: -------------------------------------------------------------------------------- 1 | # Files 2 | 3 | The **Files** page in the TopoMojo workspace allows you to upload files from your system to TopoMojo to include in your lab. You can use these files as ISOs to attach to VMs in the workspace. If your files aren't already in an ISO file format, TopoMojo wraps them in an ISO after upload. 4 | 5 | !!! note 6 | 7 | For ISO uploads to work, TopoMojo needs an NFS (Network File System) datastore presented to vSphere and TopoMojo must be able to access it. 8 | 9 | The **Files** tab in TopoMojo is where you upload ISO files to attach to virtual machines. Supply the ISO you want to attach to your VM. The ISO adds extra resources that the original VM might not include. ISO files are disk images TopoMojo mounts as virtual CD drives on the VM. You want to attach an ISO when you need additional software, datasets, or other resources. 10 | 11 | **Drag and Drop:** Admins drag their ISO file into the box on Files tab or browse to locate it on their own device. 12 | 13 | By default, the **Local** filter only displays ISOs available in the current workspace. 14 | 15 | When you upload an ISO file, TopoMojo creates a folder with *this* GUID--called out in green in screen print 1 below--in the folder name in the NFS datastore. TopoMojo puts your ISO in that folder. Only the current workspace, that is, *your* workspace has access to the ISO file. 16 | 17 | Screen print 1: GUID and Local filter applied 18 | 19 |  20 | 21 | When you remove the **Local** filter, you can see *all* of the ISOs in the global folder on the NFS data store. (The folder name will contain a GUID of all zeros.) These global ISOs are available to every workspace in TopoMojo. 22 | 23 | You can attach an ISO to a VM in the challenge workspace **Templates** tab. See "Adding and editing templates" in the [Building a new Workspace](building-a-workspace.md) chapter of this guide. When you select an ISO here, TopoMojo attaches the ISO to the VM upon its deployment. 24 | 25 | You can also attach an ISO to a VM using the workspace **Challenge** tab's **Variant Detail** function. This "dynamic ISO attachment" gives you the ability to attach a variant-specific ISO file to a template. You *must* specify a target(s) here. See also "Variants" in the [Challenge tab](challenge.md) chapter of this guide. 26 | -------------------------------------------------------------------------------- /docs/topomojo/finding-a-space.md: -------------------------------------------------------------------------------- 1 | # Finding a Space 2 | 3 | Once you're in TopoMojo, you can browse for existing TopoMojo workspaces and gamespaces. In the left panel (`Ctrl-L`) , enter terms into the **Search** field. TopoMojo automatically searches for a workspace or a gamespace that matches your terms. Click **workspace** or **gamespace** to filter results. TopoMojo sorts labs alphabetically by name. 4 | 5 | Select a gamespace, then click **Start**. You can "play" the lab now -- start by reading the instructions and launching a gamespace resource. You can end play by clicking **End**. You can invite others to play in your gamespace. Click **Invite** to copy an invitation link. Provide the other person(s) with the link. 6 | 7 |  8 | 9 | The timer counts down how much remaining time you have before the gamespace expires. 10 | -------------------------------------------------------------------------------- /docs/topomojo/getting-started.md: -------------------------------------------------------------------------------- 1 | # Getting Started 2 | 3 | ## What's New 4 | 5 | Get the latest TopoMojo source code and its accompanying release notes [here](https://github.com/cmu-sei/TopoMojo). 6 | 7 | ## Installing 8 | 9 | Installing TopoMojo is a matter of installing the Helm chart found [here](https://github.com/cmu-sei/helm-charts/tree/main/charts/topomojo) on the SEI's GitHub page. The CMU-SEI Helm charts repo is a public repository on GitHub for anyone to access and use. The TopoMojo chart contains two sub-charts: `topomojo-api` and `topomojo-ui`. The `api` and the `ui` are different apps and you should deploy them separately. 10 | 11 | !!! info 12 | 13 | This structure is consistent with the other Foundry apps: there is an `api` piece and a `ui` piece. 14 | 15 | **`TopoMojo values.yaml`:** Contains default configurations for the `api` and the `ui`. To deploy TopoMojo, configure the **`Values.yaml`** file according to your needs and `helm install` TopoMojo. 16 | 17 | ## Persistent/Shared Networks 18 | 19 | We recommend having a persistent/shared network available to all TopoMojo workspaces/gamespaces. The administrator defines a persistent/shared network at the time they deploy the TopoMojo API. 20 | 21 | For example, you could create a persistent/shared network that provides internet access to all TopoMojo VMs that specify the network name. `bridge-net` typically signifies bridging the traditionally isolated TopoMojo VM to the internet. 22 | 23 | Use the `Pod__Vlan__Reservations` environment variable to define the name of a persistent/shared network. See screen print 1 below. 24 | 25 | - `Pod__Vlan__Reservations__0__Id:` defines the vlan Id (from the hypervisor) that corresponds to the shared/persistent network. 26 | - `Pod__Vlan__Reservations__0__Name:` defines the name of the persistent/shared network. 27 | 28 | You can define more than one shared/persistent network by incrementing the variable name (`Pod__Vlan__Reservations__1__Id` and `Pod__Vlan__Reservations__1__Name`). To connect VMs to shared/persistent networks, users must have at least **Builder** permissions. 29 | 30 | !!! note "A note about bridge-net" 31 | 32 | "bridge-net" is not always reserved. It is reserved by the SEI because we configured it that way, and it is convenient to refer to in the TopoMojo documentation. 33 | 34 | *Screen print 1:* 35 | 36 |  37 | -------------------------------------------------------------------------------- /docs/topomojo/img/admin-gamespaces.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/admin-gamespaces.png -------------------------------------------------------------------------------- /docs/topomojo/img/admin-machine.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/admin-machine.png -------------------------------------------------------------------------------- /docs/topomojo/img/andrew-carnegie.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/andrew-carnegie.png -------------------------------------------------------------------------------- /docs/topomojo/img/bridge-net.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/bridge-net.png -------------------------------------------------------------------------------- /docs/topomojo/img/console-cog.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/console-cog.png -------------------------------------------------------------------------------- /docs/topomojo/img/console-copy.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/console-copy.png -------------------------------------------------------------------------------- /docs/topomojo/img/console-paste.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/console-paste.png -------------------------------------------------------------------------------- /docs/topomojo/img/end-invite-timer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/end-invite-timer.png -------------------------------------------------------------------------------- /docs/topomojo/img/guest-settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/guest-settings.png -------------------------------------------------------------------------------- /docs/topomojo/img/iso-drag.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/iso-drag.png -------------------------------------------------------------------------------- /docs/topomojo/img/iso-tag-gs.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/iso-tag-gs.png -------------------------------------------------------------------------------- /docs/topomojo/img/iso-tag-url.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/iso-tag-url.png -------------------------------------------------------------------------------- /docs/topomojo/img/iso-tag-ws.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/iso-tag-ws.png -------------------------------------------------------------------------------- /docs/topomojo/img/markdown-editor.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/markdown-editor.png -------------------------------------------------------------------------------- /docs/topomojo/img/markdown-preview.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/markdown-preview.png -------------------------------------------------------------------------------- /docs/topomojo/img/other-icons.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/other-icons.png -------------------------------------------------------------------------------- /docs/topomojo/img/refresh-deploy.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/refresh-deploy.png -------------------------------------------------------------------------------- /docs/topomojo/img/templates-edit.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/templates-edit.png -------------------------------------------------------------------------------- /docs/topomojo/img/templates-filter.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/templates-filter.png -------------------------------------------------------------------------------- /docs/topomojo/img/templates-save.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/templates-save.png -------------------------------------------------------------------------------- /docs/topomojo/img/transforms.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/transforms.png -------------------------------------------------------------------------------- /docs/topomojo/img/vm-ware-tools.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/vm-ware-tools.png -------------------------------------------------------------------------------- /docs/topomojo/img/wksp-iden.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cmu-sei/crucible/1ad262cd8ee18fee66b56f46b87299e0ca0fd7b2/docs/topomojo/img/wksp-iden.png -------------------------------------------------------------------------------- /docs/topomojo/lab-document.md: -------------------------------------------------------------------------------- 1 | # Lab Document 2 | 3 | The **Document** tab in a TopoMojo workspace is where you write the instructions that correspond with your lab. You author instructions in Markdown using TopoMojo's built-in editor. Authoring in Markdown enables you to create a nicely formatted document without writing HTML. 4 | 5 | The TopoMojo editor is a collaborative editor. Multiple people can work on the documentation at the same time. As long as you are "connected" (see the top-right corner) TopoMojo saves your updates to the document. 6 | 7 | For more information about Markdown, including the syntax guide, see [markdownguide.org](https://www.markdownguide.org/). 8 | 9 | ## Inserting an Image 10 | 11 | To insert an image into your document: 12 | 13 | 1. Click **Images**, then click **Browse** (you can drag and drop too). 14 | 2. After browsing to upload an image, you should see a preview of the image. 15 | 3. Place your cursor in the document where you want the image, hover over the image, and click **Insert**. 16 | 17 | ## Previewing the Doc 18 | 19 | To see how your instructions will look to players when they "play" your lab, click the **Preview** button. The first screen capture shows the Markdown editor. The second screen capture shows the document in preview mode. 20 | 21 |  22 | 23 | and 24 | 25 |  26 | -------------------------------------------------------------------------------- /docs/topomojo/play.md: -------------------------------------------------------------------------------- 1 | # Play 2 | 3 | The **Play** page is where you can interact with your lab in the same way others will when they launch your content or "play" through your challenge. Play deploys a read-only copy of all virtual machines in the workspace; this gives the player their own deployed configurations. 4 | 5 | **Variant:** Specify which variant of the challenge you wish to play (if it is a *variant* challenge). 6 | 7 | **Max Attempts:** The maximum number of submission attempts allowed when answering questions. 8 | 9 | **Max Minutes:** The maximum number of minutes permitted to play before the gamespace expires. 10 | 11 | **Point Value:** The point value assigned for this challenge when used with Gameboard in a cyber competition scenario. 12 | 13 | **Start:** Starts up the gamespace which includes setting the timer, deploying virtual machines, displaying the Markdown document, and making challenge questions available. Individuals get their own Play tab, so when playing, the gamespace environment is unique to you. 14 | 15 | **Reset:** Resets the gamespace. 16 | -------------------------------------------------------------------------------- /material/overrides/main.html: -------------------------------------------------------------------------------- 1 | {% extends "base.html" %} 2 | 3 | 4 | {% block extrahead %} 5 | 6 | 7 | {% set title = config.site_name %} 8 | {% if page and page.title and not page.is_homepage %} 9 | {% set title = config.site_name ~ " - " ~ page.title | striptags %} 10 | {% endif %} 11 | 12 | 13 | {% set image = config.site_url ~ 'assets/images/illustrations/banner.png' %} 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 33 | {% endblock %} -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Crucible Documentation 2 | site_description: "CRUCIBLE is an open-source application framework for creating and managing virtual environments and events." 3 | site_author: "Crucible Team" 4 | copyright: > 5 | Copyright © 2024 Carnegie Mellon University. All rights reserved. 6 | extra_css: 7 | - stylesheets/extra.css 8 | theme: 9 | name: material 10 | custom_dir: material/overrides 11 | features: 12 | - navigation.tabs 13 | - navigation.tabs.sticky 14 | - navigation.sections 15 | - navigation.indexes 16 | - toc.integrate 17 | - content.code.copy 18 | - content.code.annotate 19 | logo: assets/img/crucible-icon-c-alpha.svg 20 | favicon: assets/img/crucible-icon-c-alpha.svg 21 | palette: 22 | # Palette toggle for light mode 23 | - scheme: default 24 | toggle: 25 | icon: material/brightness-7 26 | name: Switch to dark mode 27 | primary: red 28 | 29 | # Palette toggle for dark mode 30 | - scheme: slate 31 | toggle: 32 | icon: material/brightness-4 33 | name: Switch to light mode 34 | primary: red 35 | markdown_extensions: 36 | - pymdownx.highlight: 37 | anchor_linenums: true 38 | line_spans: __span 39 | pygments_lang_class: true 40 | - pymdownx.emoji: 41 | emoji_index: !!python/name:material.extensions.emoji.twemoji 42 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 43 | - pymdownx.inlinehilite 44 | - pymdownx.snippets 45 | - pymdownx.details 46 | - pymdownx.superfences 47 | - admonition 48 | - attr_list 49 | extra: 50 | features: 51 | - content.icons 52 | social: 53 | - icon: material/message-question 54 | link: https://github.com/cmu-sei/Crucible/issues/new?template=question.md 55 | name: Ask a Question 56 | - icon: fontawesome/solid/bug 57 | link: https://github.com/cmu-sei/crucible/issues/new?template=bug_report.md 58 | name: Report a Problem 59 | - icon: material/lightbulb-on 60 | link: https://github.com/cmu-sei/crucible/issues/new?template=feature_request.md 61 | name: Request a Feature 62 | - icon: fontawesome/regular/comments 63 | link: https://github.com/cmu-sei/crucible/discussions 64 | name: Community Discussions 65 | - icon: fontawesome/brands/github 66 | link: https://github.com/cmu-sei/crucible 67 | name: cmu-sei/Crucible on Github 68 | - icon: fontawesome/regular/envelope 69 | link: mailto:info@sei.cmu.edu?subject=Crucible%20Feedback 70 | name: Email Crucible Team 71 | - icon: fontawesome/solid/house 72 | link: https://www.sei.cmu.edu/ 73 | name: Software Engineering Institute 74 | nav: 75 | - Home: index.md 76 | - Player: player/index.md 77 | - Caster: caster/index.md 78 | - Steamfitter: steamfitter/index.md 79 | - Alloy: alloy/index.md 80 | - TopoMojo: 81 | - About: topomojo/about.md 82 | - Getting started with TopoMojo: topomojo/getting-started.md 83 | - Finding an existing space: topomojo/finding-a-space.md 84 | - Building a new space: 85 | - Settings and Templates: topomojo/building-a-workspace.md 86 | - Document: topomojo/lab-document.md 87 | - Challenge: topomojo/challenge.md 88 | - Files: topomojo/files.md 89 | - Play: topomojo/play.md 90 | - Admin features: 91 | - Admin Dashboard: topomojo/admin-dashboard.md 92 | - Gamespaces: topomojo/admin-gamespaces.md 93 | - Workspaces: topomojo/admin-workspaces.md 94 | - Templates: topomojo/admin-templates.md 95 | - Machines: topomojo/admin-machines.md 96 | - Users: topomojo/admin-users.md 97 | - Log: topomojo/admin-log.md 98 | - Copy and paste: topomojo/copy-paste.md 99 | - Gameboard: 100 | - Playing games: 101 | - About the Gameboard: gameboard/index.md 102 | - Profile screen: gameboard/profile.md 103 | - Home screen and Lobby: gameboard/home-and-lobby.md 104 | - Giving feedback: gameboard/player-feedback-form.md 105 | - Practicing challenges: gameboard/practice-area.md 106 | - Getting in-game support: gameboard/support.md 107 | - Using Reports: gameboard/reports.md 108 | - Administering games: 109 | - Administration: gameboard/admin.md 110 | - Game Center: gameboard/game-center.md 111 | - Practice Area: gameboard/admin-practice-area.md 112 | - Users: gameboard/admin-users.md 113 | - Players: gameboard/admin-players.md 114 | - Sponsors: gameboard/admin-sponsors.md 115 | - Challenges: gameboard/admin-challenges.md 116 | - Support: gameboard/admin-support.md 117 | - Notifications: gameboard/admin-notifications.md 118 | - Permissions: gameboard/admin-roles.md 119 | - Configuring Player Feedback Templates: gameboard/admin-feedback-form.md 120 | - Configuring Certificate Templates: gameboard/admin-completion-certificates.md 121 | - Blueprint: blueprint/index.md 122 | - CITE: cite/index.md 123 | - Gallery: gallery/index.md 124 | - Integrations: integrations/index.md 125 | - Overview Install: install/index.md 126 | repo_url: "https://github.com/cmu-sei/crucible" 127 | repo_name: "cmu-sei/Crucible" -------------------------------------------------------------------------------- /requirements.txt: -------------------------------------------------------------------------------- 1 | mkdocs-material 2 | Pygments 3 | pillow 4 | cairosvg 5 | vale 6 | --------------------------------------------------------------------------------