🎤 Accepted to Black Hat USA Arsenal 2026, SecTor Arsenal 2026, and SecTor 2026 Briefings.

LilRAE (formerly APTL)

APTL is now LilRAE, and the package is now lilrae. The Advanced Purple Team Lab (APTL) repository moved to github.com/OpenRAE/lilrae and was renamed. It is the same project, with the same source, history, features, and issue tracker. Releases publish to PyPI as lilrae from version 8.0.0. aptl-labs 7.0.0 was the last aptl-labs release. The import package is still aptl, the command is still aptl, and existing configuration, state directories, and runtime identifiers keep their aptl names. Where current pages still say APTL, they mean LilRAE. See ADR-062.

The two distributions install the same aptl package and commands. Do not install lilrae over aptl-labs, because one installation overwrites the files of the other. Remove aptl-labs first, then install lilrae with the same extras.

With pipx:

pipx uninstall aptl-labs
pipx install lilrae
aptl --version

With pip in a virtual environment, for example with the [s3] extra:

python -m pip uninstall aptl-labs
python -m pip install "lilrae[s3]"

To roll back, remove lilrae, then install the last legacy release:

pipx uninstall lilrae
pipx install "aptl-labs==7.0.0"

The installation guide has the full procedure. All earlier aptl-labs releases stay on PyPI.

LilRAE is a local purple-team lab where human operators and AI agents exercise red- and blue-team workflows against an intentionally vulnerable enterprise range. Scenario documents select and realize the target, attacker, and SOC topology; the CLI owns validation, startup, readiness, access discovery, teardown, and run records.

Use cases include autonomous cyber-operations research, purple-team training, and AI threat-actor assessment.

Status And Safety

Active development. Not for production. Not hardened. LilRAE gives AI agents penetration-testing tools and starts intentionally vulnerable services. Use a dedicated, rebuildable host, keep unrelated credentials and workloads elsewhere, control the surrounding network, and operate only on systems you are authorized to test.

Ordinary aptl lab start uses the selected Docker daemon. On native Linux that can give the lab and its control components authority over the physical host's Docker engine; Docker Desktop or another Docker VM changes that placement but is not, by its name alone, a qualified containment boundary. aptl lab start and aptl lab info report the observed transport and boundary, or unknown when they cannot establish one. See tested profiles, host exposure and limits.

For stronger host and cross-seat isolation on Linux/KVM, use a disposable aptl seat. A VM boundary reduces risk but does not eliminate it; keep the host kernel and hypervisor current. A seat needs KVM, QEMU, OVMF, adequate per-seat resources and a verified image; it does not make the workloads inside its guest mutually isolated. Seats have no default outbound network controls. The guest can initiate ordinary internet and LAN connections through user-mode NAT, subject to the host network and any rules defined by the selected scenario. Event-specific outbound restrictions are the operator's responsibility.

Quick Start

Install the released CLI and materialize its bundled lab assets. No source checkout is required:

pipx install lilrae
aptl lab init my-lab
cd my-lab
aptl lab start --scenario techvault

Startup validates the selected scenario, creates private project state, realizes the topology, waits for required readiness checks, and reports a structured outcome with the observed execution boundary. Inspect the fresh runtime-derived state, boundary and access information:

aptl lab status
aptl lab info
aptl container list

URLs, host ports, available containers, usernames, and credential locations belong to the realized project. Use aptl lab info; do not rely on static values copied from documentation.

At the end of the session:

aptl lab stop      # preserve project volumes
aptl lab stop -v   # confirm and destroy project volume data

Read the first-lab guide for scenario selection, safe activity, result inspection, troubleshooting, and teardown.

Requirements

• Python 3.12 or newer and pipx
• Docker Engine 28.0 or newer (native, or inside Docker Desktop or Colima) with Compose and Buildx, on a cgroup v2 host
• OpenSSH client with ssh-keygen on PATH
• Node.js 20 or newer and npm for MCP artifact builds
• 20GB or more of free disk space
• Sufficient Docker memory for the selected scenario; the full acquired TechVault stack needs more than 20GB

See Prerequisites for platform-specific setup and verification.

Supported Interfaces

• CLI is the primary lab control plane.
• MCP servers give authorized agents scenario-aware red- and blue-team tools through generated private client configuration.
• Web interface provides a loopback-first local operator UI and typed API.

The APTL operator UI, vulnerable target applications, and third-party SOC interfaces are separate surfaces. The selected scenario determines which ones exist.

Scenarios

The APTL startup catalog exposes the scenario selections supported by the installed release. Reusable environment-pack definitions and authoring support live in the companion OpenRAE/env-packs repository; APTL owns admission, realization, readiness, and operation of the selected scenario in the local lab.

Documentation

The published site is the canonical user manual:

• Documentation home
• Installation
• Run your first lab
• Troubleshooting
• Architecture and historical records
• OpenSSF Best Practices assessment

The README is the GitHub and package-index gateway, not a second copy of the manual.

Project Links

• Get support
• Contribute
• Report a vulnerability privately
• Review the OpenSSF Best Practices assessment

Do not report suspected vulnerabilities through a public issue. The security policy describes scope and the private fallback contact path.

Ethics And Disclaimer

APTL uses commodity services and standard security tooling. AI agents get Kali access; this public repository does not add red-team enhancements to their latent capabilities. You are responsible for following all applicable laws and for obtaining authorization before testing a system.

The repository contains intentional test credentials used only by lab fixtures. They are not production secrets. Runtime control-plane credentials are generated into private project files and must not be committed or shared.

License

MIT