lilrae 8.0.0__py3-none-any.whl

aptl/__init__.py

@@ -0,0 +1,9 @@
+"""Advanced Purple Team Lab CLI."""
+
+# Version is bumped by release-please in lockstep with pyproject.toml on every
+# release, via the `extra-files` entry in release-please-config.json plus the
+# `x-release-please-version` annotation below (the python updater only rewrites
+# pyproject.toml, not this src-layout __init__.py). Keep the annotation comment
+# on the same line as the literal, and keep the literal equal to pyproject's
+# `version` — test_version_consistency.py enforces the latter.
+__version__ = "8.0.0"  # x-release-please-version

aptl/_asset_manifest.py

@@ -0,0 +1,91 @@
+"""Single source of truth for the bundled lab-asset manifest (DEP-008).
+
+This module is imported by *two* consumers that run in different
+environments, so it must stay dependency-free (standard library only):
+
+* ``aptl.core.assets`` (runtime) — decides what a source checkout
+  materializes into a lab project directory.
+* ``hatch_build.py`` (build time) — decides what the wheel ships under
+  ``aptl/_labdata/``. The build environment only has build backend
+  dependencies, so this module must not import pydantic, typer, or any
+  other runtime dependency.
+
+Keeping the manifest here means the wheel's bundled asset set and a
+checkout's materialized set can never drift.
+"""
+
+from __future__ import annotations
+
+# Top-level asset roots bundled into the wheel and materialized by
+# ``aptl lab init``. Each tracked file maps to the same relative path.
+# Derived from docker-compose.yml build contexts and bind mounts plus the
+# host-side steps in ``aptl lab start`` (issue #659):
+#   - several services build with ``context: .`` and
+#     ``COPY pyproject.toml README.md src`` + ``pip install .``
+#     (misp-suricata-sync, web API), so those + ``hatch_build.py`` (a declared
+#     wheel build hook) are needed;
+#   - ``web/`` is its own build context and ``scripts/`` is bind-mounted;
+#   - ``mcp/`` holds ``build-all-mcps.sh`` and the MCP server sources that the
+#     ``build_mcps`` start step compiles (needs node/npm on the host);
+#   - ``.mcp.json.example`` seeds MCP client config; ``.dockerignore`` keeps
+#     build contexts lean.
+# ``keys/`` and ``.aptl/`` are generated at lab start (zero tracked files) and
+# are intentionally absent.
+ASSET_ROOTS: tuple[str, ...] = (
+    "docker-compose.yml",
+    "docker-compose.observability.yml",
+    "docker-compose.capture.yml",
+    ".dockerignore",
+    "generate-indexer-certs.yml",
+    ".env.example",
+    ".mcp.json.example",
+    "pyproject.toml",
+    "uv.lock",
+    "requirements",
+    "README.md",
+    "hatch_build.py",
+    "src",
+    "participant-profiles/techvault-full-v1",
+    "appliance",
+    "config",
+    "containers",
+    "web",
+    "scripts",
+    "mcp",
+)
+
+# Presence of this file marks a full lab-distribution build context. Minimal
+# package build contexts — e.g. the service container images that
+# ``COPY pyproject.toml README.md src`` then ``pip install .`` — do not carry
+# it, so the build hook skips asset bundling there (issue #659 review): those
+# images must still load the declared hook (hatch_build.py is copied in), but
+# must not pull the multi-megabyte lab bundle into a service wheel.
+DISTRIBUTION_MARKER = "docker-compose.yml"
+
+# Directory names never bundled even beneath a tracked root. Only consulted
+# by the no-git walk fallback; ``git ls-files`` already omits every one.
+# Mirrors the gitignored secret/state and dev-artifact directories so a
+# fallback selection cannot ship them.
+EXCLUDED_DIR_NAMES: frozenset[str] = frozenset(
+    {
+        "__pycache__",
+        "node_modules",
+        ".venv",
+        "dist",
+        "build",
+        ".mypy_cache",
+        ".ruff_cache",
+        ".pytest_cache",
+        ".hypothesis",
+        ".git",
+        "soc_certs",
+        "lab-ssh",
+        "wazuh_indexer_ssl_certs",
+    }
+)
+
+EXCLUDED_SUFFIXES: tuple[str, ...] = (".pyc", ".pyo")
+
+# Where the bundle lives inside the wheel / installed package.
+LABDATA_DIRNAME = "_labdata"
+LABDATA_PREFIX = f"aptl/{LABDATA_DIRNAME}"

aptl/_labdata/.dockerignore

@@ -0,0 +1,26 @@
+.git
+.github
+.venv
+.pytest_cache
+.mypy_cache
+__pycache__
+*.pyc
+node_modules
+**/node_modules
+# `containers/` is intentionally NOT excluded: the in-process target
+# images (ad / dns / fileshare / webapp; issue #248) and the remaining
+# `wazuh-sidecar` image build from the repo root and need access to the
+# shared `containers/_wazuh-agent/` files plus their own per-container
+# subdirectory. Per-container build contexts (victim, workstation, kali,
+# etc.) read their own `.dockerignore` so they're unaffected.
+docs/
+notes/
+coverage.xml
+.coverage
+*.egg-info
+dist/
+build/
+.svelte-kit
+web/node_modules
+web/.svelte-kit
+web/tests

aptl/_labdata/.env.example

@@ -0,0 +1,84 @@
+# APTL Lab Credentials
+# Copy this file to .env; `aptl lab start` hydrates it, filling every
+# CHANGE_ME placeholder with a runnable value (randomizing real secrets). You
+# only need to supply values you specifically want to pin.
+# The .env file is gitignored and will not be committed.
+#
+# NOTE: INDEXER_* and DASHBOARD_* below are NOT user-selectable. They must match
+# the OpenSearch demo-user hashes baked into the checked-in
+# config/wazuh_indexer/internal_users.yml (admin=SecretPassword,
+# kibanaserver=kibanaserver); the indexer never recomputes those hashes from
+# .env. Leave the placeholders (hydration fills the correct fixtures) or set the
+# exact fixture values. Any other value is reconciled back at start with a
+# warning, because the indexer would otherwise reject it.
+
+# Wazuh Indexer / OpenSearch admin credentials (auto-managed fixture)
+INDEXER_USERNAME=admin
+INDEXER_PASSWORD=CHANGE_ME_indexer_password
+
+# Wazuh Dashboard internal user (auto-managed fixture)
+DASHBOARD_USERNAME=kibanaserver
+DASHBOARD_PASSWORD=CHANGE_ME_dashboard_password
+
+# Wazuh API credentials
+API_USERNAME=wazuh-wui
+API_PASSWORD=CHANGE_ME_api_password
+
+# Wazuh cluster key
+WAZUH_CLUSTER_KEY=CHANGE_ME_cluster_key
+
+# Web control-plane API token (ADR-039). Required when running the optional
+# aptl-web-api and aptl-web-ui services. The API rejects missing, empty, or
+# placeholder values at runtime. Generate a real token with:
+#   python3 -c 'import secrets; print(secrets.token_hex(32))'
+APTL_API_TOKEN=CHANGE_ME_api_token
+
+# Identity of the aptl-web-api container (issue #1193). It never runs as root:
+# it runs as the user that owns this project (the one who runs `aptl lab
+# start`), so it can read the owner-only lab state under .aptl/, and joins only
+# the Docker socket's group. Set both from the project owner's shell:
+#   echo "APTL_WEB_API_USER=$(id -u):$(id -g)"
+#   echo "APTL_DOCKER_SOCKET_GID=$(stat -c %g /var/run/docker.sock)"
+# Left unset, the web API container refuses to start.
+APTL_WEB_API_USER=CHANGE_ME_uid:gid
+APTL_DOCKER_SOCKET_GID=CHANGE_ME_docker_socket_gid
+
+# Enterprise services
+DB_PASSWORD=techvault_db_pass
+AD_ADMIN_PASSWORD=Admin123!
+
+# SOC tools
+MISP_ADMIN_PASSWORD=MispAdmin2024!
+# MISP REST API auth key. Used by both the MISP server (as ADMIN_KEY) and
+# every downstream consumer (aptl-misp-suricata-sync, mcp-threatintel, etc.).
+# Generate a fresh 40-character alphanumeric value with:
+#   tr -dc A-Za-z0-9 </dev/urandom | head -c 40 ; echo
+# The placeholder below is rejected by aptl-misp-suricata-sync at startup
+# so the lab fails loudly if you forget to replace it.
+MISP_API_KEY=PLEASEREPLACEMEPLEASEREPLACEMEPLEASEREPLACE
+# TLS verification for SOC stack consumers connecting to MISP.
+# SEC-006 / ADR-034 (issue #258) made the lab-managed CA the default
+# trust anchor: ServiceConfig defaults MISP_VERIFY_SSL to true, and the
+# misp-suricata-sync container mounts the CA bundle at
+# /etc/lab-ca/lab-ca.pem. Leaving these lines commented out (or unset)
+# lets the in-code defaults win. Override only for local debugging, e.g.
+# while iterating on a self-signed MISP fork:
+#   MISP_VERIFY_SSL=false
+#   MISP_CA_CERT_PATH=
+# MISP_VERIFY_SSL=true
+# MISP_CA_CERT_PATH=/etc/lab-ca/lab-ca.pem
+THEHIVE_SECRET=aptl-thehive-lab-secret-key-2024-purple
+SHUFFLE_ADMIN_PASSWORD=ShuffleAdmin2024!
+SHUFFLE_API_KEY=31a211c4-ea5c-4a49-b022-5e2434e758a7
+
+# Grafana (OTel observability stack)
+GRAFANA_ADMIN_USER=admin
+GRAFANA_ADMIN_PASSWORD=CHANGE_ME_grafana_password
+
+# Host-port publishing. Every service's published host port has a
+# `${APTL_HP_<SERVICE>_<PORT>:-default}` override. `aptl lab start` probes
+# each default and, if it is already in use on this host (e.g. an editor's
+# port-forwarding, another app), automatically publishes that service on a
+# free port instead and reports the real port in the start summary. Set any of
+# these to pin a specific port; a value you set here is always honored as-is.
+# APTL_HP_WAZUH_DASHBOARD_5601=443

aptl/_labdata/.mcp.json.example

@@ -0,0 +1,53 @@
+{
+  "mcpServers": {
+    "aptl-red": {
+      "command": "node",
+      "args": ["./mcp/mcp-red/build/index.js"],
+      "env": {
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
+      }
+    },
+    "aptl-indexer": {
+      "command": "node",
+      "args": ["./mcp/mcp-indexer/build/index.js"],
+      "env": {
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
+      }
+    },
+    "aptl-wazuh": {
+      "command": "node",
+      "args": ["./mcp/mcp-wazuh/build/index.js"],
+      "env": {
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
+      }
+    },
+    "aptl-network": {
+      "command": "node",
+      "args": ["./mcp/mcp-network/build/index.js"],
+      "env": {
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
+      }
+    },
+    "aptl-threatintel": {
+      "command": "node",
+      "args": ["./mcp/mcp-threatintel/build/index.js"],
+      "env": {
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
+      }
+    },
+    "aptl-casemgmt": {
+      "command": "node",
+      "args": ["./mcp/mcp-casemgmt/build/index.js"],
+      "env": {
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
+      }
+    },
+    "aptl-soar": {
+      "command": "node",
+      "args": ["./mcp/mcp-soar/build/index.js"],
+      "env": {
+        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
+      }
+    }
+  }
+}

aptl/_labdata/README.md

@@ -0,0 +1,194 @@
+[![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 the package is now `lilrae`.** 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. Releases publish to PyPI as
+> [`lilrae`](https://pypi.org/project/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](https://github.com/OpenRAE/lilrae/blob/main/docs/adrs/adr-062-lilrae-name-and-naming-convention.md).
+>
+> 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, 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-from-aptl-labs-to-lilrae)
+> 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 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:
+
+```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

aptl/_labdata/appliance/guest/aptl-appliance-first-boot

@@ -0,0 +1,50 @@
+#!/bin/sh
+# Start the already-provisioned seat inside its disposable overlay.
+set -eu
+umask 077
+
+# shellcheck disable=SC1091
+. /etc/aptl/appliance-release.env
+: "${APTL_SEAT_COMMIT:?missing baked seat identity}"
+test -r /run/aptl-launch/appliance-launch.json
+test -r /run/aptl-launch/boundary-policy.json
+test -r /opt/aptl/offline/oci-images.tar
+guest_python=/usr/bin/python3
+guest_path=/opt/aptl/app:/opt/aptl/python
+
+# Apply the descriptor-bound account choice before xrdp or the browser desktop
+# can accept a participant login. The root lab service retains Docker access.
+PYTHONPATH="$guest_path" "$guest_python" /opt/aptl/desktop/seat-privileges.py
+
+install -d -m 0700 /var/lib/aptl/overlay
+images_loaded=/var/lib/aptl/overlay/images-loaded
+if test ! -f "$images_loaded"; then
+    docker load --input /opt/aptl/offline/oci-images.tar
+    marker=$(mktemp /var/lib/aptl/overlay/.images-loaded.XXXXXX)
+    sha256sum /opt/aptl/offline/oci-images.tar >"$marker"
+    chmod 0600 "$marker"
+    mv "$marker" "$images_loaded"
+else
+    /usr/local/bin/aptl kill --containers --project-dir /opt/aptl/project
+fi
+
+# The desktop account and Guacamole connection are configured in this overlay.
+# Only the gateway's loopback HTTP port is forwarded to the physical host.
+rm -f /home/aptl/.config/aptl/run-ready
+/usr/local/bin/start-seat-desktop
+
+PYTHONPATH="$guest_path" "$guest_python" -m aptl.appliance.guest_services proxy &
+proxy_pid=$!
+cleanup() {
+    kill "$proxy_pid" 2>/dev/null || true
+}
+trap cleanup EXIT INT TERM
+
+/usr/local/bin/aptl lab start \
+    --project-dir /opt/aptl/project \
+    --offline-staged \
+    --appliance-launch-descriptor /run/aptl-launch/appliance-launch.json \
+    --appliance-readiness-challenge /run/aptl-launch/readiness-challenge.json \
+    --appliance-readiness-device /dev/virtio-ports/org.aptl.readiness
+
+wait "$proxy_pid"

aptl/_labdata/appliance/guest/aptl-appliance-first-boot.service

@@ -0,0 +1,23 @@
+[Unit]
+Description=APTL disposable appliance first-boot readiness
+After=docker.service network-online.target
+After=run-aptl\x2dlaunch.mount
+Requires=docker.service
+Requires=run-aptl\x2dlaunch.mount
+Wants=network-online.target
+
+[Service]
+Type=exec
+ExecStart=/usr/local/libexec/aptl-appliance-first-boot
+Environment=HOME=/var/lib/aptl
+Environment=APTL_SEAT_DESKTOP_HANDOFF=1
+Environment=APTL_SEAT_DESKTOP_MCP_SMOKE=1
+UMask=0077
+NoNewPrivileges=true
+PrivateTmp=true
+ProtectHome=false
+ProtectSystem=strict
+ReadWritePaths=/var/lib/aptl /opt/aptl/project /home/aptl /etc /usr/local/share/ca-certificates
+
+[Install]
+WantedBy=multi-user.target

aptl/_labdata/appliance/guest/aptl-launch.mount

@@ -0,0 +1,12 @@
+[Unit]
+Description=APTL read-only appliance launch inputs
+Before=aptl-appliance-first-boot.service
+
+[Mount]
+What=aptl-launch
+Where=/run/aptl-launch
+Type=9p
+Options=trans=virtio,version=9p2000.L,ro
+
+[Install]
+WantedBy=multi-user.target