orchestrator-container-spawn

## When to Use - Changing how the orchestrator launches or secures a scan container ([recon_orchestrator/container_manager.py](../../recon_orchestrator/container_manager.py)). For the no-`env_file` knob rule, see the recon_orchestrator [AGENTS.md](../AGENTS.md) CRITICAL RULES (not repeated here). --- ## Critical Rules - **NEVER add `cap_drop: [ALL]` to a scan container that writes to a host-owned source bind mount.** It strips `CAP_DAC_OVERRIDE`, so root-in-container can no longer write the host-owned files, and the scan breaks. This was reverted after breaking recon/partial spawns; hardening is deliberately deferred with `drop_caps=False` at **every** spawn site ([container_manager.py:837](../../recon_orchestrator/container_manager.py#L837), :1798, :2168). Keep it deferred unless the mount is not host-owned. - **NEVER add `security_opt: no-new-privileges` to these spawns.** It breaks `execve` for non-root users inside the recon image (reverted once already): [container_manager.py:939](../../recon_orchestrator/container_manager.py#L939). - **NEVER add a `tmpfs` mount without `uid`/`gid`/`mode` when the container runs as a NON-ROOT user and the mount lands on a path that user must write.** Docker mounts a tmpfs **root-owned 0755** unless told otherwise (only `/tmp` gets the 1777 default), and the mount SHADOWS whatever the image built at that path - so a tmpfs added to *give* a non-root user writable scratch is what *takes it away*. This shipped: the TruffleHog spawn's `/home/trufflehog` tmpfs hid the home dir `useradd --create-home` had given uid 10001, and `github_experimental` died on "failed to create .trufflehog folder in user's home directory" while the other thirteen sources were fine, because it is the only one that writes to `$HOME`. Build the spec in [`_trufflehog_tmpfs()`](../../recon_orchestrator/container_manager.py#L4644), not inline, and size-cap every entry - an uncapped tmpfs is host RAM a hostile archive can exhaust. - **ALWAYS apply hardening through `_scanner_hardening()`** ([container_manager.py:567](../../recon_orchestrator/container_manager.py#L567)), not ad-hoc per spawn, so all three spawn sites stay consistent. - **ALWAYS keep `sibling_host_path()` robust to BOTH POSIX (`/`) and Windows (`\`) host paths** ([container_manager.py:53](../../recon_orchestrator/container_manager.py#L53)). It derives a sibling source dir's host path for bind mounts; a POSIX-only assumption breaks spawns on Windows hosts. Its two companions [`parent_host_path()`](../../recon_orchestrator/container_manager.py#L77) and [`join_host_path()`](../../recon_orchestrator/container_manager.py#L90) carry the same POSIX+Windows discipline - never swap in `pathlib` / `Path(...).parent`, which collapses a Windows host path on the Linux orchestrator. - **NEVER assume a scanner source dir is a repo-root sibling.** Scanners live two levels deep under `scanners/<name>/`, so a bind mount to a repo-root sibling (e.g. `graph_db`) must climb out of `scanners/` first: `sibling_host_path(parent_host_path(scanner_path), "graph_db")`, and a `scanners/`-nested sibling is reached with `join_host_path(parent_host_path(recon_path), "scanners", "supply_chain_common")`. The old `sibling_host_path(scanner_path, "graph_db")` now resolves to a nonexistent `scanners/graph_db`; Docker silently binds an empty root-owned dir there and graph writes / imports fail with no error. The build context climbs two parents: `parent_host_path(parent_host_path(scanner_path))`. - **NEVER bind `/app/graph_db` directly at a spawn site. Always route it through `self._graph_db_mount(<derived>, baked_into_image=...)`** ([container_manager.py:605](../../recon_orchestrator/container_manager.py#L605)). Deriving graph_db's host path is a LAST RESORT, not the mechanism: the real path is auto-detected from the orchestrator's own `./graph_db:/app/graph_db:ro` mount (`GRAPH_DB_PATH`, resolved in `api.py` exactly like `RECON_PATH`). The derivation is only right when Docker reports the literal repo path - Docker Desktop on Windows/WSL2 reports rewritten bind `Source` strings whose sibling is nowhere, Docker auto-creates that path EMPTY, and the empty dir shadows the graph_db baked into the scan image. Every spawned scan then dies with `cannot import name 'Neo4jClient' from 'graph_db' (unknown location)` (issue #169). `baked_into_image=True` for recon / gvm / github-hunt (they COPY graph_db, so no mount beats a wrong mount); `False` only for supply-chain, which does not bake it. TruffleHog has NO graph_db mount at all: its container is the dirty half of a dirty/clean split and holds no Neo4j credentials, so the orchestrator ingests its findings afterwards. - **ALWAYS resolve a new host source path with `_get_host_path()` + a compose mount, not by string surgery on another path.** If a spawn needs host dir `X`, mount `X` into the orchestrator so Docker itself reports its source. A missing bind source is not an error to Docker; it silently becomes an empty directory. --- ## Why these flags break here Scan containers run as root and **bind-mount host-owned source** (the live working tree) so a `.py` change is picked up without a rebuild. Standard container hardening (drop all caps, no-new-privileges) assumes the container owns its filesystem and runs unprivileged - neither holds here, so the "secure defaults" a reviewer would add are exactly what broke production twice. ## Commands ```bash docker compose restart recon-orchestrator # container_manager.py is volume-mounted ./redamon.sh test unit # recon_orchestrator section ``` ## Resources - [recon_orchestrator/container_manager.py](../../recon_orchestrator/container_manager.py) - the three spawn sites and `_scanner_hardening` - Related: recon_orchestrator [AGENTS.md](../AGENTS.md) CRITICAL RULES (the no-`env_file` knob rule)