Skip to content

Sandbox environment integration

The Inject Exercise Platform (IXP) allows integration with sandbox virtual machines (VMs) to facilitate hands-on exercises for trainees. This integration enables instructors to capture and analyze the commands executed by trainees within the VM, providing valuable insights into their actions and decision-making processes.

Sandbox exercises

To facilitate an exercise with sandbox integration, follow the steps outlined below:

1. Exercise initiation (Instructor view)

  1. In the Exercise Panel, create an exercise and select "Enable log collection" inside the dialog.
  2. Assign trainees to teams within the exercise, ensuring a 1:1 mapping between users and teams.
  3. If the exercise is not on-demand, start the exercise.

2. Exercise execution (Trainee view)

  1. Enter the exercise.
  2. Open the "Sandbox configuration" dialog from the sidebar, and download the provided config.env file.
  3. Move the config.env file into your local client configuration directory and rename it to .env.
  4. Start the sandbox environment using the provided Docker Compose configuration.
  5. Solve the exercise tasks shown in the IXP interface while executing commands in the attacker container of the sandbox environment.

3. Command log analysis (Analyst view)

  1. Analyze the captured command logs in the Analyst view. The logs are shown in the Activity Log and on the Cause and Effect page alongside other trainee activities, and in a dedicated Command Logs page.

Test command logging

To test the command logging functionality, you can use the following curl command to send a test log entry to the IXP backend. Make sure to set the environment variables INJECT_HOST and INJECT_TEAM_TOKEN with the appropriate values from your config.env file before running the command:

curl -X POST "$INJECT_HOST" \
     -H "team-token: $INJECT_TEAM_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
          "@timestamp": "'$(date -u +"%Y-%m-%dT%H:%M:%SZ")'",
          "cmd": "echo \"This is a test command.\"",
          "cmd_source": "curl",
          "working_directory": "'"$PWD"'",
          "container": "-",
          "username": "'"$USER"'"
     }'

OpenSearch integration

The sandbox environment can be configured to send command logs to both the IXP backend and an OpenSearch instance. To set up OpenSearch integration, set up the following environment variables in your .env file when deploying the IXP. Otherwise, the user flow does not change:

  • INJECT_OPENSEARCH_HOST – OpenSearch host address for the OpenSearch service.
  • VITE_OPENSEARCH_HOST – OpenSearch host address exposed to frontend clients.
  • INJECT_OPENSEARCH_PORT – OpenSearch port number for connecting to the OpenSearch service.
  • VITE_OPENSEARCH_PORT – OpenSearch port number exposed to frontend clients.
  • INJECT_OPENSEARCH_USER – Username for authenticating with OpenSearch using an admin account.
  • INJECT_OPENSEARCH_PASSWORD – Password for the OpenSearch user account.

Limitations

Admin users

Admin users cannot access their INJECT_TEAM_TOKEN from the Sandbox Configuration dialog. If an admin downloads the config.env file, the INJECT_TEAM_TOKEN value in the config.env file will be empty.

As a workaround, admins can retrieve the INJECT_TEAM_TOKEN from the exercise details in the Exercise Panel, as they have access to all exercises.

Not-assigned users

Only the users assigned to the team can retrieve the INJECT_TEAM_TOKEN from the Sandbox Configuration dialog. If an instructor or admin user enters the trainee view of a team they are not assigned to and downloads the config.env file, the INJECT_TEAM_TOKEN value in the config.env file will be empty.

As a workaround, instructors and admins can retrieve the INJECT_TEAM_TOKEN from the exercise details in the Exercise Panel, as they have access to such exercises.

In-exercise time

In-exercise time is currently not implemented for sandbox command logs. The in-exercise time for command logs is set to 0, so if in-exercise time format is selected, the command logs timestamp will be shown as 00:00:00.

Non-running exercises

With a valid INJECT_TEAM_TOKEN for the team, command logs can be sent to the IXP backend, even if the exercise is not running. In such cases, the command logs will be stored in the backend and will be visible in the Analyst view, but their timestamps will lie outside of the exercise time range.

Exercise logs download timeout

Downloading exercise logs for high-volume command log exercises may result in a timeout. In such cases, the download results in an invalid ZIP file containing the timeout error message.

In the current version (5), the only way to retrieve the exercise logs is to extend the Nginx timeout. In version 6, the download will be optimized to avoid such issues.