Recover (RC) · Identity
Identity at the client side layer
deterministic · Outside the model's reasoning
How do I get back to a known-good state and not repeat this?
What this cell does
Regenerate credential file with strict ACLs, rotate OIDC client secret, re-authenticate operator host to SSO, verify ACLs survived.
Artifacts (1)
agent-restore-identity-localview on GitHub#!/usr/bin/env bash
# ABOUTME: Local identity-rebuild runbook. Re-issues credential from IdP, places under strict ACLs, verifies deny-on-self.
# ABOUTME: Run from a known-clean operator host. AGENT_TOKEN must already be issued (by the IdP API or a separate script).
set -euo pipefail
if [[ $# -lt 2 ]]; then
echo "Usage: agent-restore-identity-local <AGENT_NAME> <INCIDENT_ID>" >&2
echo " AGENT_TOKEN must be set in the environment (issue via IdP API first)." >&2
exit 64
fi
AGENT_NAME="$1"
INCIDENT_ID="$2"
AGENT_USER="${AGENT_USER:-agent-runner}"
OPERATOR_GROUP="${OPERATOR_GROUP:-operators}"
CRED_PATH="/etc/agents/${AGENT_NAME}"
if [[ -z "${AGENT_TOKEN:-}" ]]; then
echo "AGENT_TOKEN must be set in the environment (issue via IdP API first)." >&2
exit 1
fi
# 1. Place credential in operator-owned config.
mkdir -p "$CRED_PATH"
chown "root:${OPERATOR_GROUP}" "$CRED_PATH"
chmod 0750 "$CRED_PATH"
umask 0177
printf '%s\n' "$AGENT_TOKEN" > "$CRED_PATH/token"
chown "root:${OPERATOR_GROUP}" "$CRED_PATH/token"
chmod 0640 "$CRED_PATH/token"
# 2. Reapply deny-on-self ACL so the agent's own user cannot read the
# credential at rest (only the systemd unit reads it as root at launch).
if command -v setfacl >/dev/null 2>&1; then
setfacl -m "u:${AGENT_USER}:---" "$CRED_PATH/token"
else
echo "WARN: setfacl not available; agent user may be able to read its credential at rest" >&2
fi
# 3. Remove the requires_reauth flag from Interventions so the agent can launch.
rm -f "$CRED_PATH/.requires_reauth"
# 4. Verify ACLs and permissions survived.
EXPECTED_PERMS="640"
ACTUAL_PERMS=$(stat -c "%a" "$CRED_PATH/token")
if [[ "$ACTUAL_PERMS" != "$EXPECTED_PERMS" ]]; then
echo "WARN: credential permissions are $ACTUAL_PERMS, expected $EXPECTED_PERMS" >&2
fi
if command -v getfacl >/dev/null 2>&1; then
if ! getfacl "$CRED_PATH/token" 2>/dev/null | grep -q "user:${AGENT_USER}:---"; then
echo "WARN: deny-on-self ACL for ${AGENT_USER} is missing on $CRED_PATH/token" >&2
fi
fi
# 5. Log the recovery.
logger -t agent-recovery -p user.notice \
"$(jq -n \
--arg event "identity_restored_local" \
--arg agent "$AGENT_NAME" \
--arg incident "$INCIDENT_ID" \
--arg fingerprint "$(printf '%s' "$AGENT_TOKEN" | sha256sum | cut -d' ' -f1 | head -c 16)" \
--arg actor "$(whoami)" \
--arg ts "$(date -Iseconds)" \
'{event:$event, agent:$agent, incident:$incident, cred_fingerprint:$fingerprint, actor:$actor, ts:$ts}')"
unset AGENT_TOKEN
echo "Local identity restored for $AGENT_NAME (incident $INCIDENT_ID)"
Cell notes
Restorations, Identity / Client-side
Precondition. Interventions L2-C1 has fired (local credentials deleted, agent process killed). The IdP user/service account corresponding to this agent has been confirmed clean: no recent privilege grants from compromised admin sessions, no MFA factors added during incident window.
Authority. On-call.
Tooling
- - IdP API access (Okta, Auth0, Keycloak, Dex) for credential reissue.
- -
setfaclfor the deny-on-self ACL pattern from../../../controls/identity/client-side/.
Files in this directory
- -
agent-restore-identity-local, runbook script. Issues fresh credential from IdP, places in operator-owned config with strict ACLs, removes therequires_reauthflag, verifies the deny-on-self ACL survived.
Verification
# 1. Credential in place with correct permissions
ls -la /etc/agents/claude-code-prod/token
# expected: -rw-r----- root operators
# 2. Agent can authenticate
sudo -u agent-runner /usr/local/bin/claude --version
# 3. Old credential is invalid (test against IdP)
# Provider-specific: try a request with the old token, expect 401.
Common failure modes
- - Issuing the new credential with a long TTL by default. Re-pin to the 15-minute TTL from
controls/identity/server-side/pod-with-projected-token.yamlto limit exposure. - - Forgetting to remove the
requires_reauthflag, the agent never restarts. - - ACLs reset to defaults during recovery and not re-applied. The deny-on-self ACL must be reapplied or the agent can read its own credential at rest.
Citation
NIST CSF 2.0 RC.RP-01 (recovery plan executed), RC.IM-01 (improvements integrated). NIST SP 800-61 Rev. 2. NIST SP 800-63B Rev. 4.
Primary failure modes
Documented, not hypothetical. A control whose bypass is undocumented is worse than no control, because somebody trusted it.
- new credential issued with default long TTL
- requires_reauth flag not removed
- ACLs reset to defaults during recovery
Crosswalk
| NIST CSF 2 0 | RC.RP-01, RC.IM-01 |
|---|---|
| NIST AI RMF | MANAGE 4.1 |
| OWASP AGENTIC | ASI03, ASI10 |
| OTHER | NIST SP 800-61 Rev. 2, NIST SP 800-63B Rev. 4 |
Cite this cell:
https://agenticcovenants.com/recover/identity/client-side/