AGENT SKILL

governance-identity-hardening

Use when hardening orchestrator identity or unlock tokens.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 4
Forks
1

01 前言 Front Matter

name
governance-identity-hardening
author
Steadfaste Fleet
license
MIT
version
1.0.0
category
devops
metadata
{ "hermes": { "tags": [ "governance", "identity", "spoofing", "orchestrator", "git-authorship", "enforcer", "pre-commit" ], "related_skills": [ "enforcer-modification-considerations", "fleet-preflight", "two-hard-rules", "shell-scripting" ] } }
platforms
[ "linux", "macos" ]
description
Use when hardening orchestrator identity or unlock tokens.

03 SKILL.md 正文

Governance Identity Hardening

Class of work: closing spoof holes in the governance/enforcement chain — who is allowed to do orchestrator-only things, and how commits are attributed.

When to Use

  • Any AGENT_ID / AGENT_TYPE / IS_ORCHESTRATOR env var gates orch powers
  • Commit authorship is showing a human identity for agent-originated commits
  • An unlock/update token is accepted without verifying the caller
  • An LLM fixer cron or agent claims orchestrator identity it shouldn't have

Core Principle: Host-Derived Identity, Never Env

Env vars are claims, not proof. An LLM fixer cron told "You are Moses, the orchestrator" will happily set AGENT_ID=moses and push to orchestrator-only paths — this actually happened (a non-orch host pushed to ops/scripts/).

Orchestrator = two independent host signals, checked together:

_detect_orch() {
  local _host _home _user
  _host=$(hostname -s 2>/dev/null || echo "unknown")
  _user=$(id -un 2>/dev/null || echo "$USER")
  _home=$(getent passwd "$_user" 2>/dev/null | cut -d: -f6)
  _home="${_home:-$HOME}"
  case "$_host" in
    moses|esther)
      [[ "$_home" == "/home/$_host" ]] && return 0
      ;;
  esac
  return 1
}

Orch hosts have hostname == agent name == home dir (esther→$HOME). Non-orch hosts have hardware hostnames and shared /home/luke — neither signal alone is sufficient.

Where to Apply (every place that grants orch powers)

File Gate
pre-commit-score DOGFOOD block, orchestrator-only paths guard, ORCHESTRATOR_ONLY_PATHS block, self-test
fleet-update.sh ORCH_MAP merge (~725), ORCH_MAP protect (~795), orch-cron install (~1900)
os-config.sh FLEET_AGENT_TYPE detection (shared — propagates via check_agent_type)
doctor config.py hostname fallback (already correct for orch hosts)

Missed-gate check: after patching the hook, grep for the same env-var pattern across the whole tree — grep -rn "IS_ORCHESTRATOR\|AGENT_TYPE.*orchestrator" ops/scripts/ — the same spoof hole usually exists in 3-5 sibling locations (install-orch-crons.sh, os-config.sh, multiple fleet-update.sh gates).

Impersonation Watchtower

When a claimed identity contradicts the host signals, write a LOUD line to a state file delivered by a no_agent watchdog (never block on network in a hook):

ALERT_FILE="${HOME}/.steadfaste-fleet/state/impersonation-alerts.log"
_log_impersonation() {
  local claimed="${1:-unknown}"
  { echo "[$(date -u +%Y-%m-%dT%H:%M:%SZ)] IMPERSONATION: ${claimed} claimed on host $(hostname -s 2>/dev/null) — non-orchestrator host cannot be moses/esther"; } \
    >> "$ALERT_FILE" 2>/dev/null || true
}

The pre-commit hook writes the alert file; a separate no_agent cron (1-5 min) delivers new lines to Telegram. This matches the existing agent-governance-auditor delivery pattern.

Git Authorship: agent.env + Deploy-Time Config

Constraint: a pre-commit hook runs as a child of git commit and CANNOT set the author of the commit being created (child→parent env doesn't propagate). Identity must be set at deploy time; the hook only verifies.

Pattern:

  1. ~/.steadfaste-fleet/agent.env holds AGENT_NAME=<agent> — gitignored, per-host (each machine's /home/<user> is a separate physical box, so the file is distinct even though the home path string is shared).
  2. fleet-update.sh calls ensure_agent_identity() (in os-config.sh) which reads agent.env; orch hosts derive AGENT_NAME from hostname and write it; non-orch hosts must provision it once.
  3. fleet-update.sh sets git config user.name "AGENT_NAME-agent" / user.email "AGENT_NAME@hermes.local" — commits now carry the agent.
  4. pre-commit hook verifies agent.env exists (fails closed with setup instructions) and AGENT_NAME matches hostname on orch hosts.

PII rule: the hostname→agent mapping is infrastructure. It must NEVER be committed to the public repo — provision agent.env per machine instead.

Partial Privileges: a committer is NOT an orchestrator — keep predicates separate

When a non-orch host is allowed to do SOME orch-only things (Titus updates the fleet repo), give it its OWN predicate (_is_fleet_committer) read from a committed docs/fleet-committers.txt — do NOT fold it into the grand _detect_orch. The full predicate carries checks the committer FAILS: it forces AGENT_NAME == hostname (a mac host named worker-4 whose agent is titus fails that equality), and it may grant unrelated higher powers (enforcer auto-deploy). Route the committer only into the specific IS_ORCH gate whose paths it may touch; leave entirely separate privileges (self-edit of the guard, enforcer dogfood) on true-orchestrator-only.

Self-protection before the file exists: a config file read via git show HEAD:path cannot see itself in the very commit that creates it — a non-orch could add its own home row in that first commit. Pin both config files as hardcoded orchestrator-only in the guard from commit one, so the bootstrap window is closed before the HEAD-read guard is live.

Unexpected git failures must not masquerade as "file absent". When reading the committed committer list, a git error that is not "does not exist"/"exists on disk, but not in" must emit an observable stderr line — otherwise a broken git silently answers "not a committer" and the guard fails closed for a reason the operator never sees.

Spoofable Unlock Tokens

hermes-plugin-lock unlock --fleet-update historically accepted the token from ANY account with zero caller proof. The token was a string, not a caller.

Fix pattern: fresh root-owned marker file created inside fleet-update.sh immediately before unlocking; the helper requires the marker to exist, be root-owned, and be <60s old. --orchestrator stays account-bound (SUDO_USER/USER must be moses|esther — an account boundary, not an env var).

Pitfalls

  • Pin every identity command to an ABSOLUTE path — a bare hostname/id/ getent/dscl/git is a PATH-shadowing spoof. An agent can prepend a fake bin/ to PATH that returns whatever _detect_orch expects (a forged home, a fake hostname) and climb into orchestrator identity. Define _G_ID=/usr/bin/id, _G_HOSTNAME=/bin/hostname, _G_GETENT=/usr/bin/getent, _G_GIT=/usr/bin/git, … and call only those. $HOME and $USER are env claims too — resolve the directory-services home via getent passwd/dscl, and fail CLOSED (return non-privileged) when resolution is incomplete, never fall back to $HOME.
  • Match the committed committer row EXACTLY, never by prefix or env. A home $HOME prefix match lets a neighbouring user in; the row must equal the resolved home byte-for-byte.
  • A wrong row fails CLOSED SILENTLY — the worst failure mode. An exact-match gate with a wrong committed value looks configured (file present, row plausibly shaped) but never fires: every fleet-path edit is blocked with no signal the anchor is wrong. "Fail closed" is a safety property, not a license to skip verifying the row. Always confirm the committed value against the live host's OWN directory-services output (dscl . -read /Users/$USER NFSHomeDirectory on macOS, getent passwd $USER elsewhere) — never infer it from a path seen in someone's log or EXEC output. And add a sync/tether test asserting the committed row equals the expected literal (assert rows == ["/Users/luke"]), so a wrong value fails LOUDLY in CI instead of silently in the hook.
  • macOS home is /Users/<user>, not /<user>. A member of the fleet sees /Users/luke on mac, /home/luke on Linux — same "/luke" tail, different prefix. A row written from a Linux example silently never matches the mac host's dscl-resolved home; anchor the row to the host's real platform.
  • Piped git pull masks failure: git pull ... | tail && git commit continues after a FAILED pull because && sees the pipe's last command (tail) exit 0. Capture pull status separately or verify git status -sb shows no ahead/behind before committing.
  • Rebase bypasses hooks: git pull --rebase replays commits without the pre-commit hook; the pre-push hook then flags them. Fix: amend the commit through the hook (git commit --amend --no-edit) before pushing.
  • Self-test must match the new logic: when changing identity checks, rewrite the hook's self-test (e.g. "AGENT_ID controls orchestrator identity") to assert the hostname+home-dir behavior and env-independence — a stale self-test fails every commit.
  • Deploy ordering: fleet-update.sh sources os-config.sh at runtime; on the FIRST run after a fix it sources the OLD deployed copy. Re-run the deploy once to confirm the identity line self-heals.

Verification Checklist

  • [ ] bash -n all touched shell files
  • [ ] _detect_orch returns 0 on this host if orch; simulated non-orch host stays blocked
  • [ ] Env spoof test: AGENT_ID=moses on a non-orch host changes nothing
  • [ ] grep for residual IS_ORCHESTRATOR / AGENT_TYPE orch grants in sibling files
  • [ ] Deployed copies carry the new check (not just repo source)
  • [ ] Pre-commit self-test passes on the deployed hook
  • [ ] Agent commits show AGENT_NAME-agent <AGENT_NAME@hermes.local>, not the human

04 同仓库更多 Skills