Agentic Covenants

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

Files in this directory

  • - agent-restore-identity-local, runbook script. Issues fresh credential from IdP, places in operator-owned config with strict ACLs, removes the requires_reauth flag, 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.yaml to limit exposure.
  • - Forgetting to remove the requires_reauth flag, 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 0RC.RP-01, RC.IM-01
NIST AI RMFMANAGE 4.1
OWASP AGENTICASI03, ASI10
OTHERNIST SP 800-61 Rev. 2, NIST SP 800-63B Rev. 4