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_ORCHESTRATORenv 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:
~/.steadfaste-fleet/agent.envholdsAGENT_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).fleet-update.shcallsensure_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.- fleet-update.sh sets
git config user.name "AGENT_NAME-agent"/user.email "AGENT_NAME@hermes.local"— commits now carry the agent. - 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/gitis a PATH-shadowing spoof. An agent can prepend a fakebin/toPATHthat returns whatever_detect_orchexpects (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.$HOMEand$USERare env claims too — resolve the directory-services home viagetent 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
$HOMEprefix 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 NFSHomeDirectoryon macOS,getent passwd $USERelsewhere) — 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/lukeon mac,/home/lukeon Linux — same "/luke" tail, different prefix. A row written from a Linux example silently never matches the mac host'sdscl-resolved home; anchor the row to the host's real platform. - Piped git pull masks failure:
git pull ... | tail && git commitcontinues after a FAILED pull because&&sees the pipe's last command (tail) exit 0. Capture pull status separately or verifygit status -sbshows no ahead/behind before committing. - Rebase bypasses hooks:
git pull --rebasereplays 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 -nall touched shell files - [ ]
_detect_orchreturns 0 on this host if orch; simulated non-orch host stays blocked - [ ] Env spoof test:
AGENT_ID=moseson a non-orch host changes nothing - [ ] grep for residual
IS_ORCHESTRATOR/AGENT_TYPEorch 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
macbook-linux-maintenance
Legacy MacBook Linux fixes: GPU wedge, reboot hang, thermal.
governance-regression-triage
Triage a host's governance issues: what changed.
enforcement-immutability
Use when enforcement files lose their immutable flag.
steadfaste-fleet-repo-deploy
Use when committing to the steadfaste-fleet repo.
steadfaste-fleet-maintenance
Maintain an installed Steadfaste Fleet instance — update both the upstream Hermes Agent and the fleet repo layer, merge diverged histories, sync skills safely, and troubleshoot common issues. Covers the dual-update workflow (hermes update + fleet-update.sh), encrypted brain data backup, mycortex import, and recovery techniques.
fleet-preflight
DEPRECATED alias — merged into survey-before-action (2026-08-20). Load survey-before-action instead; its "Repo-Specific Pre-Flight" section covers git search, Hermes boundary, and deployment verification.