Skip to content
iafiliusPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

137 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

sec-agent: Enclave-Bound Session Agent for Developer Secrets

Platform: macOS Only Security: Hardware Enclave License: GPLv3

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.


โšก Core Capabilities at a Glance

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

โš ๏ธ The Problem: Plaintext Dotenv Proliferation

In modern software development, hardcoding credentials in local .env files is incredibly common. What starts as a "temporary PoC or pre-prod password" often:

  1. Accumulates over the years across multiple project folders.
  2. Leaks into shell history log files (.zsh_history, .bash_history).
  3. Gets committed accidentally to public or private Git repositories.
  4. Remains completely unencrypted, leaving credentials accessible to any local process or remote SSH connection active on your machine.

๐Ÿ’ก The "Secret Zero" Paradox Solved

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
Loading
โ™ฟ Accessible Text Walkthrough & Terminal ASCII Diagram (Screen Readers / Plain-Text View)

Screen-Reader Linear Summary:

  1. 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.
  2. sec-agent Enclave Solution: sec-agent stores 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.

๐Ÿ”’ Security Architecture

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
Loading
โ™ฟ Accessible Text Walkthrough & Terminal ASCII Diagram (Screen Readers / Plain-Text View)

Screen-Reader Linear Summary:

  1. Threat Event: An attacker or system administrator resets the macOS account password and enrolls a new fingerprint in System Settings.
  2. Enclave Hardware Trap (kSecAccessControlBiometryCurrentSet): The Secure Enclave hardware detects that the biometric fingerprint set was modified and permanently destroys the Slot 0 master key.
  3. Access Denied: When the attacker taps the Touch ID sensor, hardware decryption fails with errSecItemNotFound, blocking access.
  4. Offline Seed Recovery (Slot 1): Only the legitimate owner holding the physical 24-word BIP39 paper seed phrase can run sec session recover (using Argon2id KDF) to unwrap Slot 1 and 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-agent utilizes 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$).
  • 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 0 from 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 --force fail 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 open generates 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 sshd shell parents. In addition, it inspects the client process's active environment variables using BSD ps 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.Mutex in-memory guards. Fully resistant to race conditions under high-throughput parallel execution (e.g. make -j8, concurrent terraform 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 across GetStorePath, GetSocketPath, and GetPIDFilePath, 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 using config.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.
  • 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.

โš™๏ธ Installation

Option 1: Install via Homebrew (RECOMMENDED for macOS)

# Add Homebrew tap and install sec-agent
brew tap iafilius/tap
brew install sec-agent

Option 2: Pre-built Signed Binary Release

Download 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/

Option 3: Build from Source

# 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 test

Note

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.


๐Ÿ–ฅ๏ธ Hardened Web UI & Desktop Application (SecAgent.app)

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
Loading
โ™ฟ Accessible Text Walkthrough & Terminal ASCII Diagram (Screen Readers / Plain-Text View)

Screen-Reader Linear Summary:

  1. Primary Browser Tab: Establishes an active BroadcastChannel and heartbeat lock with the local loopback server (127.0.0.1:9876).
  2. 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.
  3. Ephemeral RAM Server & Enclave: The sec-agent gui server keeps session tokens strictly in RAM and invokes macOS LocalAuthentication Touch 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   โ”‚                      โ”‚
โ”‚                    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜                      โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

๐Ÿ›ก๏ธ Web UI Security Architecture

  1. Single-Tab Session Binding (BroadcastChannel & Heartbeat): The Web UI uses real-time browser BroadcastChannel signaling 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 returns 403 Forbidden: Tab Lock Active, preventing cross-window token hijacking.
  2. In-Browser Biometric Touch ID Unlock: Clicking ๐Ÿ”“ Touch ID Unlock in the Web UI triggers macOS LocalAuthentication hardware prompts directly inside the browser session via ensureUnlocked()โ€”eliminating the need to drop back to terminal CLI commands to authorize database access.
  3. 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.
  4. 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.
  5. Pre-Launch Stale Process Termination: Launching sec-agent gui automatically sends a graceful pre-launch HTTP /api/shutdown call to clear any legacy background processes on port 9876, guaranteeing that you are always interacting with the latest compiled binary.

Launching the Web UI:

# Option 1: Launch via CLI (Opens browser automatically)
sec-agent gui

# Option 2: Open native macOS App Bundle
open /Applications/SecAgent.app

๐Ÿš€ Quickstart Guide

1. Authorize / Start Daemon

Initialize the background daemon and unlock the Secure Enclave session.

eval $(sec open)
# Prompt: Touch ID request to authorize keychain access

2. Guided Profile Provisioning & Zero-Biometric Summaries (sec profile)

Create 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

3. Store and Retrieve Secrets

# 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 ls

Tip

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).

4. Run Applications with Dynamic Stream Redaction (sec run --redact)

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 testacc

5. Native Pure Go SSH Client & Target Wizard (sec ssh)

Connect 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 wireless

6. Automated Token Rotation & Expiring Inventory

Register 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 14d

7. Native Cross-Profile Secret Copy & Workspace Auto-Open

Safely 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)

8. Global Workstation Status, Entropy Linter & Hybrid Security Scanner (sec scan)

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-tools

9. Lock Session

Wipe decrypted credentials from system memory and lock the daemon:

sec lock
# Session locked. Memory cache cleared.

10. Multi-Environment Workspace Contexts (sec use & sec env ls)

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 test

11. Production Blast-Radius Mutation Guardrails (--confirm-prod)

Mutating 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-prod

12. Cross-Profile Template Streaming (sec stream)

Evaluate 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 stream

Tip

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).

13. Git Pre-Commit Privacy Guard & .secignore (sec githook)

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 check

Suppressing Expected Template Files via .secignore

Place 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.template

14. Zero-Trace Command Execution (sec exec)

Store 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 --verbose

15. Stealth Multi-Folder rsync Backups (sec backup)

Configure 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:
    1. Zero .zsh_history Exposure: Only sec backup run <name> is typed in the shell.
    2. Zero Local ps aux Exposure: Local rsync runs in working directory . with --exclude-from=/dev/fd/3 and -e "sec ssh-stdio" . sync:target, while sec-agent rewrites the remote rsync --server command over the encrypted Go SSH channel.
    3. Automatic "One Level Higher" Naming Derivation: Inside remote_base, sec-agent automatically derives <remote_base>/<folder>/, <remote_base>/<Prefix>-History/<YYYY-MM-DD>, and <remote_base>/rsync_<slug>_<YYYY-MM-DD_HHMM>.log.
    4. Diskless SSH Authentication: Uses golang.org/x/crypto/ssh in Go memory with ssh/<target>/password or ssh/<target>/private_key and vault-pinned host fingerprints (zero ~/.ssh/known_hosts or disk key files).
    5. Daemon NoTrace Audit Suppression: ~/.config/sec-agent/audit.log and secrets.enc mtime remain untouched during execution.

โš™๏ธ Workspace Configuration Files (.secrc / .secenv / .sec.json)

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.

๐Ÿ“„ Schema v2: Multi-Environment Workspace Configuration

{
  "environments": {
    "sandbox": {
      "profile": "router-ax3600-sandbox",
      "tier": "dev"
    },
    "staging": {
      "profile": "router-ax3600-staging",
      "tier": "staging"
    },
    "prod": {
      "profile": "router-ax3600-prod",
      "tier": "prod"
    }
  },
  "default": "sandbox"
}

๐Ÿ“„ Schema v1: Legacy Single-Profile Binding (100% Backward Compatible)

{
  "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. ""

๐Ÿš€ Automatic Workspace Behavior

  1. Single Touch ID Multi-Profile Session Unlock (eval $(sec open)): Running eval $(sec open) inside your project directory automatically detects .secrc and unlocks both default and 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.
    
  2. Automatic Directory Traversal: sec-agent automatically traverses upward from the current working directory to parent directories (up to workspace root) to discover .secrc.

  3. Subprocess Scoping (sec run -- <cmd>): sec run automatically reads .secrc to inject vault credentials from the resolved workspace environment profile into child processes without requiring explicit --profile CLI flags.

  4. Process-Isolated Context Switching (sec use <alias>): Running eval $(sec use <alias>) exports SEC_ENV="<alias>" and SEC_PROFILE="<profile>" into the calling shell, isolating context changes to the current terminal window. Zero shared disk state is written.

  5. Production Safety Interceptor: Mutating commands (set, rm, mv, rollback, restore-deleted, rotate) against any environment or profile tagged tier: "prod" require typing yes in interactive terminals or passing --confirm-prod in automated scripts, aborting with exit code 2 (PROD_MUTATION_CONFIRMATION_REQUIRED) otherwise.

๐Ÿงน Local Dotenv Migration & Git Security Protocol

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

Sanitized .env file output:

# 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:

  1. Rotate Credentials Immediately: Assume any key ever committed to Git is compromised.
  2. Purge File from Git History:
    pip install git-filter-repo
    git filter-repo --path .env --invert-paths --force
    git push origin --force --all --tags
    Note: Force-pushing rewritten history requires Repository Admin privileges to bypass branch protection rules.

๐Ÿš€ Compatibility & Exporters (Zero Platform Lock-In)

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 .kdbx file:
    sec backup my_backup.kdbx
    You can restore it later via:
    sec restore my_backup.kdbx

๐Ÿ” Diagnostics Version Checks

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 version

๐Ÿ”‘ v2.0 Dual-Slot Recovery & Mnemonic Management

sec-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.

Single 24-Word Recovery Seed Migration

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"

Rotating 24-Word Recovery Seed Phrase

Rotate the BIP39 recovery seed across all v2.0 vault envelopes without altering Keychain Touch ID bindings or secret data:

sec session rotate-seed

Un-bricking / Recovering Session Vaults

If 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-prod

Keychain ACL Hygiene & Downgrade Attack Prevention (sec keychain)

On 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 open after an upgrade, sec-agent automatically deletes and recreates the Keychain item in memory, resetting the ACL so that only the active binary's CDHash is 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]

๐ŸŒ Industry Context: How Developers Handle Secrets Today

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.

The Developer Secret Hygiene Spectrum

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.
โš ๏ธ Tier 1: Cloud SaaS Secret Tools ~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.

Why sec-agent Fits Development & PoC Workflows

  1. Friction Always Defeats Security: If a tool requires complex cloud setup or manual API integrations, developers bypass it and create a .env file. sec-agent provides a 30-second drop-in migration (sec migrate-local .env) requiring zero codebase changes.
  2. Eliminating InfoStealer Risk: Infostealers scan disk paths for .env files and shell history logs. By sanitizing .env files to <migrated_to_sec> placeholders and locking master keys inside Apple Silicon hardware, local secrets remain completely invisible to malware.

๐Ÿ”ฎ Future Roadmap Suggestions (Optional / Non-Binding)

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.

๐Ÿ“Š Comprehensive Solution Comparison Matrix

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 โš ๏ธ Physical Button Touch (External USB) โš ๏ธ Desktop App Biometrics โŒ 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) โš ๏ธ Required (USB Dongle purchase/carrying) โŒ None โŒ None โŒ None โŒ None โŒ None
Zero-Codebase Dotenv Injection Automatic <migrated_to_sec> Override โŒ Complex GPG / PKCS#11 Scripting โš ๏ธ Manual 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 โš ๏ธ Manual CLI Templating โŒ None โš ๏ธ Consul Template Daemon โŒ 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 Breakdown: sec-agent vs. YubiKey & Security Dongles

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:

  1. 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.
  2. 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 gpg or pkcs11-tool commands 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.
  3. 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, .env loaders, or Infrastructure-as-Code tools (e.g., Terraform TF_VAR_db_password, AWS credentials, Docker Compose), developers are forced to write custom wrapper scripts around gpg --decrypt or pkcs11-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-agent Frictionless 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_PASSWORD or AWS_SECRET_ACCESS_KEY) in child process memory.
      • Zero-Codebase Dotenv Overrides: Automatically overrides <migrated_to_sec> placeholders in .env files in memoryโ€”requiring zero code changes in your application or build pipelines.
      • Uncompromised Security: Even while the session is open, sec-agent continuously 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.

๐Ÿค– AI Agent Integration (Bundled Agent Skill)

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.

Quick Skill Setup for AI Assistants:

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 for eval $(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 .env files.
  • Help migrate legacy .env files using sec-agent migrate-local.

๐Ÿข Corporate MDM & Workstation Security

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:

  1. 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.
  2. Remote Administration Intercepts: Active corporate remote support sessions (such as screensharingd or AppleVNCServer) 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.

๐Ÿงน Storage Cleanup & Dry-Run Inspection (sec cleanup)

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

Dry-Run Output Example:

๐Ÿงน 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'

๐Ÿ”„ Backward Compatibility & Legacy Vault Restoration

sec-agent maintains 100% backward compatibility with legacy v1.0 vaults and backups:

  • Automatic Unwrapping: When opening or restoring a legacy v1.0 .enc file (raw AES-256-GCM ciphertext without a JSON envelope), store.LoadStore seamlessly decrypts the legacy payload.
  • Automatic v2.0 Upgrading: As soon as sec set or sec restore saves the store, sec-agent automatically wraps it in a v2.0 Dual-Slot VaultEnvelope with kSecAccessControlBiometryCurrentSet Secure 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.

๐Ÿ—บ๏ธ Roadmap & TODO Suggestions

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 FIDO2 hmac-secret hardware token taps as an alternative or secondary recovery factor alongside the 24-word Argon2id paper seed phrase.

๐Ÿ“„ License

This project is licensed under the GNU General Public License v3.0 (GPLv3) - see the LICENSE file for details.
Copyright (c) 2026 Arjan Filius.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages