Control CoreDocs

AI Agent Identity

AI agents, service accounts, MCP clients, and CI/CD runners are non-human identities (NHIs). They often carry long-lived credentials without continuous re-validation. Control Core verifies NHI context on every request at the Bouncer and surfaces discovered workloads in Observe → Agent Access Controls (/observe/nhi).

Control Core is not an identity directory. Enrollment, credential rotation, and lifecycle stay with your IAM, SPIRE, or NHI management platform. Any system can push portable attributes through the generic PIP API; Rego controls decide allow, deny, and mask.

Agent Access Controls UI (~5 min)

  1. Open the Control Plane and navigate to Observe → Agent Access Controls (/observe/nhi).
  2. Review the Discovery Inbox for first-seen NHIs (observed status).
  3. Profile each identity: set identity type, declared scopes, and privilege score.
  4. Mark identities profiled or governed when ready to enforce controls.
  5. Enable NHI control templates under Controls → Templates → AI Security.
StatusMeaning
observedFirst seen in Bouncer traffic — appears in Discovery Inbox
profiledOperator classified the identity; attributes stored in PIP
governedAccess control bound; Rego templates enforce on every request

Troubleshooting: If the inbox stays empty, confirm traffic flows through a registered Bouncer and that NHI_AUTO_DISCOVERY is not set to false. Check Bouncer logs for NHI resolution events. Full reference: /troubleshooting.

Identity signals Rego reads

SignalSourceControl use
input.subject.nhi.idSPIFFE ID (XFCC), JWT sub / client_id / azp, or x-cc-agent-idPortable subject key
input.subject.nhi.sourceTrust tier: spiffe | jwt | headerWeight enforcement by trust
input.subject.nhi.identity_type_hintDerived from resolution pathClassify workload class
data.pip.nhi_attributes[subject_key]NHI registry + POST /v1/pip/subject-attributesPrivilege score, scopes, status

SPIFFE / SPIRE workload identity (~10 min)

For cryptographic workload identity, deploy SPIRE alongside the Bouncer. Short-lived X.509 SVIDs rotate automatically; The Bouncer reads certificates via SDS.

  1. Enable SPIRE in your Helm overlay (global.spire.enabled: true) or Compose profile.
  2. Confirm the Bouncer presents a SPIFFE ID in outbound mTLS and forwards XFCC to the policy engine input.
  3. Author controls that require input.subject.nhi.source == "spiffe" for high-privilege agent paths.

See Cryptographic workload identity and SPIRE / SPIFFE for install and attestation details.

Troubleshooting: If controlcore.spiffe_id is missing from audit or trace attributes, verify the SPIRE Agent socket is mounted and the Bouncer registered with SPIRE. Logs may show MTLS_AGENT_UNAVAILABLE. See mTLS enforcement.

Sync attributes from your IAM / NHI directory

Any vendor can push portable attributes without a Control Core SDK:

curl -sS -X POST "$CONTROL_PLANE/v1/pip/subject-attributes" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_key": "spiffe://example.internal/ns/prod/sa/billing-agent",
    "attributes": [
      {"name": "privilege_score", "value": 3},
      {"name": "identity_type", "value": "orchestrator_agent"},
      {"name": "declared_scopes", "value": ["read:invoices", "tools/read"]}
    ]
  }'

Verification

After profiling an NHI and enabling a template:

  1. Send agent traffic through the protecting Bouncer.
  2. Confirm the identity appears as governed in /observe/nhi.
  3. Review audit events for allow/deny decisions referencing the NHI subject key.

Next steps