Strix (STRIX) — runtime module

docs / modules / runtime

Strix (STRIX) — runtime

flowchart LR IN["IN: scan_id, sandbox image,\nlocal_sources to mount"] --> ACT["ACT: start one Docker\ncontainer, bootstrap Caido"] ACT --> VAL["VAL: readiness probe\n(retry Caido login up to 10x)"] VAL --> OUT["OUT: live sandbox session\n+ host-side Caido client"]

What this is

strix/runtime is where the actual disposable test environment gets created — the Docker container every agent shares for the whole scan, pre-loaded with real pentest tools, plus the intercepting proxy that captures all its traffic. Nothing about "the AI" lives here; this is pure infrastructure plumbing.

What flows through it

flowchart TD SM["session_manager.py\ncreate_or_reuse()"] --> Backend["backends.py\n_docker_backend"] Backend --> DC["docker_client.py\nStrixDockerSandboxClient"] DC --> Container[("Docker container\nkalilinux/kali-rolling")] SM --> Caido["caido_bootstrap.py\nbootstrap_caido()"] Caido -- "guest login + temp project" --> Container Caido --> Client["host-side caido_client\n(bundle['caido_client'])"]

Technical details

flowchart LR IN["IN: scan_id, sandbox image,\nlocal_sources to mount"] --> ACT["ACT: start one Docker\ncontainer, bootstrap Caido"] ACT --> VAL["VAL: readiness probe\n(retry Caido login up to 10x)"] VAL --> OUT["OUT: live sandbox session\n+ host-side Caido client"]

Package: strix/runtime/ Depends on: strix.config (load_settings() for backend selection, resource limits), the Agents SDK's sandbox extension (agents.sandbox). Depended on by: strix.core.runner (the only caller of create_or_reuse), the final cleanup() call in run_strix_scan's finally block.

Files at a glance

File Role
session_manager.py create_or_reuse() — top-level sandbox bring-up, cached per scan_id; cleanup() — teardown.
docker_client.py StrixDockerSandboxClient — subclasses the Agents SDK's Docker backend to add NET_ADMIN/NET_RAW caps, host.docker.internal routing, bounded logging, and resource limits.
caido_bootstrap.py bootstrap_caido() — logs into the in-container Caido sidecar as a guest and creates a temporary project.
backends.py get_backend()/register_backend() — a small registry keyed by RuntimeSettings.backend (default docker), so non-Docker runtimes could be added without touching session_manager.py.
status.py Backend-agnostic status/health types.

Files & functions, explained

session_manager.py - create_or_reuse(scan_id, *, image, local_sources, status_sink) — builds an agents.sandbox.manifest.Manifest (host bind-mounts where supported, or uploaded LocalDir entries for remote backends), sets http_proxy/https_proxy/ALL_PROXY to route all in-container traffic through Caido (127.0.0.1:48080) while excluding localhost/127.0.0.1 from proxying (so the browser's local control channel isn't affected), calls the selected backend to actually start the container, then resolves the exposed Caido port and calls bootstrap_caido().

docker_client.py - StrixDockerSandboxClient._create_container() — a documented, deliberate reimplementation of SDK internals: passes command=["tail","-f","/dev/null"] instead of overriding entrypoint, so the image's own docker-entrypoint.sh still runs (starting caido-cli, setting up workspace dirs) before the container idles; adds NET_ADMIN/NET_RAW (needed for nmap -sS raw sockets); adds host.docker.internal -> host-gateway (so agents can reach apps served on the host machine); applies optional resource limits from env vars (STRIX_SANDBOX_MEM_LIMIT/SHM_SIZE/CPUS/PIDS_LIMIT) and bounded json-file logging (default 50 MB × 3 files) to stop a runaway scan filling host disk.

caido_bootstrap.py - bootstrap_caido(session, host_url, container_url) — POSTs a GraphQL loginAsGuest mutation via session.exec("curl", ...), retried up to 10 times with backoff (also serving as a readiness probe since the Caido listener may not be up instantly), then builds a host-side caido_sdk_client.Client and creates+selects a temporary project (temporary=True). The returned Client is what strix/tools/proxy/* use for traffic inspection.

Caido itself is an open-source intercepting HTTP proxy (functionally similar to Burp Suite) running as a CLI sidecar inside the container, listening on 127.0.0.1:48080, with a self-signed CA generated at image build time and trusted system-wide so it can transparently MITM HTTPS traffic from any in-container tool.

Related: STRIX — Architecture (HLD), STRIX — Backends, ../design/HLD.md, ../diagrams/06_sandbox_container.html.