agent_identity_governance v1.0.0

name: agent_identity_governance description: "Govern non-human identities as principals: inventory service accounts, app installs, API keys, roles, and agent credentials across platforms, give every row a named owner and purpose, check expiry and last use, score risk by reach and owner status, recertify on a cycle, and run a timed off switch drill for one identity. Use when an agent, service account, or app install is unowned, shared, dormant, overprivileged, or cannot be cut off quickly, or when building an NHI inventory or review."

Agent Identity Governance

Purpose

Govern the identities software runs as, not just the secrets those identities use. Secrets management answers where a key lives. This skill answers why an identity exists, who owns it, what it can reach, when it was last used, when it expires, and how fast its access can be cut. It ships an inventory template, a scoring tool (bin/nhi_audit.py), a recertification workflow, and a worked off switch drill. It differs from a credential location audit, which tracks where credential values are stored, and from secret rotation, which replaces one authenticator. This skill governs the principal itself across its life: create with an owner, review on a cycle, reduce reach, retire in the right order.

Workflow

1. Sweep for identities, then reconcile both ways. List principals from each cloud account and project, the identity provider, GitHub and GitLab organizations, CI systems, Kubernetes clusters, SaaS admin consoles, and infrastructure code. Types: service accounts, IAM roles, app installations, OAuth apps, API keys acting as identity, database service users, certificates, automation SSH keys, and agent credentials. Anything in a platform but not in the inventory is ungoverned. Anything in the inventory but not in a platform is a stale row to close. Method in references/inventory-and-scoring.md.
2. Fill one inventory row per identity per environment. Use templates/inventory.csv. Required per row: stable ID, exact platform name, type, platform, environment, named owner with a team inbox as backup, one sentence purpose a stranger can judge, reach (read, write, or admin by what it can do), auth type, expiry date or never, last used date or unknown, what it is shared across, third party status, and next recertification date. CIS Controls v8 safeguard 5.5 asks for at least department owner, review date, and purpose in a service account inventory. This template adds the fields that make review and cutoff possible.
3. Score and sort the work. Run python3 bin/nhi_audit.py templates/inventory.csv on a filled copy. The tool flags no owner, admin reach, production use, sharing across services or environments, never expiring or long lived auth, dormancy past 45 and 90 days, third party status, and overdue recertification, then scores 0 to 100 with bands in the reference file. The weights are a starting model to calibrate locally, not a standard. Fix in this order: give critical and high rows a named owner first, then decide recertify, reduce, replace, or retire.
4. Check last use and expiry against platform evidence. Use platform data, not memory: AWS IAM Access Analyzer unused access findings and IAM last accessed information, cloud audit logs, identity provider sign in logs, and GitHub app and token activity. An Access Analyzer finding reports unused access, it does not remove it. Compare granted against used permissions and remove the unused part, or record why it stays. Flag identities unused past 45 days: CIS safeguard 5.3 calls for deleting or disabling dormant accounts after 45 days of inactivity where supported.
5. Recertify on a cycle, at least quarterly for production. The owner answers still needed, reach still right, auth still right, and expiry and next review set, each with evidence. Outcomes per identity: recertify as is, recertify with reduced reach, rotate or replace the authenticator, schedule retirement, or retire now. Decide the non-response rule before the cycle starts. The safer default is that silence does not renew: disable on the deadline and re-enable after late review. Owner departure triggers recertification in the same change, with a named successor. Full workflow in references/inventory-and-scoring.md.
6. Prove the off switch for one identity. Run the drill in references/off-switch-drill.md: snapshot the configuration first, disable before deleting, revoke sessions and tokens the disable may have missed, check dependents, verify the cut from logs with a denied authentication attempt, then restore for a drill or delete after a soak period for a real retirement. Google Cloud service account key guidance uses the same order: disable, wait until sure, then delete, because deletion cannot be undone. On GitHub, separate the two switches: a user revokes their own app authorization, an organization owner suspends or uninstalls the app.
7. Close the loop in the record. Keep retired rows in the inventory, marked retired with date and approver. Update owner, reach, expiry, last used, and recert dates whenever a platform change happens, not only at review time. A change with no inventory update is how the next unowned identity starts.

Output Contract

A governance pass delivers:

• Inventory: the filled CSV or table, one row per identity per environment, with no blank owner, purpose, expiry, last used, or recertification fields. Unknown is an allowed value for last used, blank is not.
• Audit report: output from bin/nhi_audit.py, counts by band, and every critical and high row with its flags.
• Decision list: per critical and high identity, one decision with an owner and a date: recertify, reduce reach, replace auth type, or retire. No identity leaves the pass as "watch this space".
• Recertification record: per identity reviewed, the four answers, the evidence used, the outcome, and the next review date. Non-responses and what the non-response rule did to them are listed by name.
• Off switch record: for the drilled identity, prep gaps, elapsed time per step, verification evidence, dependent behavior, and pass or fail against the drill criteria in the reference file.

Operating Rules

1. Never record a credential value in the inventory, the audit, or a drill record. Names, IDs, permissions, dates, and truncated fingerprints only. The inventory must be safe to share with an auditor.
2. One identity, one job, one environment. Reuse across services and sharing across staging and production are findings, not conveniences. The OWASP Non-Human Identities Top 10 for 2025 lists both as named risks, NHI8 Environment Isolation and NHI9 NHI Reuse, alongside NHI1 Improper Offboarding, NHI5 Overprivileged NHI, NHI7 Long-Lived Secrets, and NHI10 Human Use of NHI. Use that list to name findings, and cite CIS or NIST controls when an auditor needs a citable source, because the OWASP list is an awareness document, not a standard.
3. Prefer managed, federated, or short lived proof over a stored static key where the platform offers it. A static key that could be replaced gets a migration task with a date at recertification.
4. Disable before delete, always. Deletion is the last step after a soak period, never the first response. Snapshot permissions and authenticators before any destructive step.
5. People do not work as a non-human identity. Human use of an NHI hides who acted and usually carries wider reach than the person's own account. Give the person their own access, then cut the shared path.
6. An unowned production identity is treated as a defect with a deadline, not a backlog item. Assign an owner, reduce it, or disable it in the current cycle.
7. Do not let the score make decisions. It orders work. Retirement, reach cuts, and cutoff in an incident stay human decisions, made from the flags and the evidence.