An unofficial Bash CLI to discover, filter, download, deploy, and track machines from DockerLabs.
Independent project: Not affiliated with or endorsed by DockerLabs. Machines and deployment scripts are third-party content. Review downloaded scripts before running them with elevated privileges, and use labs only in isolated, authorized environments.
- Browse and search the DockerLabs catalog by machine name or full metadata.
- Filter by difficulty, category, author, and completion status.
- Sort results and show colorized tables or JSON output.
- Download machine ZIP archives and validate basic file structure.
- Deploy locally downloaded labs or download and deploy with
run. - Track solved machines independently of downloaded files.
- Synchronize completion with your DockerLabs profile, reading CSRF automatically from your authenticated page when available.
- Cache the online catalog for 24 hours.
- Linux and Bash 4.4+ recommended.
- Catalog/search/download:
curl,jq,perl,file,iconv, and PerlHTML::Parser/HTML::Entities. - Deployment: Docker,
sudo,unzip,zipinfoand standard Unix tools.
For Kali Linux / Debian:
sudo apt update
sudo apt install -y bash curl jq perl libhtml-parser-perl file unzipInstall and configure Docker separately to use deploy and run.
git clone https://github.com/Scan0r/DockerLabCTL.git
cd DockerLabCTL
chmod +x dockerlabctl.sh
sudo install -m 755 dockerlabctl.sh /usr/local/bin/dockerlabctlOr run ./dockerlabctl.sh directly without system-wide installation.
dockerlabctl --helpdockerlabctl list
dockerlabctl list -r
dockerlabctl list -d easy -c 'Hacking Web' -p no
dockerlabctl list -t -b --sort difficulty
dockerlabctl search Analyst -rt
dockerlabctl name analyst
dockerlabctl random -d hard -p no
dockerlabctl info Analyst
dockerlabctl list --json --limit 10name searches machine names only; search also indexes descriptions and other catalog metadata.
dockerlabctl link Analyst
dockerlabctl download Analyst
dockerlabctl download Analyst -o ~/Labs/DockerLabs
dockerlabctl local
dockerlabctl deploy Analyst
# You can also use the catalog ID: dockerlabctl deploy <ID>
dockerlabctl run Analyst
dockerlabctl remove Analyst
# You can also use the catalog ID: dockerlabctl remove <ID>downloadsaves the ZIP without extracting or executing it.deployuses an existing local lab without downloading it. Bothdeployandremoveaccept names or catalog IDs. ID lookups use the cached catalog when available and refresh it if missing; names remain usable offline.rundownloads the lab if needed, then attempts to deploy it.--yesskips confirmation for deployment and local removal. Only use it after reviewing the relevant files.removedeletes local lab files only; it does not stop or delete Docker containers, images, or networks.
Important: Deployment executes a supplied auto_deploy.sh using sudo. These scripts are not independently audited by this project. Some password-protected ZIPs may require manual extraction before deployment.
Progress syntax in --help:
dockerlabctl progress done <Name|All>
dockerlabctl progress fetch <Name|All>
dockerlabctl progress list [local|remote|both] # local is the default
dockerlabctl progress push <Name|All>
dockerlabctl progress undone <Name|All>
NAME... means one or more names or IDs; all is used alone. done/undone all affect locally downloaded machines, whereas fetch/push all traverse the full catalog.
All operations use the progress command. Local changes are the default, and -p / --push explicitly applies the same done or undone operation to the website.
dockerlabctl progress done Analyst # local only
dockerlabctl progress undone Analyst # local only
dockerlabctl progress done Analyst -p # local + website
dockerlabctl progress undone Analyst --push # local + website (long option)
dockerlabctl progress list # local only (default)
dockerlabctl progress list local # explicit local listing
dockerlabctl progress list remote # completed on website
dockerlabctl progress list both # compare both, identify conflicts
dockerlabctl progress fetch Analyst # website -> local
dockerlabctl progress push Analyst # local -> website
dockerlabctl progress fetch all --yes # website -> local, entire catalog
dockerlabctl progress push all --yes # local -> website, entire catalogTo authenticate on Kali Linux, save the Cookie header value from your own logged-in browser in a private file:
mkdir -p ~/.config/dockerlabs
chmod 700 ~/.config/dockerlabs
nano ~/.config/dockerlabs/cookie
chmod 600 ~/.config/dockerlabs/cookieCookie file format (~/.config/dockerlabs/cookie): one line of plain text, without quotes or JSON. For example:
session=YOUR_SESSION_VALUE; cf_clearance=YOUR_CLEARANCE_VALUE
Copy the values from the Cookie header of your own authenticated browser session. The Cookie: prefix is optional. Do not add Bearer, quote marks, or any other HTTP headers.
Optional CSRF file format (~/.config/dockerlabs/csrf): a single token value, with no X-CSRFToken: prefix, quotes, or JSON. For example:
YOUR_CSRF_TOKEN_VALUE
If automatic CSRF detection fails, create the file using umask 077; nano ~/.config/dockerlabs/csrf and then use --csrf-file ~/.config/dockerlabs/csrf. Keep this file out of Git, as with your cookie.
The file can contain session=...; cf_clearance=... or Cookie: session=...; cf_clearance=.... The CLI reads ~/.config/dockerlabs/cookie automatically for remote commands, or you can specify --cookie-file /private/path. Never commit credentials. Prefer the file option over --cookie, which may expose secrets in shell history and process listings. If you have disclosed a real session cookie, sign out/revoke the session and obtain fresh credentials.
The script attempts to extract a CSRF token from the authenticated homepage; use --csrf-file only if automatic extraction fails. This depends on the current DockerLabs site layout and has not been verified with a real signed-in profile.
| Local | Website | fetch (website wins) |
push (local wins) |
|---|---|---|---|
| Completed | Completed | No change | No change |
| Completed | Not completed | Unmark locally | Mark on website |
| Not completed | Completed | Mark locally | Unmark on website |
| Not completed | Not completed | No change | No change |
done -p / done --push and undone -p / undone --push set the explicitly requested state on the website before modifying the local record. Without -p, they only update local progress, even if a cookie is configured. Remote writes first check GET /api/completed_machines/NAME so the toggle endpoint is not called unnecessarily, then verify the result. fetch is read-only for the website. push is an intentional overwrite of website state, including unmarking completed machines. fetch all / push all operate on every catalog machine and require confirmation or --yes, not just locally downloaded machines. done all / undone all operate on downloaded local machines.
-p is context-sensitive: for progress done/undone, it means --push; for list/name/search/random, -p yes/no still filters local completion status. -s remains --sort for catalog commands and is not a progress sync option. The older progress sync command is removed.
If authentication, CSRF parsing, a remote GET, POST or verification fails, the command stops without intentionally changing the local state of that machine. A timed-out POST can still have reached the website. Multiple-machine operations may have successfully updated earlier machines before a later failure; they are not transactional. Concurrent browser changes can race because the website exposes a toggle endpoint rather than an atomic set-state endpoint. Local completion filters (-p yes/no) and progress list (or progress list local) do not query the website. progress list remote lists completed machines from the website; progress list both compares local and website states and reports differences. Remote listing checks each catalog machine and requires authentication, but never changes either state.
| Option | Purpose |
|---|---|
-d, --difficulty |
Filter difficulty (very easy, easy, medium, hard) |
-c, --category |
Filter category |
-a, --author |
Filter author |
-p, --completed |
Filter yes / no |
-l, --limit |
Limit displayed or JSON results |
-p, --push (progress done/undone) |
Also apply the requested state to the website; requires authenticated cookie |
-s, --sort (catalog commands) |
Sort by id, name, difficulty, category, or author |
-t, --description |
Show descriptions |
-b, --bold |
Highlight terms in descriptions (-t required) |
-r, --color |
Colorize table output |
-o, --output |
Use a different local storage directory |
--json |
Output JSON for catalog commands |
--refresh |
Bypass the 24-hour catalog cache |
--cookie, --cookie-file |
Authenticate progress synchronization using a cookie value or private file |
--csrf, --csrf-file |
Override automatic CSRF detection (optional) |
See dockerlabctl --help for the complete reference.
The included tests don't need Docker or access to DockerLabs:
bash -n dockerlabctl.sh
bash tests/tests.shtests/tests.sh creates a temporary mock catalog and checks filtering, sorting, JSON limits, machine lookup, progress tracking, local file removal, and mocked authenticated HTML, CSRF extraction, and profile API responses. GitHub Actions runs these tests on pushes and pull requests.
The test runner prints each named check as [PASS] or [FAIL], followed by a total count and final result. All API tests use a local mock with Analyst; no real profile or Docker deployment is modified.
- Catalog parsing relies on the current HTML layout of the DockerLabs website; changes to its markup could require parser updates.
- Archive filenames are derived automatically from machine names; exceptions may require manual handling.
- Archive checks do not establish that the contents are trustworthy.
- End-to-end deployments are not run in CI.