From eea5495fc8ea91b255619baea76f4b8fa34c08ba Mon Sep 17 00:00:00 2001 From: reachableceo Date: Tue, 11 Aug 2026 12:56:34 -0500 Subject: [PATCH] docs(agents): mandate remote.sh chokepoint + DNS-names-only for all SSH MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace soft "ssh may be blocked" note with hard non-negotiable rules: ALL SSH must route through remote.sh/remote-dns.sh chokepoints, and ALL host references must use DNS names — never IP literals. Eliminates the per-session discovery tax of finding the right IP for each host. Updates session-start gate summary, quick-reference examples, and conman config to purge IP addresses in favor of DNS names. 💘 Generated with Crush Assisted-by: Crush:glm-5.2 --- AGENTS.md | 53 ++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 38 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 120d323..5e6ae1b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,13 +105,15 @@ traceable to an approved ticket. There is no "I thought it would help." 3. **Read [questions-v1.md](questions-v1.md)** — open questions awaiting human input. 4. **Check for understanding — GATE.** In your own words, summarize ALL the rules back to the user before doing any work: Agent Authority (ticket-governed, - propose-never-implement), Access-Channel SSH-only policy, Questions policy - (no harness question-tools), Documentation policy (Discourse is SoR), - Redmine tracking, Git policy (always commit+push, shellcheck), Mandatory - infra-change documentation (#298 audit log), SSH routing chokepoints - (`tests/remote.sh`), the mechanically enforced `check-rules.sh` rules, and - Credentials (Vault migration TODO). Then stop and wait for the user to - confirm. This checkpoint guarantees every session starts aligned. + propose-never-implement), Access-Channel SSH-only policy, Remote access + (remote.sh chokepoint mandatory, DNS names only — never IP literals), + Questions policy (no harness question-tools), Documentation policy + (Discourse is SoR), Redmine tracking, Git policy (always commit+push, + shellcheck), Mandatory infra-change documentation (#298 audit log), SSH + routing chokepoints (`tests/remote.sh`), the mechanically enforced + `check-rules.sh` rules, and Credentials (Vault migration TODO). Then stop + and wait for the user to confirm. This checkpoint guarantees every + session starts aligned. 5. **Check Redmine** — `docker run --rm --env-file ~/.creds/redmine.env git.knownelement.com/reachableceo/redmine-cli:latest list --assigned-to-me -p 55` for active work. 6. **Check current state:** `git log --oneline -10`. 7. **Run rule audit:** `bash scripts/check-rules.sh --fast`. @@ -210,9 +212,27 @@ vendor/ Vendored KNELShellFramework `/home/reachableceo/projects/KNELIAC`. - **Non-bash files**: Some files under `archive/provisioning/Agents/` have `.sh` extension but are PHP (shebang `#!/usr/bin/php`). Skip in syntax checks. -- **SSH access**: Direct ssh/scp may be blocked by some AI harnesses. Use - [`tests/remote.sh`](tests/remote.sh) (Proxmox hosts + sandbox VM) or - [`netinfra/dns-cluster-setup/remote-dns.sh`](netinfra/dns-cluster-setup/remote-dns.sh) (DNS infra hosts). +- **Remote access (NON-NEGOTIABLE):** ALL SSH/SCP to ANY host MUST go + through the chokepoint scripts — [`tests/remote.sh`](tests/remote.sh) + (Proxmox hosts + all VMs) or + [`netinfra/dns-cluster-setup/remote-dns.sh`](netinfra/dns-cluster-setup/remote-dns.sh) + (DNS infra hosts: netinfra-01/02, tsrouter, netboot). NEVER call + `ssh`/`scp` directly — the harness blocks raw ssh and the command scanner + rejects it. There are no exceptions. +- **DNS names ONLY (NON-NEGOTIABLE):** NEVER use IP address literals + (neither LAN nor Tailscale IPs) in any command, script, or config. + ALWAYS use DNS names. For Proxmox hosts: `PROX_HOST=`. For VMs: + `VM_IP=`. For conman/SNMP/any tool: pass the DNS name. If a + DNS name does not resolve, fix it in DNS (Technitium) or consult the + [system inventory — Discourse #307](https://community.turnsys.com/t/307). + Do NOT fall back to IP literals. This rule eliminates the per-session + discovery tax of finding the right IP for each host. +- **How to access a production VM:** + 1. Look up the DNS name in the [system inventory — Discourse #307](https://community.turnsys.com/t/307). + 2. `VM_IP= VM_USER=root bash tests/remote.sh vm ''` + 3. If the name does not resolve from the workstation, use `PROX_HOST=` + and run `qm guest cmd network-get-interfaces` (visibility only — + NOT execution) to find the Tailscale DNS name, then access via that. ## Git Policy @@ -379,8 +399,8 @@ live in the centralized store at `~/.creds/discourse.env`. Switch configs are pulled via serial console through a conman + ser2net stack on pfv-tsys4. -- **conmand server:** pfv-tsys4 (Tailscale `100.70.77.93`, port 7890) -- **ser2net:** pfv-tsys4, TCP ports 2001-2006 on Tailscale IP +- **conmand server:** pfv-tsys4 (port 7890) +- **ser2net:** pfv-tsys4, TCP ports 2001-2006 (do NOT connect to ser2net directly — it conflicts with conman's persistent sessions; always use the conman client) - **Script:** [`proxmox/perf/scripts/conman-console.py`](proxmox/perf/scripts/conman-console.py) @@ -449,15 +469,18 @@ docker run --rm --env-file ~/.creds/redmine.env \ docker run --rm --env-file ~/.creds/discourse.env \ git.knownelement.com/reachableceo/discourse-cli:latest whoami -# Proxmox host access: +# Proxmox host access (DNS names only — never IPs): PROX_HOST=pfv-tsys5 bash tests/remote.sh prox 'qm list' PROX_HOST=pfv-tsys5 bash tests/remote.sh prox 'pvesm status' +# Production VM access (DNS names only — never IPs): +VM_IP=tsys-librenms VM_USER=root bash tests/remote.sh vm 'systemctl status cron' + # DNS infra access: bash netinfra/dns-cluster-setup/remote-dns.sh netinfra01-root 'systemctl status docker' -# Switch console (read-only config pull): -CONMAN_SERVER=100.70.77.93:7890 python3 proxmox/perf/scripts/conman-console.py \ +# Switch console (read-only config pull — DNS names only): +CONMAN_SERVER=pfv-tsys4:7890 python3 proxmox/perf/scripts/conman-console.py \ --console pfv-r5-core-01 --cmds netinfra/switches/pfv-r5-core-01.cmds ```