redamon / recon_orchestrator

# recon_orchestrator - Agent Ruleset

> **Skills**: on-demand rulesets live in [`../skills/`](../skills/); the full
> list is the SKILLS CATALOGUE in the [root AGENTS.md](../AGENTS.md). The table
> below is generated by `sync.sh` - never hand-edit it.

### Auto-invoke Skills

When performing these actions, ALWAYS invoke the corresponding skill FIRST:

| Action | Skill |
| ------ | ----- |
| Editing container_manager.py bind mounts or security options | `orchestrator-container-spawn` |
| Spawning or hardening a scan container from the orchestrator | `orchestrator-container-spawn` |

---

## CRITICAL RULES - NON-NEGOTIABLE

<!-- Add a rule only if an agent breaks it while working elsewhere AND cannot
     discover it from the file being edited. See the root AGENTS.md for repo-wide rules. -->

- **NEVER** assume a `.env` var reaches this service. The orchestrator has **no
  `env_file`**; a var is honoured only if it is listed in its `environment:`
  block in `docker-compose.yml`. A knob added to `.env` alone is silently inert.

---

## TECH STACK

Python 3.11 · FastAPI HTTP surface. **Volume-mounted** (`./recon_orchestrator:/app`)
so a `.py` change is live after `docker compose restart recon-orchestrator` (no
rebuild). It spawns the scan containers (recon, partial-recon, gvm, github-hunt,
trufflehog, supply-chain) via `container_manager.py` and gates them through a
memory governor.

## PROJECT STRUCTURE

```
api.py                 the HTTP surface (scan lifecycle, /defaults, RUNTIME_ONLY_KEYS)
container_manager.py   spawns scan containers; sibling bind mounts + security hardening
resource_governor.py   memory-envelope admission control        mem_calibrate.py  calibration
scan_scheduler.py      scheduled scans           admission_ledger.py  in-flight accounting
hard_guardrail.py  auth.py  local_llm_manager.py
tests/                 pytest (section recon_orchestrator, image redamon-recon-orchestrator)
```

## COMMANDS

```bash
docker compose restart recon-orchestrator     # apply a .py change (volume-mounted, no rebuild)
docker compose build recon-orchestrator && docker compose up -d recon-orchestrator   # only for Dockerfile/requirements changes
./redamon.sh test unit                        # includes the recon_orchestrator section
```

## QA CHECKLIST

- [ ] `./redamon.sh test unit` green (recon_orchestrator section).
- [ ] New or changed behaviour is covered by a test (see the `redamon-testing` skill for where + how).
- [ ] Added a new env knob? It is in the `environment:` block in `docker-compose.yml`, not only `.env`.
- [ ] No new Python import unless it is already in the image (a missing one crash-loops the service).
- [ ] Restarted (or rebuilt, for Dockerfile changes) `recon-orchestrator`.

More agent context in samugit83/redamon

24 other files this repository gives its agents.