Metadata-Version: 2.4
Name: aptl-labs
Version: 7.0.0
Summary: Advanced Purple Team Lab CLI
Project-URL: Homepage, https://github.com/OpenRAE/lilrae
Project-URL: Repository, https://github.com/OpenRAE/lilrae
Project-URL: Issues, https://github.com/OpenRAE/lilrae/issues
Author: Brad Edwards
License: MIT
License-File: LICENSE
Keywords: cyber-range,kali,mcp,purple-team,raes,security,wazuh
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.12
Requires-Dist: blake3<2,>=1.0.8
Requires-Dist: cryptography>=50.0.0
Requires-Dist: icontract<3.0,>=2.6.0
Requires-Dist: mcp<3,>=2
Requires-Dist: opentelemetry-api>=1.33.0
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.33.0
Requires-Dist: opentelemetry-sdk>=1.33.0
Requires-Dist: opentelemetry-semantic-conventions>=0.54b0
Requires-Dist: packaging>=24.2
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: raes-env-packs==6.2.1
Requires-Dist: raes==6.0.1
Requires-Dist: rfc8785<0.2.0,>=0.1.4
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: build>=1.2.0; extra == 'dev'
Requires-Dist: coverage>=7.0.0; extra == 'dev'
Requires-Dist: httpx>=0.27.0; extra == 'dev'
Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
Requires-Dist: pyarrow>=17.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.15.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0; extra == 'docs'
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Provides-Extra: parquet
Requires-Dist: pyarrow>=17.0.0; extra == 'parquet'
Provides-Extra: s3
Requires-Dist: boto3>=1.28.0; extra == 's3'
Provides-Extra: web
Requires-Dist: asyncssh>=2.17.0; extra == 'web'
Requires-Dist: fastapi>=0.115.0; extra == 'web'
Requires-Dist: httpx>=0.28.1; extra == 'web'
Requires-Dist: sse-starlette>=2.0.0; extra == 'web'
Requires-Dist: uvicorn[standard]>=0.34.0; extra == 'web'
Description-Content-Type: text/markdown

[![Quality gate](https://sonarcloud.io/api/project_badges/quality_gate?project=Brad-Edwards_aptl&token=4dd88be3421d6d030a4615b86ac8ab0e3c9eb4d3)](https://sonarcloud.io/summary/new_code?id=Brad-Edwards_aptl)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/OpenRAE/lilrae/badge)](https://scorecard.dev/viewer/?uri=github.com/OpenRAE/lilrae)

🎤 **Accepted to [Black Hat USA Arsenal 2026](https://blackhat.com/us-26/arsenal/schedule/#aptl-advanced-purple-team-labs-52322), [SecTor Arsenal 2026](https://blackhat.com/sector/arsenal/schedule/index.html#aptl-advanced-purple-team-labs-54785), and SecTor 2026 Briefings.**

# LilRAE (formerly APTL)

> **APTL is now LilRAE, and `aptl-labs` 7.0.0 is planned as the last
> `aptl-labs` release.** The Advanced Purple Team Lab (APTL) repository moved to
> [github.com/OpenRAE/lilrae](https://github.com/OpenRAE/lilrae) and was
> renamed. It is the same project, with the same source, history, features,
> and issue tracker. Later releases will publish to PyPI as
> [`lilrae`](https://pypi.org/project/lilrae/), starting at version 8.0.0. 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](https://github.com/OpenRAE/lilrae/blob/main/docs/adrs/adr-062-lilrae-name-and-naming-convention.md).
>
> Do not change packages until `lilrae` 8.0.0 or later shows on its PyPI page.
> Until then, keep `aptl-labs`. 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:
>
> ```shell
> pipx uninstall aptl-labs
> pipx install lilrae
> aptl --version
> ```
>
> With pip in a virtual environment, for example with the `[s3]` extra:
>
> ```shell
> python -m pip uninstall aptl-labs
> python -m pip install "lilrae[s3]"
> ```
>
> To roll back after a migration, remove `lilrae`, then install the last legacy
> release:
>
> ```shell
> pipx uninstall lilrae
> pipx install "aptl-labs==7.0.0"
> ```
>
> The [installation guide](https://github.com/OpenRAE/lilrae/blob/main/docs/getting-started/installation.md#move-to-the-lilrae-package)
> 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](docs/getting-started/prerequisites.md#tested-execution-profiles-and-limits).

For stronger host and cross-seat isolation on Linux/KVM, use a disposable
[`aptl seat`](docs/reference/appliance-seat-launcher.md). 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:

```shell
pipx install aptl-labs
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:

```shell
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:

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

Read the [first-lab guide](docs/getting-started/quick-start.md) for scenario
selection, safe activity, result inspection, troubleshooting, and teardown.

## Requirements

- Python 3.12 or newer and [pipx](https://pipx.pypa.io/)
- 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](docs/getting-started/prerequisites.md) for platform-specific
setup and verification.

## Supported Interfaces

- [CLI](docs/reference/cli.md) is the primary lab control plane.
- [MCP servers](docs/reference/mcp.md) give authorized agents scenario-aware
  red- and blue-team tools through generated private client configuration.
- [Web interface](docs/reference/web.md) 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](https://github.com/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](https://openrae.github.io/lilrae/)
- [Installation](docs/getting-started/installation.md)
- [Run your first lab](docs/getting-started/quick-start.md)
- [Troubleshooting](docs/troubleshooting/index.md)
- [Architecture and historical records](docs/architecture/index.md)
- [OpenSSF Best Practices assessment](docs/security/openssf-best-practices.md)

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

## Project Links

- [Get support](https://github.com/OpenRAE/lilrae/blob/dev/SUPPORT.md)
- [Contribute](https://github.com/OpenRAE/lilrae/blob/dev/CONTRIBUTING.md)
- [Report a vulnerability privately](https://github.com/OpenRAE/lilrae/security/advisories/new)
- [Review the OpenSSF Best Practices assessment](docs/security/openssf-best-practices.md)

Do not report suspected vulnerabilities through a public issue. The
[security policy](SECURITY.md) 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
