redamon

# RedAmon - Agent Ruleset (Repository Root)

> **Skills**: on-demand rulesets live in [`skills/`](skills/). The full list is
> the **SKILLS CATALOGUE** at the bottom of this file. The table directly below
> is generated by `sync.sh` from each skill's frontmatter - never hand-edit it.
>
> This ruleset system is documented in
> [`docs/readmes/skills_management/SKILLS_MANAGEMENT.md`](docs/readmes/skills_management/SKILLS_MANAGEMENT.md).

### Auto-invoke Skills

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

| Action | Skill |
| ------ | ----- |
| Adding a node label, relationship, or property to the graph schema | `graph-db-writes` |
| Adding or editing a test file in any section | `redamon-testing` |
| Changing how a triage score, review or verdict is computed or written | `priority-board-triage` |
| Changing test tiers, conftest.py, pytest.ini, or the runner in redamon.sh | `redamon-testing` |
| Checking or ratcheting a coverage floor | `redamon-testing` |
| Editing the Priority Board, the triage graph mixin, or the MCP triage tools | `priority-board-triage` |
| Investigating a red, skipped or xfailed test | `redamon-testing` |
| Writing to the Neo4j graph or editing a graph_db mixin | `graph-db-writes` |

---

## CRITICAL RULES - NON-NEGOTIABLE

<!-- Every line here is in context on EVERY turn. Add one only if an agent could
     break it while working on something else AND could not discover it from the
     file being edited. Component specifics belong in a scoped skill, not here. -->

- **NEVER** commit real-world target data - live hostnames, IPs, scan output,
  recon results, captured traffic, or credentials - in code, fixtures, tests,
  issues, or PRs. See `CONTRIBUTING.md` -> "Legal and Ethical Responsibilities".
- **NEVER** validate a change by running `pytest` on the host. The Python gate
  runs each section INSIDE its Docker image (`redamon-agent`, `redamon-recon`,
  ...) via `./redamon.sh test` / `./agentic/run_tests.sh`; host pytest sees the
  wrong dependency set and mis-collects. The unit tier must stay 100% green.

---

## CODE COMMENTS

Comment the **why**, not the **what**. Keep them short - a comment earns its
place by saying something the code cannot.

- **DON'T restate the line below it.** `# CVE Lookup` above `'CVE_LOOKUP_ENABLED'`
  or `// IncludeSecurity blog` above `{ name: 'IncludeSecurity blog' }` adds
  nothing. Delete echo comments; let the identifier speak.
- **DO explain non-obvious intent**: why a value is what it is, a footgun, an
  ordering constraint, or the provenance of a magic constant (e.g. the source
  repo + byte size behind a favicon hash). These are the comments worth keeping,
  even when long.
- **NO changelog narration.** `# was 900 MB, now 1.75 GB` / `# renamed from X`
  belongs in the git log. State current behavior; keep the rationale only if it
  still guides a future edit.
- **NO commented-out code.** Delete it - git remembers.
- **Prefer a clearer name or a helper over a comment** when the comment only
  exists to decode the code. Reach for prose (a docstring / block comment) when
  the reasoning genuinely needs more than a line.

LLM-facing text is exempt: tool docstrings and prompt strings the agent reads at
runtime are content, not code comments - size them for the model, not this rule.

---

## TECH STACK

Polyglot monorepo orchestrated by Docker Compose. Python 3.11 services (the
agent, recon pipeline, recon orchestrator, MCP/kali-sandbox, scan tools) + a
Next.js 16 / React 19 / TypeScript / Prisma webapp + Neo4j graph DB + Postgres. `redamon.sh`
(bash) is the control plane for build/run/test.

## PROJECT STRUCTURE

Only the roots an agent needs to place a file. Each component root carries its
own `AGENTS.md`.

```
agentic/              Python - the LangGraph agent (baked into redamon-agent image)
recon/                Python - the recon pipeline (spawned per scan job)
recon_orchestrator/   Python - orchestrates scan containers (volume-mounted)
mcp/                  Python - MCP servers incl. kali-sandbox
graph_db/             Python - Neo4j graph layer (COPY-baked into agent image)
webapp/               TypeScript - Next.js frontend + API + Prisma
skills/               agent skills (this ruleset system)
tests/                repo-root Python tests + shell integration tests

scanners/             the 11 scan tools, each its own container image
  supply_chain_*/       malicious/vulnerable package detection (OSV offline)
  capture_proxy/        mitmproxy HTTP capture
  ai_attack_surface_scan/  LLM/AI attack-surface scanning
  gvm_scan/  github_secret_hunt/  trufflehog_scan/  baddns_scan/  wcvs/  codefix_sandbox/
services/             supporting services (docker_broker, knowledge_base, postgres_db)
testing/              e2e/ (Playwright) + guinea_pigs/ (vulnerable targets)
tooling/              scripts/ (e.g. pytest_isolated.py), hooks/, deploy/
docs/                 readmes/ (prose docs) + assets/ (media)
```

A scanner's container-side paths stay `/app/<scanner>`; only host-side paths
carry the `scanners/` prefix.

Prose docs live in `docs/readmes/` (architecture, `README.<SUBSYSTEM>.md`, and
`docs/readmes/coding_agent_prompts/` "how to add X" guides) and `redamon.wiki/`
(the published GitHub wiki). This ruleset system and its templates live in
`docs/readmes/skills_management/`.

## COMMANDS

```bash
# Build & run the stack (always via Docker; never local npx/node/pip)
# There is no `build` subcommand: building happens inside install/update, which
# wrap it in the adaptive, memory-safe batching (compose_build).
./redamon.sh install          # first run (add --gvm / --kbase)
./redamon.sh update           # pull + smart-rebuild only what changed
./redamon.sh up               # start what is already built

# Test - runs each section inside its Docker image, per-file isolated
./redamon.sh test unit        # the gate; must be 100% green
./agentic/run_tests.sh        # agent-image unit gate (alias: focused)

# Webapp (needs the webapp image or `npm ci` in webapp/)
cd webapp && npm run test     # vitest run --no-file-parallelism
cd webapp && npm run type-check && npm run lint
```

Credentials for the local stack live in the repo-root `.env` (gitignored). To sign
in to the UI in a browser, use `UI_LOGIN_USERNAME` / `UI_LOGIN_PASSWORD`. To call
the MCP server, send `MCP_SERVER_TOKEN` as `Authorization: Bearer` to
`http://localhost:3000/api/mcp-server` (the port is `WEBAPP_PORT` if changed).
Read the values from `.env` when needed; never print them.

## QA CHECKLIST

- [ ] `./redamon.sh test unit` is green (Docker gate, not host pytest).
- [ ] Changed a component? Its `AGENTS.md` QA checklist also satisfied.
- [ ] Rebuilt/restarted the right container for the files you touched.
- [ ] No real-world target data added anywhere.
- [ ] Commit follows Conventional Commits; branch is `feature|fix|refactor|docs/*`.

---

## SKILLS CATALOGUE

Maintained by hand (not touched by `sync.sh`). One row per skill.

| Skill | Description | URL |
| --- | --- | --- |
| `redamon-testing` | How tests run + how to author them: the per-file Docker gate, tiers, and green-run-that-lies failure modes | [SKILL.md](skills/redamon-testing/SKILL.md) |
| `agentic-tool-integration` | Wiring a new tool the agent can call: registry, phase map, dispatch chokepoint, duplicated exec paths | [SKILL.md](skills/agentic-tool-integration/SKILL.md) |
| `builtin-agent-skill` | Adding a built-in attack skill across its 9 layers (incl. the KNOWN_ATTACK_PATHS gate + silent drawer layers) | [SKILL.md](skills/builtin-agent-skill/SKILL.md) |
| `project-settings-cascade` | Changing/adding a project default across Prisma + two Python modules + /defaults + frontend + existing rows | [SKILL.md](skills/project-settings-cascade/SKILL.md) |
| `graph-db-writes` | Writing the Neo4j graph: the tenant-isolation MERGE key, mixin placement, schema-sync | [SKILL.md](skills/graph-db-writes/SKILL.md) |
| `recon-ai-enrichment` | Wiring an LLM into a recon tool: never-raise, per-target cache, full+partial, two toggles one field | [SKILL.md](skills/recon-ai-enrichment/SKILL.md) |
| `recon-tool-integration` | Adding a recon pipeline tool: the enrichment `_isolated` contract, graph completeness, preset catalog | [SKILL.md](skills/recon-tool-integration/SKILL.md) |
| `llm-provider-integration` | Adding an LLM provider: keys never reach scan containers, prefix-routed model ids, the registry | [SKILL.md](skills/llm-provider-integration/SKILL.md) |
| `orchestrator-container-spawn` | Spawning/hardening scan containers: the cap_drop / no-new-privileges footgun, sibling bind mounts | [SKILL.md](skills/orchestrator-container-spawn/SKILL.md) |
| `traffic-capture` | Capture proxy + replay/fuzz: the egress guard (resolved-IP SSRF denylist), off the scan's critical path | [SKILL.md](skills/traffic-capture/SKILL.md) |
| `supply-chain-scan` | Supply-chain scanner: offline OSV DB (not scan-bootstrapped), world-readable DB, soft-error markers | [SKILL.md](skills/supply-chain-scan/SKILL.md) |
| `add-community-skill` | Importable .md attack workflow: real tool names only, no rebuild, stay classifiable, per-user | [SKILL.md](skills/add-community-skill/SKILL.md) |
| `add-partial-recon` | Partial-recon support: graph-sourced inputs, MERGE dedup, the input-node modal, mirror the right ref impl | [SKILL.md](skills/add-partial-recon/SKILL.md) |
| `mcp-server-tools` | Inbound MCP server tools: regenerate the wiki API reference, spec-accurate destructiveHint, runnable example calls | [SKILL.md](skills/mcp-server-tools/SKILL.md) |
| `priority-board-triage` | Priority Board layers: nobody writes a score (combine_layers only), one layer per writer, never updated_at, legacy-tolerant readers | [SKILL.md](skills/priority-board-triage/SKILL.md) |

More agent context in samugit83/redamon

24 other files this repository gives its agents.