Anti-Impersonation & Process Verification (keychain-auth)

To protect AI agents against context leakage and prompt injections, AgentSecrets enforces the principle of least privilege: the local proxy resolves credentials, and application code only references keys by name. However, a local socket and proxy architecture introduces a critical attack vector: binary impersonation and local credential hijacking.

If an unauthorized script, compromised dependency, or rogue tool runs on your machine, what stops it from calling the local credential socket directly and exfiltrating your secrets?

AgentSecrets solves this through Kernel-Enforced Process Attestation via the keychain-auth security daemon (v3.2.x).

The Zero-Trust Security Broker Model

keychain-auth operates as an isolated, zero-trust security broker between client applications (like the agentsecrets CLI) and operating system credential stores:

Loading diagram...

Core Security Pillars

Kernel-Enforced Identity Resolution (Anti-Spoofing)

keychain-auth completely ignores any caller-supplied process IDs, headers, or paths. Identity resolution is enforced at the kernel layer:

• Linux (SO_PEERCRED): The daemon inspects Unix domain socket options via getsockopt(fd, SOL_SOCKET, SO_PEERCRED, ...) to retrieve the caller's true pid, uid, and gid directly from kernel memory.
• macOS (LOCAL_PEERPID): The daemon queries socket options using LOCAL_PEERPID to extract the caller's kernel-assigned process ID, then resolves the path via proc_pidpath.
• Windows (Named Pipes): Connections over \\.\pipe\keychain-auth query GetNamedPipeClientProcessId via the Win32 API.

Once the PID is established, the daemon inspects /proc/[PID]/exe (Linux), proc_pidpath (macOS), or QueryFullProcessImageName (Windows) to locate the binary on disk and calculates its SHA-256 cryptographic hash. Because modern OS kernels lock running binaries (ETXTBSY), the binary cannot be swapped on disk while running.

Handle Isolation via O_CLOEXEC

When an authorized client connects to keychain-auth and later forks or spawns child processes (e.g., executing a build script or running an untrusted sub-command), standard file descriptors are inherited by default.

• The Attack: An untrusted child could write requests directly to the inherited socket descriptor, bypassing authentication.
• The Defense: All connections are created with the SOCK_CLOEXEC / O_CLOEXEC descriptor flag (or non-inheritable handles on Windows). The kernel automatically closes the descriptor during any exec() system call, completely neutralizing handle-hijacking attacks.

Connection-Bound Sessions

In keychain-auth, the connection itself is the authenticated session. There are no session tokens or API keys transmitted over IPC that could be intercepted. Closing the socket or pipe instantly terminates the authenticated session.

Storage Backends & Hardware Key Sealing

keychain-auth adapts to the host operating system with defense-in-depth storage backends:

WSL Host Interop Auto-Extraction

Linux virtual machines inside Windows Subsystem for Linux (WSL) typically lack running D-Bus or Secret Service daemons. keychain-auth automatically extracts a companion Windows utility (keychain-helper.exe) to C:\Users\<user>\.config\keychain-auth\keychain-helper.exe. Master encryption keys and credentials are saved directly into the Windows Host's native Credential Manager with zero manual configuration.

Linux TPM 2.0 Hardware Key Sealing

On Linux machines equipped with a TPM 2.0 chip, master fallback keys are sealed directly to system hardware registers via tpm2_create and tpm2_unseal, ensuring credentials cannot be extracted if disk storage is cloned.

Binary Registration & Upgrade Flow

Because keychain-auth enforces strict binary hash verification:

1Initial Registration

# Registers the AgentSecrets binary with the daemon
keychain-auth authorize $(which agentsecrets) AgentSecrets

2Updating Binaries

Summary

With keychain-auth process attestation active:

• Only authorized binaries can request credential decryption.
• Compromised dependencies or scripts cannot spoof caller identities over local sockets.
• Untrusted child processes cannot hijack inherited connection descriptors.
• Master keys are hardware-sealed or persisted into native OS keychains with zero-disk plaintext residue.