To build a UGC lab in Lab Builder, create a project, choose your machine settings, add your lab details, deploy the machine, build your lab on it, and save a snapshot. Then import the project into your UGC submission. Lab Builder is available in the OffSec Learning Portal (portal.offsec.com) as a beta feature. Lab Builder currently supports single-VM labs.
Note: The screenshots in this article use example details only, such as the project name, machine name, and flavor. Your details will be different.
What is Lab Builder?
Lab Builder is an OffSec tool that lets you build a lab in your browser. You choose a base image, deploy a machine, connect to it, build your lab on it, and save a snapshot. After that, you import the project into a UGC submission instead of uploading artifacts.zip and a build guide.
You can open Lab Builder in the OffSec Portal at portal.offsec.com/lab-builder.
How do I create a Lab Builder project and set up my machine?
To create a project and choose your machine settings, follow these steps:
- Sign in to the OffSec Learning Portal and open Lab Builder.
- Click + New project, enter a project name, and click Create.
- On the machine card, click the Image field and choose a base image.
- Click the Flavor field and choose a size. Each flavor shows its vCPU, RAM, and disk size. The Flavor field is available after you choose an image.
- Click the Network field and choose the network shown in the list.
- Click Save. The top bar changes from Not saved yet to Saved.
The Configure the base panel shows a check mark for each setting that is complete. Lab Builder gives your machine a generated name. You do not need to change it. Note: The project name helps you find your build. The lab name that learners see is set in Lab details.
How do I add lab details and flags?
To add your lab details, click Lab details in the top bar. Complete these sections:
| Section | What to do |
| 1. Basics | Enter the lab name that learners will see. |
| 2. How is this lab solved? | Select Direct flags and click Add flag, or select Questions. A lab uses flags or questions, not both. A standalone lab needs at least one flag before you can submit it. For each flag, choose the Location (Root or Local) and the Difficulty, and enter the Path of the flag file, for example /root/proof.txt. |
| 3. Machine setup | Optional. Select bash or PowerShell as the Shell and enter your script. The limit is 65,536 characters. |
| 4. Review | Check Before you can submit for anything that is missing. |
To test your setup script, deploy your machine, and then click Run on my machine.
The counter next to Lab details, for example 0/2, shows how many required items are complete. The required items are the lab name, and the flags or questions.
Can I change the image, flavor, or network after I deploy?
No. After you deploy a machine, Lab Builder locks the image, flavor, and network. To change them, save a snapshot, destroy the machine, and deploy again.
How do I deploy my machine and connect to it?
To deploy and connect to your machine, follow these steps:
- Click Deploy stack. The settings lock while the machine deploys, and a timer shows the progress.
- When the status shows that the machine is deployed, install the Tailscale client on your computer if you have not done so.
- Copy the tailscale up command from Lab Builder and run it on your computer.
- Use the machine IP, the login details, and the connection command that Lab Builder shows to sign in to your machine.
After you connect, build your lab on the machine as you would on any other build machine. Before you take your snapshot, change the default root or Administrator password. OffSec does not accept labs that keep the default password.
How do I save a snapshot of my lab?
When your lab is built and working, take a snapshot. A snapshot is required: reviewers deploy a preview of your lab from your snapshot, and without one they get only the base image and do not see your build. To take a snapshot, follow these steps:
- In the Snapshot this machine section, enter a Snapshot name and an optional description.
- Click Snapshot.
- Read the message and click Snapshot now. Lab Builder powers off your machine while it captures the disk, then powers it on again. Anything that is running on the machine stops, and SSH and RDP sessions disconnect.
- Wait for the snapshot to finish. This usually takes 10 to 15 minutes, and longer for a large disk. You can leave or reload the page while it runs.
When the snapshot completes, your project uses it as its base, and the lab template boots from it. Destroy your machine and deploy again to run from the snapshot. Lab Builder also saves the snapshot under My snapshots in the image picker, so you can use it in any of your projects.
The submission form shows a Snapshot ready label on the machine card when a snapshot is complete. The form does not check for a snapshot, so please make sure that you have taken one.
How do I destroy my machine?
When you finish, click Destroy machine in the side panel. The settings stay locked while the machine is destroyed. When it finishes, the status returns to Not deployed and you can edit the settings again.
Please destroy your machine when you are not using it. To change the settings later, snapshot first, destroy the machine, and deploy again.
Lab Builder may also remove a machine that has been idle for a long time. Your project and your snapshots are kept.
How many machines can I deploy at the same time?
Lab Builder limits how many machines you can have deployed at the same time. If you reach the limit, Lab Builder does not start a new deployment. Destroy a machine that you no longer need, and then deploy again. The Other machines section on the Lab Builder Projects page lists machines that are not part of one of your projects, and each one has a Destroy button.
What should I do if my deploy fails?
If a deploy fails, Lab Builder shows a Last deploy failed message with the reason. Click Dismiss, check your image, flavor, and network settings, and click Deploy stack again. If a deploy stays in progress for a long time, Lab Builder marks it as failed.
If the problem continues, please contact OffSec Support and include your project name, the time of the error, and a screenshot.
What should I do if my snapshot fails?
If a snapshot fails, check your lab details before you try again. The page can reset when a snapshot fails, so copy your setup script and notes to a separate file before you click Snapshot.
If the problem continues, please contact OffSec Support and include your Discord name and ID, project name, and a screenshot.