diff --git a/docs/gameboard/admin-clone-yaml-json.md b/docs/gameboard/admin-clone-yaml-json.md index 300a751..d96f6d7 100644 --- a/docs/gameboard/admin-clone-yaml-json.md +++ b/docs/gameboard/admin-clone-yaml-json.md @@ -1,3 +1,6 @@ +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). # Clone, yaml, and json options **Clone:** Creates a copy of the game that replicates most of the original game. diff --git a/docs/gameboard/admin-feedback-form.md b/docs/gameboard/admin-feedback-form.md index c73d5a6..c3a957d 100644 --- a/docs/gameboard/admin-feedback-form.md +++ b/docs/gameboard/admin-feedback-form.md @@ -1,158 +1,161 @@ -# Feedback Form - -In the Gameboard application, it is possible to create feedback forms to capture participant feedback on the game and individual challenges. Collecting and analyzing participant feedback can help you refine and improve your games and challenges. - -To create a feedback form, you must have the *Administrator* role in the Gameboard. For more information about roles, please see the [Gameboard Roles Guide](admin-roles.md). - -Creating a feedback form is not required to build a game or challenge. It is up to you whether or not you choose to implement it. If feedback is not configured in the gameboard administration section, then the feedback form does not appear for the participant. You can create questions for *just* a game, *just* challenges, or *both* game and challenges. See the "Configuration YAML" sections below for additional detail. - -## Creating feedback form for the game - -This documentation assumes that you have been granted the Administrator role in gameboard, you are logged in, and you have a game created. - -In the top-right corner, click **Admin**. - -Hover over an existing game, then click **Settings**. - -Scroll down to the **Feedback Questions** sections. If this is blank, then you will have to add your own YAML here. The YAML format has to be correct and there is some validation built in. - -**Feedback Questions** is blank when: - -- no defaults are set and a new game is created - -**Feedback Questions** is populated when: - -- some YAML has been saved from a previous session -- defaults have been established and a new game is created -- a game is cloned where original game contained save YAML - -!!! note - - When cloning a game, the feedback YAML will always be copied *exactly* from the original game, even if the game's feedback YAML is blank. In this instance, the default template is never used. - -If your questions are built correctly, you will see a message confirming this: - -`x game, y challenge questions configured` - -Where `x` and `y` are the numbers of questions in your YAML template. - -If your questions are not built correctly, you will see a message stating: - -`Invalid YAML format` - -Invalid YAML format prevents the feedback form from appearing on a game or challenge to a participant. Invalid YAML format does not prevent saving the game. The game is saved - the gameboard functions as expected - however, it will look to participants as if no questions were configured. - -### Configuration YAML - -Review the following sample YAML for a *game* feedback form to understand the keys and their values. Notice in the example below there is `game:` but not `challenge:`. The feedback questions are for the game only; no questions appear for challenges. - -```yaml -# Default Template for Game and Challenge Feedback -message: This feedback is not monitored during competition. -game: -- id: q1 - prompt: Please rate the difficulty of this game. - shortName: Difficulty - type: likert - max: 10 - minLabel: Very Easy - maxLabel: Very Difficult - required: true -- id: q2 - prompt: What did you like about this game? - type: text -``` - -- **message:** in the example above, _message_ is a communication meant for the participants; here the message informs participants that the feedback form is not monitored by competition user support. They would need to seek technical support through other established channels. Message is configurable and can be left blank. If left blank, no message appears to the participants. -- **id:** *ids* must be unique within the `game` list or `challenge` list; i.e., game and challenge could each have a `q1` id. If ids in a single list are not unique, you are presented with a warning. The warning does not prevent saving the configuration and the feedback form is still visible to a participant. -- **prompt:** this is the question you want the participant to answer or the property you want them to rate. -- **shortName:** an abbreviated version of the prompt. `shortName` is optional, but is helpful for use in tables as the column header. Good examples are "Difficult" or "Quality". -- **type:** *likert* or *text*; if the type is Likert, then defining the scale (`max`, `minLabel`, `maxLabel`) of how much a participant can agree or disagree with your prompt is required. If the type is *text*, a participant is free to answer your prompt however they like. Text type questions have a 2,000 character limit. -- **max:** this is the upper extreme of your Likert scale; 10 is the recommended upper limit. Any integer greater than 1 will work, but a scale that goes past 10 may become unwieldy or awkward. -- **minLabel:** specify the labels for the extremes of your Likert scale; examples of the negative extreme might be "very easy", "strongly disagree", or "very dissatisfied". -- **maxLabel:** specify the labels for the extremes of your Likert scale; examples of the positive extreme might be " very difficult", "strongly agree", or "very satisfied". -- **required:** this key is optional; set `required` to `true` if you want to make your question required. - -## Creating feedback form for a challenge - -The procedure for creating challenge feedback questions is the same as creating game feedback questions, except that you specify `challenge` in the YAML template. Review the following sample YAML with *game* and *challenge* feedback questions specified. You could specify `challenge:` and omit `game:` here. In that case, no questions would appear for the game; just the challenges. - -You can't configure a unique set of questions for each challenge. Each challenge in a game gets the same questions as defined in the YAML template. So, `Challenge abc` gets the same set of questions as `Challenge xyz` provided that `Challenge abc` and `Challenge xyz` are attached to the same game. - -```yaml -# Default Template for Game and Challenge Feedback -message: This feedback is not monitored during competition. -game: -- id: q1 - prompt: Please rate the difficulty of this game. - shortName: Difficulty - type: likert - max: 10 - minLabel: Very Easy - maxLabel: Very Difficult - required: true -- id: q2 - prompt: Please rate the quality of this game. - shortName: Quality - type: likert - max: 5 - minLabel: Low Quality - maxLabel: High Quality -challenge: -- id: q1 - prompt: Please rate the difficulty of this challenge. - shortName: Difficulty - type: likert - max: 5 - minLabel: Low Quality - maxLabel: High Quality -- id: q2 - prompt: Please rate the quality of this challenge. - shortName: Quality - type: likert - max: 10 - minLabel: Very Easy - maxLabel: Very Difficult -``` - -## Changing questions mid-game - -It is possible to change these keys in the YAML question configuration at any point during a game: `prompt`, `shortName`, `minLabel`, and `maxLabel`. These keys are for display purposes, and the administrator should be able to fix a typo or a spelling error on the fly. - -Do not change these keys in the YAML question configuration during a game, especially if participants have already submitted feedback: question `id`, `type`, `max` (when `likert`), the order of questions, or the number of questions in the list. - -## Configuration settings - -**Defaults_FeedbackTemplateFile** is the file name/location in the app directory where the default yaml file is found. To configure the **Defaults_FeedbackTemplateFile**: - -1. Create a yaml file with the template that is desired to be the default of any new games. -2. Add that file to app files prior to deployment. -3. In `appsettings.conf` or via whatever method you choose to set environment variables, set **Defaults_FeedbackTemplateFile** as the file name of the new file (for example: `default-template.yaml`). - -### Additional notes - -Configuring default questions is completely optional and not required to have feedback working in a deployment. It is an additional feature to make things more efficient, especially in the case where it is likely all games will use the same or similar questions. It could also be used as an example of valid yaml with placeholder values that the creator needs to change like "prompt 1 here". - -If no defaults are set (i.e., there is no yaml file and no envar set), then any new game will have a blank text area to start from or to copy/paste something into. If there is a default question file provided, any new game is created with the contents of the default questions copied into the text area for yaml. - -Once a game is created, changing the feedback questions of a game does not change the original defaults of the app for any new games, and questions can be completely changed or removed. Finally, changing the default feedback question file after a game is created (this is only done at deployment) does not change the questions of any existing game as the YAML was copied and not linked to it anymore. - -## Reporting - -Viewing and exporting survey responses is also a function of the Administrator role. Assuming that you are logged into gameboard as an administrator, in the top-right corner, select **Admin**. Then click **Reports**, and **Feedback Reports**. - -To view *game* feedback, toggle **Game Feedback**, and select a game. Game feedback refers to feedback at the game level; it does not include challenge-specific feedback. - -- **Game Overview:** Provides some general metrics like the count of configured questions, types, and required and the number of responses **submitted**, **in progress**, and **not started**. **Not started** indicates participants who started a game and the survey was available to them, but they chose not to respond. -- **Question Summary:** Provides metrics for the numerical questions like **Average** (based upon submitted responses), **Lowest Rating**, **Highest Rating** and a count of questions answered. All aggregates are based on submitted only, even min and max which are "Lowest Rating" and "Highest Rating". -- **Export to CSV (summary):** Allows you to export summary statistics per question as a comma-separated values file. From here, you can perform more detailed analysis. -- **Individual Submissions:** Provides a list of questions and answers by player. - - **Export to CSV (submission):** Allows you to export submitted feedback report results as a comma-separated values file. From here, you can perform more detailed analysis. Each row is a single user's response. The number of columns depends on the number of questions configured. - -To view *challenge* feedback, toggle **Challenge Feedback**, then select a game and a challenge. Selecting **All Challenges** here aggregates the feedback for all challenges for a particular game. - -- **Challenge Overview:** Provides some general metrics like the count of configured questions, types, and required versus the number of responses **submitted**, **in progress**, and **not started**. **Not started** indicates participants who started a challenge and the survey was available to them, but they chose not to respond. -- **Question Summary:** Provides metrics for the numerical questions like **Average** (based upon submitted responses), **Lowest Rating**, **Highest Rating** and a count of questions answered. - - **Export to CSV (summary):** Allows you to export summary statistics per question as a comma-separated values file. From here, you can perform more detailed analysis. -- **Individual Submissions:** Provides a list of questions and answers by player. +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Feedback Form + +In the Gameboard application, it is possible to create feedback forms to capture participant feedback on the game and individual challenges. Collecting and analyzing participant feedback can help you refine and improve your games and challenges. + +To create a feedback form, you must have the *Administrator* role in the Gameboard. For more information about roles, please see the [Gameboard Roles Guide](admin-roles.md). + +Creating a feedback form is not required to build a game or challenge. It is up to you whether or not you choose to implement it. If feedback is not configured in the gameboard administration section, then the feedback form does not appear for the participant. You can create questions for *just* a game, *just* challenges, or *both* game and challenges. See the "Configuration YAML" sections below for additional detail. + +## Creating feedback form for the game + +This documentation assumes that you have been granted the Administrator role in gameboard, you are logged in, and you have a game created. + +In the top-right corner, click **Admin**. + +Hover over an existing game, then click **Settings**. + +Scroll down to the **Feedback Questions** sections. If this is blank, then you will have to add your own YAML here. The YAML format has to be correct and there is some validation built in. + +**Feedback Questions** is blank when: + +- no defaults are set and a new game is created + +**Feedback Questions** is populated when: + +- some YAML has been saved from a previous session +- defaults have been established and a new game is created +- a game is cloned where original game contained save YAML + +!!! note + + When cloning a game, the feedback YAML will always be copied *exactly* from the original game, even if the game's feedback YAML is blank. In this instance, the default template is never used. + +If your questions are built correctly, you will see a message confirming this: + +`x game, y challenge questions configured` + +Where `x` and `y` are the numbers of questions in your YAML template. + +If your questions are not built correctly, you will see a message stating: + +`Invalid YAML format` + +Invalid YAML format prevents the feedback form from appearing on a game or challenge to a participant. Invalid YAML format does not prevent saving the game. The game is saved - the gameboard functions as expected - however, it will look to participants as if no questions were configured. + +### Configuration YAML + +Review the following sample YAML for a *game* feedback form to understand the keys and their values. Notice in the example below there is `game:` but not `challenge:`. The feedback questions are for the game only; no questions appear for challenges. + +```yaml +# Default Template for Game and Challenge Feedback +message: This feedback is not monitored during competition. +game: +- id: q1 + prompt: Please rate the difficulty of this game. + shortName: Difficulty + type: likert + max: 10 + minLabel: Very Easy + maxLabel: Very Difficult + required: true +- id: q2 + prompt: What did you like about this game? + type: text +``` + +- **message:** in the example above, _message_ is a communication meant for the participants; here the message informs participants that the feedback form is not monitored by competition user support. They would need to seek technical support through other established channels. Message is configurable and can be left blank. If left blank, no message appears to the participants. +- **id:** *ids* must be unique within the `game` list or `challenge` list; i.e., game and challenge could each have a `q1` id. If ids in a single list are not unique, you are presented with a warning. The warning does not prevent saving the configuration and the feedback form is still visible to a participant. +- **prompt:** this is the question you want the participant to answer or the property you want them to rate. +- **shortName:** an abbreviated version of the prompt. `shortName` is optional, but is helpful for use in tables as the column header. Good examples are "Difficult" or "Quality". +- **type:** *likert* or *text*; if the type is Likert, then defining the scale (`max`, `minLabel`, `maxLabel`) of how much a participant can agree or disagree with your prompt is required. If the type is *text*, a participant is free to answer your prompt however they like. Text type questions have a 2,000 character limit. +- **max:** this is the upper extreme of your Likert scale; 10 is the recommended upper limit. Any integer greater than 1 will work, but a scale that goes past 10 may become unwieldy or awkward. +- **minLabel:** specify the labels for the extremes of your Likert scale; examples of the negative extreme might be "very easy", "strongly disagree", or "very dissatisfied". +- **maxLabel:** specify the labels for the extremes of your Likert scale; examples of the positive extreme might be " very difficult", "strongly agree", or "very satisfied". +- **required:** this key is optional; set `required` to `true` if you want to make your question required. + +## Creating feedback form for a challenge + +The procedure for creating challenge feedback questions is the same as creating game feedback questions, except that you specify `challenge` in the YAML template. Review the following sample YAML with *game* and *challenge* feedback questions specified. You could specify `challenge:` and omit `game:` here. In that case, no questions would appear for the game; just the challenges. + +You can't configure a unique set of questions for each challenge. Each challenge in a game gets the same questions as defined in the YAML template. So, `Challenge abc` gets the same set of questions as `Challenge xyz` provided that `Challenge abc` and `Challenge xyz` are attached to the same game. + +```yaml +# Default Template for Game and Challenge Feedback +message: This feedback is not monitored during competition. +game: +- id: q1 + prompt: Please rate the difficulty of this game. + shortName: Difficulty + type: likert + max: 10 + minLabel: Very Easy + maxLabel: Very Difficult + required: true +- id: q2 + prompt: Please rate the quality of this game. + shortName: Quality + type: likert + max: 5 + minLabel: Low Quality + maxLabel: High Quality +challenge: +- id: q1 + prompt: Please rate the difficulty of this challenge. + shortName: Difficulty + type: likert + max: 5 + minLabel: Low Quality + maxLabel: High Quality +- id: q2 + prompt: Please rate the quality of this challenge. + shortName: Quality + type: likert + max: 10 + minLabel: Very Easy + maxLabel: Very Difficult +``` + +## Changing questions mid-game + +It is possible to change these keys in the YAML question configuration at any point during a game: `prompt`, `shortName`, `minLabel`, and `maxLabel`. These keys are for display purposes, and the administrator should be able to fix a typo or a spelling error on the fly. + +Do not change these keys in the YAML question configuration during a game, especially if participants have already submitted feedback: question `id`, `type`, `max` (when `likert`), the order of questions, or the number of questions in the list. + +## Configuration settings + +**Defaults_FeedbackTemplateFile** is the file name/location in the app directory where the default yaml file is found. To configure the **Defaults_FeedbackTemplateFile**: + +1. Create a yaml file with the template that is desired to be the default of any new games. +2. Add that file to app files prior to deployment. +3. In `appsettings.conf` or via whatever method you choose to set environment variables, set **Defaults_FeedbackTemplateFile** as the file name of the new file (for example: `default-template.yaml`). + +### Additional notes + +Configuring default questions is completely optional and not required to have feedback working in a deployment. It is an additional feature to make things more efficient, especially in the case where it is likely all games will use the same or similar questions. It could also be used as an example of valid yaml with placeholder values that the creator needs to change like "prompt 1 here". + +If no defaults are set (i.e., there is no yaml file and no envar set), then any new game will have a blank text area to start from or to copy/paste something into. If there is a default question file provided, any new game is created with the contents of the default questions copied into the text area for yaml. + +Once a game is created, changing the feedback questions of a game does not change the original defaults of the app for any new games, and questions can be completely changed or removed. Finally, changing the default feedback question file after a game is created (this is only done at deployment) does not change the questions of any existing game as the YAML was copied and not linked to it anymore. + +## Reporting + +Viewing and exporting survey responses is also a function of the Administrator role. Assuming that you are logged into gameboard as an administrator, in the top-right corner, select **Admin**. Then click **Reports**, and **Feedback Reports**. + +To view *game* feedback, toggle **Game Feedback**, and select a game. Game feedback refers to feedback at the game level; it does not include challenge-specific feedback. + +- **Game Overview:** Provides some general metrics like the count of configured questions, types, and required and the number of responses **submitted**, **in progress**, and **not started**. **Not started** indicates participants who started a game and the survey was available to them, but they chose not to respond. +- **Question Summary:** Provides metrics for the numerical questions like **Average** (based upon submitted responses), **Lowest Rating**, **Highest Rating** and a count of questions answered. All aggregates are based on submitted only, even min and max which are "Lowest Rating" and "Highest Rating". +- **Export to CSV (summary):** Allows you to export summary statistics per question as a comma-separated values file. From here, you can perform more detailed analysis. +- **Individual Submissions:** Provides a list of questions and answers by player. + - **Export to CSV (submission):** Allows you to export submitted feedback report results as a comma-separated values file. From here, you can perform more detailed analysis. Each row is a single user's response. The number of columns depends on the number of questions configured. + +To view *challenge* feedback, toggle **Challenge Feedback**, then select a game and a challenge. Selecting **All Challenges** here aggregates the feedback for all challenges for a particular game. + +- **Challenge Overview:** Provides some general metrics like the count of configured questions, types, and required versus the number of responses **submitted**, **in progress**, and **not started**. **Not started** indicates participants who started a challenge and the survey was available to them, but they chose not to respond. +- **Question Summary:** Provides metrics for the numerical questions like **Average** (based upon submitted responses), **Lowest Rating**, **Highest Rating** and a count of questions answered. + - **Export to CSV (summary):** Allows you to export summary statistics per question as a comma-separated values file. From here, you can perform more detailed analysis. +- **Individual Submissions:** Provides a list of questions and answers by player. - **Export to CSV (submission):** Allows you to export submitted feedback report results as a comma-separated values file. From here, you can perform more detailed analysis. Each row is a single user's response. The number of columns depends on the number of questions configured. \ No newline at end of file diff --git a/docs/gameboard/admin-observe.md b/docs/gameboard/admin-observe.md index d9436fc..536bd20 100644 --- a/docs/gameboard/admin-observe.md +++ b/docs/gameboard/admin-observe.md @@ -1,37 +1,40 @@ -# Observe Mode - -Observe mode allows a game administrator with the correct role to see participant VMs during a particular game. Observers do not have the ability to interact with, or interfere with, the VM they are observing. - -You must have either Observer Role or Admin Role to use Observe mode. Assuming you have been granted the appropriate role in the Gameboard, select **Admin**. Hover your mouse over an active board, then click **Observe**. - -**Search:** The Search feature is relative to the screen you are viewing when performing the search. Searching on the Observe Challenges screen means you're searching that list of challenges for some criteria (name, challenge, tag, id). Searching on the Observe Players screen means you're searching that list of teams/players for some criteria (team name/player name, team id). - -Gameboard talks to TopoMojo to launch challenges and to provide the Observe interface. - -## Observe Challenges - -**Observe Challenges** is a list of all challenges for all players in one table for that game. The console grid for this contains all VMs for a challenge --- whether active or not. - -Under **Consoles**, select the grid icon to view active VMs in a grid view side-by-side according to player or team. Minimize and maximize the consoles within the grid as you observe. When the grid containing the consoles is open, the observe mode updates in real-time. - -Selecting the four-square icon allows you to view the consoles of another player or team. Multiple observers can be on the same VM. - -VM name (*win10-workstation*) and player display name (*Wolverine 3*) help observers identify the console they are viewing, especially if there are many players with many challenges. Click the **pop-out** icon to open the console in a new browser tab. - -![observe-pop-out](img/observe-pop-out.png) - -**Name:** Sort the consoles alphabetically by the Team/Player and then by challenge name. - -**Rank:** Sort the consoles by scoreboard rank. - -You can move a row to the top and "pin" it there to keep it in place. You can pin multiple rows at the top as well. This is useful when you are interested in following a certain few teams, players, or challenges. This is also useful after you have searched--you can pin results at the top where you can reference them frequently. - -![observe-pin](img/observe-pin.png) - -## Observe Players - -**Observe Players** is a list of all players/teams for the game. The list of players/teams matches the entries on the scoreboard and contains "live" sessions; that is, sessions that are started. The console grid is one rectangle per user on a team. Users may not be on a VM at all yet or two users could be looking at the same VM. - -In Observer mode, click the **Observe Players** link to follow a team or individual player. - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Observe Mode + +Observe mode allows a game administrator with the correct role to see participant VMs during a particular game. Observers do not have the ability to interact with, or interfere with, the VM they are observing. + +You must have either Observer Role or Admin Role to use Observe mode. Assuming you have been granted the appropriate role in the Gameboard, select **Admin**. Hover your mouse over an active board, then click **Observe**. + +**Search:** The Search feature is relative to the screen you are viewing when performing the search. Searching on the Observe Challenges screen means you're searching that list of challenges for some criteria (name, challenge, tag, id). Searching on the Observe Players screen means you're searching that list of teams/players for some criteria (team name/player name, team id). + +Gameboard talks to TopoMojo to launch challenges and to provide the Observe interface. + +## Observe Challenges + +**Observe Challenges** is a list of all challenges for all players in one table for that game. The console grid for this contains all VMs for a challenge --- whether active or not. + +Under **Consoles**, select the grid icon to view active VMs in a grid view side-by-side according to player or team. Minimize and maximize the consoles within the grid as you observe. When the grid containing the consoles is open, the observe mode updates in real-time. + +Selecting the four-square icon allows you to view the consoles of another player or team. Multiple observers can be on the same VM. + +VM name (*win10-workstation*) and player display name (*Wolverine 3*) help observers identify the console they are viewing, especially if there are many players with many challenges. Click the **pop-out** icon to open the console in a new browser tab. + +![observe-pop-out](img/observe-pop-out.png) + +**Name:** Sort the consoles alphabetically by the Team/Player and then by challenge name. + +**Rank:** Sort the consoles by scoreboard rank. + +You can move a row to the top and "pin" it there to keep it in place. You can pin multiple rows at the top as well. This is useful when you are interested in following a certain few teams, players, or challenges. This is also useful after you have searched--you can pin results at the top where you can reference them frequently. + +![observe-pin](img/observe-pin.png) + +## Observe Players + +**Observe Players** is a list of all players/teams for the game. The list of players/teams matches the entries on the scoreboard and contains "live" sessions; that is, sessions that are started. The console grid is one rectangle per user on a team. Users may not be on a VM at all yet or two users could be looking at the same VM. + +In Observer mode, click the **Observe Players** link to follow a team or individual player. + Other than the differences described above Observe Players functions the same as Observe Challenges. \ No newline at end of file diff --git a/docs/gameboard/admin-players.md b/docs/gameboard/admin-players.md index 9bdc2f5..c0e3ca2 100644 --- a/docs/gameboard/admin-players.md +++ b/docs/gameboard/admin-players.md @@ -1,3 +1,6 @@ +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). You must have the Admin Role to get to the Players screen in a game. Assuming you have been granted the appropriate role in the Gameboard, select **Admin**. Hover your mouse over an active game, then click **Players**. **Search:** The Search feature is relative to the screen you are viewing when performing the search. You can apply the following filters to your search results and take action(s). diff --git a/docs/gameboard/admin-practice-area.md b/docs/gameboard/admin-practice-area.md index 56f45a0..367e113 100644 --- a/docs/gameboard/admin-practice-area.md +++ b/docs/gameboard/admin-practice-area.md @@ -1,3 +1,6 @@ +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). # Admin Practice Area Gameboard administrators configure the global Practice Area context here. In the main navigation bar, click **Admin**, then **Practice Area**. diff --git a/docs/gameboard/admin-roles.md b/docs/gameboard/admin-roles.md index 8fb576d..bd639e5 100644 --- a/docs/gameboard/admin-roles.md +++ b/docs/gameboard/admin-roles.md @@ -1,66 +1,69 @@ -# Gameboard Roles - -The following is a list of roles in the gameboard. Note that these roles aren't additive -- they are independent. Therefore, each role has to be added individually and a single user can have multiple roles. Each assigned role only grants the privileges for that role. Roles do not inherit permissions from other roles. - -## Gameboard privileges by role - -The **Observer** role can: - -- Observe consoles - -The **Support** role can: - -- Use the integrated support feature - -The **Tester** role can: - -- Enroll in games outside of the execution period -- Play games outside of the execution period -- View hidden games - -The **Designer** role can: - -- Create, edit, and delete games - -The **Registrar** role can: - -- Manage enrollment and registration - -The **Director** role can: - -- Observe consoles -- Use the integrated support feature -- Enroll in games outside of the execution period -- Play games outside of the execution period -- View hidden games -- Create, edit, and delete games -- Manage enrollment and registration -- *Cannot* assign or remove roles - -The **Admin** role can: - -- Observe consoles -- Use the integrated support feature -- Enroll in games outside of the execution period (see *Enroll vs. Admin Enroll* below) -- Play games outside of the execution period -- View hidden games -- Create, edit, and delete games -- Manage enrollment and registration -- Assign and remove roles -- Awards points manually to a player and team - -## Enroll vs. Admin Enroll - -After logging into Gameboard, but before playing a game or completing a lab users have to *enroll* in the game lobby. Users log into Gameboard, select a game on the **Home** page, and **Enroll** and **confirm** to start the session. The Enroll button appears when the user has set a display name and a sponsoring organization in their Profile and registration for that game is "open" (open and close dates and times are defined in the Admin Game Settings). - -If a user is a *Registrar*, *Tester*, or *Admin*, then the **Admin Enroll** button appears next to the **Enroll** button. See the screen print below. - -**Admin Enroll** allows a user with elevated roles to bypass the restrictions of time for registration, but it does *not* allow the user to bypass display name and sponsoring organization requirements. Those still need to be set prior to game play. **Admin Enroll** is useful for testing, troubleshooting, and customer support purposes. - -!!! note - - If you do have access to the **Admin Enroll** button, it behaves *identically* to the standard **Enroll** button for you. If you can see both **Enroll** and **Admin Enroll**, it does not matter which button you select. - -*Enroll and Admin Enroll* - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Gameboard Roles + +The following is a list of roles in the gameboard. Note that these roles aren't additive -- they are independent. Therefore, each role has to be added individually and a single user can have multiple roles. Each assigned role only grants the privileges for that role. Roles do not inherit permissions from other roles. + +## Gameboard privileges by role + +The **Observer** role can: + +- Observe consoles + +The **Support** role can: + +- Use the integrated support feature + +The **Tester** role can: + +- Enroll in games outside of the execution period +- Play games outside of the execution period +- View hidden games + +The **Designer** role can: + +- Create, edit, and delete games + +The **Registrar** role can: + +- Manage enrollment and registration + +The **Director** role can: + +- Observe consoles +- Use the integrated support feature +- Enroll in games outside of the execution period +- Play games outside of the execution period +- View hidden games +- Create, edit, and delete games +- Manage enrollment and registration +- *Cannot* assign or remove roles + +The **Admin** role can: + +- Observe consoles +- Use the integrated support feature +- Enroll in games outside of the execution period (see *Enroll vs. Admin Enroll* below) +- Play games outside of the execution period +- View hidden games +- Create, edit, and delete games +- Manage enrollment and registration +- Assign and remove roles +- Awards points manually to a player and team + +## Enroll vs. Admin Enroll + +After logging into Gameboard, but before playing a game or completing a lab users have to *enroll* in the game lobby. Users log into Gameboard, select a game on the **Home** page, and **Enroll** and **confirm** to start the session. The Enroll button appears when the user has set a display name and a sponsoring organization in their Profile and registration for that game is "open" (open and close dates and times are defined in the Admin Game Settings). + +If a user is a *Registrar*, *Tester*, or *Admin*, then the **Admin Enroll** button appears next to the **Enroll** button. See the screen print below. + +**Admin Enroll** allows a user with elevated roles to bypass the restrictions of time for registration, but it does *not* allow the user to bypass display name and sponsoring organization requirements. Those still need to be set prior to game play. **Admin Enroll** is useful for testing, troubleshooting, and customer support purposes. + +!!! note + + If you do have access to the **Admin Enroll** button, it behaves *identically* to the standard **Enroll** button for you. If you can see both **Enroll** and **Admin Enroll**, it does not matter which button you select. + +*Enroll and Admin Enroll* + ![enroll vs. admin enroll](img/enroll-admin-enroll.png) \ No newline at end of file diff --git a/docs/gameboard/admin-settings.md b/docs/gameboard/admin-settings.md index 9f3fd85..bbb9572 100644 --- a/docs/gameboard/admin-settings.md +++ b/docs/gameboard/admin-settings.md @@ -1,148 +1,151 @@ -# Admin Game Settings - -You arrive at the **Admin Game Settings** by creating a new game or by editing an existing one. With the appropriate role granted to you, click **Admin** then either: - -- click **+ New Game** to create a new game, or -- hover over an existing game card and click **Settings** - -**Game id:** The game id is a unique string of alpha numeric characters displayed here and in the game URL. It is the primary key for a game in the database. The game id is automatically generated upon creating a new game and really only becomes important when an admin needs to investigate an issue in the database. - -## Metadata - -**Name:** The title of your game. Displayed in the game lobby and on the scoreboard. - -**Publish:** Toggle *Hidden* or *Visible* to make the game visible to players on the Home screen. - -!!! info - - When a game is hidden, a user with permissions that can view both hidden and visible games -- such as Designer or Tester -- will see the game card on the Home screen; however, the game card appears with an "eye-slash" icon to denote that it is hidden. - -**Key:** A short, unique key distinguishing *this* event. - -**Series:** The name of the series; perhaps the same event is run annually making it a *series*. - -**Track:** A course of action in your event. An event may have different categories for teams and individuals to compete in or an event may have an offensive skills track and defensive skills track. - -**Season:** A fixed time period for when a series occurred. The *series* describes the event---for example, a fictitious "Cyber Cup". The *season* is the iteration of that event---Cyber Cup: Season 1, Cyber Cup: Season 2, and Cyber Cup: Season 3. - -**Division:** The tier or level of the audience participating in the event. Is this for working professionals or just students? - -**Card Image:** Upload an image to become game tile or card to identify your game in the lobby. - -**Card Text Top:** Enter text that will appear superimposed on your card at the top. - -**Card Text Middle:** Enter text that will appear superimposed on your card in the middle. - -**Card Text Bottom:** Enter text that will appear superimposed on your card along the bottom. - -**Lobby Markdown:** Using Markdown enter any information you would like players to see when they enter the game lobby. For help with Markdown syntax, see this [Markdown Guide](https://www.markdownguide.org/). - -**Feedback Questions:** It's possible -- but not required -- to create questions to capture participant feedback on the game and individual challenges. Create your feedback questions here using Yaml. For help with the feedback feature, see the [Feedback Form documentation](admin-feedback-form.md). - -**About feedback templates:** This modal provides instructions for configuring questions presented to players after they complete a challenge or game. - -**Paste Example Configuration:** Pastes sample feedback configuration into the Feedback Questions field for you to modify and use for your own needs. - -**Certificate Template:** Design a certificate template here by entering HTML into the Certificate Template field. More information on certificates can be found in the [Playing in the Gameboard](participating.md) documentation under "The Profile screen" heading. For your convenience, selecting the **i** button displays instructions for designing a certificate that can dynamically display information related to a game, such as leaderboard rankings, player scores, and other details. - -## Modes - -**Player Mode:** Toggle to set the game to **Competition** or **Practice**. When at least *one* game is set to Practice in your environment, a link to Practice is visible in the top-right corner of gameboard for authenticated players. Players can click the Practice link and select a challenge start their practice session. - -**Require Synchronized Start:** Toggle on to require the game to have a synchronized start. When enabled, no player can start a session until *all* players have indicated that they are "ready to play" in the game lobby. Use this feature for games when you want all players to start at the same time and end at the same time. Synchronized start adheres to other gameboard settings: for example, team size minimum and maximum. - -!!! note - - The Admin Start feature bypasses the "ready to play" feature; that is, users assigned the `Admin` role can Admin Start regardless of whether all players have "readied up" or not. - -**Show On Homepage When In Practice Mode:** - -**Engine Mode:** Specify the game mode (Standard, External, Legacy Unity Games). In VM mode, the gameboard reaches out to TopoMojo to start the VMs. - -## Settings - -These settings pertain to registration, execution, and general game and challenge limitations. - -### Execution - -**Opens:** The date and the time that your game begins. - -**Closes:** The date and the time that your game ends. - -**Session Duration:** The duration of game session in minutes. Games are created with a default session time of 60 minutes. - -**Session Limit:** The maximum number of sessions -- a session is when a game is started and challenges can be deployed and solved -- per game. - -**Gamespace Limit:** The maximum number of concurrent "gamespaces" allowed. A *gamespace* is the virtual environment that participants use to compete in a challenge. The default value is 0; the value that you enter here is inherited by a newly created board. For example, if you set this value to 5 in the game, any board created will inherit the 5 concurrent gamespace setting. - -**Max Submissions:** The maximum number of solutions a participant can send to the grading server per challenge---whether that submission is correct, incorrect, or blank. Once the submission amount is reached, the competitor is locked out of further submissions for that challenge. - -**Allow Preview:** Toggle *Hidden* or *Visible* to allow participants to view a challenge and documentation prior to starting. You may want to prevent too much information from being given away before a challenge start. - -**Allow Reset:** Toggle *Forbidden* or *Allowed* to permit participants to restart their game and attempt challenges again. This option is generally allowed on a "practice" game since that game is meant to help users get their bearings on how a competition works; however, you may decide players will be forbidden to reset an "official" game. - -**Allow Late Starts:** Toggle *Forbidden* or *Allowed* to permit players to start within a session length of the execution period end. When toggled to allow, players whose session would end prematurely due to the execution window closing will be allowed to play; however, their session will be shortened to match the end of the game. - -**Allow Public Scoreboard Access:** Toggle *Forbidden* or *Allowed* to permit players to view the complete scoreboard after the game ends. Not that the scoreboard itself is public, but if toggled to forbid, players can't view detailed score information for competing players. - -### Registration - -Offering a different execution period from registration period is an option. This gives participants the opportunity to register for a period of time prior to round one of the competition getting underway. No need for a registration period for later rounds where a competitor would have had to qualify for the next round to even continue. - -**Opens:** The date and the time that your registration period begins. - -**Closes:** The date and the time that your registration period ends. - -**Team Size:** This is self-explanatory. A matching *minimum* and *maximum* of one means that the challenge is a single player challenge. That is, a "team" of one. In a true team tournament, two or more would probably be the minimum. - -**Team Sponsorship:** Toggle *Open* or *Required*. When required, members on a team must have the same sponsor. Team sponsors are chosen during enrollment. For more information on sponsors, see [Gameboard Administration](admin.md). - -**Registration Markdown:** Using Markdown enter any information you would like players to see when they register for the game. For help with Markdown syntax, see this [Markdown Guide](https://www.markdownguide.org/). - -## Challenges - -### Search - -Search for challenges on TopoMojo to place in the game. *Search* here is limited by *Audience* on the workspace Settings in TopoMojo. - -### Edit - -Selecting a challenge from the search results adds it to the Edit icon. - -#### Challenge Specs - -**Sync with Source:** Synchronizes the Gameboard challenge markdown guide with the TopoMojo challenge markdown guide so that the content is the same in both apps. - -**Support Key:** Assign a unique "key" here that gets appended to a TopoMojo gamespace id to help troubleshoot problems during competition. For example: `b28c7911 a03` --- **b28c7911** is the uniquely generated gamespace ID from TopoMojo; **a03** is the support key *manually* assigned here to a challenge. For more information on support keys, see [Gameboard Administration](admin.md). - -**Points:** Assign a point value to your challenge here. - -**Solution Guide URL:** Add links to challenge solution guides here for *practice mode* challenges. When added here, the link to the solution guide is available to players in the challenge instructions. Enabling **Show Solution Guide in Competitive Mode** permits the link to a solution guide to be available to players in a *competitive* game. - -**Disabled:** Check to disable this challenge in the game without removing it. Disabled challenges are unavailable to players, don't count toward scores, and are not deployed when an admin initiates deployment on a player’s behalf. Essentially, disabling a challenge removes the spec from the game without deleting any underlying data. - -**Hidden:** Hidden challenges can't be manually deployed by players and don't count toward scores. However, they are deployed when an admin initiates deployment on a player's behalf or if the game configured in External mode. The need for a hidden challenge is typically related to the implementation details of an externally hosted game and is not useful for the vast majority of games. - -**Remove This Challenge:** Removes the challenge from the game. - -##### Prereqs - -Prerequisites are for challenges that unlock other challenges. For example: Your game has two challenges tagged **c01** and **c02**. You want to force participants to score 500 points on c01 before c02 is unlocked for them to attempt. Challenge c02 will not be available to deploy until the prerequisite condition is met. Complete the fields so that `c02 requires 500 on c01`. - -##### Automatic Bonuses - -Gameboard can automatically award bonus points to teams and players based on the order in which they solve a challenge. For instance, the first team to solve a challenge can earn an extra 100 points, the second team 50 points, and so on. To configure this, use the YAML format specified below. - -**Paste this example configuration:** Click to paste the "hint" text contained in the textbox. This is a useful starting point for creating your own bonus structure YAML configuration. - -**Import this configuration:** When you have finished editing your YAML, click to commit it to Gameboard. - -### Map - -Here is where the visual representation of the game is arranged. Challenges are placed on the game map here. The challenges you selected appear as hotspots on the map. Drag them into position on the map. - -**Show Grid:** Each map has a grid. By selecting Show Grid, you can toggle displaying the grid. When enabled, the grid overlays the map image and makes it easier for you place your challenge hotspots. - -**Browse:** Select **Browse** to search for an image that will serve as a backdrop to your map. - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Admin Game Settings + +You arrive at the **Admin Game Settings** by creating a new game or by editing an existing one. With the appropriate role granted to you, click **Admin** then either: + +- click **+ New Game** to create a new game, or +- hover over an existing game card and click **Settings** + +**Game id:** The game id is a unique string of alpha numeric characters displayed here and in the game URL. It is the primary key for a game in the database. The game id is automatically generated upon creating a new game and really only becomes important when an admin needs to investigate an issue in the database. + +## Metadata + +**Name:** The title of your game. Displayed in the game lobby and on the scoreboard. + +**Publish:** Toggle *Hidden* or *Visible* to make the game visible to players on the Home screen. + +!!! info + + When a game is hidden, a user with permissions that can view both hidden and visible games -- such as Designer or Tester -- will see the game card on the Home screen; however, the game card appears with an "eye-slash" icon to denote that it is hidden. + +**Key:** A short, unique key distinguishing *this* event. + +**Series:** The name of the series; perhaps the same event is run annually making it a *series*. + +**Track:** A course of action in your event. An event may have different categories for teams and individuals to compete in or an event may have an offensive skills track and defensive skills track. + +**Season:** A fixed time period for when a series occurred. The *series* describes the event---for example, a fictitious "Cyber Cup". The *season* is the iteration of that event---Cyber Cup: Season 1, Cyber Cup: Season 2, and Cyber Cup: Season 3. + +**Division:** The tier or level of the audience participating in the event. Is this for working professionals or just students? + +**Card Image:** Upload an image to become game tile or card to identify your game in the lobby. + +**Card Text Top:** Enter text that will appear superimposed on your card at the top. + +**Card Text Middle:** Enter text that will appear superimposed on your card in the middle. + +**Card Text Bottom:** Enter text that will appear superimposed on your card along the bottom. + +**Lobby Markdown:** Using Markdown enter any information you would like players to see when they enter the game lobby. For help with Markdown syntax, see this [Markdown Guide](https://www.markdownguide.org/). + +**Feedback Questions:** It's possible -- but not required -- to create questions to capture participant feedback on the game and individual challenges. Create your feedback questions here using Yaml. For help with the feedback feature, see the [Feedback Form documentation](admin-feedback-form.md). + +**About feedback templates:** This modal provides instructions for configuring questions presented to players after they complete a challenge or game. + +**Paste Example Configuration:** Pastes sample feedback configuration into the Feedback Questions field for you to modify and use for your own needs. + +**Certificate Template:** Design a certificate template here by entering HTML into the Certificate Template field. More information on certificates can be found in the [Playing in the Gameboard](participating.md) documentation under "The Profile screen" heading. For your convenience, selecting the **i** button displays instructions for designing a certificate that can dynamically display information related to a game, such as leaderboard rankings, player scores, and other details. + +## Modes + +**Player Mode:** Toggle to set the game to **Competition** or **Practice**. When at least *one* game is set to Practice in your environment, a link to Practice is visible in the top-right corner of gameboard for authenticated players. Players can click the Practice link and select a challenge start their practice session. + +**Require Synchronized Start:** Toggle on to require the game to have a synchronized start. When enabled, no player can start a session until *all* players have indicated that they are "ready to play" in the game lobby. Use this feature for games when you want all players to start at the same time and end at the same time. Synchronized start adheres to other gameboard settings: for example, team size minimum and maximum. + +!!! note + + The Admin Start feature bypasses the "ready to play" feature; that is, users assigned the `Admin` role can Admin Start regardless of whether all players have "readied up" or not. + +**Show On Homepage When In Practice Mode:** + +**Engine Mode:** Specify the game mode (Standard, External, Legacy Unity Games). In VM mode, the gameboard reaches out to TopoMojo to start the VMs. + +## Settings + +These settings pertain to registration, execution, and general game and challenge limitations. + +### Execution + +**Opens:** The date and the time that your game begins. + +**Closes:** The date and the time that your game ends. + +**Session Duration:** The duration of game session in minutes. Games are created with a default session time of 60 minutes. + +**Session Limit:** The maximum number of sessions -- a session is when a game is started and challenges can be deployed and solved -- per game. + +**Gamespace Limit:** The maximum number of concurrent "gamespaces" allowed. A *gamespace* is the virtual environment that participants use to compete in a challenge. The default value is 0; the value that you enter here is inherited by a newly created board. For example, if you set this value to 5 in the game, any board created will inherit the 5 concurrent gamespace setting. + +**Max Submissions:** The maximum number of solutions a participant can send to the grading server per challenge---whether that submission is correct, incorrect, or blank. Once the submission amount is reached, the competitor is locked out of further submissions for that challenge. + +**Allow Preview:** Toggle *Hidden* or *Visible* to allow participants to view a challenge and documentation prior to starting. You may want to prevent too much information from being given away before a challenge start. + +**Allow Reset:** Toggle *Forbidden* or *Allowed* to permit participants to restart their game and attempt challenges again. This option is generally allowed on a "practice" game since that game is meant to help users get their bearings on how a competition works; however, you may decide players will be forbidden to reset an "official" game. + +**Allow Late Starts:** Toggle *Forbidden* or *Allowed* to permit players to start within a session length of the execution period end. When toggled to allow, players whose session would end prematurely due to the execution window closing will be allowed to play; however, their session will be shortened to match the end of the game. + +**Allow Public Scoreboard Access:** Toggle *Forbidden* or *Allowed* to permit players to view the complete scoreboard after the game ends. Not that the scoreboard itself is public, but if toggled to forbid, players can't view detailed score information for competing players. + +### Registration + +Offering a different execution period from registration period is an option. This gives participants the opportunity to register for a period of time prior to round one of the competition getting underway. No need for a registration period for later rounds where a competitor would have had to qualify for the next round to even continue. + +**Opens:** The date and the time that your registration period begins. + +**Closes:** The date and the time that your registration period ends. + +**Team Size:** This is self-explanatory. A matching *minimum* and *maximum* of one means that the challenge is a single player challenge. That is, a "team" of one. In a true team tournament, two or more would probably be the minimum. + +**Team Sponsorship:** Toggle *Open* or *Required*. When required, members on a team must have the same sponsor. Team sponsors are chosen during enrollment. For more information on sponsors, see [Gameboard Administration](admin.md). + +**Registration Markdown:** Using Markdown enter any information you would like players to see when they register for the game. For help with Markdown syntax, see this [Markdown Guide](https://www.markdownguide.org/). + +## Challenges + +### Search + +Search for challenges on TopoMojo to place in the game. *Search* here is limited by *Audience* on the workspace Settings in TopoMojo. + +### Edit + +Selecting a challenge from the search results adds it to the Edit icon. + +#### Challenge Specs + +**Sync with Source:** Synchronizes the Gameboard challenge markdown guide with the TopoMojo challenge markdown guide so that the content is the same in both apps. + +**Support Key:** Assign a unique "key" here that gets appended to a TopoMojo gamespace id to help troubleshoot problems during competition. For example: `b28c7911 a03` --- **b28c7911** is the uniquely generated gamespace ID from TopoMojo; **a03** is the support key *manually* assigned here to a challenge. For more information on support keys, see [Gameboard Administration](admin.md). + +**Points:** Assign a point value to your challenge here. + +**Solution Guide URL:** Add links to challenge solution guides here for *practice mode* challenges. When added here, the link to the solution guide is available to players in the challenge instructions. Enabling **Show Solution Guide in Competitive Mode** permits the link to a solution guide to be available to players in a *competitive* game. + +**Disabled:** Check to disable this challenge in the game without removing it. Disabled challenges are unavailable to players, don't count toward scores, and are not deployed when an admin initiates deployment on a player’s behalf. Essentially, disabling a challenge removes the spec from the game without deleting any underlying data. + +**Hidden:** Hidden challenges can't be manually deployed by players and don't count toward scores. However, they are deployed when an admin initiates deployment on a player's behalf or if the game configured in External mode. The need for a hidden challenge is typically related to the implementation details of an externally hosted game and is not useful for the vast majority of games. + +**Remove This Challenge:** Removes the challenge from the game. + +##### Prereqs + +Prerequisites are for challenges that unlock other challenges. For example: Your game has two challenges tagged **c01** and **c02**. You want to force participants to score 500 points on c01 before c02 is unlocked for them to attempt. Challenge c02 will not be available to deploy until the prerequisite condition is met. Complete the fields so that `c02 requires 500 on c01`. + +##### Automatic Bonuses + +Gameboard can automatically award bonus points to teams and players based on the order in which they solve a challenge. For instance, the first team to solve a challenge can earn an extra 100 points, the second team 50 points, and so on. To configure this, use the YAML format specified below. + +**Paste this example configuration:** Click to paste the "hint" text contained in the textbox. This is a useful starting point for creating your own bonus structure YAML configuration. + +**Import this configuration:** When you have finished editing your YAML, click to commit it to Gameboard. + +### Map + +Here is where the visual representation of the game is arranged. Challenges are placed on the game map here. The challenges you selected appear as hotspots on the map. Drag them into position on the map. + +**Show Grid:** Each map has a grid. By selecting Show Grid, you can toggle displaying the grid. When enabled, the grid overlays the map image and makes it easier for you place your challenge hotspots. + +**Browse:** Select **Browse** to search for an image that will serve as a backdrop to your map. + **Reset:** Removes the image from your map. Reset does not remove challenge hotspots. \ No newline at end of file diff --git a/docs/gameboard/admin.md b/docs/gameboard/admin.md index 64b1e26..a470384 100644 --- a/docs/gameboard/admin.md +++ b/docs/gameboard/admin.md @@ -1,138 +1,141 @@ -# Gameboard Administration - -The Admin function of Gameboard helps those with the admin role: - -- Create, clone, manage, and delete games and challenges -- Manage users -- Observe participants -- Enter sponsor information -- Run and export user, gameboard, challenge, and feedback reports -- Broadcast messages to all game participants - -After logging into the gameboard app with the appropriate role, click **Admin**. By default, you land on the **Games** tab. - -## Search - -This **Search** feature allows game administrators to search on name, season, track, etc., of the game tiles that appear here. - -## Toggle Cards and Table - -Toggle between the view of games displayed as game *cards* or rows in a *table*. - -## New Game - -Click **+ New Game** to create a new game, or import from YAML, or upload or drop a YAML file. - -## Game Card hover - -When games are toggled to display as *Cards*, you can hover over the game to see options. - -- **Players:** Refer to the help documentation on [Players](admin-players.md). Players on the game card are only players who have enrolled in that game. -- **Observe:** Refer to the help documentation on [Observe Mode](admin-observe.md). -- **Settings:** Refer to the help documentation on [Admin Game Settings](admin-settings.md). -- **Clone, yaml, and json:** Refer to the help documentation on [Clone, yaml, and json options](admin-clone-yaml-json.md). -- **Delete:** Deletes the game. - -## Administration tabs - -### Overview - -#### Live Stats - -The **Admin Overview** tab allows game administrators to click **Live Stats** (e.g., the number of *Active Competitive Challenges* deployed, the number of *Active Practice Challenges* deployed, etc.). *Registered Users* is not clickable at this time. - -#### Send Announcement - -The **Announcement** feature allows game administrators to broadcast important messages to all participants within a game. Among other uses, these could be messages regarding gameboard issues, challenge issues, and changes to logistics. - -In the Announcement field, enter the content of the announcement and click **Announce**. - -### Games (landing page) - -The **Games** tab is where you land when you click **Admin** in the menu. See the topics above: *Search*, *Toggle Cards and Table*, *New Game*, and *Game Card Hover*. - -### Practice Area - -See the help documentation on [Administering the Practice Area](admin-practice-area.md). - -### Users - -This is where users are assigned roles and participant names are approved or disapproved. In Gameboard, a *user* is a person. A user has a *Name*. - -To search for a user across the whole of Gameboard, enter a term into the **Search** field or filter by: - -- **Has Roles:** contains only those participants who have been granted additional roles (Observer, Tester, Designer, etc.) -- **Has Pending Name:** contains only those participants whose display names are pending approval or disapproval from an admin. -- **Has Disallowed Name:** contains only those participants whose display names have been disapproved by an admin. - -### Approving and disapproving requested display names - -After registering for a new account, participants must choose a default name for public display. Participants are expected to refrain from any names that are controversial in nature. Admins approve participant names before the names can appear on the scoreboard here. - -To approve a requested display name, click **Has Pending Name**. That gives you a list of participants waiting for display name approval. Find the user in the list, select **Approve** or **Disapprove**. - -In the screen capture below, Tom Bombadil is requesting a name change to "Treebeard." - -![admin-pending](img/admin-pending.png) - -If *approved*, the name moves from the **Has Pending Name** list. From the user's point of view, the *requested* display name becomes the display name. - -If *disapproved*, you can provide a reason (`disallowed`, `disallowed_pii`, `disallowed_unit`, etc.). The disallowed requested name moves from **Has Pending Name** to **Has Disallowed Name**. From the player's point of view in this instance the *requested* name remains Treebeard, the *approved* name remains Tom Bombadil, and the *display name status* is disallowed. - -### Players - -A *Player* is a person enrolled in a game. Like a user, a player also has a name. These names can be the same, or they can be different. For example, Tom Bombadil's user name can be `Treebeard`, but when Tom enrolls in a game, he wants his name to display on the scoreboard as `Bombadillo`, so he changes his **Game Display Name** in the game's lobby. - -Searching the "global" **Players** tab lists the first 200 players who match the search, or 200 arbitrary players until you refine the search terms. Players on this tab are *all* players across *all* games. - -Filter by player names pending approval or player names disallowed by a game admin. - -### Sponsors - -This is where admins define who the sponsors are and what logo to associate with each. To create a new sponsor: - -1. Click the **plus** sign, then upload a logo file. -2. Enter a sponsor **Name**. -3. Select a **Parent Sponsor** if appropriate. -4. Click **Save**. - -Sponsor logo files may be in any of the following formats: *.png, .jpeg, .jpg, .gif, .webp,* and *.svg*. Your new sponsor appears in the list of sponsors. You can **edit** and **delete** sponsors from the list. - -### Challenges - -The Challenges tab is largely for game admins to troubleshoot problems with challenges. - -**Search:** Search for specific teams, players, challenge ids, and tags. - -**Current:** *Active* challenges have a green dot next them. Active indicates a challenge has *not* yet been solved correctly, maximum submissions have *not* been attempted, or a session has *not* expired. A challenge is active until one of those three criteria are met; then, the challenge is over and *inactive*. When a challenge is inactive, it still counts towards total score, rank, cumulative time. - -A challenge is *current* and not *archived* because it has not been reset when the Reset Session button is clicked. - -**Archived:** When a participant clicks **Reset Session**, before the session is deleted, historical information from participant and challenge event is archived. This archived session information is available here for the game admin to access. - -**Submissions:** Displays a date and time stamp and the answers submitted by the player and stored in Gameboard. - -**Game Engine Audit:** Clicking **Audit from game engine?** queries the game engine (if you're using the Foundry stack, this is TopoMojo) to provide its list of submitted answers. The purpose of game engine audit is to compare Gameboard's record of submissions to the game engine's record of submissions. - -**Regrade:** Clicking **Regrade** has the gameboard check all submissions by a player against expected answers again. Regrade is used when a challenge has two possible answers or players submit in a format that is correct, but that was unexpected by game or challenge developers. When this happens, the TopoMojo workspace is updated manually to include the new correct answers. Then, the challenge is regraded and the player's score updated if a previously entered incorrect answer is now correct. - -### Support Settings - -**Greeting:** Text entered here appears as a banner on the Support page to provide any pertinent information related to competition customer support. Enter your customized message. The greeting supports Markdown formatting. - -### Notifications - -Use **Notifications** to post alerts to players. Upon login, players will see a banner for each notification created. Once a player dismisses a notification, they won't see it again. To create a new notification: - -1. Click **Create Notification**. -2. Enter a **Title**. -3. Enter the **Content** of the notification. The content supports Markdown formatting. -4. Optionally, set the **Availability dates**. Availability dates aren't required. When set, the notification is shown to players *after* the start date and *until* the end date. -5. Select a **Type**: General Info (blue), Warning (yellow), or Emergency (red). -6. Click **Save**. - -You can **edit** and **delete** notifications from the list. - -### Reports - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Gameboard Administration + +The Admin function of Gameboard helps those with the admin role: + +- Create, clone, manage, and delete games and challenges +- Manage users +- Observe participants +- Enter sponsor information +- Run and export user, gameboard, challenge, and feedback reports +- Broadcast messages to all game participants + +After logging into the gameboard app with the appropriate role, click **Admin**. By default, you land on the **Games** tab. + +## Search + +This **Search** feature allows game administrators to search on name, season, track, etc., of the game tiles that appear here. + +## Toggle Cards and Table + +Toggle between the view of games displayed as game *cards* or rows in a *table*. + +## New Game + +Click **+ New Game** to create a new game, or import from YAML, or upload or drop a YAML file. + +## Game Card hover + +When games are toggled to display as *Cards*, you can hover over the game to see options. + +- **Players:** Refer to the help documentation on [Players](admin-players.md). Players on the game card are only players who have enrolled in that game. +- **Observe:** Refer to the help documentation on [Observe Mode](admin-observe.md). +- **Settings:** Refer to the help documentation on [Admin Game Settings](admin-settings.md). +- **Clone, yaml, and json:** Refer to the help documentation on [Clone, yaml, and json options](admin-clone-yaml-json.md). +- **Delete:** Deletes the game. + +## Administration tabs + +### Overview + +#### Live Stats + +The **Admin Overview** tab allows game administrators to click **Live Stats** (e.g., the number of *Active Competitive Challenges* deployed, the number of *Active Practice Challenges* deployed, etc.). *Registered Users* is not clickable at this time. + +#### Send Announcement + +The **Announcement** feature allows game administrators to broadcast important messages to all participants within a game. Among other uses, these could be messages regarding gameboard issues, challenge issues, and changes to logistics. + +In the Announcement field, enter the content of the announcement and click **Announce**. + +### Games (landing page) + +The **Games** tab is where you land when you click **Admin** in the menu. See the topics above: *Search*, *Toggle Cards and Table*, *New Game*, and *Game Card Hover*. + +### Practice Area + +See the help documentation on [Administering the Practice Area](admin-practice-area.md). + +### Users + +This is where users are assigned roles and participant names are approved or disapproved. In Gameboard, a *user* is a person. A user has a *Name*. + +To search for a user across the whole of Gameboard, enter a term into the **Search** field or filter by: + +- **Has Roles:** contains only those participants who have been granted additional roles (Observer, Tester, Designer, etc.) +- **Has Pending Name:** contains only those participants whose display names are pending approval or disapproval from an admin. +- **Has Disallowed Name:** contains only those participants whose display names have been disapproved by an admin. + +### Approving and disapproving requested display names + +After registering for a new account, participants must choose a default name for public display. Participants are expected to refrain from any names that are controversial in nature. Admins approve participant names before the names can appear on the scoreboard here. + +To approve a requested display name, click **Has Pending Name**. That gives you a list of participants waiting for display name approval. Find the user in the list, select **Approve** or **Disapprove**. + +In the screen capture below, Tom Bombadil is requesting a name change to "Treebeard." + +![admin-pending](img/admin-pending.png) + +If *approved*, the name moves from the **Has Pending Name** list. From the user's point of view, the *requested* display name becomes the display name. + +If *disapproved*, you can provide a reason (`disallowed`, `disallowed_pii`, `disallowed_unit`, etc.). The disallowed requested name moves from **Has Pending Name** to **Has Disallowed Name**. From the player's point of view in this instance the *requested* name remains Treebeard, the *approved* name remains Tom Bombadil, and the *display name status* is disallowed. + +### Players + +A *Player* is a person enrolled in a game. Like a user, a player also has a name. These names can be the same, or they can be different. For example, Tom Bombadil's user name can be `Treebeard`, but when Tom enrolls in a game, he wants his name to display on the scoreboard as `Bombadillo`, so he changes his **Game Display Name** in the game's lobby. + +Searching the "global" **Players** tab lists the first 200 players who match the search, or 200 arbitrary players until you refine the search terms. Players on this tab are *all* players across *all* games. + +Filter by player names pending approval or player names disallowed by a game admin. + +### Sponsors + +This is where admins define who the sponsors are and what logo to associate with each. To create a new sponsor: + +1. Click the **plus** sign, then upload a logo file. +2. Enter a sponsor **Name**. +3. Select a **Parent Sponsor** if appropriate. +4. Click **Save**. + +Sponsor logo files may be in any of the following formats: *.png, .jpeg, .jpg, .gif, .webp,* and *.svg*. Your new sponsor appears in the list of sponsors. You can **edit** and **delete** sponsors from the list. + +### Challenges + +The Challenges tab is largely for game admins to troubleshoot problems with challenges. + +**Search:** Search for specific teams, players, challenge ids, and tags. + +**Current:** *Active* challenges have a green dot next them. Active indicates a challenge has *not* yet been solved correctly, maximum submissions have *not* been attempted, or a session has *not* expired. A challenge is active until one of those three criteria are met; then, the challenge is over and *inactive*. When a challenge is inactive, it still counts towards total score, rank, cumulative time. + +A challenge is *current* and not *archived* because it has not been reset when the Reset Session button is clicked. + +**Archived:** When a participant clicks **Reset Session**, before the session is deleted, historical information from participant and challenge event is archived. This archived session information is available here for the game admin to access. + +**Submissions:** Displays a date and time stamp and the answers submitted by the player and stored in Gameboard. + +**Game Engine Audit:** Clicking **Audit from game engine?** queries the game engine (if you're using the Foundry stack, this is TopoMojo) to provide its list of submitted answers. The purpose of game engine audit is to compare Gameboard's record of submissions to the game engine's record of submissions. + +**Regrade:** Clicking **Regrade** has the gameboard check all submissions by a player against expected answers again. Regrade is used when a challenge has two possible answers or players submit in a format that is correct, but that was unexpected by game or challenge developers. When this happens, the TopoMojo workspace is updated manually to include the new correct answers. Then, the challenge is regraded and the player's score updated if a previously entered incorrect answer is now correct. + +### Support Settings + +**Greeting:** Text entered here appears as a banner on the Support page to provide any pertinent information related to competition customer support. Enter your customized message. The greeting supports Markdown formatting. + +### Notifications + +Use **Notifications** to post alerts to players. Upon login, players will see a banner for each notification created. Once a player dismisses a notification, they won't see it again. To create a new notification: + +1. Click **Create Notification**. +2. Enter a **Title**. +3. Enter the **Content** of the notification. The content supports Markdown formatting. +4. Optionally, set the **Availability dates**. Availability dates aren't required. When set, the notification is shown to players *after* the start date and *until* the end date. +5. Select a **Type**: General Info (blue), Warning (yellow), or Emergency (red). +6. Click **Save**. + +You can **edit** and **delete** notifications from the list. + +### Reports + Use the Reports feature. See the [Reports](reports-beta.md) documentation for additional help. \ No newline at end of file diff --git a/docs/gameboard/completion-certificates.md b/docs/gameboard/completion-certificates.md index 65ac9b1..e5c012c 100644 --- a/docs/gameboard/completion-certificates.md +++ b/docs/gameboard/completion-certificates.md @@ -1,39 +1,42 @@ -# Completion Certificates - -Gameboard supports a convenient way for participants to view and print a certificate as proof that they participated in a game. Certificates are unique to the participant and specific to a game. - -To create a *certificate template*, you must have the *Administrator* role in the Gameboard. For more information about roles, please see the [Gameboard Roles Guide](C:\Users\rgreeder\OneDrive - Software Engineering Institute\Desktop\gameboard-docs). - -To generate and print a *certificate* of completion, you must be a participant in a game that is completed and the scoreboard is final. - -## Generating certificates as a player - -Upon completing a game, a player can view and print a customized certificate specific to a completed game. - -In the Gameboard, click **Home**. Under **Completed Games**, select a completed game card. - -Expand **Certificate** to view and print the certificate as a .PDF. The options to print the certificate are the same as printing any other .PDF. - -Players can view a list of past certificates from their gameboard Profile page too. In gameboard, click **Profile**. Then click **Certificates**. A table view of all game certificates is displayed. You can view and print the certificate as a .PDF from the table view. - -!!! info - - Certificates are not available during live games. - -## Configuring certificates as an administrator - -This section assumes that you have been granted the Administrator role in gameboard, you are logged in, and you have a game created. - -In the top-right corner, click **Admin**. - -Hover over an existing game, then click **Settings**. Under **Metadata**, see the **Certificate Template** field. Certificate Template holds default HTML that you can use to start your template. For help, toggle the `i` icon. - -Of course, you can substitute your own HTML to design the certificate template. - -There is an optional app configuration to specify an HTML filename to use as a site default for all new games. - -This allows an admin to copy in an HTML template for a game in the settings. - -### Cloning a game with a configured certificate template - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Completion Certificates + +Gameboard supports a convenient way for participants to view and print a certificate as proof that they participated in a game. Certificates are unique to the participant and specific to a game. + +To create a *certificate template*, you must have the *Administrator* role in the Gameboard. For more information about roles, please see the [Gameboard Roles Guide](C:\Users\rgreeder\OneDrive - Software Engineering Institute\Desktop\gameboard-docs). + +To generate and print a *certificate* of completion, you must be a participant in a game that is completed and the scoreboard is final. + +## Generating certificates as a player + +Upon completing a game, a player can view and print a customized certificate specific to a completed game. + +In the Gameboard, click **Home**. Under **Completed Games**, select a completed game card. + +Expand **Certificate** to view and print the certificate as a .PDF. The options to print the certificate are the same as printing any other .PDF. + +Players can view a list of past certificates from their gameboard Profile page too. In gameboard, click **Profile**. Then click **Certificates**. A table view of all game certificates is displayed. You can view and print the certificate as a .PDF from the table view. + +!!! info + + Certificates are not available during live games. + +## Configuring certificates as an administrator + +This section assumes that you have been granted the Administrator role in gameboard, you are logged in, and you have a game created. + +In the top-right corner, click **Admin**. + +Hover over an existing game, then click **Settings**. Under **Metadata**, see the **Certificate Template** field. Certificate Template holds default HTML that you can use to start your template. For help, toggle the `i` icon. + +Of course, you can substitute your own HTML to design the certificate template. + +There is an optional app configuration to specify an HTML filename to use as a site default for all new games. + +This allows an admin to copy in an HTML template for a game in the settings. + +### Cloning a game with a configured certificate template + When cloning a game, the HTML from the Certificate Template field will always be copied *exactly* from the original game, even when the Certificate Template field is blank. \ No newline at end of file diff --git a/docs/gameboard/game-center.md b/docs/gameboard/game-center.md index 2fa076c..dff3d24 100644 --- a/docs/gameboard/game-center.md +++ b/docs/gameboard/game-center.md @@ -1,171 +1,174 @@ -# Game Center [BETA] - -The **Game Center** is the game admin's one stop shop when administering a live game. The Game Center unifies various Gameboard administrative and support elements such as game and challenge settings, player information, live sessions, support tickets, observe mode, and more. - -To access the Game Center for a given game, click **Admin**, hover over a game card, and click **Game Center**. Users must have the `Admin` role to access a game center. - -In the Game Center header, game metadata and settings information is displayed, including: name, modes, series, season, track, and execution dates. - -## The Gear tab - -### Metadata - -**Name:** The title of your game. Displayed in the game lobby and on the scoreboard. - -**Publish:** Toggle *Hidden* or *Visible* to make the game visible to players on the Home screen. - -!!! info - - When a game is hidden, a user with permissions that can view both hidden and visible games -- such as Designer or Tester -- will see the game card on the Home screen; however, the game card appears with an "eye-slash" icon to denote that it is hidden. - -**Feature:** Toggle *Normal* or *Featured*. When *Featured*, the game appears under Featured Games at the top of the Gameboard home page. - -**Key:** A short, unique key distinguishing *this* event. - -**Series:** The name of the series; perhaps the same event is run annually making it a *series*. - -**Track:** A course of action in your event. An event may have different categories for teams and individuals to compete in or an event may have an offensive skills track and defensive skills track. - -**Season:** A fixed time period for when a series occurred. The *series* describes the event--for example, a fictitious "Cyber Cup". The *season* is the iteration of that event--Cyber Cup: Season 1, Cyber Cup: Season 2, and Cyber Cup: Season 3. - -**Division:** The tier or level of the audience participating in the event. Is this for working professionals or just students? - -**Card Image:** Upload an image to become game tile or card to identify your game in the lobby. - -**Card Text Top:** Enter text that will appear superimposed on your card at the top. - -**Card Text Middle:** Enter text that will appear superimposed on your card in the middle. - -**Card Text Bottom:** Enter text that will appear superimposed on your card along the bottom. - -**Lobby Markdown:** Using Markdown enter any information you would like players to see when they enter the game lobby. For help with Markdown syntax, see this [Markdown Guide](https://www.markdownguide.org/). - -**Feedback Questions:** It's possible -- but not required -- to create questions to capture participant feedback on the game and individual challenges. Create your feedback questions here using Yaml. For help with the feedback feature, see the [Feedback Form documentation](admin-feedback-form.md). - -**About feedback templates:** This modal provides instructions for configuring questions presented to players after they complete a challenge or game. - -**Paste Example Configuration:** Pastes sample feedback configuration into the Feedback Questions field for you to modify and use for your own needs. - -**Certificate Template:** Design a certificate template here by entering HTML into the Certificate Template field. More information on certificates can be found in the [Playing in the Gameboard](participating.md) documentation under "The Profile screen" heading. For your convenience, selecting the **i** button displays instructions for designing a certificate that can dynamically display information related to a game, such as leaderboard rankings, player scores, and other details. - -### Modes - -**Player Mode:** Toggle to set the game to **Competition** or **Practice**. When at least *one* game is set to Practice in your environment, a link to Practice is visible in the top-right corner of gameboard for authenticated players. Players can click the Practice link and select a challenge start their practice session. - -**Require Synchronized Start:** Toggle on to require the game to have a synchronized start. When enabled, no player can start a session until *all* players have indicated that they are "ready to play" in the game lobby. Use this feature for games when you want all players to start at the same time and end at the same time. Synchronized start adheres to other gameboard settings: for example, team size minimum and maximum. - -!!! note - - The Admin Start feature bypasses the "ready to play" feature; that is, users assigned the `Admin` role can Admin Start regardless of whether all players have "readied up" or not. - -**Show On Homepage When In Practice Mode:** Toggle *Yes* to make the game's game card visible on the home page even when the game is in Practice mode. - -**Engine Mode:** Specify the game mode (Standard, External, Legacy Unity Games). In VM mode, the gameboard reaches out to TopoMojo to start the VMs. - -### Settings - -These settings pertain to registration, execution, and general game and challenge limitations. - -#### Execution - -**Opens:** The date and the time that your game begins. - -**Closes:** The date and the time that your game ends. - -**Session Duration:** The duration of game session in minutes. Games are created with a default session time of 60 minutes. - -**Session Limit:** The maximum number of sessions -- a session is when a game is started and challenges can be deployed and solved -- per game. - -**Gamespace Limit:** The maximum number of concurrent "gamespaces" allowed. A *gamespace* is the virtual environment that participants use to compete in a challenge. The default value is 0; the value that you enter here is inherited by a newly created board. For example, if you set this value to 5 in the game, any board created will inherit the 5 concurrent gamespace setting. - -**Max Submissions:** The maximum number of solutions a participant can send to the grading server per challenge---whether that submission is correct, incorrect, or blank. Once the submission amount is reached, the competitor is locked out of further submissions for that challenge. - -**Allow Preview:** Toggle *Hidden* or *Visible* to allow participants to view a challenge and documentation prior to starting. You may want to prevent too much information from being given away before a challenge start. - -**Allow Reset:** Toggle *Forbidden* or *Allowed* to permit participants to restart their game and attempt challenges again. This option is generally allowed on a "practice" game since that game is meant to help users get their bearings on how a competition works; however, you may decide players will be forbidden to reset an "official" game. - -**Allow Late Starts:** Toggle *Forbidden* or *Allowed* to permit players to start within a session length of the execution period end. When toggled to allow, players whose session would end prematurely due to the execution window closing will be allowed to play; however, their session will be shortened to match the end of the game. - -**Allow Public Scoreboard Access:** Toggle *Forbidden* or *Allowed* to permit players to view the complete scoreboard after the game ends. Not that the scoreboard itself is public, but if toggled to forbid, players can't view detailed score information for competing players. - -#### Registration - -Offering a different execution period from registration period is an option. This gives participants the opportunity to register for a period of time prior to round one of the competition getting underway. No need for a registration period for later rounds where a competitor would have had to qualify for the next round to even continue. - -**Access:** *None* means players can't register themselves for a game. An administrator must add players to the game or advance players from another game. *Open* means players can register themselves within the specified registration period. - -**Opens:** The date and the time that your registration period begins. - -**Closes:** The date and the time that your registration period ends. - -**Team Size:** This is self-explanatory. A matching *minimum* and *maximum* of one means that the challenge is a single player challenge. That is, a "team" of one. In a true team tournament, two or more would probably be the minimum. - -**Team Sponsorship:** Toggle *Open* or *Required*. When required, members on a team must have the same sponsor. Team sponsors are chosen during enrollment. For more information on sponsors, see [Gameboard Administration](admin.md). - -**Registration Markdown:** Using Markdown enter any information you would like players to see when they register for the game. For help with Markdown syntax, see this [Markdown Guide](https://www.markdownguide.org/). - -## The Challenges tab - -### Search - -Search for challenges on TopoMojo to place in the game. *Search* here is limited by *Audience* on the workspace Settings in TopoMojo. - -### Edit - -Selecting a challenge from the search results adds it to the Edit icon. - -### Challenge Specs - -**Sync with Source:** Synchronizes the Gameboard challenge markdown guide with the TopoMojo challenge markdown guide so that the content is the same in both apps. - -**Support Key:** Assign a unique "key" here that gets appended to a TopoMojo gamespace id to help troubleshoot problems during competition. For example: `b28c7911 a03` -- **b28c7911** is the uniquely generated gamespace ID from TopoMojo; **a03** is the support key *manually* assigned here to a challenge. For more information on support keys, see [Gameboard Administration](admin.md). - -**Points:** Assign a point value to your challenge here. - -**Solution Guide URL:** Add links to challenge solution guides here for *practice mode* challenges. When added here, the link to the solution guide is available to players in the challenge instructions. Enabling **Show Solution Guide in Competitive Mode** permits the link to a solution guide to be available to players in a *competitive* game. - -**Disabled:** Check to disable this challenge in the game without removing it. Disabled challenges are unavailable to players, don't count toward scores, and are not deployed when an admin initiates deployment on a player’s behalf. Essentially, disabling a challenge removes the spec from the game without deleting any underlying data. - -**Hidden:** Hidden challenges can't be manually deployed by players and don't count toward scores. However, they are deployed when an admin initiates deployment on a player's behalf or if the game configured in External mode. The need for a hidden challenge is typically related to the implementation details of an externally hosted game and is not useful for the vast majority of games. - -**Remove This Challenge:** Removes the challenge from the game. - -#### Prereqs - -Prerequisites are for challenges that unlock other challenges. For example: Your game has two challenges tagged **c01** and **c02**. You want to force participants to score 500 points on c01 before c02 is unlocked for them to attempt. Challenge c02 will not be available to deploy until the prerequisite condition is met. Complete the fields so that `c02 requires 500 on c01`. - -#### Automatic Bonuses - -Gameboard can automatically award bonus points to teams and players based on the order in which they solve a challenge. For instance, the first team to solve a challenge can earn an extra 100 points, the second team 50 points, and so on. To configure this, use the YAML format provided in the Gameboard app. - -**Paste this example configuration:** Click to paste the "hint" text contained in the textbox. This is a useful starting point for creating your own bonus structure YAML configuration. - -**Import this configuration:** When you have finished editing your YAML, click to commit it to Gameboard. - -### Map - -Here is where the visual representation of the game is arranged. Challenges are placed on the game map here. The challenges you selected appear as hotspots on the map. Drag them into position on the map. - -**Show Grid:** Each map has a grid. By selecting Show Grid, you can toggle displaying the grid. When enabled, the grid overlays the map image and makes it easier for you place your challenge hotspots. - -**Browse:** Select **Browse** to search for an image that will serve as a backdrop to your map. - -**Reset:** Removes the image from your map. Reset does not remove challenge hotspots. - -## Teams/Players tab - -The **Teams/Players** tab contains the list of game players. If the game is a *team* game, then you will see the Teams tab. If the game is an *individual* game then you will see the Players tab. Select **Use legacy player list** to view the player list in traditional mode (as if you navigated to **Games**, then hovered over a game card and selected **Players**). - -Here you can search, see who advanced to the next game and who did not, who started, who is currently playing, who finished, and sort by rank, name, and time remaining. - -## Observe tab - -The observation functionality found here is the same observe capability documented here: [Observe Mode](admin-observe.md). - -## Tickets tab - -The support ticketing functionality found here is the same as the interface documented here: [Using the Integrated Support feature](support.md). However, the support tickets are constrained to the game you viewing. You can perform all of the usual support ticket actions here (filter, search, export tickets) except for creating a new ticket. - -## Scoreboard tab - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Game Center [BETA] + +The **Game Center** is the game admin's one stop shop when administering a live game. The Game Center unifies various Gameboard administrative and support elements such as game and challenge settings, player information, live sessions, support tickets, observe mode, and more. + +To access the Game Center for a given game, click **Admin**, hover over a game card, and click **Game Center**. Users must have the `Admin` role to access a game center. + +In the Game Center header, game metadata and settings information is displayed, including: name, modes, series, season, track, and execution dates. + +## The Gear tab + +### Metadata + +**Name:** The title of your game. Displayed in the game lobby and on the scoreboard. + +**Publish:** Toggle *Hidden* or *Visible* to make the game visible to players on the Home screen. + +!!! info + + When a game is hidden, a user with permissions that can view both hidden and visible games -- such as Designer or Tester -- will see the game card on the Home screen; however, the game card appears with an "eye-slash" icon to denote that it is hidden. + +**Feature:** Toggle *Normal* or *Featured*. When *Featured*, the game appears under Featured Games at the top of the Gameboard home page. + +**Key:** A short, unique key distinguishing *this* event. + +**Series:** The name of the series; perhaps the same event is run annually making it a *series*. + +**Track:** A course of action in your event. An event may have different categories for teams and individuals to compete in or an event may have an offensive skills track and defensive skills track. + +**Season:** A fixed time period for when a series occurred. The *series* describes the event--for example, a fictitious "Cyber Cup". The *season* is the iteration of that event--Cyber Cup: Season 1, Cyber Cup: Season 2, and Cyber Cup: Season 3. + +**Division:** The tier or level of the audience participating in the event. Is this for working professionals or just students? + +**Card Image:** Upload an image to become game tile or card to identify your game in the lobby. + +**Card Text Top:** Enter text that will appear superimposed on your card at the top. + +**Card Text Middle:** Enter text that will appear superimposed on your card in the middle. + +**Card Text Bottom:** Enter text that will appear superimposed on your card along the bottom. + +**Lobby Markdown:** Using Markdown enter any information you would like players to see when they enter the game lobby. For help with Markdown syntax, see this [Markdown Guide](https://www.markdownguide.org/). + +**Feedback Questions:** It's possible -- but not required -- to create questions to capture participant feedback on the game and individual challenges. Create your feedback questions here using Yaml. For help with the feedback feature, see the [Feedback Form documentation](admin-feedback-form.md). + +**About feedback templates:** This modal provides instructions for configuring questions presented to players after they complete a challenge or game. + +**Paste Example Configuration:** Pastes sample feedback configuration into the Feedback Questions field for you to modify and use for your own needs. + +**Certificate Template:** Design a certificate template here by entering HTML into the Certificate Template field. More information on certificates can be found in the [Playing in the Gameboard](participating.md) documentation under "The Profile screen" heading. For your convenience, selecting the **i** button displays instructions for designing a certificate that can dynamically display information related to a game, such as leaderboard rankings, player scores, and other details. + +### Modes + +**Player Mode:** Toggle to set the game to **Competition** or **Practice**. When at least *one* game is set to Practice in your environment, a link to Practice is visible in the top-right corner of gameboard for authenticated players. Players can click the Practice link and select a challenge start their practice session. + +**Require Synchronized Start:** Toggle on to require the game to have a synchronized start. When enabled, no player can start a session until *all* players have indicated that they are "ready to play" in the game lobby. Use this feature for games when you want all players to start at the same time and end at the same time. Synchronized start adheres to other gameboard settings: for example, team size minimum and maximum. + +!!! note + + The Admin Start feature bypasses the "ready to play" feature; that is, users assigned the `Admin` role can Admin Start regardless of whether all players have "readied up" or not. + +**Show On Homepage When In Practice Mode:** Toggle *Yes* to make the game's game card visible on the home page even when the game is in Practice mode. + +**Engine Mode:** Specify the game mode (Standard, External, Legacy Unity Games). In VM mode, the gameboard reaches out to TopoMojo to start the VMs. + +### Settings + +These settings pertain to registration, execution, and general game and challenge limitations. + +#### Execution + +**Opens:** The date and the time that your game begins. + +**Closes:** The date and the time that your game ends. + +**Session Duration:** The duration of game session in minutes. Games are created with a default session time of 60 minutes. + +**Session Limit:** The maximum number of sessions -- a session is when a game is started and challenges can be deployed and solved -- per game. + +**Gamespace Limit:** The maximum number of concurrent "gamespaces" allowed. A *gamespace* is the virtual environment that participants use to compete in a challenge. The default value is 0; the value that you enter here is inherited by a newly created board. For example, if you set this value to 5 in the game, any board created will inherit the 5 concurrent gamespace setting. + +**Max Submissions:** The maximum number of solutions a participant can send to the grading server per challenge---whether that submission is correct, incorrect, or blank. Once the submission amount is reached, the competitor is locked out of further submissions for that challenge. + +**Allow Preview:** Toggle *Hidden* or *Visible* to allow participants to view a challenge and documentation prior to starting. You may want to prevent too much information from being given away before a challenge start. + +**Allow Reset:** Toggle *Forbidden* or *Allowed* to permit participants to restart their game and attempt challenges again. This option is generally allowed on a "practice" game since that game is meant to help users get their bearings on how a competition works; however, you may decide players will be forbidden to reset an "official" game. + +**Allow Late Starts:** Toggle *Forbidden* or *Allowed* to permit players to start within a session length of the execution period end. When toggled to allow, players whose session would end prematurely due to the execution window closing will be allowed to play; however, their session will be shortened to match the end of the game. + +**Allow Public Scoreboard Access:** Toggle *Forbidden* or *Allowed* to permit players to view the complete scoreboard after the game ends. Not that the scoreboard itself is public, but if toggled to forbid, players can't view detailed score information for competing players. + +#### Registration + +Offering a different execution period from registration period is an option. This gives participants the opportunity to register for a period of time prior to round one of the competition getting underway. No need for a registration period for later rounds where a competitor would have had to qualify for the next round to even continue. + +**Access:** *None* means players can't register themselves for a game. An administrator must add players to the game or advance players from another game. *Open* means players can register themselves within the specified registration period. + +**Opens:** The date and the time that your registration period begins. + +**Closes:** The date and the time that your registration period ends. + +**Team Size:** This is self-explanatory. A matching *minimum* and *maximum* of one means that the challenge is a single player challenge. That is, a "team" of one. In a true team tournament, two or more would probably be the minimum. + +**Team Sponsorship:** Toggle *Open* or *Required*. When required, members on a team must have the same sponsor. Team sponsors are chosen during enrollment. For more information on sponsors, see [Gameboard Administration](admin.md). + +**Registration Markdown:** Using Markdown enter any information you would like players to see when they register for the game. For help with Markdown syntax, see this [Markdown Guide](https://www.markdownguide.org/). + +## The Challenges tab + +### Search + +Search for challenges on TopoMojo to place in the game. *Search* here is limited by *Audience* on the workspace Settings in TopoMojo. + +### Edit + +Selecting a challenge from the search results adds it to the Edit icon. + +### Challenge Specs + +**Sync with Source:** Synchronizes the Gameboard challenge markdown guide with the TopoMojo challenge markdown guide so that the content is the same in both apps. + +**Support Key:** Assign a unique "key" here that gets appended to a TopoMojo gamespace id to help troubleshoot problems during competition. For example: `b28c7911 a03` -- **b28c7911** is the uniquely generated gamespace ID from TopoMojo; **a03** is the support key *manually* assigned here to a challenge. For more information on support keys, see [Gameboard Administration](admin.md). + +**Points:** Assign a point value to your challenge here. + +**Solution Guide URL:** Add links to challenge solution guides here for *practice mode* challenges. When added here, the link to the solution guide is available to players in the challenge instructions. Enabling **Show Solution Guide in Competitive Mode** permits the link to a solution guide to be available to players in a *competitive* game. + +**Disabled:** Check to disable this challenge in the game without removing it. Disabled challenges are unavailable to players, don't count toward scores, and are not deployed when an admin initiates deployment on a player’s behalf. Essentially, disabling a challenge removes the spec from the game without deleting any underlying data. + +**Hidden:** Hidden challenges can't be manually deployed by players and don't count toward scores. However, they are deployed when an admin initiates deployment on a player's behalf or if the game configured in External mode. The need for a hidden challenge is typically related to the implementation details of an externally hosted game and is not useful for the vast majority of games. + +**Remove This Challenge:** Removes the challenge from the game. + +#### Prereqs + +Prerequisites are for challenges that unlock other challenges. For example: Your game has two challenges tagged **c01** and **c02**. You want to force participants to score 500 points on c01 before c02 is unlocked for them to attempt. Challenge c02 will not be available to deploy until the prerequisite condition is met. Complete the fields so that `c02 requires 500 on c01`. + +#### Automatic Bonuses + +Gameboard can automatically award bonus points to teams and players based on the order in which they solve a challenge. For instance, the first team to solve a challenge can earn an extra 100 points, the second team 50 points, and so on. To configure this, use the YAML format provided in the Gameboard app. + +**Paste this example configuration:** Click to paste the "hint" text contained in the textbox. This is a useful starting point for creating your own bonus structure YAML configuration. + +**Import this configuration:** When you have finished editing your YAML, click to commit it to Gameboard. + +### Map + +Here is where the visual representation of the game is arranged. Challenges are placed on the game map here. The challenges you selected appear as hotspots on the map. Drag them into position on the map. + +**Show Grid:** Each map has a grid. By selecting Show Grid, you can toggle displaying the grid. When enabled, the grid overlays the map image and makes it easier for you place your challenge hotspots. + +**Browse:** Select **Browse** to search for an image that will serve as a backdrop to your map. + +**Reset:** Removes the image from your map. Reset does not remove challenge hotspots. + +## Teams/Players tab + +The **Teams/Players** tab contains the list of game players. If the game is a *team* game, then you will see the Teams tab. If the game is an *individual* game then you will see the Players tab. Select **Use legacy player list** to view the player list in traditional mode (as if you navigated to **Games**, then hovered over a game card and selected **Players**). + +Here you can search, see who advanced to the next game and who did not, who started, who is currently playing, who finished, and sort by rank, name, and time remaining. + +## Observe tab + +The observation functionality found here is the same observe capability documented here: [Observe Mode](admin-observe.md). + +## Tickets tab + +The support ticketing functionality found here is the same as the interface documented here: [Using the Integrated Support feature](support.md). However, the support tickets are constrained to the game you viewing. You can perform all of the usual support ticket actions here (filter, search, export tickets) except for creating a new ticket. + +## Scoreboard tab + The scoreboard found here is the same scoreboard you would find if you clicked the Scoreboard link in a game lobby. \ No newline at end of file diff --git a/docs/gameboard/getting-started.md b/docs/gameboard/getting-started.md index e69de29..7c73395 100644 --- a/docs/gameboard/getting-started.md +++ b/docs/gameboard/getting-started.md @@ -0,0 +1,3 @@ +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). diff --git a/docs/gameboard/index.md b/docs/gameboard/index.md index 0c20c04..acae3e8 100644 --- a/docs/gameboard/index.md +++ b/docs/gameboard/index.md @@ -1,3 +1,6 @@ +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). # About the Gameboard Developed by Carnegie Mellon University's [Software Engineering Institute](github.com/cmu-sei) (SEI), Gameboard is a flexible web platform that provides game design capabilities and a competition-ready user interface. The *Gameboard * explains how to implement it when you want to run your own cybersecurity game. diff --git a/docs/gameboard/participating.md b/docs/gameboard/participating.md index bf8f97c..2410801 100644 --- a/docs/gameboard/participating.md +++ b/docs/gameboard/participating.md @@ -1,125 +1,128 @@ -# Participating in a Game - -This topic describes the Gameboard from a participant's point-of-view. A *participant* is a player in a game or a competitor in a competition who has no special role(s) attached them. These instructions assume that a fully configured game environment is available to the reader and they have an account on the Identity server. - -1. Browse to the gameboard's designated URL. Some gamecards are visible prior to logging in. -2. Click **Profile**, then **Login**. You're on the Identity server now. Here you can login with an existing account or register for a new one. - -!!! danger - - This topic requires significant revisions. It's here as a placeholder *only*. Thank you for your patience. - -## The Profile screen - -**Display Name:** Set a default name for public display that is suitable for all audiences. This name will apply to all new games, however, you can customize it during registration. - -**Sponsoring organization:** Select *your* organization. Gameboard admins define who the sponsors are and what image to associate with each. - -**Certificates:** View and print a certificate as proof of participation. This feature allows players to provide a record of achievements to friends, colleagues, and organizations to validate professional development time. Select **Competitive** to find and print certificates which validate player performance in a *game*. Select **Practice** to find and print certificates which validate player performance in a *practice challenge*. You can also save them as PDFs. - -- **Publish/Unpublish:** Optionally "publish" a certificate on a per-certificate basis. Players can send the link to the certificate to anyone including non-Gameboard users. Players can "unpublish" a certificate at any time removing access to the certificate. -- **Open:** Launches the certificate in a new tab in the browser. - -**History:** View game history, including where you finished on the scoreboard and whether it was in practice or competition. - -**Settings:** - -Users with the appropriate permissions (`Support` and `Admin`) may opt to receive browser notifications when support tickets are opened, closed, and updated. Users can choose to play an audio alert when a browser notification is received. - -Browser notifications are subject to OS-level settings which may need to be changed and browser site settings for pop-ups and redirects which need to be allowed. - -## The Home screen - -The Home screen is where you start a "live" game, preview upcoming games, and view completed games. Hover over a gamecard and select **Open Game**. Click **Enroll** to proceed to the game lobby. - -## The Game lobby - -This is the staging area where players join team members (if playing on a team) and get organized before starting a game session. Information about the session and enrollment appears here in blue: e.g., "Game window closes in -270d 1h." A yellow light indicates a player is registered to play but hasn't started a session. A green light indicates a player is active (i.e., has started a session). A red light indicates that player's session has ended. - -**Unenroll** and **Reset Session:** Players can unenroll here or reset a session if their gameboard administrator permits it. - -**Set Game Display Name/Set Team Display Name:** The game display name chosen here is used to represent an individual player or a team (based on the competition type) on the public scoreboard for a particular game. This display name is the same as your profile display name by default, but you can change the name of your player/team for a specific game if you choose. Like your *profile* display name, your *game* or *team* display name is subject to approval. - -### Organizing a team - -If the game is a team game, you organize your team in the game lobby. Under **Set Team Display Name**, enter a team name for the scoreboard. If you're the team manager, generate an invitation for your teammates. Copy the invitation code and distribute it to your teammates. Team members redeem your invitation code here too. - -!!! warning - Team managers: generating a new invitation code invalidates previous invitation codes. - -## Starting a session - -To start your session, click **Start Session** and click through the confirmation messages. - -!!! warning - For team players, make sure your teammates are ready to start. You can't add or remove team members after your session has started. Also note that *any* team member can start a session -- the continuous session timer starts when the final **Confirm** button is clicked. - -## Starting a challenge - -After your session is started, click **Continue to Gameboard**. To start a challenge, click a hot spot on the gameboard. Click **Start Challenge** and click through the confirmation messages. - -## Getting support in-game - -Players can get to the in-game support feature from the launched challenge screen below the challenge questions and the Support link in the top navigation. - -From either of these locations, click **Create Ticket**. If you create a ticket from the challenge screen, then the Support Code, challenge information, Game Id, Player Id, Team Id are automatically generated. If you create a ticket from the Support link, then this information can be added later. - -![support corner](img/get-support.png) - -*Getting support from a launched challenge* - -In the **Summary**, enter a brief statement of the problem. - -In the **Description**, enter a more detailed statement of your problem. Include error messages and other pertinent details. - -Under **Attachments**, attach files -- especially screen shots -- here. - -Click **Submit**. - -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. - -**Copy to markdown:** Allows you to copy the support ticket information in Markdown format. This is convenient if you need to distribute the ticket's content quickly and easily. - -!!! question "What is the Support Code?" - The support code is a unique identifier that will help game support staff locate each challenge. The support code for a challenge is automatically added to support tickets linked to challenges. The support code for a challenge can be found below the challenge questions, near the button to create a support ticket. See the screen capture above. - -### Finding an existing ticket - -From the Support page, use the dropdowns and the **Search** field to locate existing tickets. - -Filter tickets by status: Any, Open, In progress, Not closed (*open* plus *in progress*), and Closed. - -Search by entering terms. Search covers ticket summary, labels, challenge titles, and player name. - -## Giving feedback as a player - -Provided that a Gameboard administrator has enabled and configured the *feedback* feature, players are permitted **one** feedback submission per game and per challenge. Every member of a team is permitted to provide individual feedback. The feedback form is available at any time after session is started. This way, if participants quit the game before time expires they still have the opportunity to submit feedback. - -*The screen print below shows an example of a challenge feedback form as a player would see it.* - -![challenge form](img/challenge-feedback.png) - -Completing a challenge is not a requirement for submitting challenge feedback. Participants are able to begin a challenge, go through it, not make any submissions and still provide feedback. Perhaps the challenge was either too difficult for them or they just went down the wrong path. Either way, their feedback is valuable. - -Only feedback that has been submitted can be viewed in the reports. Once feedback has been submitted, a participant cannot go back and edit their feedback. - -??? note "Note on submitted vs in progress" - - "In progress" feedback is feedback a participant has begun in some capacity that triggered the autosave feature at least once but they have not clicked the **Submit** button yet. "In progress" feedback (i.e., *autosaved* feedback) and "submitted" feedback are both stored in the database; however, only submitted feedback is queried for the reports. - -This documentation assumes that you you are logged into a game and successfully enrolled. To view the *game* feedback as a participant: - -Select a game tile then click **Start**, then **Confirm** to start the session. - -Expand the **Game Feedback** form and complete the survey. Click **Submit**, then **Confirm** when finished. Responses can't be edited after clicking **Submit**. Game feedback responses do autosave. - -To view the *challenge* feedback as a participant: - -Select a game tile then click **Start**, then **Confirm** to start the session. Continue to Gameboard and start a challenge. - -Expand the **Challenge Feedback** form and complete the survey. Click **Submit**, then **Confirm** when finished. Responses can't be edited after clicking **Submit**. Challenge feedback responses do autosave. - -Whether or not the feedback form is expanded or collapsed depends upon the status of the game or the challenge. If a game is active, then participants will manually expand the feedback form. If a game is complete, the feedback form is automatically expanded. - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Participating in a Game + +This topic describes the Gameboard from a participant's point-of-view. A *participant* is a player in a game or a competitor in a competition who has no special role(s) attached them. These instructions assume that a fully configured game environment is available to the reader and they have an account on the Identity server. + +1. Browse to the gameboard's designated URL. Some gamecards are visible prior to logging in. +2. Click **Profile**, then **Login**. You're on the Identity server now. Here you can login with an existing account or register for a new one. + +!!! danger + + This topic requires significant revisions. It's here as a placeholder *only*. Thank you for your patience. + +## The Profile screen + +**Display Name:** Set a default name for public display that is suitable for all audiences. This name will apply to all new games, however, you can customize it during registration. + +**Sponsoring organization:** Select *your* organization. Gameboard admins define who the sponsors are and what image to associate with each. + +**Certificates:** View and print a certificate as proof of participation. This feature allows players to provide a record of achievements to friends, colleagues, and organizations to validate professional development time. Select **Competitive** to find and print certificates which validate player performance in a *game*. Select **Practice** to find and print certificates which validate player performance in a *practice challenge*. You can also save them as PDFs. + +- **Publish/Unpublish:** Optionally "publish" a certificate on a per-certificate basis. Players can send the link to the certificate to anyone including non-Gameboard users. Players can "unpublish" a certificate at any time removing access to the certificate. +- **Open:** Launches the certificate in a new tab in the browser. + +**History:** View game history, including where you finished on the scoreboard and whether it was in practice or competition. + +**Settings:** + +Users with the appropriate permissions (`Support` and `Admin`) may opt to receive browser notifications when support tickets are opened, closed, and updated. Users can choose to play an audio alert when a browser notification is received. + +Browser notifications are subject to OS-level settings which may need to be changed and browser site settings for pop-ups and redirects which need to be allowed. + +## The Home screen + +The Home screen is where you start a "live" game, preview upcoming games, and view completed games. Hover over a gamecard and select **Open Game**. Click **Enroll** to proceed to the game lobby. + +## The Game lobby + +This is the staging area where players join team members (if playing on a team) and get organized before starting a game session. Information about the session and enrollment appears here in blue: e.g., "Game window closes in +270d 1h." A yellow light indicates a player is registered to play but hasn't started a session. A green light indicates a player is active (i.e., has started a session). A red light indicates that player's session has ended. + +**Unenroll** and **Reset Session:** Players can unenroll here or reset a session if their gameboard administrator permits it. + +**Set Game Display Name/Set Team Display Name:** The game display name chosen here is used to represent an individual player or a team (based on the competition type) on the public scoreboard for a particular game. This display name is the same as your profile display name by default, but you can change the name of your player/team for a specific game if you choose. Like your *profile* display name, your *game* or *team* display name is subject to approval. + +### Organizing a team + +If the game is a team game, you organize your team in the game lobby. Under **Set Team Display Name**, enter a team name for the scoreboard. If you're the team manager, generate an invitation for your teammates. Copy the invitation code and distribute it to your teammates. Team members redeem your invitation code here too. + +!!! warning + Team managers: generating a new invitation code invalidates previous invitation codes. + +## Starting a session + +To start your session, click **Start Session** and click through the confirmation messages. + +!!! warning + For team players, make sure your teammates are ready to start. You can't add or remove team members after your session has started. Also note that *any* team member can start a session -- the continuous session timer starts when the final **Confirm** button is clicked. + +## Starting a challenge + +After your session is started, click **Continue to Gameboard**. To start a challenge, click a hot spot on the gameboard. Click **Start Challenge** and click through the confirmation messages. + +## Getting support in-game + +Players can get to the in-game support feature from the launched challenge screen below the challenge questions and the Support link in the top navigation. + +From either of these locations, click **Create Ticket**. If you create a ticket from the challenge screen, then the Support Code, challenge information, Game Id, Player Id, Team Id are automatically generated. If you create a ticket from the Support link, then this information can be added later. + +![support corner](img/get-support.png) + +*Getting support from a launched challenge* + +In the **Summary**, enter a brief statement of the problem. + +In the **Description**, enter a more detailed statement of your problem. Include error messages and other pertinent details. + +Under **Attachments**, attach files -- especially screen shots -- here. + +Click **Submit**. + +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. + +**Copy to markdown:** Allows you to copy the support ticket information in Markdown format. This is convenient if you need to distribute the ticket's content quickly and easily. + +!!! question "What is the Support Code?" + The support code is a unique identifier that will help game support staff locate each challenge. The support code for a challenge is automatically added to support tickets linked to challenges. The support code for a challenge can be found below the challenge questions, near the button to create a support ticket. See the screen capture above. + +### Finding an existing ticket + +From the Support page, use the dropdowns and the **Search** field to locate existing tickets. + +Filter tickets by status: Any, Open, In progress, Not closed (*open* plus *in progress*), and Closed. + +Search by entering terms. Search covers ticket summary, labels, challenge titles, and player name. + +## Giving feedback as a player + +Provided that a Gameboard administrator has enabled and configured the *feedback* feature, players are permitted **one** feedback submission per game and per challenge. Every member of a team is permitted to provide individual feedback. The feedback form is available at any time after session is started. This way, if participants quit the game before time expires they still have the opportunity to submit feedback. + +*The screen print below shows an example of a challenge feedback form as a player would see it.* + +![challenge form](img/challenge-feedback.png) + +Completing a challenge is not a requirement for submitting challenge feedback. Participants are able to begin a challenge, go through it, not make any submissions and still provide feedback. Perhaps the challenge was either too difficult for them or they just went down the wrong path. Either way, their feedback is valuable. + +Only feedback that has been submitted can be viewed in the reports. Once feedback has been submitted, a participant cannot go back and edit their feedback. + +??? note "Note on submitted vs in progress" + + "In progress" feedback is feedback a participant has begun in some capacity that triggered the autosave feature at least once but they have not clicked the **Submit** button yet. "In progress" feedback (i.e., *autosaved* feedback) and "submitted" feedback are both stored in the database; however, only submitted feedback is queried for the reports. + +This documentation assumes that you you are logged into a game and successfully enrolled. To view the *game* feedback as a participant: + +Select a game tile then click **Start**, then **Confirm** to start the session. + +Expand the **Game Feedback** form and complete the survey. Click **Submit**, then **Confirm** when finished. Responses can't be edited after clicking **Submit**. Game feedback responses do autosave. + +To view the *challenge* feedback as a participant: + +Select a game tile then click **Start**, then **Confirm** to start the session. Continue to Gameboard and start a challenge. + +Expand the **Challenge Feedback** form and complete the survey. Click **Submit**, then **Confirm** when finished. Responses can't be edited after clicking **Submit**. Challenge feedback responses do autosave. + +Whether or not the feedback form is expanded or collapsed depends upon the status of the game or the challenge. If a game is active, then participants will manually expand the feedback form. If a game is complete, the feedback form is automatically expanded. + The same is true of challenge feedback. If participants are actively working a challenge, they will manually expand the feedback form. When participants complete a challenge, the challenge feedback form expands automatically (and collapses when submitted). The feedback form section can be expanded or collapsed at any time once the session has started. \ No newline at end of file diff --git a/docs/gameboard/practice-area.md b/docs/gameboard/practice-area.md index ee05e56..9c12c8b 100644 --- a/docs/gameboard/practice-area.md +++ b/docs/gameboard/practice-area.md @@ -1,37 +1,40 @@ -# Practice Area - -The **Practice Area** is where Gameboard players can go to rehearse challenges (labs) to become proficient in certain skills. Practice Area is a lightweight version of a formal competition. After logging into Gameboard, click **Practice** in the main navigation. - -The Practice Area contains a greeting configured by a Gameboard admin for your organization or environment and a list of challenges designated for practice. - -You can **search** for a challenge to practice on. - -![practice search](img/practice-search.png) - -You can copy a link to your search by selecting the **clipboard icon** next to the search field. In the example above, you may want to share the list of challenges/labs that have "firewall" content with another Gameboard user. - -Under *Need a place to start?* the Gameboard admin may have configured some suggested searches for participants. Players can select one of these tags to be directed to a set of available practice challenges. Gameboard admins should refer to "Suggested searches" in the [Admin Practice Area](admin-practice-area.md). - -To start a practice session, select a challenge, then click **Start Practice Session**, and **Confirm**. You can only launch *one* practice challenge at a time. In the **Active Practice Challenge** screen, you can: - -- Extend your challenge session -- End your session -- Read the challenge guide -- Launch any gamespace resource -- Answer challenge questions -- Create a support ticket -- Provide feedback on the challenge - -In short, you get nearly the full competition challenge experience in the active practice session! - -Upon successfully solving the practice challenge, you can view a printable certificate commemorating your achievement...and you are returned to the Practice Area where you can select a new practice challenge. - -!!! tip - - You can view and print any certificate you earned in competition or in practice at any time from your profile screen. In the main navigation, click **Profile**. Then, select the **Certificates** link. - -If your attempt to solve the practice challenge is *unsuccessful* (you've run out of time or used your allotted submissions), you can try the challenge again or return to the Practice Area to find another challenge. No certificates are awarded for partially completing a practice challenge. - -## Administering the Practice Area - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Practice Area + +The **Practice Area** is where Gameboard players can go to rehearse challenges (labs) to become proficient in certain skills. Practice Area is a lightweight version of a formal competition. After logging into Gameboard, click **Practice** in the main navigation. + +The Practice Area contains a greeting configured by a Gameboard admin for your organization or environment and a list of challenges designated for practice. + +You can **search** for a challenge to practice on. + +![practice search](img/practice-search.png) + +You can copy a link to your search by selecting the **clipboard icon** next to the search field. In the example above, you may want to share the list of challenges/labs that have "firewall" content with another Gameboard user. + +Under *Need a place to start?* the Gameboard admin may have configured some suggested searches for participants. Players can select one of these tags to be directed to a set of available practice challenges. Gameboard admins should refer to "Suggested searches" in the [Admin Practice Area](admin-practice-area.md). + +To start a practice session, select a challenge, then click **Start Practice Session**, and **Confirm**. You can only launch *one* practice challenge at a time. In the **Active Practice Challenge** screen, you can: + +- Extend your challenge session +- End your session +- Read the challenge guide +- Launch any gamespace resource +- Answer challenge questions +- Create a support ticket +- Provide feedback on the challenge + +In short, you get nearly the full competition challenge experience in the active practice session! + +Upon successfully solving the practice challenge, you can view a printable certificate commemorating your achievement...and you are returned to the Practice Area where you can select a new practice challenge. + +!!! tip + + You can view and print any certificate you earned in competition or in practice at any time from your profile screen. In the main navigation, click **Profile**. Then, select the **Certificates** link. + +If your attempt to solve the practice challenge is *unsuccessful* (you've run out of time or used your allotted submissions), you can try the challenge again or return to the Practice Area to find another challenge. No certificates are awarded for partially completing a practice challenge. + +## Administering the Practice Area + Gameboard administrators configure global Practice Area settings including: a practice page greeting, certificate template, and session limits in the Gameboard Administration settings. For help on configuring these settings, see the [Admin Practice Area](./admin-practice-area.md) documentation. \ No newline at end of file diff --git a/docs/gameboard/reports-beta.md b/docs/gameboard/reports-beta.md index e4aebce..c1daf82 100644 --- a/docs/gameboard/reports-beta.md +++ b/docs/gameboard/reports-beta.md @@ -1,110 +1,113 @@ -# Reports - -The **Reports** module is available to users who have `Admin`, `Registrar`, or `Support` roles in the main navigation bar. Six report "cards" display available reports: - -- **Challenges Report:** View information about the challenges configured in the Gameboard app. This report is good for site utilization metrics related to challenges, challenge deploys, and challenge solves. -- **Enrollment Report:** View a summary of player enrollment data; who enrolled when, which sponsors do they represent, and how many played challenges. -- **Players Report:** View data on player activity. A “player” is a person with an account on the Gameboard site (i.e., a "user"). -- **Practice Area Report:** View metrics on players who are spending free time honing their skills in Gameboard. See which challenges are practiced most, have the best success rates, and which players are accessing the Gameboard to complete challenges in practice. -- **Site Usage Report:** View a high-level overview of user activity in the Gameboard. This report, optionally filtered by date range and sponsor, offers a digestible view of data related to players, sponsors, and challenges. Each statistic within the report contains a modal view for more detailed information. Note that the Site Usage Report can't be exported. -- **Support Report:** View a summary of support tickets created in Gameboard; including ticket creation and assignment details, ticket categories, and tickets attached to games/challenges. - -## Legacy Reports - -The legacy reporting functionality has not yet been deprecated; these reports are still available at the bottom of the Reports screen. Legacy reports won’t get future fixes or enhancements. Eventually, they will be removed from the Gameboard application. - -## Common report characteristics - -Each report shares common characteristics. - -- **Filter controls:** Dedicated filter controls allow users to narrow down or restrict the data displayed on a report. For example, if you're interested in seeing enrollments from a given sponsor in the Enrollment Report, use the **Sponsors** filter to select the sponsor(s) you're interested in. If you don't select any values in a filter, all data from that filter is included in the results. -- **Copy link to report:** When a report is run, the browser generates a link that represents filter selections for the current report. Select the **clipboard icon** to copy the current report and share it with another Gameboard user. The user whom you are sharing with must have the appropriate Gameboard role and must be logged into Gameboard. You can also copy the link in your browser's address bar and share. - -!!! tip - Bookmark useful filters via the browser so you can return to them quickly. - -- **Export to CSV:** To export report results CSV, click **Export to CSV**. -- **Reset Filters:** Deselecting filter values on multiple filters can be inconvenient. Click **Reset Filters** to deselect all filter values at once. -- **Summary:** Each report contains a summary that presents key data points. For example: the Enrollment Report shows the Leading Sponsor based upon filter selections. - -## Drilling down in results - -In some places in the report results, you can "drill down" by clicking a link in the metrics. A modal window displays a more granular view within the same data. For example: in the Enrollment Report, in the Performance category, some data points are links. See *screen print 1* below. Clicking that link goes deeper into that element. See *screen print 2* below. - -*Screen print 1: Summary Table* - -![score summary](img/score.png) - -Click **300** to view the detailed information that comprises score in the summary. - -*Screen print 2: Data breakdown* - -![score detailed](img/breakdown.png) - -In this view, the challenges and scores this player achieved are displayed. Now, you can see the details that make up the score. - -## Challenges Report - -The **Challenges** report answers questions like these: - -1. How many different challenges are configured? -2. How many competitive challenges have been deployed? -3. How many practice area challenges have been deployed? -4. What are the most popular competitive/practice mode challenges? - -## Enrollment Report - -The **Enrollment** report shows information about players who are enrolled in competitive-mode games on the Gameboard. You can filter this report to show enrollment numbers for each game. You can filter this report to only show information about challenges from specific games and seasons. You can also filter this report by Sponsor. - -The screen print below shows a summary of a typical game. The summary shows: - -1. 1390 different players (people, “users”, with an account in Gameboard) enrolled in our example game. The Department of Defense, the Leading Sponsor, leads enrollment with 1069 players enrolled. -2. Those 1390 players created 1422 teams. - - - The number of teams is higher than the number of players here because some people played in more than one “track” of the competition. Therefore, they have more than one “team” attached to one player/person/user. - - This number can also be higher than the number of players if the competition contains several rounds. So, if your filters are looking at a Round 1 and a Round 2, there are some teams in both and counted twice. - -3. 25 different sponsors participated in this example game. - -*Screen print 3: Sample Enrollment report* - -![sample enrollment](img/sample-enroll-report.png) - -## Players Report - -The **Players** report is good for viewing site utilization metrics. This report answers questions like these: - -1. How many users does the site have? -2. How many users have deployed competitive and practice area challenges? -3. How many users have achieved a full solve on at least one competitive and/or practice area challenge? - -You can also filter the Players report by *Account Creation Date* to understand when players create accounts. For example, it may be useful for you to know many users created an account since January 1, 2024 (or any date you prefer). - -## Practice Area Report - -The **Practice Area** report answers questions like these: - -1. How many practice challenges have been deployed? -2. How many practice challenges achieved a full solve? -3. How many different challenges have been deployed via the practice area? -4. How many users have deployed a practice challenge? -5. How many different sponsors have deployed a practice challenge? - -## Site Usage Report - -The **Site Usage** report answers questions like these: - -1. How many players are active in the Gameboard in a given period of time? -2. How many sponsors had active players and how many players represented each? -3. How many players are competitive players versus how many players are practice-only players? -4. How many unique challenges versus how many total challenges were attempted in a given period of time? -5. How many hours were spent playing games? - -## Support Report - -The **Support** report displays information about support tickets. Filter tickets by label, creation date and time, challenge, etc. The Support report answers questions like these: - -1. How many support tickets did we receive regarding the challenge titled "The Best Challenge"? -2. How many tickets with a specific label did we receive? -3. How many tickets did we receive on Tuesday? +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Reports + +The **Reports** module is available to users who have `Admin`, `Registrar`, or `Support` roles in the main navigation bar. Six report "cards" display available reports: + +- **Challenges Report:** View information about the challenges configured in the Gameboard app. This report is good for site utilization metrics related to challenges, challenge deploys, and challenge solves. +- **Enrollment Report:** View a summary of player enrollment data; who enrolled when, which sponsors do they represent, and how many played challenges. +- **Players Report:** View data on player activity. A “player” is a person with an account on the Gameboard site (i.e., a "user"). +- **Practice Area Report:** View metrics on players who are spending free time honing their skills in Gameboard. See which challenges are practiced most, have the best success rates, and which players are accessing the Gameboard to complete challenges in practice. +- **Site Usage Report:** View a high-level overview of user activity in the Gameboard. This report, optionally filtered by date range and sponsor, offers a digestible view of data related to players, sponsors, and challenges. Each statistic within the report contains a modal view for more detailed information. Note that the Site Usage Report can't be exported. +- **Support Report:** View a summary of support tickets created in Gameboard; including ticket creation and assignment details, ticket categories, and tickets attached to games/challenges. + +## Legacy Reports + +The legacy reporting functionality has not yet been deprecated; these reports are still available at the bottom of the Reports screen. Legacy reports won’t get future fixes or enhancements. Eventually, they will be removed from the Gameboard application. + +## Common report characteristics + +Each report shares common characteristics. + +- **Filter controls:** Dedicated filter controls allow users to narrow down or restrict the data displayed on a report. For example, if you're interested in seeing enrollments from a given sponsor in the Enrollment Report, use the **Sponsors** filter to select the sponsor(s) you're interested in. If you don't select any values in a filter, all data from that filter is included in the results. +- **Copy link to report:** When a report is run, the browser generates a link that represents filter selections for the current report. Select the **clipboard icon** to copy the current report and share it with another Gameboard user. The user whom you are sharing with must have the appropriate Gameboard role and must be logged into Gameboard. You can also copy the link in your browser's address bar and share. + +!!! tip + Bookmark useful filters via the browser so you can return to them quickly. + +- **Export to CSV:** To export report results CSV, click **Export to CSV**. +- **Reset Filters:** Deselecting filter values on multiple filters can be inconvenient. Click **Reset Filters** to deselect all filter values at once. +- **Summary:** Each report contains a summary that presents key data points. For example: the Enrollment Report shows the Leading Sponsor based upon filter selections. + +## Drilling down in results + +In some places in the report results, you can "drill down" by clicking a link in the metrics. A modal window displays a more granular view within the same data. For example: in the Enrollment Report, in the Performance category, some data points are links. See *screen print 1* below. Clicking that link goes deeper into that element. See *screen print 2* below. + +*Screen print 1: Summary Table* + +![score summary](img/score.png) + +Click **300** to view the detailed information that comprises score in the summary. + +*Screen print 2: Data breakdown* + +![score detailed](img/breakdown.png) + +In this view, the challenges and scores this player achieved are displayed. Now, you can see the details that make up the score. + +## Challenges Report + +The **Challenges** report answers questions like these: + +1. How many different challenges are configured? +2. How many competitive challenges have been deployed? +3. How many practice area challenges have been deployed? +4. What are the most popular competitive/practice mode challenges? + +## Enrollment Report + +The **Enrollment** report shows information about players who are enrolled in competitive-mode games on the Gameboard. You can filter this report to show enrollment numbers for each game. You can filter this report to only show information about challenges from specific games and seasons. You can also filter this report by Sponsor. + +The screen print below shows a summary of a typical game. The summary shows: + +1. 1390 different players (people, “users”, with an account in Gameboard) enrolled in our example game. The Department of Defense, the Leading Sponsor, leads enrollment with 1069 players enrolled. +2. Those 1390 players created 1422 teams. + + - The number of teams is higher than the number of players here because some people played in more than one “track” of the competition. Therefore, they have more than one “team” attached to one player/person/user. + - This number can also be higher than the number of players if the competition contains several rounds. So, if your filters are looking at a Round 1 and a Round 2, there are some teams in both and counted twice. + +3. 25 different sponsors participated in this example game. + +*Screen print 3: Sample Enrollment report* + +![sample enrollment](img/sample-enroll-report.png) + +## Players Report + +The **Players** report is good for viewing site utilization metrics. This report answers questions like these: + +1. How many users does the site have? +2. How many users have deployed competitive and practice area challenges? +3. How many users have achieved a full solve on at least one competitive and/or practice area challenge? + +You can also filter the Players report by *Account Creation Date* to understand when players create accounts. For example, it may be useful for you to know many users created an account since January 1, 2024 (or any date you prefer). + +## Practice Area Report + +The **Practice Area** report answers questions like these: + +1. How many practice challenges have been deployed? +2. How many practice challenges achieved a full solve? +3. How many different challenges have been deployed via the practice area? +4. How many users have deployed a practice challenge? +5. How many different sponsors have deployed a practice challenge? + +## Site Usage Report + +The **Site Usage** report answers questions like these: + +1. How many players are active in the Gameboard in a given period of time? +2. How many sponsors had active players and how many players represented each? +3. How many players are competitive players versus how many players are practice-only players? +4. How many unique challenges versus how many total challenges were attempted in a given period of time? +5. How many hours were spent playing games? + +## Support Report + +The **Support** report displays information about support tickets. Filter tickets by label, creation date and time, challenge, etc. The Support report answers questions like these: + +1. How many support tickets did we receive regarding the challenge titled "The Best Challenge"? +2. How many tickets with a specific label did we receive? +3. How many tickets did we receive on Tuesday? 4. How many tickets did we receive during PC5 Teams Round 1? \ No newline at end of file diff --git a/docs/gameboard/support.md b/docs/gameboard/support.md index d274e6b..26eba6e 100644 --- a/docs/gameboard/support.md +++ b/docs/gameboard/support.md @@ -1,71 +1,74 @@ -# Using the Integrated Support feature - -The gameboard platform comes with a built-in customer support interface so that competition hosts and administrators can assist competitors and players. This way, Gameboard is a "one-stop shop" and no outside apps or systems are required to track and measure issues reported by participants. - -You must have either the `Support` role or `Admin` role to use the support feature and manage tickets. Assuming you have been granted the appropriate role in Gameboard, select **Support**. - -## Support from participant point-of-view - -### Creating new support ticket - -You can create tickets from two places: the *Support* page or a challenge screen. In both cases you click the blue **Create Ticket** button to get started. 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. - -In the **Summary**, enter a brief statement of the problem. - -In the **Description**, enter a more detailed statement of your problem. Include error messages and other pertinent details. - -Under **Attachments**, attach files--especially screen shots--here. - -Click **Submit**. - -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. - -### Finding an existing ticket - -From the Support page, use the dropdowns and the **Search** field to locate existing tickets. Filter tickets by status: - -- Any Status -- Open -- In progress -- Not Closed (*Open* plus *In Progress*) -- Closed - -Filter by *Assigned to me*, *Unassigned*, and *Any Assignment*. Finally, you can also *filter by labels*. - -Search by entering terms. Search covers ticket description, label, user, challenge title, and player. - -## Support from the Support role point-of-view - -Click the links in the ticket header to instantly jump to the submitter's *Game* and *Challenge* details. - -### Creating new support ticket - -The procedure for support staff (i.e., users given the `Support` role) 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. - -### Managing support tickets - -From the Ticket management side-bar: - -**Assigned to:** Assign the ticket to another support person. The dropdown is filtered by users who have been granted the support role. - -**Status:** Move the ticket through the support workflow. Tickets are `Open`, `In progress`, or `Closed`. - -- **Open** - Indicates that ticket has been reported, but not yet acted upon by support staff. The ticket is "waiting" on an action. -- **In progress** - The ticket is actively being worked on. -- **Closed** - The ticket has been resolved and no longer requires action from support or participants. - -**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. - -**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. - -**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. - -Add a **comment** to communicate with the participant. - -### Copy to markdown - -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. - -## Support-related Reporting - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current Gameboard documentation [here](https://cmu-sei.github.io/crucible/gameboard/). +# Using the Integrated Support feature + +The gameboard platform comes with a built-in customer support interface so that competition hosts and administrators can assist competitors and players. This way, Gameboard is a "one-stop shop" and no outside apps or systems are required to track and measure issues reported by participants. + +You must have either the `Support` role or `Admin` role to use the support feature and manage tickets. Assuming you have been granted the appropriate role in Gameboard, select **Support**. + +## Support from participant point-of-view + +### Creating new support ticket + +You can create tickets from two places: the *Support* page or a challenge screen. In both cases you click the blue **Create Ticket** button to get started. 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. + +In the **Summary**, enter a brief statement of the problem. + +In the **Description**, enter a more detailed statement of your problem. Include error messages and other pertinent details. + +Under **Attachments**, attach files--especially screen shots--here. + +Click **Submit**. + +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. + +### Finding an existing ticket + +From the Support page, use the dropdowns and the **Search** field to locate existing tickets. Filter tickets by status: + +- Any Status +- Open +- In progress +- Not Closed (*Open* plus *In Progress*) +- Closed + +Filter by *Assigned to me*, *Unassigned*, and *Any Assignment*. Finally, you can also *filter by labels*. + +Search by entering terms. Search covers ticket description, label, user, challenge title, and player. + +## Support from the Support role point-of-view + +Click the links in the ticket header to instantly jump to the submitter's *Game* and *Challenge* details. + +### Creating new support ticket + +The procedure for support staff (i.e., users given the `Support` role) 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. + +### Managing support tickets + +From the Ticket management side-bar: + +**Assigned to:** Assign the ticket to another support person. The dropdown is filtered by users who have been granted the support role. + +**Status:** Move the ticket through the support workflow. Tickets are `Open`, `In progress`, or `Closed`. + +- **Open** - Indicates that ticket has been reported, but not yet acted upon by support staff. The ticket is "waiting" on an action. +- **In progress** - The ticket is actively being worked on. +- **Closed** - The ticket has been resolved and no longer requires action from support or participants. + +**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. + +**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. + +**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. + +Add a **comment** to communicate with the participant. + +### Copy to markdown + +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. + +## Support-related Reporting + 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. \ No newline at end of file diff --git a/docs/topomojo/admin-dashboard.md b/docs/topomojo/admin-dashboard.md index 50300f2..c1beb26 100644 --- a/docs/topomojo/admin-dashboard.md +++ b/docs/topomojo/admin-dashboard.md @@ -1,21 +1,24 @@ -# Admin features - -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. The initial `admin` role is given to the first user who authenticates successfully. - -### Hub Connections - -**Hub connections** informs Topo admins about which users are currently logged into TopoMojo. - -### Announcement - -The **Announcement** feature allows Topo admins to broadcast important messages to everyone in TopoMojo. Announcements appear in the Topo interface. In the Message field, enter the content of the announcement and click **Send**. - -### Import/Export - -This is future functionality for the TopoMojo UI. The API equivalent of import/export is available for use. - -### Janitor - -The **Janitor** service cleans up unused resources (e.g., a workspace VM that has been idle for a long time) in TopoMojo. - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Admin features + +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. The initial `admin` role is given to the first user who authenticates successfully. + +### Hub Connections + +**Hub connections** informs Topo admins about which users are currently logged into TopoMojo. + +### Announcement + +The **Announcement** feature allows Topo admins to broadcast important messages to everyone in TopoMojo. Announcements appear in the Topo interface. In the Message field, enter the content of the announcement and click **Send**. + +### Import/Export + +This is future functionality for the TopoMojo UI. The API equivalent of import/export is available for use. + +### Janitor + +The **Janitor** service cleans up unused resources (e.g., a workspace VM that has been idle for a long time) in TopoMojo. + **Cleanup Report:** Provides a log of the Janitor's activity. \ No newline at end of file diff --git a/docs/topomojo/admin-gamespaces.md b/docs/topomojo/admin-gamespaces.md index 37511bc..ef1dd13 100644 --- a/docs/topomojo/admin-gamespaces.md +++ b/docs/topomojo/admin-gamespaces.md @@ -1,27 +1,30 @@ -# Admin Gamespaces - -The **Gamespaces** tab is where the admin can search for, and filter by, **active** and **inactive** gamespaces. Once gamespaces are found, the admin can perform certain actions. By default, the search is for *active* gamespaces. Green indicates *active* gamespaces and gray indicates *inactive* gamespaces. - -**Refresh:** Refreshes your search. - -**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. - -Gamespaces in the table show the gamespace id or support code in Gameboard (e.g. `e9416013`), the time remaining (if active), the user who is interacting with (or *had* interacted with) the gamespace; and the title of the *workspace* that the *gamespace* was deployed from. The screen print below, several active and inactive gamespaces are shown. User names have been redacted. - -![admin gamespaces](img/admin-gamespaces.png) - -## View (expanded) - -**View:** Selecting **View** expands the gamespace information where a list of all the VMs associated with the gamespace and their state. Additional information on how the View works is found below. - -- **refresh:** Refreshes the VM instance. -- **console:** Allows you to interact with the VM (a user's gamespace). -- **stop:** Stops a powered on VM. -- **revert:** Reverts to last saved state. -- **delete:** Deletes a running VM instance. -- **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 questions were answered correctly or incorrectly. -- **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. - -## Delete - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Admin Gamespaces + +The **Gamespaces** tab is where the admin can search for, and filter by, **active** and **inactive** gamespaces. Once gamespaces are found, the admin can perform certain actions. By default, the search is for *active* gamespaces. Green indicates *active* gamespaces and gray indicates *inactive* gamespaces. + +**Refresh:** Refreshes your search. + +**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. + +Gamespaces in the table show the gamespace id or support code in Gameboard (e.g. `e9416013`), the time remaining (if active), the user who is interacting with (or *had* interacted with) the gamespace; and the title of the *workspace* that the *gamespace* was deployed from. The screen print below, several active and inactive gamespaces are shown. User names have been redacted. + +![admin gamespaces](img/admin-gamespaces.png) + +## View (expanded) + +**View:** Selecting **View** expands the gamespace information where a list of all the VMs associated with the gamespace and their state. Additional information on how the View works is found below. + +- **refresh:** Refreshes the VM instance. +- **console:** Allows you to interact with the VM (a user's gamespace). +- **stop:** Stops a powered on VM. +- **revert:** Reverts to last saved state. +- **delete:** Deletes a running VM instance. +- **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 questions were answered correctly or incorrectly. +- **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. + +## Delete + **Delete:** As you would expect, deletes the gamespace and associated VMs. \ No newline at end of file diff --git a/docs/topomojo/admin-log.md b/docs/topomojo/admin-log.md index f677211..b199689 100644 --- a/docs/topomojo/admin-log.md +++ b/docs/topomojo/admin-log.md @@ -1,3 +1,6 @@ +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). # Admin Dashboard Log tab The **Log** tab is useful from the admin point of view when trying to troubleshoot. Only errors are shown here, not every log line. \ No newline at end of file diff --git a/docs/topomojo/admin-machines.md b/docs/topomojo/admin-machines.md index 79ecfc5..6b6de2b 100644 --- a/docs/topomojo/admin-machines.md +++ b/docs/topomojo/admin-machines.md @@ -1,3 +1,6 @@ +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). # Admin Machines This tab provides a list of all VMs TopoMojo is tracking and the gamespaces they are attached to without the use of the vSphere Client. diff --git a/docs/topomojo/admin-templates.md b/docs/topomojo/admin-templates.md index d8cd83c..df53e36 100644 --- a/docs/topomojo/admin-templates.md +++ b/docs/topomojo/admin-templates.md @@ -1,37 +1,40 @@ -# Admin Templates - -The **Templates** tab is where you can view all of the templates that exist in TopoMojo. - -**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`. - -![templates filter](img/templates-filter.png) - -You can filter for specific workspaces here too. Clicking the *name* of the of the workspace takes you directly to the workspace. - -!!! note "Linked and unlinked templates" - - 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. - -## Template Properties - -**Name:** The VM name can't contain spaces; Topo will replace spaces in a name with a `-`. - -**Description:** Not visible to users; use the *Description* in a way that meets your needs. For example, VM credentials could be included here. - -**Networks:** A space delimited list of network names. When the VM is deployed, it will have *one* network interface for each of the named networks. Networks are created on the hypervisor by TopoMojo at VM-deploy time if they don't already exist. - -TopoMojo appends the isolation tag of the workspace/gamespace to network names to ensure network isolation. - -TopoMojo does not append the isolation tag to persistent/shared networks listed here; the VM will be connected to the existing shared/persistent network. - -For more information on *isolation tags*, see "Isolation tags" in [TopoMojo concepts](index.md). - -**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. Key/value pairs are placed 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”. - -**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 Topo 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. - -When deciding how many replicas are needed, 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`. Topo will deploy five, two will get used, and the three extra won't get used everytime the gamespace is deployed. - -`-1`: Setting Replicas to `-1` means Topo will deploy one VM template copy per user. If there are two users, then two copies are deployed; if there are 10 users, then 10 copies. No extra VMs are deployed. This setting is used in conjunction with the Gameboard app, where Gameboard informs TopoMojo on how many copies to make based upon the Gameboard team size. - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Admin Templates + +The **Templates** tab is where you can view all of the templates that exist in TopoMojo. + +**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`. + +![templates filter](img/templates-filter.png) + +You can filter for specific workspaces here too. Clicking the *name* of the of the workspace takes you directly to the workspace. + +!!! note "Linked and unlinked templates" + + 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. + +## Template Properties + +**Name:** The VM name can't contain spaces; Topo will replace spaces in a name with a `-`. + +**Description:** Not visible to users; use the *Description* in a way that meets your needs. For example, VM credentials could be included here. + +**Networks:** A space delimited list of network names. When the VM is deployed, it will have *one* network interface for each of the named networks. Networks are created on the hypervisor by TopoMojo at VM-deploy time if they don't already exist. + +TopoMojo appends the isolation tag of the workspace/gamespace to network names to ensure network isolation. + +TopoMojo does not append the isolation tag to persistent/shared networks listed here; the VM will be connected to the existing shared/persistent network. + +For more information on *isolation tags*, see "Isolation tags" in [TopoMojo concepts](index.md). + +**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. Key/value pairs are placed 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”. + +**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 Topo 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. + +When deciding how many replicas are needed, 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`. Topo will deploy five, two will get used, and the three extra won't get used everytime the gamespace is deployed. + +`-1`: Setting Replicas to `-1` means Topo will deploy one VM template copy per user. If there are two users, then two copies are deployed; if there are 10 users, then 10 copies. No extra VMs are deployed. This setting is used in conjunction with the Gameboard app, where Gameboard informs TopoMojo on how many copies to make based upon the Gameboard team size. + 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. \ No newline at end of file diff --git a/docs/topomojo/admin-users.md b/docs/topomojo/admin-users.md index 6819ccf..080ffdb 100644 --- a/docs/topomojo/admin-users.md +++ b/docs/topomojo/admin-users.md @@ -1,36 +1,39 @@ -# Admin Users - -The **Users** tab is where Topo users are listed, created, and assigned permissions. The **Search** feature allows Topo admins to search on the name of a Topo user. To search for a user across all of TopoMojo, enter the term into the **Search** field or filter by *role* or *audience*. - -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. - -**View:** Select **View** to see the properties for the user. The properties are defined under "Create a new User" below. - -**Delete:** Deletes the user. - -## Roles - -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. - -- **Admin:** Highest level of permission in TopoMojo; can do everything the other roles can do. -- **Observer:** Allows a user to view and use the Gamespaces tab. Access is limited by the *scope* of the user (see below). An observer can deploy gamespaces with a matching *audience* and these are the only gamespaces the user can observe. -- **Creator:** Can have as many workspaces and templates as wanted. -- **Builder:** Can connect to bridge-net. -- **User:** No extra permissions in TopoMojo. This is the TopoMojo default. -- **Disabled:** No permissions in TopoMojo. - -## Create a new User - -**Name:** Enter a new user name here. - -**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). - -**Workspace Limit:** The maximum number of workspaces this user can manage. - -**Gamespace Limit:** The maximum number of concurrent gamespaces allowed for this user. - -**Gamespace Max Duration:** The maximum amount of minutes allowed for a gamespace. - -**Gamespace Cleanup Grace time:** The number of "grace" minutes between the time the gamespace expires and when it is torn down. - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Admin Users + +The **Users** tab is where Topo users are listed, created, and assigned permissions. The **Search** feature allows Topo admins to search on the name of a Topo user. To search for a user across all of TopoMojo, enter the term into the **Search** field or filter by *role* or *audience*. + +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. + +**View:** Select **View** to see the properties for the user. The properties are defined under "Create a new User" below. + +**Delete:** Deletes the user. + +## Roles + +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. + +- **Admin:** Highest level of permission in TopoMojo; can do everything the other roles can do. +- **Observer:** Allows a user to view and use the Gamespaces tab. Access is limited by the *scope* of the user (see below). An observer can deploy gamespaces with a matching *audience* and these are the only gamespaces the user can observe. +- **Creator:** Can have as many workspaces and templates as wanted. +- **Builder:** Can connect to bridge-net. +- **User:** No extra permissions in TopoMojo. This is the TopoMojo default. +- **Disabled:** No permissions in TopoMojo. + +## Create a new User + +**Name:** Enter a new user name here. + +**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). + +**Workspace Limit:** The maximum number of workspaces this user can manage. + +**Gamespace Limit:** The maximum number of concurrent gamespaces allowed for this user. + +**Gamespace Max Duration:** The maximum amount of minutes allowed for a gamespace. + +**Gamespace Cleanup Grace time:** The number of "grace" minutes between the time the gamespace expires and when it is torn down. + **Generate ApiKey:** Generate API keys here. This allows users to programmatically interact with the TopoMojo API without needing to log in. \ No newline at end of file diff --git a/docs/topomojo/admin-workspaces.md b/docs/topomojo/admin-workspaces.md index e47bb1d..3bafa31 100644 --- a/docs/topomojo/admin-workspaces.md +++ b/docs/topomojo/admin-workspaces.md @@ -1,33 +1,36 @@ -# Admin Workspaces - -The **Workspaces** tab is where the admin can search for workspaces and perform limited actions. Workspaces are where challenges (or labs) are built. Here, an admin can view every workspace. - -!!! note - - 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. - -In the left navigation pane, you can use the **Search** field to locate a workspace. However, searching here only returns workspaces you have created or have been invited to join. - -**Create:** Create a new workspace from the Admin Workspaces panel.For additional help, see [Building a new workspace](building-a-workspace.md). - -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). - -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. The workspace identifier is called out in the screen capture below. - -![tm-wksp-iden](img/wksp-iden.png) - -## View (expanded) - -**Template Limit:** Defines the number of VMs that can be in the workspace. - -**Template Scope:** Limits a workspace to using templates that have the given scope. - -**Audience:** Limits who can deploy a gamespace as a workspace. - -**VMs:** Refresh, deploy, view the console, start/stop, revert and delete from here. -- **Refresh**: Queries the state of the VM from the hypervisor. -- **Deploy**: Deploys that virtual machine into your workspace. -- **Console:** Opens the console for the virtual machine. -- **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. -- **Revert:** Reverts the VM to its last saved state. All changes made since the last commit are lost. +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Admin Workspaces + +The **Workspaces** tab is where the admin can search for workspaces and perform limited actions. Workspaces are where challenges (or labs) are built. Here, an admin can view every workspace. + +!!! note + + 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. + +In the left navigation pane, you can use the **Search** field to locate a workspace. However, searching here only returns workspaces you have created or have been invited to join. + +**Create:** Create a new workspace from the Admin Workspaces panel.For additional help, see [Building a new workspace](building-a-workspace.md). + +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). + +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. The workspace identifier is called out in the screen capture below. + +![tm-wksp-iden](img/wksp-iden.png) + +## View (expanded) + +**Template Limit:** Defines the number of VMs that can be in the workspace. + +**Template Scope:** Limits a workspace to using templates that have the given scope. + +**Audience:** Limits who can deploy a gamespace as a workspace. + +**VMs:** Refresh, deploy, view the console, start/stop, revert and delete from here. +- **Refresh**: Queries the state of the VM from the hypervisor. +- **Deploy**: Deploys that virtual machine into your workspace. +- **Console:** Opens the console for the virtual machine. +- **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. +- **Revert:** Reverts the VM to its last saved state. All changes made since the last commit are lost. - **Delete:** Deletes a running VM instance. \ No newline at end of file diff --git a/docs/topomojo/building-a-workspace.md b/docs/topomojo/building-a-workspace.md index 9bef066..b2b93d2 100644 --- a/docs/topomojo/building-a-workspace.md +++ b/docs/topomojo/building-a-workspace.md @@ -1,85 +1,88 @@ -# Building a new workspace - -The workspace interface contains six tabs: Settings, Templates, Document, Challenge, Files, and Play. To build a new Topo workspace click **Home**, then **New Workspace**. - -## Settings - -The Settings tab holds the metadata for your lab. - -**Title:** The title of your workspace; remember that the title should be unique. - -**Description:** A brief description of your workspace to display when browsing titles. The **Description** is viewable to everyone, and when used in conjunction with Gameboard, visible there too. - -**Tags:** Internal metadata to add data about the lab; for example, if using for a cyber competition, then your tag may be something like `cyber-cup c01`. Now, you can search for that challenge (or lab) using that tag. - -**Authorship:** Your name and the names of others who may have assisted you. - -**Audience:** A space-delimited list of administrator-defined groups that have permission to deploy gamespaces from the workspace. Administrators define an *audience* with any name here. Only users with a *scope* matching one of the provided *audiences* are permitted to deploy gamespaces from the workspace. `Everyone` is the global audience that allows all users to deploy gamespaces from the workspace. For more information, see the [Admin Dashboard - Users](admin-users.md) documentation. - -**Duration:** Recommended length of time in minutes that it takes to play through a gamespace launched from your workspace. - -**Collaboration:** To share your workspace with others click **Generate invitation**. Paste the link into an email and send. Collaborators are shown here alongside the author. When a collaborator is connected to your workspace, you'll see them `connected` in the top right corner of the workspace. - -**Clone:** Clones your workspace; `-CLONE` is appended to the title of the new workspace. - -**Delete:** Deletes an existing workspace. - -## Templates - -The template selector allows you to add virtual machine templates to your workspace. The templates here are "starting point" virtual machines that you can customize. There are blank disc templates for installing your own operating system plus other VMs with operating systems pre-installed. - -### Adding and editing templates - -To add a template to your workspace: - -1. On the Templates tab, click **Add Templates**. -2. Search for and add the templates you need for your topology. -3. Click the **edit** icon to expand the template(s) to make changes. - -![templates-edit](img/templates-edit.png) - -### Template field definitions - -The list below explains the fields in the VM template. - -- **Name:** Edit the name here. Remember that the name should be unique within the workspace. -- **Description:** The Description should contain the credentials for the virtual machine and the purpose of the virtual machine. -- **Networks:** The Networks fields allows you to add a space-delimited list of networks where the virtual machines connect. These names should be the same for all systems in your lab that need to connect to the same network. -- **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. Key/value pairs are placed 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”. - - *Transforms* allow you to define dynamic variables that are generated based on certain criteria or types. To add the concept of transforms here, select **Challenge** and see **Transforms**. The **info** icon in the Transforms section describes the transform types that are available. See also the "Transforms" topic [here](challenge.md/#transforms). - - Guest info variables can be accessed from a Gamespace VM by using VMware Tools such as `open-vm-tools`and the `vmtoolsd` command. See [Open VM Tools](https://docs.vmware.com/en/VMware-Tools/12.3.0/com.vmware.vsphere.vmwaretools.doc/GUID-8B6EA5B7-453B-48AA-92E5-DB7F061341D1.html) and [VMware Tools daemon help](https://helpmanual.io/help/vmtoolsd/). - - ![vm-ware-tools](img/vm-ware-tools.png) - -- **Replicas:** Set this number to deploy copies of the same VM template. For example: to deploy three copies of a VM template when a *gamespace* is started, set **Replicas** to "3". To deploy one copy of the VM template for each team member that the gamespace is started for, set **Replicas** to "-1". -- **Variant:** Specify that the VM template should only be deployed for a particular variant. For example: when **Variant** is set to "2", the VM template will only be deployed when TopoMojo deploys variant 2 of the challenge. -- **Iso:** Use the Iso Selector to attach an ISO image to your virtual machine. -- **Console Access:** Toggle **Hidden** to hide a specific VM from being accessible by the person completing the lab. This is useful for systems like a DHCP server that do not require user interaction. -- **Linked:** *Unlinking* creates a new a new copy of the template that can be saved and customized. Toggle **Unlink** for any virtual machine that will not use the default disk included with the template. -- **Delete Template:** Deletes the template. | - -### Refresh and Deploy - -![refresh-deploy](img/refresh-deploy.png) - -Once the template is in the appropriate state: - -- **Refresh**: (arrows) Refresh queries the state of the VM from the hypervisor. This is useful if you run a `shutdown` command in the VM and the TopoMojo UI icons haven't updated to reflect the powered-off state of the VM yet. -- **Deploy**: (lightning bolt) Deploys that virtual machine into your workspace. - -From left to right, the following additional icons are used in the deployed virtual machine: - -![other-icons](img/other-icons.png) - -- **Console:** Opens the console for the virtual machine. -- **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. -- **Revert:** Reverts the VM to its last saved state. All changes made since the last commit are lost. -- **Delete:** Deletes a running VM instance. Before you click **delete**, make sure you have saved any changes to the disk. - -### Save - -![templates-save](img/templates-save.png) - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Building a new workspace + +The workspace interface contains six tabs: Settings, Templates, Document, Challenge, Files, and Play. To build a new Topo workspace click **Home**, then **New Workspace**. + +## Settings + +The Settings tab holds the metadata for your lab. + +**Title:** The title of your workspace; remember that the title should be unique. + +**Description:** A brief description of your workspace to display when browsing titles. The **Description** is viewable to everyone, and when used in conjunction with Gameboard, visible there too. + +**Tags:** Internal metadata to add data about the lab; for example, if using for a cyber competition, then your tag may be something like `cyber-cup c01`. Now, you can search for that challenge (or lab) using that tag. + +**Authorship:** Your name and the names of others who may have assisted you. + +**Audience:** A space-delimited list of administrator-defined groups that have permission to deploy gamespaces from the workspace. Administrators define an *audience* with any name here. Only users with a *scope* matching one of the provided *audiences* are permitted to deploy gamespaces from the workspace. `Everyone` is the global audience that allows all users to deploy gamespaces from the workspace. For more information, see the [Admin Dashboard - Users](admin-users.md) documentation. + +**Duration:** Recommended length of time in minutes that it takes to play through a gamespace launched from your workspace. + +**Collaboration:** To share your workspace with others click **Generate invitation**. Paste the link into an email and send. Collaborators are shown here alongside the author. When a collaborator is connected to your workspace, you'll see them `connected` in the top right corner of the workspace. + +**Clone:** Clones your workspace; `-CLONE` is appended to the title of the new workspace. + +**Delete:** Deletes an existing workspace. + +## Templates + +The template selector allows you to add virtual machine templates to your workspace. The templates here are "starting point" virtual machines that you can customize. There are blank disc templates for installing your own operating system plus other VMs with operating systems pre-installed. + +### Adding and editing templates + +To add a template to your workspace: + +1. On the Templates tab, click **Add Templates**. +2. Search for and add the templates you need for your topology. +3. Click the **edit** icon to expand the template(s) to make changes. + +![templates-edit](img/templates-edit.png) + +### Template field definitions + +The list below explains the fields in the VM template. + +- **Name:** Edit the name here. Remember that the name should be unique within the workspace. +- **Description:** The Description should contain the credentials for the virtual machine and the purpose of the virtual machine. +- **Networks:** The Networks fields allows you to add a space-delimited list of networks where the virtual machines connect. These names should be the same for all systems in your lab that need to connect to the same network. +- **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. Key/value pairs are placed 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”. + + *Transforms* allow you to define dynamic variables that are generated based on certain criteria or types. To add the concept of transforms here, select **Challenge** and see **Transforms**. The **info** icon in the Transforms section describes the transform types that are available. See also the "Transforms" topic [here](challenge.md/#transforms). + + Guest info variables can be accessed from a Gamespace VM by using VMware Tools such as `open-vm-tools`and the `vmtoolsd` command. See [Open VM Tools](https://docs.vmware.com/en/VMware-Tools/12.3.0/com.vmware.vsphere.vmwaretools.doc/GUID-8B6EA5B7-453B-48AA-92E5-DB7F061341D1.html) and [VMware Tools daemon help](https://helpmanual.io/help/vmtoolsd/). + + ![vm-ware-tools](img/vm-ware-tools.png) + +- **Replicas:** Set this number to deploy copies of the same VM template. For example: to deploy three copies of a VM template when a *gamespace* is started, set **Replicas** to "3". To deploy one copy of the VM template for each team member that the gamespace is started for, set **Replicas** to "-1". +- **Variant:** Specify that the VM template should only be deployed for a particular variant. For example: when **Variant** is set to "2", the VM template will only be deployed when TopoMojo deploys variant 2 of the challenge. +- **Iso:** Use the Iso Selector to attach an ISO image to your virtual machine. +- **Console Access:** Toggle **Hidden** to hide a specific VM from being accessible by the person completing the lab. This is useful for systems like a DHCP server that do not require user interaction. +- **Linked:** *Unlinking* creates a new a new copy of the template that can be saved and customized. Toggle **Unlink** for any virtual machine that will not use the default disk included with the template. +- **Delete Template:** Deletes the template. | + +### Refresh and Deploy + +![refresh-deploy](img/refresh-deploy.png) + +Once the template is in the appropriate state: + +- **Refresh**: (arrows) Refresh queries the state of the VM from the hypervisor. This is useful if you run a `shutdown` command in the VM and the TopoMojo UI icons haven't updated to reflect the powered-off state of the VM yet. +- **Deploy**: (lightning bolt) Deploys that virtual machine into your workspace. + +From left to right, the following additional icons are used in the deployed virtual machine: + +![other-icons](img/other-icons.png) + +- **Console:** Opens the console for the virtual machine. +- **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. +- **Revert:** Reverts the VM to its last saved state. All changes made since the last commit are lost. +- **Delete:** Deletes a running VM instance. Before you click **delete**, make sure you have saved any changes to the disk. + +### Save + +![templates-save](img/templates-save.png) + The **save** icon appears only when an unlinked disk is being used; changes can't be saved to a linked disk. The **save** icon removes the last disk snapshot and creates a new snapshot that saves all changes made to the VM. \ No newline at end of file diff --git a/docs/topomojo/challenge.md b/docs/topomojo/challenge.md index 1233122..28f6a27 100644 --- a/docs/topomojo/challenge.md +++ b/docs/topomojo/challenge.md @@ -1,60 +1,63 @@ -# Challenge tab - -The *Challenge* tab in the Topo workspace is used when both Gameboard and TopoMojo are integrated to execute a cyber competition. More information on linking those two applications together can be found elsewhere in the Foundry documentation. The Challenge tab is where you create random key/values, embed them in a *gamespace* at deploy time, and ask questions and answers of competitors (players). - -## Transforms - -**Transforms** allow you to define dynamic variables that are generated 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. - -*Screen print 1:* - -![transforms](img/transforms.png) - -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. - -Any of the sections on the Challenge tab (e.g., Transforms, Markdown, Questions, Answers) can contain *double-pounder-keys* that will be replaced 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*). - -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 a gamespace is deployed. - -*Screen print 2:* - -![guest-settings](img/guest-settings.png) - -Click [here](building-a-workspace.md/#template-field-definitions) to learn more about Guest Settings. - -## Markdown - -The markdown you enter here gets appended to the gamespace document. - -## Variants - -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 a challenge is deployed, 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. - -## Question Set - -**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. - -**Question:** Enter the question you expect the participant to answer here. Your question should be specific, so that there is only one correct answer. - -**Answer:** Enter the correct answer that the competitor must submit to earn a score. - -These options are revealed when **Detail** is selected. - -**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. - -**Grader:** Select the grading type here. The Grader determines if players submitted the correct answer to a question. Select one of four types: - -- `Match`: The submission must exactly match what is in the **Answer** field. Use this when there is exactly one possible answer to a question. -- `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. -- `MatchAll`: The submission must match all of the pipe-delimited answers in the **Answer** field. Use this when a list of answers to a question is expected. -- `MatchAlpha`: The submission must exactly match what is in the **Answer** field *after* all non-alphanumeric characters are removed. 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. - -All four graders are case-insensitive, meaning that all answers and submissions are converted to lower-case by the grader before the submission is compared to the expected answer in all grader types. - -### Weight - -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). Zero (`0`) values are calculated evenly. - -### Example - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Challenge tab + +The *Challenge* tab in the Topo workspace is used when both Gameboard and TopoMojo are integrated to execute a cyber competition. More information on linking those two applications together can be found elsewhere in the Foundry documentation. The Challenge tab is where you create random key/values, embed them in a *gamespace* at deploy time, and ask questions and answers of competitors (players). + +## Transforms + +**Transforms** allow you to define dynamic variables that are generated 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. + +*Screen print 1:* + +![transforms](img/transforms.png) + +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. + +Any of the sections on the Challenge tab (e.g., Transforms, Markdown, Questions, Answers) can contain *double-pounder-keys* that will be replaced 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*). + +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 a gamespace is deployed. + +*Screen print 2:* + +![guest-settings](img/guest-settings.png) + +Click [here](building-a-workspace.md/#template-field-definitions) to learn more about Guest Settings. + +## Markdown + +The markdown you enter here gets appended to the gamespace document. + +## Variants + +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 a challenge is deployed, 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. + +## Question Set + +**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. + +**Question:** Enter the question you expect the participant to answer here. Your question should be specific, so that there is only one correct answer. + +**Answer:** Enter the correct answer that the competitor must submit to earn a score. + +These options are revealed when **Detail** is selected. + +**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. + +**Grader:** Select the grading type here. The Grader determines if players submitted the correct answer to a question. Select one of four types: + +- `Match`: The submission must exactly match what is in the **Answer** field. Use this when there is exactly one possible answer to a question. +- `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. +- `MatchAll`: The submission must match all of the pipe-delimited answers in the **Answer** field. Use this when a list of answers to a question is expected. +- `MatchAlpha`: The submission must exactly match what is in the **Answer** field *after* all non-alphanumeric characters are removed. 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. + +All four graders are case-insensitive, meaning that all answers and submissions are converted to lower-case by the grader before the submission is compared to the expected answer in all grader types. + +### Weight + +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). Zero (`0`) values are calculated evenly. + +### Example + 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. \ No newline at end of file diff --git a/docs/topomojo/copy-paste.md b/docs/topomojo/copy-paste.md index 8768e96..f3a89d6 100644 --- a/docs/topomojo/copy-paste.md +++ b/docs/topomojo/copy-paste.md @@ -1,25 +1,28 @@ -# Copy and paste - -The procedures below show you how to: - -- Copy text from a local machine (an *out of game* computer) and paste it into an *in game* virtual machine -- Copy text from a virtual machine and paste it into a local machine - -*The VM console cog icon:* - -![console-cog](img/console-cog.png) - -## From local ("out of game") to "in game" - -1. On your local machine select, then copy, the content you want to place into a launched virtual machine. -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`. -3. In the VM, select where you want the copied text to go (this can be a new file or an open application, etc.). -4. Under **Clipboard**, click **Paste**. This inserts the copied content into the virtual machine. -![console-paste](img/console-paste.png) - -## From "in game" to "out of game" - -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`). -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. -![console-copy](img/console-copy.png) +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Copy and paste + +The procedures below show you how to: + +- Copy text from a local machine (an *out of game* computer) and paste it into an *in game* virtual machine +- Copy text from a virtual machine and paste it into a local machine + +*The VM console cog icon:* + +![console-cog](img/console-cog.png) + +## From local ("out of game") to "in game" + +1. On your local machine select, then copy, the content you want to place into a launched virtual machine. +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`. +3. In the VM, select where you want the copied text to go (this can be a new file or an open application, etc.). +4. Under **Clipboard**, click **Paste**. This inserts the copied content into the virtual machine. +![console-paste](img/console-paste.png) + +## From "in game" to "out of game" + +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`). +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. +![console-copy](img/console-copy.png) 3. On your local machine, paste the copied text into an application using right-click Paste or `ctrl+V`. \ No newline at end of file diff --git a/docs/topomojo/files.md b/docs/topomojo/files.md index e2c9a25..b5774f9 100644 --- a/docs/topomojo/files.md +++ b/docs/topomojo/files.md @@ -1,23 +1,26 @@ -The **Files** page in the Topo workspace allows you to upload files from your system to TopoMojo to include in your lab. These files are used as ISOs that can be attached to VMs in the workspace. If your files aren’t already in an ISO file format, TopoMojo wraps them in an ISO after upload. - -!!! note - - For ISO uploads to work, TopoMojo needs an NFS (Network File System) datastore presented to vSphere and Topo must be able to access it. - -The **Files** tab in TopoMojo is where ISO files are uploaded to attach to virtual machines. Supply the ISO that you want to attach to your VM here to provide additional resources to a VM that might not be included in the original VM. ISO files are disk images that can be mounted as virtual CD drives on the VM. You want to attach an ISO when you need additional software, datasets, or other resources. - -**Drag and Drop:** Admins drag their ISO file into the box on Files tab or browse to locate it on their own device. - -By default, the **Local** filter is applied so it only displays ISOs available in the current workspace. - -When you upload an ISO file in the box, 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. - -*Screen print 1: GUID and Local filter applied* - -![iso-drag](img/iso-drag.png) - -When the **Local** filter is removed, *all* of the ISOs in the global folder on the NFS data store can be seen. (The folder name will contain a GUID of all zeros.) These global ISOs are available to every workspace in TopoMojo. - -ISOs can be attached 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 an ISO is selected here, the ISO will be attached to the VM upon its deployment. - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +The **Files** page in the Topo workspace allows you to upload files from your system to TopoMojo to include in your lab. These files are used as ISOs that can be attached to VMs in the workspace. If your files aren’t already in an ISO file format, TopoMojo wraps them in an ISO after upload. + +!!! note + + For ISO uploads to work, TopoMojo needs an NFS (Network File System) datastore presented to vSphere and Topo must be able to access it. + +The **Files** tab in TopoMojo is where ISO files are uploaded to attach to virtual machines. Supply the ISO that you want to attach to your VM here to provide additional resources to a VM that might not be included in the original VM. ISO files are disk images that can be mounted as virtual CD drives on the VM. You want to attach an ISO when you need additional software, datasets, or other resources. + +**Drag and Drop:** Admins drag their ISO file into the box on Files tab or browse to locate it on their own device. + +By default, the **Local** filter is applied so it only displays ISOs available in the current workspace. + +When you upload an ISO file in the box, 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. + +*Screen print 1: GUID and Local filter applied* + +![iso-drag](img/iso-drag.png) + +When the **Local** filter is removed, *all* of the ISOs in the global folder on the NFS data store can be seen. (The folder name will contain a GUID of all zeros.) These global ISOs are available to every workspace in TopoMojo. + +ISOs can be attached 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 an ISO is selected here, the ISO will be attached to the VM upon its deployment. + ISOs can also be attached to a VM by using the workspace **Challenge** tab's **Variant Detail** function. This is called "dynamic ISO attachment" and 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. \ No newline at end of file diff --git a/docs/topomojo/finding-a-space.md b/docs/topomojo/finding-a-space.md index 7d1a492..134285e 100644 --- a/docs/topomojo/finding-a-space.md +++ b/docs/topomojo/finding-a-space.md @@ -1,9 +1,12 @@ -# Finding a space - -Once you're in Topo, 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. Topo labs are sorted alphabetically by name. - -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. - -![end and invite](img/end-invite-timer.png) - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Finding a space + +Once you're in Topo, 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. Topo labs are sorted alphabetically by name. + +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. + +![end and invite](img/end-invite-timer.png) + The timer counts down how much remaining time you have before the gamespace expires. \ No newline at end of file diff --git a/docs/topomojo/getting-started.md b/docs/topomojo/getting-started.md index 4fa431e..5726d24 100644 --- a/docs/topomojo/getting-started.md +++ b/docs/topomojo/getting-started.md @@ -1,36 +1,39 @@ -# Getting started - -## What's new - -Get the latest Topo source code and its accompanying release notes [here](github.com/cmu-sei/TopoMojo/releases). - -## Installing - -Installing Topo 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 Topo chart contains two sub-charts: `topomojo-api` and `topomojo-ui`. The `api` and the `ui` are different apps and need to be deployed separately. - -!!! info - - This structure is consistent with the other Foundry apps: there is an `api` piece and a `ui` piece. - -**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. - -## Persistent/Shared Networks - -Having a persistent/shared network available to all TopoMojo workspaces/gamespaces is recommended. The persistent/shared network is defined by an administrator at the time the TopoMojo API is deployed. - -Use case: create a persistent/shared network that provides internet access to all TopoMojo VMs that specify the network name (e.g., `bridge-net` signifies bridging the traditionally isolated TopoMojo VM to the internet). - -Use the `Pod__Vlan__Reservations` environment variable to define the name of a persistent/shared network. See screen print 1 below. - -- `Pod__Vlan__Reservations__0__Id:` defines the vlan Id (from the hypervisor) that corresponds to the shared/persistent network. -- `Pod__Vlan__Reservations__0__Name:` defines the name of the persistent/shared network. - -More than one shared/persistent network can be defined 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. - -!!! note "A note about bridge-net" - - "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 Topo documentation. - -*Screen print 1:* - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Getting started + +## What's new + +Get the latest Topo source code and its accompanying release notes [here](github.com/cmu-sei/TopoMojo/releases). + +## Installing + +Installing Topo 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 Topo chart contains two sub-charts: `topomojo-api` and `topomojo-ui`. The `api` and the `ui` are different apps and need to be deployed separately. + +!!! info + + This structure is consistent with the other Foundry apps: there is an `api` piece and a `ui` piece. + +**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. + +## Persistent/Shared Networks + +Having a persistent/shared network available to all TopoMojo workspaces/gamespaces is recommended. The persistent/shared network is defined by an administrator at the time the TopoMojo API is deployed. + +Use case: create a persistent/shared network that provides internet access to all TopoMojo VMs that specify the network name (e.g., `bridge-net` signifies bridging the traditionally isolated TopoMojo VM to the internet). + +Use the `Pod__Vlan__Reservations` environment variable to define the name of a persistent/shared network. See screen print 1 below. + +- `Pod__Vlan__Reservations__0__Id:` defines the vlan Id (from the hypervisor) that corresponds to the shared/persistent network. +- `Pod__Vlan__Reservations__0__Name:` defines the name of the persistent/shared network. + +More than one shared/persistent network can be defined 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. + +!!! note "A note about bridge-net" + + "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 Topo documentation. + +*Screen print 1:* + ![bridge-net](img/bridge-net.png) \ No newline at end of file diff --git a/docs/topomojo/index.md b/docs/topomojo/index.md index 4979384..b54c06f 100644 --- a/docs/topomojo/index.md +++ b/docs/topomojo/index.md @@ -1,3 +1,6 @@ +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). # TopoMojo Docs This documentation introduces users to the TopoMojo environment and provides information necessary to launch existing labs and create new topologies. diff --git a/docs/topomojo/lab-document.md b/docs/topomojo/lab-document.md index b76aae8..9c76b45 100644 --- a/docs/topomojo/lab-document.md +++ b/docs/topomojo/lab-document.md @@ -1,25 +1,28 @@ -# Lab Document - -The **Document** tab in a Topo workspace is where you write the instructions that correspond with your lab. Instructions are authored in Markdown using Topo's built-in editor. Authoring in Markdown enables you to create a nicely formatted document without writing HTML. - -The Topo 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) your updates to the document are being saved. - -More information about Markdown, including the syntax guide, can be found at [markdownguide.org](https://www.markdownguide.org/). - -## Inserting an image - -To insert an image into your document: - -1. Click **Images**, then click **Browse** (you can drag and drop too). -2. After browsing to upload an image, you should see a preview of the image. -3. Place your cursor in the document where you want the image, hover over the image, and click **Insert**. - -## Previewing the doc - -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. - -![markdown-editor](img/markdown-editor.png) - -and - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +# Lab Document + +The **Document** tab in a Topo workspace is where you write the instructions that correspond with your lab. Instructions are authored in Markdown using Topo's built-in editor. Authoring in Markdown enables you to create a nicely formatted document without writing HTML. + +The Topo 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) your updates to the document are being saved. + +More information about Markdown, including the syntax guide, can be found at [markdownguide.org](https://www.markdownguide.org/). + +## Inserting an image + +To insert an image into your document: + +1. Click **Images**, then click **Browse** (you can drag and drop too). +2. After browsing to upload an image, you should see a preview of the image. +3. Place your cursor in the document where you want the image, hover over the image, and click **Insert**. + +## Previewing the doc + +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. + +![markdown-editor](img/markdown-editor.png) + +and + ![markdown-preview](img/markdown-preview.png) \ No newline at end of file diff --git a/docs/topomojo/play.md b/docs/topomojo/play.md index 129bc55..fb49d80 100644 --- a/docs/topomojo/play.md +++ b/docs/topomojo/play.md @@ -1,13 +1,16 @@ -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. - -**Variant:** Specify which variant of the challenge you wish to play (if it is a *variant* challenge). - -**Max Attempts:** The maximum number of submission attempts allowed when answering questions. - -**Max Minutes:** The maximum number of minutes permitted to play before the gamespace expires. - -**Point Value:** The point value assigned for this challenge when used with Gameboard in a cyber competition scenario. - -**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. - +!!! Warning "" + + :warning: This documentation site has been deprecated and will no longer be updated as of 11/11/24. Foundry applications are now part of the [Crucible Framework](https://cmu-sei.github.io/crucible/). Please find current TopoMojo documentation [here](https://cmu-sei.github.io/crucible/topomojo/). +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. + +**Variant:** Specify which variant of the challenge you wish to play (if it is a *variant* challenge). + +**Max Attempts:** The maximum number of submission attempts allowed when answering questions. + +**Max Minutes:** The maximum number of minutes permitted to play before the gamespace expires. + +**Point Value:** The point value assigned for this challenge when used with Gameboard in a cyber competition scenario. + +**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. + **Reset:** Resets the gamespace. \ No newline at end of file