Building an NHI Inventory: A Step-by-Step Guide

You cannot secure what you cannot see. Every mature NHI programme starts with inventory. Every failed NHI programme starts with policy. The order matters.

This is a working guide — the sequence we recommend to teams standing up NHI security from scratch, with time budgets that hold up in practice.

The teams that attempt to write policy before completing inventory make the same mistake every time: they write rules based on the NHIs they know about, which are typically the well-managed ones. The risky NHIs — the orphaned service accounts, the hard-coded API keys, the AI agents that nobody registered — are precisely the ones that are not yet in the inventory. Policy without discovery is security theatre applied to the wrong population.

Week 1 — sources and connectors

• Cloud IAM. AWS IAM, Azure AD service principals, GCP service accounts. Read-only credentials, `List*` and `Get*` scopes only.
• Kubernetes. ServiceAccounts per namespace, plus workload identity federation mappings.
• Source control. GitHub app installations, deploy keys, Actions secrets. GitLab equivalent.
• Secrets managers. HashiCorp Vault, AWS Secrets Manager, Azure Key Vault, GCP Secret Manager.
• SaaS. Okta OAuth grants, Google Workspace app connections, Slack apps, Salesforce connected apps.
• Databases. Service-user accounts, replication accounts, backup accounts.

The temptation in week one is to go deep on one source rather than broad across many. Resist it. A shallow scan across all six source categories in the first week gives you an accurate picture of the inventory's true shape. Going deep on cloud IAM first and discovering later that CI/CD holds three times as many credentials will derail your timeline.

Connector deployment order matters for a second reason: some sources emit change events (GitHub webhooks, Okta system log streaming) and some must be polled (most cloud IAM APIs). The change-event sources should be wired in week one even if the initial scan has not completed, because you want to start receiving deltas as soon as the baseline is established.

The connector configuration pattern

# connector config — read-only, principle of least privilege
connectors:
  - id: aws-iam-prod
    type: aws_iam
    credentials:
      method: role_assumption
      role_arn: arn:aws:iam::123456789012:role/TigerIdentityReadOnly
    permissions: [ListUsers, ListRoles, GetUser, GetRole,
                  ListAccessKeys, ListAttachedRolePolicies]
    scan_cadence: 15m
    change_events: cloudtrail_stream   # real-time delta on top of batch scan

  - id: github-org
    type: github_app
    installation_id: 12345678
    scopes: [read:org, read:repo, read:secrets]
    scan_cadence: on_push
    webhook: true

  - id: okta-prod
    type: okta
    api_token_ref: vault://connectors/okta-prod-token
    scopes: [okta.apps.read, okta.groups.read, okta.users.read]
    scan_cadence: 1h
    change_events: system_log_stream

Every connector should use the minimum permissions required for discovery. This is not only good security hygiene — it also means the connector deployment can be approved by an IT admin rather than requiring a CISO sign-off, which keeps the programme moving.

Week 2 — the graph

The graph schema decisions made in week two will be load-bearing for years. The most important choice is deduplication granularity. Folding two representations of the same secret into a single node is correct — but doing it too aggressively (for example, treating any two secrets with similar names as duplicates) will produce a graph that hides real risk. When in doubt, maintain two nodes with an "IS_SAME_AS" edge and let analysts confirm.

Timestamped edges are another decision that pays dividends later. When an auditor asks "show me all service accounts that had write access to this database in Q2," a graph with timestamped edges can answer directly. A graph without timestamps can only tell you the current state. Given how much remediation work happens over the course of a year, current-state-only graphs become unreliable compliance evidence quickly.

Week 3 — ownership attribution

The single most useful column in the inventory is "owner." Without it, every subsequent action (rotate this key, revoke this token) becomes a manual investigation.

• Git blame. The last human to touch the file that provisioned the identity, minus service-account committers.
• Deployment manifests. Helm chart owner, Terraform module owner, ECS task-definition author.
• HRIS reconciliation. If the attributed owner is inactive in Workday, the identity is orphaned.
• Manual override. Owners must be reassignable in 30 seconds. If it takes a Jira ticket, no one will do it.

Attribution confidence matters as much as attribution completeness. A "90% confident" owner attribution is more useful than "unknown" — but only if the system makes the confidence score visible and routes low-confidence attributions to a human confirmation queue. The worst outcome is a high-confidence wrong attribution: a service account pointing to an engineer who left two years ago, which nobody notices because the system confidently reported an owner.

Week three should also establish the "orphan" workflow: what happens when attribution fails or the attributed owner is no longer active. The default should be to quarantine the identity (read access still valid, write/execute blocked) and notify the team lead of the most recently attributed human owner. A 72-hour window to claim the identity before it is retired is a reasonable default for non-critical workloads.

Week 4 — the freshness problem

A stale inventory is worse than no inventory. Two guarantees to design for from day one:

• Every source re-scans on a schedule. Cloud IAM every 15 minutes. Code every commit. SaaS every hour.
• Every source emits change events. New identity → NATS event → workers update graph → dashboards reflect it in seconds, not on next scan.

The freshness problem has a second dimension beyond polling cadence: what happens when a connector goes offline? A connector that stops reporting should not silently drop its last-known findings — they should remain in the graph with a "connector offline" annotation. An inventory that shows "no findings from AWS IAM" when the connector is down is indistinguishable from "no NHIs in AWS IAM" and actively dangerous.

Design a connector health dashboard on week four alongside the inventory itself. Track: last successful scan per connector, delta between scan time and current time, connector error rate, and coverage (number of sources where connectors are configured vs. total known sources). A green inventory dashboard with an offline connector is a false green.

The metrics that matter

Once the four-week foundation is in place, the programme needs leading indicators that drive ongoing improvement. The following metrics form a useful NHI programme scorecard.

What to expect in the first result

• 3–10× more NHIs than the running list your identity team maintains.
• 30–40% of secrets untouched in 90 days.
• 15–25% of service accounts with no human owner mappable via HRIS.
• A handful of highly privileged identities that nobody can immediately explain — always the highest-priority remediation.
• Several CI/CD pipeline credentials with production-wide permissions — these are common and consistently underestimated as a risk surface.
• At least one AI agent or MCP server that engineering deployed without security's knowledge, now appearing in the graph for the first time.

The final two items on that list are newer additions to what we see in first scans, reflecting how rapidly both CI/CD complexity and AI agent adoption have grown. Two years ago, teams were surprised by the sheer count of secrets outside their vault. Today, they are equally surprised by the number of AI agent identities that have quietly accumulated in their environment. The inventory is not just a one-time exercise — it is a live signal about where your organisation's risk is actually growing.