Zero-Plaintext, Hardware-Sealed Secrets Management for macOS Engineers & AI Coding Agents.
sec-agent is a fully local, offline-first credentials manager designed to protect developer secrets (API keys, database credentials, cloud tokens, and certificates) from session takeover vectors (hijacked terminal sessions, remote SSH shell attackers, or administrative screen monitoring).
It functions similarly to ssh-agent or gpg-agent, but is engineered specifically for secure secret, variable, and key-value retrievalโcompletely eliminating the need for plaintext passwords, .env files, or stored credentials on disk, across local development environments and multi-tier cloud pipelines.
Warning
macOS Exclusivity: This tool utilizes macOS-specific APIs, including LocalAuthentication (Touch ID/Apple Watch hardware prompts), Keychain Services (Secure Enclave master key storage), and macOS Hardened Runtime memory protections. It is not compatible with Windows or Linux.
| Capability | Description | Command / Feature |
|---|---|---|
| ๐ Hardware-Anchored Silicon Storage | Master keys generated and sealed inside the Apple Silicon Secure Enclave. Zero plaintext keys on disk. | kSecAccessControlBiometryCurrentSet |
| ๐ Touch ID Physical Presence Gate | Physical sensor contact required. Unlocks in < 0.1s without typing master passwords. Blocks remote scripts. | eval $(sec open) |
| ๐ก๏ธ Active Session Hijack Interceptor | Process tree & environment scanner detects remote SSH (sshd, SSH_CLIENT) and VNC/screensharing, self-locking instantly. |
Active daemon defense |
| ๐ Multi-Tier Environment Contexts | Switch between dev, dta, staging, prod in memory with zero disk writes. |
sec use staging / sec env ls |
| ๐ Zero-Plaintext Process Injection | Inject secrets into child processes with dynamic streaming log redaction ([REDACTED_BY_SEC]). |
sec run --redact -- <cmd> |
| ๐ Subprocess Stdin Streaming | Feed secrets into child process stdin or stdout stream pipes directly in memory with zero temp files. | sec run --stdin-key / sec pipe |
| ๐ Two-Tier Secret Metadata | Separate concise summaries from multiline notes, inspectable via CLI or JSON, with interactive $EDITOR editing. |
sec describe / sec edit-notes |
| ๐ Cross-Profile Template Streaming | Interpolate mustache {{key}} and cross-profile {{@env:key}} templates from files or stdin in memory. |
sec stream <file> |
| ๐ก๏ธ Git Pre-Commit Privacy Guard | Staged file scanner combining Shannon entropy analysis and active vault exact-match leak detection. | sec githook install / check |
| ๐ Hybrid Workspace Security Scanner | Multi-engine plaintext scanner (sec-native + Homebrew gitleaks/trufflehog) with a 3-Tier Integration Action List. |
sec scan [path] [--json] |
| ๐ต๏ธ Zero-Trace Script Runner & Backups | Execute vault-stored scripts over stdin pipes and run stealth multi-folder rsync backups with zero ps aux or history leaks. |
sec exec / sec backup run |
| ๐ค Autonomous AI Coding Partner | Turn-1 biometric protocol, dual-audience diagnostics, and bundled Agent Skill for Antigravity & IDEs. | sec skill install / update |
| ๐ฅ๏ธ Hardened Web UI & Desktop App | Local Web UI (127.0.0.1:9876) with single-tab BroadcastChannel binding and direct in-browser Touch ID. |
sec gui / SecAgent.app |
In modern software development, hardcoding credentials in local .env files is incredibly common. What starts as a "temporary PoC or pre-prod password" often:
- Accumulates over the years across multiple project folders.
- Leaks into shell history log files (
.zsh_history,.bash_history). - Gets committed accidentally to public or private Git repositories.
- Remains completely unencrypted, leaving credentials accessible to any local process or remote SSH connection active on your machine.
Most secret management tools (Vault, Doppler, SOPS, 1Password CLI) suffer from the "Secret Zero" Paradox: to pull your encrypted secrets, they require a plaintext API token, private key file, or bootstrap certificate stored on your disk. They simply shift the vulnerability from a database password to a key file.
flowchart LR
accTitle: The Secret Zero Paradox: Traditional Secret Managers versus sec-agent Secure Enclave Model
accDescr {
Comparison diagram with two horizontal tracks.
Track 1 (Traditional Tools like Vault, Doppler, SOPS, 1Password CLI): A Secret Vault relies on a Plaintext Token or Key File stored on disk, which can be stolen by a local script, infostealer malware, or remote SSH attacker.
Track 2 (sec-agent Secure Enclave Model): An Encrypted Store is sealed by a master key inside the Apple Silicon Secure Enclave Hardware Chip, gated by the physical Touch ID Finger Sensor, keeping credentials hardware-locked with zero plaintext files on disk.
}
subgraph Traditional["โ Traditional CLI Secret Tools (Vault, Doppler, SOPS, 1Password CLI)"]
direction LR
T1["๐๏ธ Secret Vault"] --> T2["๐ Plaintext Token / Key File on Disk"]
T2 --> T3["๐จ STOLEN BY ATTACKER / LOCAL SCRIPT"]
end
subgraph SecAgent["โ
sec-agent (Apple Silicon Secure Enclave Model)"]
direction LR
S1["๐ Encrypted Store (secrets.enc)"] --> S2["๐ macOS Secure Enclave Chip"]
S2 --> S3["๐ Touch ID Finger Sensor"]
S3 --> S4["๐ก๏ธ HARDWARE LOCKED IN RAM"]
end
classDef danger fill:#4a151b,stroke:#f85149,stroke-width:2px,color:#ffdcd7
classDef warn fill:#3b2300,stroke:#d29922,stroke-width:2px,color:#fef3c7
classDef safe fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#d1fae5
classDef enclave fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#e0f2fe
class T1,T2 warn
class T3 danger
class S1,S2,S3 enclave
class S4 safe
โฟ Accessible Text Walkthrough & Terminal ASCII Diagram (Screen Readers / Plain-Text View)
Screen-Reader Linear Summary:
- Traditional Tools Vulnerability: Tools like Vault, Doppler, SOPS, and 1Password CLI require a bootstrap token, session file, or private key file on disk to authenticate. Any local malware or remote SSH attacker can read that plaintext file directly from the filesystem.
sec-agentEnclave Solution:sec-agentstores zero plaintext key files on disk. The master key is sealed inside the Apple Silicon Secure Enclave chip and requires physical finger contact on the Touch ID sensor to unlock secrets in memory.
TRADITIONAL TOOLS (Vault, Doppler, SOPS, 1Password CLI)
[ Secret Vault ] โโโถ [ Plaintext Token / Key File on Disk ] โโโถ โ STOLEN BY ATTACKER / LOCAL SCRIPT
SEC-AGENT (Secure Enclave Model)
[ Encrypted Store ] โโโถ [ macOS Secure Enclave Hardware Chip ] โโโถ [ Touch ID Finger Sensor ] โโโถ โ
HARDWARE LOCKED
- No Plaintext Keys on Disk: Zero secret key files, API tokens, or certificates sit anywhere on your filesystem.
- Hardware-Anchored Silicon Storage: Master keys are generated and sealed inside the macOS Secure Enclave. The master key never touches the disk.
- Biometric Physical Presence Gate: Decrypting secrets requires physical Touch ID sensor contact on the laptop console. Software scripts and remote attackers cannot fake physical presence.
- Zero-Friction PoC/Dev Adoption: Drop it into any local development project or PoC in 30 seconds with
sec-agent migrate-local .envโrequiring zero cloud setup, zero API tokens, and zero codebase modifications.
sec-agent is built on a secure-by-design model to prevent credential leakage:
flowchart TD
accTitle: sec-agent Secure Enclave Biometric Hardware Trap and Dual-Slot Recovery Architecture
accDescr {
Flowchart illustrating how sec-agent defends against local account takeover when an attacker or rogue administrator resets the macOS login password and enrolls a new fingerprint.
The Apple Silicon Secure Enclave detects the biometric database change via kSecAccessControlBiometryCurrentSet and immediately destroys the Slot 0 Master Key in hardware.
When the attacker taps Touch ID, access is denied because the hardware key was erased.
Access can only be restored by the legitimate owner entering the offline 24-word BIP39 paper seed phrase via Slot 1 Argon2id key derivation.
}
subgraph Threat["โ ๏ธ Threat Vector: Local Account / Admin Takeover"]
A["๐ต๏ธ Attacker / Rogue Sysadmin<br/>Resets macOS Password & Enrolls New Fingerprint"]
end
subgraph HardwareTrap["๐ Apple Silicon Secure Enclave Biometric Hardware Trap"]
B["๐ก๏ธ kSecAccessControlBiometryCurrentSet Triggered"]
C["๐ฅ Slot 0 Master Key Destroyed<br/>(Hardware Key Permanently Erased)"]
D["๐ Touch ID Tap by Attacker"]
E["โ ACCESS DENIED<br/>(errSecItemNotFound โ Vault Remains Sealed)"]
end
subgraph OfflineRecovery["๐ฑ Slot 1: Legitimate Owner Offline Seed Recovery"]
F["๐ Recovery Only via Offline Seed<br/>(User Enters 24-Word Paper BIP39 Mnemonic)"]
G["๐ Argon2id KDF Unwraps Slot 1<br/>(m=64MB, t=3, p=4)"]
H["โ
ACCESS RESTORED FOR OWNER<br/>(Re-Sealed to Owner's Touch ID)"]
end
A --> B
B -->|"Enclave Auto-Purge"| C
B -->|"Attacker Tries Sensor"| D
C --> E
D --> E
E -.->|"Cannot Bypass Without Paper Seed"| F
F --> G --> H
classDef threatNode fill:#4a151b,stroke:#f85149,stroke-width:2px,color:#ffdcd7
classDef trapNode fill:#1e293b,stroke:#f59e0b,stroke-width:2px,color:#fef3c7
classDef denyNode fill:#581c1c,stroke:#ef4444,stroke-width:2px,color:#fecaca
classDef recoverNode fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#d1fae5
class A threatNode
class B,C,D trapNode
class E denyNode
class F,G,H recoverNode
โฟ Accessible Text Walkthrough & Terminal ASCII Diagram (Screen Readers / Plain-Text View)
Screen-Reader Linear Summary:
- Threat Event: An attacker or system administrator resets the macOS account password and enrolls a new fingerprint in System Settings.
- Enclave Hardware Trap (
kSecAccessControlBiometryCurrentSet): The Secure Enclave hardware detects that the biometric fingerprint set was modified and permanently destroys theSlot 0master key. - Access Denied: When the attacker taps the Touch ID sensor, hardware decryption fails with
errSecItemNotFound, blocking access. - Offline Seed Recovery (
Slot 1): Only the legitimate owner holding the physical 24-word BIP39 paper seed phrase can runsec session recover(using Argon2id KDF) to unwrapSlot 1and restore access.
[ ATTACKER / SYSADMIN ]
โ
Resets macOS Password & Enrolls Fingerprint
โ
โผ
[ SECURE ENCLAVE BIOMETRIC HARDWARE TRAP ]
โ
kSecAccessControlBiometryCurrentSet Triggered
โ
โโโโโโโโโโโโโโโโโโโดโโโโโโโโโโโโโโโโโโ
โผ โผ
[ Slot 0 Master Key Destroyed ] [ Touch ID Tap by Attacker ]
โ โ
โผ โผ
[ Hardware Key Erased ] [ ACCESS DENIED ]
โ โ
โโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโ
โ
โผ
[ RECOVERY ONLY VIA OFFLINE SEED ]
โ
User enters 24-word paper BIP39 seed
โ
โผ
[ ACCESS RESTORED FOR OWNER ]
-
v2.0 Dual-Slot Vault Envelope:
sec-agentutilizes a LUKS-style dual key-slot envelope (VaultEnvelope):-
Slot 0 (Daily Biometric Slot): Master key protected in macOS Keychain under
kSecAccessControlBiometryCurrentSet. Unlocks instantly with a Touch ID tap (zero passwords typed). -
Slot 1 (Offline Recovery Slot): Master key encrypted with AES-256-GCM using an Argon2id key derived from an offline 24-word BIP39 seed phrase (CPU/memory-hard KDF:
$m=64\text{MB}, t=3, p=4$ ).
-
Slot 0 (Daily Biometric Slot): Master key protected in macOS Keychain under
-
Corporate Admin & Fingerprint Tamper Defense: In enterprise environments where a system administrator (or root attacker) resets the macOS account password and enrolls a new fingerprint in System Settings:
- The Secure Enclave hardware detects the biometric enrollment database modification.
- The Secure Enclave instantly and permanently purges
Slot 0from hardware storage. - When the attacker taps the sensor with their new fingerprint, the key no longer exists in hardware (
errSecItemNotFound). - Commands like
sec migrate-v2 --forcefail and skip locked vaults because the attacker cannot decrypt the active vault payload without the original key or the physical 24-word paper seed.
- Touch ID Physical Presence Gate: Decrypting daily session keys requires hardware-backed physical user validation (Touch ID contact or Apple Watch click), instantly blocking remote attackers and headless background scripts.
-
Cryptographic Session Isolation: Initializing
sec opengenerates a temporary random session token in the active shell context (SEC_SESSION_TOKEN). The background socket daemon enforces this token on all queries, preventing separate terminal processes or browser processes from querying your secrets. -
Multi-Layer Session Hijacking Intercepts: On every query request, the daemon walks the caller's process tree to block
sshdshell parents. In addition, it inspects the client process's active environment variables using BSDps e -ww -p <PID>to detect remote shell variables (SSH_CLIENT,SSH_TTY,SSH_CONNECTION). It also checks for active VNC graphical sharing (AppleVNCServer) and native sharing (screensharingd). If detected, the daemon locks itself and wipes all memory cache keys instantly, and records the triggering signal to the audit log. -
Disaster-Proof Write Transactions: All filesystem mutations (database saves, dotenv migrations, KeePassXC exports) utilize atomic sibling renames. The payload is written to a temporary file, flushed to storage blocks via
fsync(), and atomically replaced. Profile-isolated backups of the last 10 database snapshots are rotated automatically under~/.config/sec-agent/backups/<profile>/. -
SMP & Parallel Concurrency Resilient: Built with goroutine-per-connection Unix sockets and
sync.Mutexin-memory guards. Fully resistant to race conditions under high-throughput parallel execution (e.g.make -j8, concurrentterraform plan, or multi-agent AI swarm workloads). - Hardened Runtime Isolation: The daemon executes under macOS Hardened Runtime protections with no debugging entitlements. System Integrity Protection (SIP) blocks standard user-space debuggers and memory readers (including root UID 0) from inspecting its memory.
-
Input Boundary Hardening & Attack Vector Defense: All user parameters, profile identifiers, and environment inputs are strictly validated at boundary entrypoints:
-
Path Traversal Shield:
ProfileName.Validate()strictly enforces string invariants acrossGetStorePath,GetSocketPath, andGetPIDFilePath, explicitly rejecting directory traversal sequences (..), path separators (/,\), and control characters. Vault payloads cannot be written outside~/.config/sec-agent/. -
Subshell Environment Variable Sanitization: Subshell execution (
sec run) validates all secret key paths usingconfig.EnvVarKey.Validate(). Key paths containing control characters, null bytes (\x00), or=signs are automatically filtered out to prevent shell environment pollution or subshell process corruption. -
Automated Security Auditing: Releases undergo automated static security AST analysis via
gosec(make sec-check) and pre-release privacy audits (scripts/privacy_audit.sh) to guarantee zero secret leakage and 100% vulnerability resilience.
-
Path Traversal Shield:
-
Post-Quantum Cryptography (PQC) & Decoupled Architecture: Database payloads (
secrets.enc) are encrypted at rest with AES-256-GCM (offering 128-bit post-quantum security against Grover's algorithm). Exposing the encrypted file to local MDM scanners or IT backups yields zero usable data. Furthermore, the backend crypto engine (internal/crypto/) is strictly decoupled from the CLI/IPC layer, ensuring future NIST PQC algorithm upgrades (e.g. ML-KEM/Kyber) require zero changes to CLI flags, shell wrappers, or AI Agent Skills. - Offline First: No cloud synchronization, no third-party APIs, and zero SaaS dependency.
# Add Homebrew tap and install sec-agent
brew tap iafilius/tap
brew install sec-agentDownload the latest pre-compiled, macOS Hardened Runtime signed binary tarball from GitHub Releases:
# Extract and install binary to /usr/local/bin
tar -xzf sec-agent_v2.14.4_darwin_arm64.tar.gz
sudo mv sec-agent /usr/local/bin/# Clone repository and compile with macOS Hardened Runtime signature
make build codesign
# Run security static analysis checks (vet, vulncheck, gosec)
make sec-check
# Run tests
make testNote
Zero Name Collision: The CLI binary executable is named sec-agent to avoid conflicts with Homebrew's existing Perl sec (Simple Event Correlator) package. If you do not have the Perl sec tool installed and prefer 3-letter typing, you can optionally add alias sec=sec-agent in your ~/.zshrc.
sec-agent features a local, zero-friction Hardened Web UI served directly from the local loopback (http://127.0.0.1:9876). It can be launched via the CLI (sec-agent gui) or directly from macOS Finder as a standalone native application bundle (/Applications/SecAgent.app).
flowchart TD
accTitle: Hardened Web Browser GUI Architecture and Single-Tab Session Binding
accDescr {
Architecture diagram showing how the sec-agent gui local HTTP server on 127.0.0.1:9876 protects the browser session.
The Primary Browser Tab maintains an active BroadcastChannel and session heartbeat, receiving authenticated access.
Any Secondary or External Tab attempting to hijack or paste the URL is blocked with a 403 Forbidden Tab Lock response.
The local HTTP server uses ephemeral RAM-only session tokens and communicates directly with the macOS Secure Enclave and Keychain for in-process Touch ID biometric unlock.
}
subgraph Browser["๐ Browser Window Isolation (BroadcastChannel & Heartbeat)"]
Tab1["๐ข Primary Browser Tab<br/>(Active Session Heartbeat)"]
Tab2["๐ด Secondary / External Tab<br/>(Hijack or Pasted URL)"]
end
subgraph Server["๐ฅ๏ธ `sec-agent gui` Loopback Server (127.0.0.1:9876)"]
GUI["๐ก๏ธ Hardened Local HTTP Engine<br/>โข Single-Tab Binding via BroadcastChannel & Heartbeat<br/>โข Ephemeral RAM-Only Session Tokens (Zero Disk Storage)<br/>โข Direct In-Process Touch ID Biometric Unlock<br/>โข Pre-Launch Listener Auto-Cleanup (Zero Stale Port Conflicts)"]
end
subgraph Silicon["๐ Hardware Security Boundary"]
Enclave["๐ macOS Secure Enclave + Keychain"]
end
Tab1 -->|"โ
Authenticated Session"| GUI
Tab2 -.->|"โ 403 Forbidden: Tab Lock Active"| GUI
GUI -->|"LocalAuthentication Touch ID"| Enclave
classDef activeTab fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#d1fae5
classDef blockedTab fill:#4a151b,stroke:#f85149,stroke-width:2px,color:#ffdcd7
classDef serverBox fill:#1e293b,stroke:#38bdf8,stroke-width:2px,color:#e0f2fe
classDef enclaveBox fill:#312e81,stroke:#818cf8,stroke-width:2px,color:#e0e7ff
class Tab1 activeTab
class Tab2 blockedTab
class GUI serverBox
class Enclave enclaveBox
โฟ Accessible Text Walkthrough & Terminal ASCII Diagram (Screen Readers / Plain-Text View)
Screen-Reader Linear Summary:
- Primary Browser Tab: Establishes an active
BroadcastChanneland heartbeat lock with the local loopback server (127.0.0.1:9876). - Secondary / Hijack Tab Blocked: Any secondary browser tab or external window attempting to open the GUI URL while the primary tab is active immediately receives
403 Forbidden: Tab Lock Active. - Ephemeral RAM Server & Enclave: The
sec-agent guiserver keeps session tokens strictly in RAM and invokes macOSLocalAuthenticationTouch ID directly against the Apple Silicon Secure Enclave and Keychain.
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ HARDENED WEB BROWSER GUI ARCHITECTURE โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโค
โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ Primary Browser Tab โ โ Secondary / External Tab โ โ
โ โ (Active Session Heartbeat) โ โ (Hijack or Pasted URL) โ โ
โ โโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโ โ
โ โ โ โ
โ Authenticated 403 Block โ
โ โ โ โ
โ โผ โผ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ `sec-agent gui` HTTP Server (127.0.0.1:9876) โ โ
โ โ - Single-Tab Binding via BroadcastChannel & Heartbeat โ โ
โ โ - Ephemeral RAM-Only Session Tokens (Zero Disk Storage) โ โ
โ โ - Direct In-Process Touch ID Biometric Unlock โ โ
โ โ - Pre-Launch Listener Auto-Cleanup (Zero Stale Port Conflicts) โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ โ
โ โผ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โ โ macOS Secure Enclave + Keychain โ โ
โ โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
- Single-Tab Session Binding (
BroadcastChannel& Heartbeat): The Web UI uses real-time browserBroadcastChannelsignaling and active heartbeat monitoring. The server locks itself strictly to your primary active browser tab. Opening or pasting the Web UI URL into a secondary tab or external browser immediately returns403 Forbidden: Tab Lock Active, preventing cross-window token hijacking. - In-Browser Biometric Touch ID Unlock:
Clicking
๐ Touch ID Unlockin the Web UI triggers macOSLocalAuthenticationhardware prompts directly inside the browser session viaensureUnlocked()โeliminating the need to drop back to terminal CLI commands to authorize database access. - Zero Plaintext Tokens on Disk:
Session tokens are stored exclusively in an in-memory map in RAM (
guiTokens[profile]). No tokens, session cookies, or authorization credentials sit on your filesystem. - Logical Record Cards View vs. Flat List Switcher:
Sub-attributes (such as
username,password,url,notes) belonging to a shared path namespace (e.g.router-ax3600-prod/xiamo_ax3600_darkstat/) are automatically grouped into a single Logical Record Card. Users can toggle seamlessly between ๐ฆ Grouped Records mode (default) and ๐ Flat List mode using the Web UI view mode switcher. - Pre-Launch Stale Process Termination:
Launching
sec-agent guiautomatically sends a graceful pre-launch HTTP/api/shutdowncall to clear any legacy background processes on port 9876, guaranteeing that you are always interacting with the latest compiled binary.
# Option 1: Launch via CLI (Opens browser automatically)
sec-agent gui
# Option 2: Open native macOS App Bundle
open /Applications/SecAgent.appInitialize the background daemon and unlock the Secure Enclave session.
eval $(sec open)
# Prompt: Touch ID request to authorize keychain accessCreate a completely isolated profile vault in a single step with Touch ID (Slot 0), offline 24-word recovery seed (Slot 1), and an optional unencrypted profile summary:
# Interactively choose between generating a new recovery seed or linking an existing master seed
sec profile new router-ax3600-prod
# Provision a new profile with an unencrypted human-readable summary
sec profile new router-ax3600-prod --summary "OpenWrt home router gateway & Wi-Fi keys"
# Directly link an existing 24-word master recovery seed phrase (skips menu and throwaway seed generation)
sec profile new router-ax3600-prod --reuse-seed # alias: --existing-seed
# Non-interactive / pre-supplied recovery seed
sec profile new router-ax3600-prod --seed "<24-word mnemonic>" [--secrc | --no-secrc]
# Inspect unencrypted profile metadata and summary without Touch ID biometrics
sec profile describe router-ax3600-prod [--json]
# Update or clear unencrypted profile summary offline without Touch ID
sec profile describe router-ax3600-prod --summary "Updated description"
sec profile describe router-ax3600-prod --clear-summary
# Inspect status of all discovered profile stores on disk in an aligned columnar table
sec profile ls# 1. Interactive Hidden Prompt (RECOMMENDED - No Shell History / ps aux leakage)
sec set app-secrets/db-pass
# Enter secret value: [hidden]
# Re-enter secret value: [hidden]
# 2. Pipe from Stdin (trailing newlines trimmed automatically)
echo "secret-value" | sec set app-secrets/db-pass --stdin
# 3. Pipe Multiline Secrets (e.g. PEM private keys, TLS certs) preserving exact bytes
cat id_ed25519 | sec set ssh/key --stdin --no-trim
# 4. Direct Positional Value with Two-Tier Metadata (Description & Multiline Notes)
sec set app-secrets/db-pass "my-super-secret-password" --desc "Primary DB master password" --notes "Rotated monthly by DBA team"
# 5. Formatted Metadata Inspection (Timestamps, Versioning, Access Stats & Notes)
sec describe app-secrets/db-pass
sec describe app-secrets/db-pass --json
# 6. Interactive Notes Editing with $EDITOR (Zero Secret Modification)
sec edit-notes app-secrets/db-pass
# 7. Update Secret Metadata Without Modifying Value or Prompting Biometrics (`sec relabel`)
sec relabel app-secrets/db-pass --desc "Primary DB master password" --notes "Rotated monthly by DBA team"
# 8. List Secrets with Description Column
sec lsTip
Shell History & Process List Security: Passing secret values directly as CLI command-line positional arguments can be recorded in shell history (.zsh_history, .bash_history) or inspected by non-root OS processes via ps aux. For sensitive production keys, always use the interactive prompt (sec set <path>) or piped stdin (--stdin).
Instead of sourcing .env files, execute commands directly in a wrapped environment. Secrets are dynamically replaced with [REDACTED_BY_SEC] in stdout/stderr using sliding-window buffer streaming to prevent log leaks:
# Execute test process with secrets injected & buffer-boundary-aware redaction
sec run --redact -- go test -v ./...
# Feed secret directly into child process stdin (appends '\n' for password prompts like keepassxc-cli or gpg)
sec run --stdin-key kdbx/master_key -- keepassxc-cli merge -s target.kdbx incoming.kdbx
# In-memory stdin injection without trailing newline (pure raw bytes)
sec run --stdin-key token/raw --stdin-raw -- ./service_consumer
# Dedicated raw binary stdout stream for shell composition (0: ok, 2: not found, 3: locked)
sec pipe kdbx/master_key | keepassxc-cli ls target.kdbx
# Restrict injection strictly to specified keys (Principle of Least Privilege for AI subagents)
sec run --allow-keys VCO_URL,VCO_ENTERPRISE_ID --redact -- make test-unit
# Inspect injection plan without executing command or prompting Touch ID
sec run --dry-run -- make testaccConnect to remote nodes or execute remote commands with vault authentication without requiring external sshpass:
# Interactively configure remote target into vault and workspace .secrc
sec ssh init router --host 192.168.31.1 --user root
# Connect to named target from .secrc ("ssh_targets")
sec ssh router
# Execute remote non-interactive command under vault password authentication
sec ssh router -- uci show wirelessRegister rotation hooks to rotate tokens in seconds and inspect expiring keys:
# Register token with custom rotation hook command
sec set velocloud-provider-dev/vco_token "..." --expires 30d \
--rotate-cmd "sec run --profile velocloud-provider-dev -- curl -s -X POST \$VCO_URL/portal/rest/login/enterpriseLogin -d '{\"username\":\"admin\",\"password\":\"\$VCO_PASSWORD\"}' | jq -r .token" \
--rotate-ttl 30d
# Trigger one-command token rotation
sec rotate velocloud-provider-dev/vco_token
# Inspect expiring keys across vault profiles
sec ls --expiring 14dSafely copy credentials across vault profile stores in memory without shell process leaks, and unlock workspace profiles in a single Touch ID prompt:
# Copy a secret from default profile to router-ax3600-prod profile
sec copy wifi/passphrase router/wifi_passphrase --from-profile default --to-profile router-ax3600-prod
# Workspace .secrc Auto-Open: Automatically unlocks both 'default' and workspace target profile in 1 Touch ID tap
eval $(sec open)Single-pane-of-glass status dump, side-channel safe entropy audit, and multi-engine plaintext credential scanner (sec-native + Homebrew gitleaks / trufflehog) with a 3-Tier Integration Feasibility Advisor:
# Global status matrix across all vault profiles & background daemons
sec status --all
# Side-channel safe password entropy & weakness scan
sec check --scan-weak
# Scan a workspace, directory, or home folder (~) for plaintext credentials
sec scan .
sec scan ~
# Export a machine-readable Security Improvement Action List for automated processing
sec scan . --output .sec-audit-actions.json
sec scan . --json
# Deep scan with Git commit history, live verification, and automatic Homebrew tool installation
sec scan . --git-history --deep --verify-live --install-toolsWipe decrypted credentials from system memory and lock the daemon:
sec lock
# Session locked. Memory cache cleared.Switch active environment context in memory without touching disk or affecting other terminals:
# List discovered workspace environments with active marker (*) and tier badges
sec env ls
# Switch active subshell context to an environment alias
eval $(sec use staging)
# Clear environment override back to workspace default
eval $(sec use --clear)
# One-off command override without altering shell context
sec -E prod run -- npm testMutating commands targeting tier: "prod" require interactive confirmation or --confirm-prod:
# In CI/CD or non-interactive automation:
sec set app/db_password "val" --confirm-prod
sec rm app/old_key --confirm-prodEvaluate configuration templates in-memory with local and cross-profile vault secrets without leaving unencrypted temporary files on disk:
# 1. Stream from a template file (positional argument or -f / --file)
sec stream config.yaml.tmpl > config.yaml
sec stream -f deploy.env.tmpl | docker compose --env-file - up
# 2. Stream inline template strings
sec stream --template "export LOCAL='{{db/password}}' GLOBAL_CA='{{@global-shared:pki/ca}}'" | sh
# 3. Stream from stdin
cat app.conf.tmpl | sec streamTip
Executable Disambiguation: sec stream is strictly for template interpolation. If you inadvertently pass an executable name as a positional argument (e.g. sec stream python3 ...), sec-agent inspects $PATH and provides an immediate remediation hint directing you to sec run -- <cmd> (for process execution with secrets) or sec pipe <key> (for raw secret streaming).
Prevent accidental secret leaks before code ever touches Git history. Combines Shannon entropy scanning with exact-match detection against active vault credentials:
# Install pre-commit hook into local repository (.git/hooks/pre-commit)
sec githook install
# Or install globally for all git repositories on your workstation
sec githook install --global
# Manually trigger a privacy scan on staged changes
sec githook checkPlace a .secignore file in your project root to suppress harmless template files across any subdirectory (e.g. *.tmpl or terraform/.secrets.tmpl):
# Suppress templates with mustache placeholders across all subdirectories
*.tmpl
**/*.secret.templateStore sensitive shell commands or multi-line operational scripts inside the encrypted vault (exec/<name>) and execute them over an in-memory stdin pipe into /bin/sh -s with NoTrace: trueโleaving zero traces in .zsh_history, temporary files on disk, ps aux wrapper arguments, or ~/.config/sec-agent/audit.log:
# Save a command or script into exec/<name> inside the encrypted vault
echo 'rsync -a ~/Documents backup@host:/vol/docs' | sec exec save daily-sync --stdin
# List, inspect, or remove stored executable scripts
sec exec list
sec exec show daily-sync
sec exec rm daily-sync
# Execute a stored script in memory (optionally forwarding positional arguments)
sec exec daily-sync
sec exec daily-sync -- --dry-run --verboseConfigure and run multi-folder rsync backups over sec-agent's pure-Go SSH transport without exposing folder names, remote volume paths, usernames, or IP addresses on the local host:
# Initialize a stealth backup job stored in backup/<name> inside the vault
sec backup init work --target backup@10.0.0.50 --local-base ~ --remote-base /Volumes/BackupDrive/Work
# Add one or more relative folders (supporting spaces and custom excludes)
sec backup add-folder work "CloudFolder - Work"
# View backup job configuration or list all backup jobs
sec backup show work
sec backup jobs
# Run all folders in the backup job (or filter to a specific folder, with optional --tofu)
sec backup run work
sec backup run work "CloudFolder - Work" --tofu- 5 Zero-Trace Guarantees:
- Zero
.zsh_historyExposure: Onlysec backup run <name>is typed in the shell. - Zero Local
ps auxExposure: Localrsyncruns in working directory.with--exclude-from=/dev/fd/3and-e "sec ssh-stdio" . sync:target, whilesec-agentrewrites the remotersync --servercommand over the encrypted Go SSH channel. - Automatic "One Level Higher" Naming Derivation: Inside
remote_base,sec-agentautomatically derives<remote_base>/<folder>/,<remote_base>/<Prefix>-History/<YYYY-MM-DD>, and<remote_base>/rsync_<slug>_<YYYY-MM-DD_HHMM>.log. - Diskless SSH Authentication: Uses
golang.org/x/crypto/sshin Go memory withssh/<target>/passwordorssh/<target>/private_keyand vault-pinned host fingerprints (zero~/.ssh/known_hostsor disk key files). - Daemon
NoTraceAudit Suppression:~/.config/sec-agent/audit.logandsecrets.encmtimeremain untouched during execution.
- Zero
To bind a codebase repository or directory tree to sec-agent vault profiles, place a .secrc (or .secenv / .sec.json) configuration file in your project root directory.
{
"environments": {
"sandbox": {
"profile": "router-ax3600-sandbox",
"tier": "dev"
},
"staging": {
"profile": "router-ax3600-staging",
"tier": "staging"
},
"prod": {
"profile": "router-ax3600-prod",
"tier": "prod"
}
},
"default": "sandbox"
}{
"profile": "router-ax3600-prod",
"prefix": ""
}| Configuration Field | Type | Description | Default |
|---|---|---|---|
environments |
object |
Map of named environment aliases to their target vault profile and safety tier. | {} |
default |
string |
The default environment alias when no explicit -E flag or SEC_ENV is set. |
First entry |
profile |
string |
Target vault profile for single-profile workspaces. | "default" |
prefix |
string |
Optional path prefix filter when injecting environment variables via sec run. |
"" |
-
Single Touch ID Multi-Profile Session Unlock (
eval $(sec open)): Runningeval $(sec open)inside your project directory automatically detects.secrcand unlocks bothdefaultand your workspace target profile (router-ax3600-prod) in a single Touch ID prompt:โ๏ธ Detected workspace config file (.secrc): profile = "router-ax3600-prod" โจ Unlocked profile "default" and workspace profile "router-ax3600-prod" in 1 Touch ID prompt. -
Automatic Directory Traversal:
sec-agentautomatically traverses upward from the current working directory to parent directories (up to workspace root) to discover.secrc. -
Subprocess Scoping (
sec run -- <cmd>):sec runautomatically reads.secrcto inject vault credentials from the resolved workspace environment profile into child processes without requiring explicit--profileCLI flags. -
Process-Isolated Context Switching (
sec use <alias>): Runningeval $(sec use <alias>)exportsSEC_ENV="<alias>"andSEC_PROFILE="<profile>"into the calling shell, isolating context changes to the current terminal window. Zero shared disk state is written. -
Production Safety Interceptor: Mutating commands (
set,rm,mv,rollback,restore-deleted,rotate) against any environment or profile taggedtier: "prod"require typingyesin interactive terminals or passing--confirm-prodin automated scripts, aborting with exit code 2 (PROD_MUTATION_CONFIRMATION_REQUIRED) otherwise.
To clean up plaintext credentials in local folders, sec migrate-local automatically scans a dotenv file, securely stores all keys inside the enclave daemon, and replaces raw values with safe placeholders:
sec migrate-local .env --prefix app-secrets --profile my-project# Migrated to sec. Run your commands using: sec run --profile my-project -- <command>
DATABASE_PASSWORD="<migrated_to_sec>"
STRIPE_KEY="<migrated_to_sec>"Note: Since standard dotenv libraries do not override existing process variables, running your app via sec run -- <app> automatically overrides these placeholders in memory with the actual secrets, requiring zero codebase modifications.
Caution
Git History Exposure Warning:
Running sec migrate-local .env sanitizes local disk files to <migrated_to_sec> placeholders. However, if .env was previously committed to Git, those plaintext credentials STILL EXIST permanently in Git commit history!
Remediation Protocol:
- Rotate Credentials Immediately: Assume any key ever committed to Git is compromised.
- Purge File from Git History:
Note: Force-pushing rewritten history requires Repository Admin privileges to bypass branch protection rules.
pip install git-filter-repo git filter-repo --path .env --invert-paths --force git push origin --force --all --tags
Your database contents belong to you. sec supports multiple export formats matching target secret vaults:
- Doppler JSON Map: Dumps flat key-value configurations ready to upload:
sec export --format doppler | doppler secrets upload
- AWS Secrets Manager Payload: Dumps batch secret payloads:
sec export --format aws - KeePassXC Backup: Exports the active session database to a standard encrypted
.kdbxfile:You can restore it later via:sec backup my_backup.kdbx
sec restore my_backup.kdbx
The sec version command allows you to inspect compiled VCS commit history, build timestamps, and Go modules dependencies, and queries the background daemon to warn you if a client-daemon version mismatch exists:
sec versionsec-agent v2.0+ uses a Dual-Slot encryption architecture:
- Slot 0: macOS Keychain protected by Touch ID biometric enrollment (
kSecAccessControlBiometryCurrentSet). - Slot 1: Argon2id BIP39 24-word recovery seed phrase wrapping the inner master key.
Upgrade all active vault profile stores (default, dev, prod, router-ax3600-prod, etc.) to v2.0 bound to a single 24-word recovery seed:
# Interactive migration (generates & displays 24-word seed on physical screen)
sec migrate-v2
# Bind existing vaults to a pre-existing 24-word seed phrase across all profile stores
sec migrate-v2 --seed "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"Rotate the BIP39 recovery seed across all v2.0 vault envelopes without altering Keychain Touch ID bindings or secret data:
sec session rotate-seedIf Touch ID biometric credentials are reset by macOS System Settings or hardware updates, recover vault access with your 24-word seed phrase:
sec session recover --profile router-ax3600-prodOn macOS, ad-hoc signed binaries (codesign -s -) accumulate authorizations in the Keychain Access Control List (ACL) whenever the user authorizes an update with their Mac login password. macOS never prunes previous version hashes from the ACL, which could theoretically allow an older, unpatched binary to be executed and request Touch ID without triggering a password alert.
sec-agent neutralizes this vector:
- Automatic Re-Sealing: Upon the first
sec openafter an upgrade,sec-agentautomatically deletes and recreates the Keychain item in memory, resetting the ACL so that only the active binary'sCDHashis authorized. - Explicit Operator Pruning:
# Re-seal Keychain item to active binary, purging stale historical version authorizations
sec keychain prune [--profile <name>] [--all]
# Inspect Keychain binding mode, presence, and version alignment (zero Touch ID prompt)
sec keychain status [--profile <name>] [--json]In real-world software engineering, developer credential hygiene is notoriously poor. Security research from GitGuardian (State of Secrets Sprawl) reveals that over 12 million plaintext secrets were leaked to GitHub in 2023 alone, making exposed local credentials the #1 vector for corporate security breaches.
| Level | Estimated Adoption | Typical Setup & Risk Profile |
|---|---|---|
โ Tier 0: Plaintext .env / Shell Exports |
~75 - 80% (Industry Norm) | Plaintext .env files in root directories, .zshrc/.bash_profile exports, or hardcoded strings. Easily targeted by InfoStealer malware (RedLine, Raccoon, Vidar) searching local disks. |
| ~10 - 15% | Doppler, Infisical. Centralized cloud sync, but introduces the "Secret Zero" flaw (storing unencrypted API token files on disk) and requires monthly SaaS subscriptions. | |
| ๐ Tier 2: Password Manager CLIs | ~5 - 10% | 1Password (op run), Bitwarden CLI. Improves local security via desktop vaults, but requires running heavy desktop GUI apps and lacks active session hijacking detection. |
| ๐ก๏ธ Tier 3: Hardware Enclave Agents | < 1 - 2% (sec-agent) | macOS Secure Enclave + Touch ID + Active Hijack Intercepts. Zero plaintext files on disk, zero cloud dependencies, and zero SaaS lock-in. |
- Friction Always Defeats Security: If a tool requires complex cloud setup or manual API integrations, developers bypass it and create a
.envfile.sec-agentprovides a 30-second drop-in migration (sec migrate-local .env) requiring zero codebase changes. - Eliminating InfoStealer Risk: Infostealers scan disk paths for
.envfiles and shell history logs. By sanitizing.envfiles to<migrated_to_sec>placeholders and locking master keys inside Apple Silicon hardware, local secrets remain completely invisible to malware.
The following feature ideas have been recorded as optional future architectural suggestions (no active commitment or fixed release target):
- Centralized Remote Vault Sync Adapter: Optional background OIDC/SSO sync module to pull shared team credentials from corporate vaults (HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Doppler) directly into the local Touch ID-sealed enclave while preserving 100% offline Touch ID security.
- Cross-Profile Key Matrix Inspection: UI/CLI tooling to audit key drift across staging and production profiles.
| Feature | sec-agent |
YubiKey / Hardware Keys (PKCS#11/PGP) | 1Password CLI / Bitwarden CLI | Delinea (Secret Server / DSV) | HashiCorp Vault | Doppler / Infisical | SOPS / Age (Mozilla) |
|---|---|---|---|---|---|---|---|
| Primary Target | Local macOS Workstation & Session Agent | Hardware Authentication & SSH/PGP Keys | Desktop Password Vault CLI Injection | Enterprise Privileged Access Management (PAM) | Enterprise / Infrastructure Production Vault | Cloud Team Secret Synchronization | GitOps Repository File Encryption |
| Deployment Model | 100% Offline (Zero SaaS / Zero Server) | Local USB Hardware Dongle | Local App + Cloud SaaS Subscription | Enterprise Cloud SaaS or On-Prem IIS/SQL | Self-Hosted Cluster or Cloud SaaS | Cloud SaaS Platform | Local CLI (Key Server optional) |
| Master Key Protection | macOS Secure Enclave (Silicon) | USB Security Key Cryptographic Chip | Software Vault Key (Argon2 / Master Pass) | Enterprise Tenant / Cloud Vault | Server Master Key / AppRole | Cloud Account Token | Local GPG / Age Key File |
| "Secret Zero" Disk Dependency | โ Zero Plaintext Files (Hardware Sealed) | โ Zero Key Files on Disk | โ Plaintext Session Token File | โ Plaintext Client ID / Token on Disk | โ Plaintext Vault Token / AppRole | โ Plaintext Service Token File | โ Plaintext GPG / Age Key File |
| Hardware Biometric Gate | Built-in Touch ID / Apple Watch | โ Software Auth Only | โ Software Auth Only | โ Software Auth Only | โ Software Auth Only | ||
| Remote Session Hijack Intercept | Active BSD Process Tree & SSH/VNC Scanner | โ None (Triggers while plugged in) | โ None (CLI queryable during unlock) | โ None | โ None | โ None | โ None |
| External Hardware Needed | โ None (Uses Built-in Apple Silicon) | โ None | โ None | โ None | โ None | โ None | |
| Zero-Codebase Dotenv Injection | Automatic <migrated_to_sec> Override |
โ Complex GPG / PKCS#11 Scripting | op run Template Mapping |
SDK / Custom API Scripts | Custom Agent / Template Injection | CLI Secret Ingestion | Manual Decrypt Scripting |
| Dynamic Log Stream Redaction | โ
Built-in ([REDACTED_BY_SEC]) |
โ None | โ None | โ None | โ None | โ None | โ None |
| In-Memory Template Streaming | โ
Built-in (sec stream <file>) |
โ None | โ None | โ None | โ None | ||
| Git Pre-Commit Privacy Guard | โ
Built-in (sec githook check) |
โ None | โ None | โ None | โ None | โ None | โ None |
| Autonomous AI Agent Skill Protocol | โ Built-in (Zero-stall TTL + IDE Skills) | โ None | โ None | โ None | โ None | โ None | โ None |
Hardware security keys (such as YubiKeys using PGP or PKCS#11 modules) are often considered the gold standard for authentication, but face severe limitations when applied to developer local secret management:
- Zero External Hardware Friction:
- YubiKey: Requires purchasing, configuring, and carrying external USB-C dongles that can be lost, left at home, or broken in USB ports.
sec-agent: Leverages the built-in macOS Secure Enclave and built-in Touch ID sensor already present in Apple Silicon Macsโdelivering enterprise-grade hardware cryptography out of the box with zero additional hardware cost.
- Active Hijacking Intercepts:
- YubiKey: A YubiKey has no process context or ancestry awareness. If a YubiKey remains plugged into a USB port with cached PIN entry, an attacker who gains remote SSH shell access or background process execution can issue
gpgorpkcs11-toolcommands to decrypt secrets without prompting for a physical touch button. sec-agent: Actively scans the client's BSD process tree and environment variables (SSH_CLIENT,SSH_TTY,AppleVNCServer). If an SSH or remote sharing session is detected, the daemon immediately self-locks and purges decrypted keys from RAM, neutralizing remote session takeover attempts.
- YubiKey: A YubiKey has no process context or ancestry awareness. If a YubiKey remains plugged into a USB port with cached PIN entry, an attacker who gains remote SSH shell access or background process execution can issue
- Seamless Local Pipelines, Terraform & Script Integration:
- YubiKey High-Friction Workflow: YubiKeys cannot natively inject environment variables into child process trees. To pass secrets into local build scripts,
.envloaders, or Infrastructure-as-Code tools (e.g., TerraformTF_VAR_db_password, AWS credentials, Docker Compose), developers are forced to write custom wrapper scripts aroundgpg --decryptorpkcs11-tool. Every execution forces constant physical button taps or PIN prompts. If a developer enables PIN/touch caching to avoid tap fatigue, it opens a severe vulnerability where background scripts or remote SSH shells can steal credentials from the cached YubiKey session. sec-agentFrictionless Experience:- Single Session Authorization: Unlock your session once (
eval $(sec-agent open)) backed by a single Touch ID hardware check. - In-Memory Hot-Reload (
sec restart --hot-reload): Upgrade binary images in memory via kernel pipe state handoffs (unix.Pipe()) during CLI updates without clearing active session state or requiring Touch ID re-authentication. - Transparent Process Wrapper: Execute any local pipeline, shell script, or Terraform command directly without modifying scripts or codebase files:
sec-agent run -- terraform plan sec-agent run -- make deploy-staging sec-agent run -- docker compose up
- Automatic Key-to-Env Mapping: Secret paths (e.g.
tf-vars/db-password) are automatically converted to uppercase environment variables (TF_VARS_DB_PASSWORDorAWS_SECRET_ACCESS_KEY) in child process memory. - Zero-Codebase Dotenv Overrides: Automatically overrides
<migrated_to_sec>placeholders in.envfiles in memoryโrequiring zero code changes in your application or build pipelines. - Uncompromised Security: Even while the session is open,
sec-agentcontinuously monitors the process tree and peer environment (SSH_CLIENT,SSH_TTY,AppleVNCServer). If a remote session attempts to query secrets, the daemon self-locks instantly.
- Single Session Authorization: Unlock your session once (
- YubiKey High-Friction Workflow: YubiKeys cannot natively inject environment variables into child process trees. To pass secrets into local build scripts,
To make AI-assisted software development frictionless, sec-agent includes a pre-packaged Agent Skill (docs/skills/sec-agent-integration/SKILL.md). This enables AI coding assistants (such as Antigravity, Cursor, Claude Code, Windsurf, or custom agent frameworks) to use sec-agent automatically across your project workspaces.
Simply copy or link the bundled skill into your agent's skills directory:
# Register the bundled skill globally for your AI coding assistant
mkdir -p ~/.gemini/config/skills/sec-agent-integration
cp docs/skills/sec-agent-integration/SKILL.md ~/.gemini/config/skills/sec-agent-integration/Once installed, your AI assistant will automatically:
- Check daemon lock status (
sec-agent version) and prompt foreval $(sec-agent open)when needed. - Follow the Vault Taxonomy Design & Workspace Migration Guide to enforce per-workspace profile isolation (
.secrc) and high-level secret schema design. - Wrap local test/build/deploy commands with
sec-agent run -- <cmd>to inject credentials in memory without creating plaintext.envfiles. - Help migrate legacy
.envfiles usingsec-agent migrate-local.
In enterprise environments, developer laptops are often enrolled in Mobile Device Management (MDM) platforms (e.g. Jamf, Kandji, Microsoft Intune) with corporate endpoint detection and automated file inventory collection. Plaintext .env files lying around in workspace subdirectories pose a high risk of being indexed, backed up to unencrypted IT stores, or exposed during IT support remote sessions.
sec-agent addresses this threat model specifically for corporate workstations:
- Hardware-Enforced Privacy: Secrets are encrypted at rest using keys sealed inside the macOS Secure Enclave (
SecAccessControl). Even if an MDM script or local admin process reads the database file (secrets.enc), it cannot decrypt the contents without physical Touch ID contact on the console. - Remote Administration Intercepts: Active corporate remote support sessions (such as
screensharingdorAppleVNCServer) and remote SSH administration sessions (SSH_CLIENT,SSH_TTY) are automatically intercepted. The daemon instantly locks itself and purges decrypted keys from RAM, preventing remote support engineers or administrative monitoring software from viewing your secrets.
sec-agent includes an interactive and previewable storage cleanup tool to keep your configuration directory (~/.config/sec-agent/) and macOS Keychain free of stale files:
# Preview files and Keychain keys that would be removed without deleting anything
sec cleanup --dry-run
# Perform actual cleanup and purge legacy .bak files and orphaned sockets
sec cleanup๐งน sec-agent Storage & Keychain CLEANUP (DRY-RUN PREVIEW)
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
๐ก๏ธ Protected Active Vaults (Preserved โ Never Deleted):
โข [โ SAFE] ~/.config/sec-agent/secrets.enc (v2.0 Dual-Slot Vault)
โข [โ SAFE] ~/.config/sec-agent/secrets_prod.enc (v2.0 Dual-Slot Vault)
๐ Legacy (v1.0) & Rolling Backup Snapshots Identified (54 items):
โข [DRY-RUN WOULD REMOVE] ~/.config/sec-agent/backups/dev/secrets.enc.1785922652106329000
๐ Orphaned Sockets & Locks: None found (Clean).
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Summary: 54 item(s) would be deleted (approx. 1.1 MB freed).
Active vaults remain 100% untouched.
To perform actual deletion, run: 'sec cleanup'
sec-agent maintains 100% backward compatibility with legacy v1.0 vaults and backups:
- Automatic Unwrapping: When opening or restoring a legacy v1.0
.encfile (raw AES-256-GCM ciphertext without a JSON envelope),store.LoadStoreseamlessly decrypts the legacy payload. - Automatic v2.0 Upgrading: As soon as
sec setorsec restoresaves the store,sec-agentautomatically wraps it in a v2.0 Dual-SlotVaultEnvelopewithkSecAccessControlBiometryCurrentSetSecure Enclave protection. - Recovery Seed Preparation: Users are strongly encouraged to print or write down their 24-word recovery seed phrase (generated during initialization or
sec session recover) and store it in an offline paper vault or password manager. If macOS fingerprints are added or re-enrolled by an administrator, the 24-word seed phrase is required to re-bind Touch ID.
The following architectural enhancements are tracked for future evaluation:
- Hardware Token Recovery Factor (YubiKey / FIDO2 / CTAP2): An optional hardware recovery slot (
Slot 2) enabling YubiKey HMAC-SHA1 challenge-response or FIDO2hmac-secrethardware token taps as an alternative or secondary recovery factor alongside the 24-word Argon2id paper seed phrase.
This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the LICENSE file for details.
Copyright (c) 2026 Arjan Filius.