AgentSecrets v3.0.0

AgentSecrets v3.0.0 marks a major milestone, expanding the zero-knowledge credential infrastructure to now host and enforce complete credential governance for AI agents, rather than just secrets management. By moving beyond simple secrets retrieval to active runtime governance, this release introduces structural layers that prevent prompt injection leaks, trace agent operations, and lock down production credentials.

With the introduction of the transient proxy, AgentSecrets enforces active credential security regardless of whether you remember to run the daemon. This is the difference between a security tool and a security guarantee.

What's New in v3.0.0

Additions

Agent Identity & Capabilities

LLM agents now run under a formal identity framework rather than having unauthenticated, unrestricted access.

• Agent Capabilities: Limit what specific secrets an agent token can access by setting strict whitelists and blacklists.
• Granular Controls: Use agentsecrets agent policy set <agent-id> --allow PUBLIC_SECRET --deny PRIVATE_SECRET to restrict access right at the proxy boundary.
• Identity Tokens: Generate secure identity tokens (agt_...) bound to these policies via agentsecrets agent token issue.
• Secure Token Keychain Storage: Store newly registered or issued agent tokens directly in the native OS Keychain.
• Offline Caching & Outage Fallback: Validated agent capabilities are cached in the keyring to allow proxy authentication and policy checks to continue executing during cloud API outages.
• Read more in Agent Capabilities.

Secret-Level Policies

Define fine-grained, secret-specific usage rules that restrict how and where credentials can be used.

• Domain-Specific Rules (--rule): Configure specific rules matching target domains and their allowed HTTP methods and actions (e.g. POST=request_permission, GET=allow). Rules can be repeated using the repeatable --rule flag.
• Global fallback: When no domain-specific rules match, the proxy falls back to evaluating global constraints (--domains and --methods). If no global rules are configured and domain-specific rules are defined, unlisted domains are denied by default.
• Default-Allow for Unlisted Methods: If a method is not explicitly restricted in a rule or global methods map, it now defaults to allow. This simplifies policies by allowing you to define constraints like POST=request_permission without needing to explicitly allow GET or other methods.
• Request Permission Flow: Configure policies to require manual developer approval at runtime (via agentsecrets proxy approve) for critical actions.
• Cloud Synchronization & Caching: Policies are synchronized on write with the cloud backend, and dynamically resolved via read-through local keyring caching.
• Read more in Secret Policies.

Zero-Disk Configuration Storage

We have completely eliminated the local config file attack surface by migrating all cryptographic operations and session storage directly to the native OS Keychain. By moving session tokens and workspace keys out of config.json and token.json into the OS Keychain, we eliminate an entire class of credential theft attacks.

• Zero plaintext keys on disk: Sensitive authentication tokens, decrypted workspace keys, and agent capabilities are stored securely inside your OS Keychain (macOS Keychain, Windows Credential Manager, or Linux GNOME Keyring/KWallet via the keychain-auth daemon). config.json and token.json on disk are purged of secret values.
• Seamless Legacy Migration: Legacy disk configurations are automatically detected, migrated to the secure Keychain, and purged from disk files upon upgrading.
• Read more in keychain-auth Subsystem and Keychain Storage Troubleshooting.

Forensic Governance Logs & Replay

A tamper-proof auditing engine that captures complete execution context to reconstruct or verify runtime operations. Unlike standard application logs, forensic logs maintain strict cryptographic integrity and record structural call metadata to trace credential usage.

• Forensic Metadata Tracking: Captures the exact calling binary path, binary hash, requesting PID, agent identity, target URL, and timestamp. This allows security teams to verify exactly which binary code resolved a credential.
• SQLite Storage: Logs are saved locally in a high-performance SQLite database under ~/.agentsecrets/audit.db.
• Cryptographic Hash Chaining: Every log entry is chained to the previous one via SHA-256 (chain_hash = sha256(prev_id + current_id + created_at)), making the audit trail mathematically immutable. Any tampering (deleting or editing entries) breaks the chain.
• Log Verification & Replay: Use agentsecrets logs verify to instantly flag deleted, edited, or reordered entries, and agentsecrets logs replay <id> to visually reconstruct the exact environment state at the millisecond of execution.
• Workspace Management Logs: CLI administrative operations—such as allowlist modifications, project/workspace bindings, agent registrations, and policy updates—are captured as secure management events in audit.db and rendered inline in chronological audit trails.
• Read more in Audit Logs.

Child Process Output Masking (Stdout/Stderr Redaction)

Although our zero-knowledge architecture does an excellent job keeping secret values out of sight, the env command was identified as a potential weak link. Since dynamic applications and SDKs require secrets in their environment variables, an attacker or compromised agent could simply execute a script to print the entire environment block, exposing the raw credentials.

To mitigate this threat, we introduced mandatory stdout/stderr stream masking:

• Mandatory Output Redaction: When executing child processes using agentsecrets env -- <command>, the CLI intercepts the child's output streams. If any secret or its encoding variants (Base64, Hex, URL-encoded, Case variations) is printed, it is automatically replaced with [REDACTED] before hitting the console.
• Always Enforced: This layer cannot be bypassed via flags or configuration overrides, guaranteeing that compromised subprocesses or rogue AI agents cannot leak secrets by turning off the masking.
• Read more in the env command documentation.

Expanded Model Context Protocol (MCP) Server

While the MCP server was already a built-in feature of AgentSecrets, this release significantly expands its capabilities, bringing the total to 19 built-in tools that allow LLM agents and modern AI clients to interact with AgentSecrets out-of-the-box.

This expansion enables a new class of self-governing agent behavior. Instead of being passive consumers, agents can now actively govern their own environment. For example:

• Autonomous Credential Rotation: The rotate_key tool allows an LLM agent to trigger credential rotation on its own when necessary.
• Self-Auditing Posture: Using get_blocked_requests and get_redaction_events, an agent can inspect and audit its own security logs to report its current compliance level.
• Drift Detection: The diff_environments tool lets an agent check for credential discrepancies across dev, staging, and production environments.

Other tools cover core credential operations (api_call, list_keys, check_key, get_coverage), context management (get_status, get_environment, switch_environment, pull_secrets, diff_secrets), agent identity, and allowlist inspection. Simply running agentsecrets mcp install automatically registers all 19 tools in Cursor, Claude Desktop, and OpenClaw.

• Read more in Cursor integration and Claude Desktop integration.

Improvements

Transient Proxy & Outbound Security

A paradigm shift in active credential protection.

• 100% Security Parity: If the background proxy daemon is not running, the client dynamically spawns a transient proxy on a free port, executes the request securely, and tears it down. Security policies are always enforced, even if you forget to start the proxy.
• Fail-Fast Sequence of Checks: Reordered the proxy resolution checks to follow a "shortest path to block" (fail-fast) pipeline. Cheapest local checks (such as key presence and agent identity scopes) execute first, followed by allowlist matching, secret policy evaluation, actual decryption, and finally outbound TCP connection setup.
• Local Pre-Shared Session Token: Blocks unauthorized local processes or browser extensions from calling the proxy. The CLI secures and rotates this token automatically via the OS Keychain using the X-AS-Session-Token header.
• SSRF & DNS Rebinding Defenses: Intercepts connections targeting private subnet ranges (RFC 1918) or loopback addresses. Resolves target IPs directly to prevent DNS Rebinding.
• Read more in SSRF Protection and Session Token.

Security Boundary Gating & Write-Protection

Actions affecting administrative configurations or the production environment require local verification.

• Local Password Verification: Modifying production secrets, updating variables globally (--all-envs), registering new agents, issuing agent tokens, or updating agent policies prompts for the user password. The hash is verified locally using a PasswordHash derived from email and password (SHA-256).
• Delete Password Gating: Explicitly gates all secret deletion operations (e.g. agentsecrets secrets delete or clearing key configurations) behind local password verification, preventing rogue scripts or compromised agents from performing unauthorized destructive actions.
• Bypass Gate Protection: Gates all credential management and access escalation functions to prevent rogue scripts, compromised packages, or misbehaving agents from silently registering identities or issuing bypass tokens.
• Read more in Environments Overview.

CLI Enhancements & Telemetry

• Offline Status Checks: The status command now operates offline, gracefully showing Login to view for sync statuses instead of raising a blocking 401 error.
• Optimized Agent Retrieval: Listing agents or getting policies now retrieves all workspace and project-scoped agents in a single database request via the include_projects=true query parameter, avoiding N+1 slow sequential queries.
• Telemetry & Performance Insights: Track individual secret resolutions (secrets_resolved), cumulative proxy latency (total_proxy_duration_ms), and execution path breakdown. Monitor proxy usage, security ROI, onboarding friction, and performance.
• Read more in Proxy Performance.

Approval Flow UX

The request_permission approval flow is redesigned from a 30-second polling denial into a real-time interactive pause with dual-terminal notification:

• Request is held open: Instead of denying after 30 seconds, the proxy holds the HTTP connection open (up to 5 minutes) using a channel — no busy-waiting, no re-run required.
• Proxy terminal prompt — immediate: The moment a request is blocked, an interactive approval prompt appears in the proxy start terminal. No timeout expiry first.

  Approval Required
  ──────────────────────────────
  Secret:   STRIPE_KEY
  Agent:    billing-processor
  Request:  POST → api.stripe.com
  
  Allow? [y/N/always]:

• Caller terminal hint — 2 seconds: If running agentsecrets call, the caller's terminal shows a waiting hint after 2 seconds of silence — including the exact proxy approve command to run from any terminal.
• always option: Grants session-wide approval for the secret+method+domain combination without re-prompting for the lifetime of the proxy session.
• Headless/CI compatibility: The interactive goroutine is TTY-gated and silently no-ops in non-interactive environments. The /approve HTTP endpoint remains available for programmatic approval.
• Read more in Secret Policies & Approvals.

Fixes

Windows Compatibility

• Named Pipe Daemon Support: Added support for communicating with the keychain-auth background service via Windows Named Pipes (\\.\pipe\keychain-auth) as an alternative to Unix domain sockets.
• Process Verification: Ported process credential extraction to Windows, query-matching caller process ID and binary path using native system properties to ensure identity verification works seamlessly on Windows.
• Config Path Resolution: Resolved configuration and helper path differences between POSIX and Windows directories to ensure native executable execution and keychain helper tools resolve paths correctly.

Upgrading & Migration

1Migrate Legacy Configuration

agentsecrets status

2Re-Authorize the Binary Hash (Linux & WSL only)

sudo keychain-auth authorize $(which agentsecrets) AgentSecrets

3Review Capabilities & Secret Policies