diff --git a/AGENTS.md b/AGENTS.md index 950df0e..3fba1fc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -164,6 +164,25 @@ docker run --rm --env-file ~/.creds/discourse.env \ - **Secrets:** NEVER commit secrets. Credentials come from env vars / `.env` (gitignored). Use placeholders in `.env.example`. - **IAC testing:** test against the corresponding `sectestbed-` VM (snapshot to base state). `preprod-` VMs for vendor-upgrade testing. Do not require AWX as a prerequisite. +## Remote Access (projects with remote hosts) + +**If this project manages remote hosts** (servers, VMs, network devices), +these rules are NON-NEGOTIABLE: + +- **Ship a `remote.sh` chokepoint.** ALL SSH/SCP to any host MUST route + through a single chokepoint script (`tests/remote.sh` or equivalent). + NEVER call `ssh`/`scp` directly — the harness blocks raw ssh and the + command scanner rejects it. One script = one place to configure + hosts/users/keys, one place to audit. +- **DNS names ONLY.** NEVER use IP address literals in any command, script, + or config. ALWAYS use DNS names. If a DNS name does not resolve, fix DNS + first — do not fall back to IP literals. This eliminates the per-session + discovery tax of finding the right IP for each host. +- **If using qemu-guest-agent:** visibility only (`qm guest cmd ping`, + `network-get-interfaces`). NEVER use `qm guest exec` or any wrapper as an + execution, access, or key-delivery channel. SSH is the only approved + remote access path. + ## Key Commands At a terminal (Mode 1), use `make` or call scripts directly: @@ -217,6 +236,9 @@ Bypass with `--no-verify` in genuine emergencies only. - Install language toolchains on the host. - Use `:latest` image tags or Docker's default container naming. - Author long-form docs in gitea — use Discourse. +- Call `ssh`/`scp` directly — always route through the project's `remote.sh` chokepoint. +- Use IP address literals for any host — always use DNS names. +- Use `qm guest exec` or any guest-agent execution channel — SSH only. - Commit secrets. - Run destructive git operations without explicit instruction. - Declare the work "done" — the human decides that.