Identity and authentication

DefenseClaw ties each agent action to the person who ran it and to the agent that did it. On a shared Linux host, for example an AD/Kerberos deployment where developers sign in over SSH, it records the directory principal and domain of the account, whether the login came over SSH, and a stable identity for each agent. Guardrail profiles can then give a group, a user, a connector or a single agent its own policy, and every decision records which profile applied and why.

What's new

• Who ran the agent. Records carry the account's directory principal, domain, directory type and an assurance level (verified or claimed), plus the login session (SSH, remote desktop or console) and the Kerberos principal. Read from the OS only. See How DefenseClaw knows who a user is.
• User- and group-based policies. Assign a guardrail profile by directory group, user, connector or agent, and check the result with defenseclaw guardrail profile list|show|explain. See User- and group-based policies.
• Agent identity. Every agent install gets a stable agt- ID, listed by defenseclaw agent identities (one row per install, user and connector), and every chat and sub-agent a stable ais- ID, which its records carry with the lineage and the user's principal. See Agent identity.
• IDE and plugin inventory. Every extension and plugin in VS Code and its forks, JetBrains IDEs, Visual Studio, Zed, Eclipse and Neovim, per user, with enabled state and an AI flag, in defenseclaw agent ide-plugins, the API, AIBOM, the TUI and Grafana. See IDE plugin inventory.
• Observability. A Grafana Identity & Users board, a $user filter on the other boards, new identity, profile and IDE attributes and records, and principal, domain, agent identity and profile name in Galileo spans. See Grafana dashboards.
• Managed hosts. enterprise linux|macos|windows profile-explain, agent-identities and ide-plugins give an administrator the same answers where no defenseclaw CLI is installed. See Check what DefenseClaw knows about a user.
• Doctor. defenseclaw doctor fails and doctor --fix repairs a hook script that lost its execute bit, reports one root cause per problem, and names the guardrail profile that decides for the account that runs it.

Attribution, not authentication

DefenseClaw reads identity only from the operating system the agent runs on.

• It never calls an identity provider (no Entra, Okta or LDAP API calls).
• It holds no identity credentials: no passwords, tokens, tickets or keys.
• It adds no new secrets and no sign-in step.
• Okta and Entra ID appear only through what the OS already knows: a joined device, Platform SSO, or a directory synced into AD or LDAP.

Each fact has an assurance level, sent as defenseclaw.user.principal.assurance: verified when the gateway or the root guardian resolved it for a uid or SID the gateway took from how it authenticated the caller (the kernel's peer credentials, a per-user credential, or on a per-user install the account the gateway runs as), claimed when the hook reported it from the user's own session and the user could change it. The reference for what is read on each OS is How DefenseClaw knows who a user is.

Supported identity types

Each cell names what DefenseClaw reads and the assurance it records. Per-user means the OSS install in the user's own home; enterprise means the standalone enterprise profile with its root guardian or SYSTEM enumerator.

What differs between platforms and installs, as exercised on real hosts:

• Kerberos ticket location on Linux. RHEL 9 keeps the ticket in a KCM: cache (sssd-kcm) and leaves KRB5CCNAME unset. Ubuntu 24.04 stores the ticket that ssh -K delegates in a file cache, FILE:/tmp/krb5cc_<uid>_<random>, named by KRB5CCNAME. DefenseClaw reads the default principal from either one, directly, and never runs klist.
• Linux per-user and enterprise. Both resolve the account, domain, groups and source through NSS, and the directory type from realmd, which any account may ask. Only enterprise adds the UPN from InfoPipe, so on a per-user install an SSSD account's principal is account@realm. An SSSD domain that no joined realm covers, such as plain LDAP or the Okta LDAP Interface, has no defenseclaw.user.directory on a per-user install; standalone enterprise reads its type, ldap, from InfoPipe.
• Windows per-user and managed. A per-user install resolves the account, the AD UPN and the Entra UPN and tenant itself, but has no group list: groups assignments cannot match there. The managed host's SYSTEM enumerator supplies the sign-in token groups.
• macOS per-user and enterprise. A per-user install reports the account and its groups as verified, directory local, source macos_opendirectory. The directory, domain and SSO provider of a bound Mac need the enterprise root enumerator. The session's Kerberos principal and the SSH session are claimed. The principal comes from the default API: cache, which the hook reads with macOS's own /usr/bin/klist --json at most once per 5 minutes, or from a FILE: cache that KRB5CCNAME or krb5.conf names.
• Okta is never an Okta lookup. On Linux and Windows an Okta user is whatever AD or LDAP account the OS gets from Okta: an AD account Okta syncs to, or an LDAP account SSSD reads from the Okta LDAP Interface. The okta directory value comes only from a Mac's Platform SSO or Okta Device Access provider.
• Okta through the Okta LDAP Interface and SSSD was tested live on RHEL 9 with an Okta org; see Okta on Linux.
• Entra ID was tested on a live tenant. Per-user installs on an Entra-joined Windows 11 computer and on Ubuntu with Entra ID SSH sign-in report directory entra_id, the UPN as principal and, on Windows, the tenant ID; a users assignment by UPN selected the profile on both. See Entra ID fields, as seen live. Windows puts an Entra group into the sign-in token only when a built-in local group lists it. On Linux, Entra groups reach the host only through Himmelblau or Microsoft Entra Domain Services with SSSD, both tested live; the aad module gives none. On macOS, Platform SSO gives no Entra groups (tested live); a local group has to carry the membership. The Okta Device Access and Okta Platform SSO readers were tested against recorded OS output, not a live tenant. See the limits in How DefenseClaw knows who a user is.

Agent identity

Each agent gets an identity of its own instead of only inheriting the person's. The identities are digests of facts the gateway already holds, so they need no credential and stay the same across sessions, gateway restarts and upgrades.

The machine ID comes from /etc/machine-id, the Windows MachineGuid or the macOS IOPlatformUUID. A config root the agent claims, such as a CLAUDE_CONFIG_DIR override, is recorded as a hint and never changes the ID. Linux and macOS give a removed account's uid to the next account created, so the account name, as getent passwd shows it for the uid, is part of the ID there: the new account gets agent IDs of its own, also in the removed account's home, and an agents profile assignment of the removed account never applies to it. Renaming the account starts new agent IDs too. The removed account's agent identities stay listed under its name, with "retired": true, and inventory records of its installs carry no agent ID. A Windows SID is never reused, so a renamed Windows account keeps its agent IDs. On a managed Linux, macOS or Windows host, a deleted account's agent identities are retired the same way once the hook guardian has dropped the account from its enrollment, and an account created again under the same name gets agent IDs of its own. Two users who reuse the same session ID get different ais- IDs and different agents: the main agent's ID is made from the user's agt-, the connector and the session ID, so gen_ai.agent.id and the lineage IDs below differ too. A chat that resumes after a gateway restart keeps its ais- ID and is not counted again in the Sessions column of defenseclaw agent identities, however many chats were open at the restart. The column counts chats: a sub-agent that runs in a session of its own, as a Codex 0.160 thread does, is not counted. The Secure Client profile keeps its existing agent IDs and gets no new attributes.

A record carries an ais- ID only when its hook belongs to a session. Hermes sends transform_terminal_output without a session; the gateway gives it the session that the pre_tool_call of its task named or, when it names no task (Hermes 0.21), the session of the last pre_tool_call of the same agent within ten minutes, so it carries the same ais-. The OpenCode defenseclaw.plugin.loaded record is sent when the plugin loads, before any session exists, so it carries the agt- ID and no ais-. A denial of the foreign-hook guard (an unapproved plugin or hook) carries the agt- ID, and an ais- only when the hook named its session: the guard keys a block on the agent process, so the OpenCode plugin sends none with its defenseclaw.plugin.loaded and tool.execute.before denials.

Claude Code and Codex name a sub-agent on every hook it makes, so each of those hooks carries the sub-agent's ais- at depth one with the main agent as its parent, also when the gateway restarted after the sub-agent started. Codex 0.160 runs a spawned agent as a session of its own and sends no SubagentStart; the gateway links that session to the agent that created it, so it is a sub-agent at depth one with the parent session named, under the ais- of its own session. Copilot CLI also runs a task sub-agent, such as explore, as a session of its own, and that session's hooks name only the session. Its subagentStart arrives first, in the parent's session, and its subagentStop names the child session. The gateway links the session's first hook to the agent of the open subagentStart and does not count the session as a chat. When the same user has open sub-agent starts under two different chats, the gateway cannot tell which chat a new session belongs to. The link then waits for subagentStop, and the hooks before it stay at depth zero.

A sub-agent has no agt- of its own: it runs in its parent's install, so it shares the parent's agt- and has its own ais-. The lineage attributes link it to its parent and hold the IDs the connector reports. A main agent that reports none, as Claude Code's and Codex's do, gets one DefenseClaw makes (agent- and 16 hex digits) from the agt-, the connector and the session ID. defenseclaw.agent.parent.id and defenseclaw.agent.root.id name the connector agent ID of the parent and the root (gen_ai.agent.id on their own records), and defenseclaw.session.parent.id and defenseclaw.session.root.id name their connector session ID (gen_ai.conversation.id). No attribute holds the parent's ais-, so join a sub-agent to its parent on those connector IDs and the shared agt-.

List the identities the gateway has seen:

defenseclaw agent identities
defenseclaw agent identities --user alice --connector codex --json

User                    Connector  Agent identity        Sessions  Last seen  Config root
alice@corp.example.com  codex      agt-3f9c0a1b2c3d4e5f  4         2m ago     /home/alice@corp.example.com/.codex

The command lists every identity, most recently seen first. --limit N lists only the N most recent. When the list is cut short, the command says so on stderr and names the total; narrow a long list with --user or --connector. The gateway API returns 1000 identities a page (limit and cursor), and the TUI Agents tab shows the 1000 most recently seen as Agents (1000+). Use the command to see them all.

Sandboxed agents

An agent that runs in an OpenShell sandbox is attributed like a host agent, with four differences.

• The user is the host user on the sandbox binding, the account that started the sandbox. The binding is attribution, not proof of the calling process, so it supplies no verified directory facts or groups. User, group and agent identity selectors cannot match from that binding; the default guardrail profile or a connector-only assignment applies. Identity headers the sandbox sends are ignored.
• Each sandbox has its own agt-. The agent's install is the sandbox, not a config directory in the home, so a project run in two sandboxes is two agents, and the agt- of the host install does not name a sandboxed run. defenseclaw agent identities lists one per sandbox, and they stay listed after the sandbox is gone.
• Its hooks always enforce. A sandbox's hooks run in action mode whatever guardrail.mode or the profile's mode says, because DefenseClaw launched the harness and its hooks are the only gate on the tool calls. The selected profile's thresholds and rule pack still apply.
• Its web egress follows the sandbox's network profile. The egress proxy decides each site by the sandbox's OpenShell profile (open, balanced or strict) and its policy pack, not by a guardrail profile. See Network and egress.

Guides

The guides below use Active Directory and Okta. For Microsoft Entra ID users on Entra-joined Windows and on Azure Linux VMs, see Deploy with Microsoft Entra ID.

Join a Linux host to AD and see what DefenseClaw learns

This guide uses RHEL 9 or Ubuntu 24.04, the domain CORP.EXAMPLE.COM and the user alice. DefenseClaw needs nothing from AD beyond what a normal domain join gives the host.

sudo dnf install realmd sssd sssd-tools sssd-dbus sssd-kcm adcli samba-common-tools krb5-workstation oddjob oddjob-mkhomedir

sudo apt-get install realmd sssd-ad sssd-tools sssd-dbus sssd-kcm libnss-sss libpam-sss adcli krb5-user
sudo pam-auth-update --enable mkhomedir
sudo hostnamectl set-hostname host.corp.example.com
sudo grep -qxF 'includedir /etc/krb5.conf.d/' /etc/krb5.conf || sudo sed -i '1i includedir /etc/krb5.conf.d/' /etc/krb5.conf

sudo realm discover corp.example.com
sudo realm join --membership-software=adcli --client-software=sssd -U administrator corp.example.com
sudo realm permit alice@corp.example.com

printf 'GSSAPIAuthentication yes\n' | sudo tee /etc/ssh/sshd_config.d/50-gssapi.conf
sudo sshd -t
sudo systemctl reload ssh

[sssd]
services = ifp

[ifp]
user_attributes = +userPrincipalName

sudo sss_cache -E
sudo systemctl restart sssd
systemctl is-system-running
getent passwd alice@corp.example.com
id alice@corp.example.com
realm list
dbus-send --system --print-reply --dest=org.freedesktop.sssd.infopipe /org/freedesktop/sssd/infopipe org.freedesktop.sssd.infopipe.GetUserAttr string:alice@corp.example.com array:string:userPrincipalName

kinit -f alice@CORP.EXAMPLE.COM
ssh -K alice@corp.example.com@host.corp.example.com

defenseclaw audit export --since 10m \
  | jq -c 'select(.action=="hook_decision") | .structured
      | {user: ."defenseclaw.user.name", domain: ."defenseclaw.user.domain",
         directory: ."defenseclaw.user.directory", source: ."defenseclaw.user.identity.source",
         principal: ."defenseclaw.user.principal",
         kerberos_principal: ."defenseclaw.session.kerberos_principal",
         assurance: ."defenseclaw.user.principal.assurance", session: ."defenseclaw.session.kind",
         agent: ."defenseclaw.agent.identity.id"}' | sort -u

audit_file=$(mktemp)
sudo /opt/defenseclaw/bin/defenseclaw-gateway audit export --since 10m -o "$audit_file" --force
jq -c 'select(.action=="hook_decision") | .structured' "$audit_file"
rm "$audit_file"

Assign a guardrail profile to an AD group

Define a profile, assign it to the group, then ask the gateway who gets it:

guardrail:
  mode: observe
  profiles:
    contractors:
      mode: action
      block_at: MEDIUM
  profile_assignments:
    - profile: contractors
      match: {groups: ["contractors@corp.example.com"]}
  default_profile: ""        # "" keeps the global guardrail.* behaviour

defenseclaw config validate
defenseclaw guardrail profile list
defenseclaw guardrail profile explain --user bob@corp.example.com --connector codex

  user:    bob@CORP.EXAMPLE.COM (2 group(s))
  profile: contractors
  match:   group (contractors@corp.example.com)
  digest:  sha256:4f460f32fe21aa052aa524027ba08c9f89fe695cbe39cea2fb0252e5e0a738bd
  applies (codex): mode=action block_at=MEDIUM alert_at=pack hilt=off rule_pack=...

Users of a child domain of the joined domain (bob@emea.corp.example.com on a host joined to corp.example.com) match users assignments only when you list their domain in ai_discovery.trusted_ad_child_domains; an empty list trusts the joined domain only. See Child domains of the joined realm.

Use the group name exactly as id -Gn prints it. A Windows group is CORP\Contractors, the bare name or its SID. The full guide, with precedence, worked scenarios, the audit record and delivery to managed hosts, is User- and group-based policies.

Use Okta users on Linux through the Okta LDAP Interface

DefenseClaw never calls Okta. On Linux, SSSD reads Okta users and groups through the Okta LDAP Interface, and DefenseClaw sees them as it sees any SSSD account: the uid, the name and the Okta groups are verified, on per-user installs and on the standalone enterprise profile, and an Okta group can choose a guardrail profile. This was run live on RHEL 9.8 against an Okta org. SSSD 2.9, the version in RHEL 9, cannot bind to Okta; the guide names the fix.

The whole path, with the Okta setup, the SSSD build, starter scripts, what DefenseClaw records, and troubleshooting, is Okta on Linux.

Check what DefenseClaw knows about a user

For a user on a host with the defenseclaw CLI (the OSS install):

defenseclaw guardrail profile explain --user alice@corp.example.com --json | jq .subject
defenseclaw agent identities --user alice
defenseclaw agent ide-plugins --user alice --ai-only

subject shows the user ID, the principal, the UPN and the groups as the gateway resolves them, the same way it does for a live request. --user takes the account name as getent passwd (or id) shows it, a uid or a SID, in any case.

A managed install (the enterprise package, MDM or Setup) has no defenseclaw Python CLI. As root on a managed Linux or macOS host, read the same answers from the managed gateway, as JSON. The package does not put defenseclaw-gateway on root's PATH, so use its full path:

sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux profile-explain --user alice@corp.example.com --connector codex
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux agent-identities --user alice@corp.example.com
sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux ide-plugins --user alice@corp.example.com --ai-only

On a Mac, run sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos ... instead. On a managed Windows computer, run them from an elevated PowerShell prompt (or as LocalSystem from an MDM script):

& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows profile-explain --user CORP\alice --connector codex
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows agent-identities
& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows ide-plugins --user alice

After an account is deleted, agent-identities --user still finds its agent identities by the name they are listed under, by its uid or by its SID.

profile-explain also lists every configured profile with its digest under profiles, in place of profile list and profile show. For fleet-wide views, use the Grafana Identity & Users board.

Turn off the principal or the IDE inventory

Two settings decide how much personal data leaves the host:

config_version: 9
ai_discovery:
  include_user_principal: false   # the default; true sends the principal
  ide_inventory: ai_only          # all | ai_only | off

Then check the file with defenseclaw config validate. A running gateway applies the change on its next reload; on a managed host, edit the machine configuration instead. Confirm with the audit export in the first guide: the principal and kerberos_principal keys are absent while the setting is off. A home-directory path can still contain the UPN on SSSD hosts with fully qualified names; see End-user identity.

What stays on in either case: user.id, the account name, the domain, the directory type, the assurance, the session kind and the client address. There is no separate switch for them, so choose destinations accordingly. The principal, the Kerberos principal, the client address and the tenant ID are marked sensitive. Unlike user.id, nothing joins records on them, so the strict redaction profile (and a custom profile that extends it) removes them from what a destination receives, while none, sensitive and content keep them. See Redaction. The identity.observed record carries a group count, never group names. The Secure Client profile collects none of these facts.

Troubleshooting

IDE plugin inventory

DefenseClaw also lists every extension and plugin in each user's IDEs, with its enabled state and an AI flag. That inventory is part of AI discovery, and each row carries the verified user it belongs to. See IDE plugin inventory for the IDE families, where the enabled state comes from, what is and is not collected, and the CLI, API, AIBOM, TUI and Grafana views.

Next steps