SecretHarbor Technical Manual

Overview & Core Philosophy

AI coding agents—such as Claude Code, Cursor, Codex, Google Antigravity, Gemini CLI, OpenCode, Amazon Kiro, Ollama, and Aider—require expansive read/write access to your workspace to generate tests, execute builds, inspect compiler outputs, and refactor code.

However, granting an untrusted AI model unconfined access to your local machine inevitably exposes sensitive API keys (Stripe, OpenAI, AWS), production database credentials, local SSH keys (~/.ssh), Docker daemon sockets (/var/run/docker.sock), and private loopback IPC endpoints.

Host Operating System (Human Developer / Trusted Workstation)
│
├── Real .env (Real Production Database Passwords, Live Stripe Keys)
├── Real SSH Private Keys (~/.ssh/id_ed25519) & Cloud Tokens (~/.aws)
│
└── ═══════════════════════════════════════════════════════════════════════
    [ SecretHarbor Security Boundary (Kernel-Level Enforcement) ]
    ═══════════════════════════════════════════════════════════════════════
      │
      ├── AI Agent Process (claude, cursor-agent, agy, gemini, codex)
      │     ├── Sees Format-Preserving Synthetic Fakes (sk_test_shb_fake_...)
      │     ├── Egress Network Policy (Allowed with explicit deny lists)
      │     ├── Intercepted Docker & Unix Domain Sockets
      │     └── Close-on-Exec Sanitized File Descriptors (FD 3+ Closed)
      │
      └── Sandboxed Descendants (MCP Servers, bun test, pytest, npm, bash)

The Core Principle

Traditional agent security frameworks fail because they operate inside the agent or as natural-language system prompts. Prompt injection, subagent delegation, or shell tool escapes immediately bypass prompt guardrails. SecretHarbor is designed around a single immutable tenet:

"Do not lock the file. Lock the agent's capability to access the file."

Enforcement occurs strictly below the agent at the operating system kernel layer. An agent cannot negotiate with, hallucinate past, or prompt-inject its own kernel sandbox boundary.

The 6 Non-Negotiable Security Invariants

Kernel & Operating System Architecture

SecretHarbor implements native operating system primitives across supported platforms, avoiding heavyweight virtual machines or Docker-in-Docker overhead while delivering hardware-speed execution.

macOS Enforcement: Apple Seatbelt

On macOS (12.0+ Monterey and later), SecretHarbor leverages the Apple Seatbelt kernel subsystem (sandbox-exec and native libsandbox.dylib).

• Dynamic Scheme Compilation: Generates and compiles fine-grained Sandbox Scheme profiles ((version 1) (deny default)...) tailoring exact filesystem and IPC capabilities per session.
• Shadow Workspace Virtualization: Before launch, SecretHarbor creates an ephemeral mirror of the project. Non-secret files are hard-linked (so agent edits flow back to the real project), secret files are replaced with format-preserving synthetic fakes, and control-plane files (secretharbor.yaml) are exposed read-only. The real .env on disk is never modified, so a crash or kill -9 cannot leave fakes behind.
• Whole-Tree Process Termination: When an agent session completes, SecretHarbor initiates a clean signal cascade (SIGTERM followed by SIGKILL after a 5-second grace period) to eliminate orphan background tasks.
• GUI Terminal Decoupling & Desktop App Boundary: The SecretHarbor security boundary is scoped to the process tree rooted at shb run. Desktop apps opened directly — by double-clicking, Spotlight, Dock, or any GUI launcher — start outside that tree and receive no protection. Bring a GUI app inside the boundary with shb run -d cursor-app (detached), or adopt a running one with shb adopt.

Linux Enforcement: Unprivileged User Namespaces & Landlock

On Linux (kernel 5.10+), SecretHarbor utilizes unprivileged user namespaces, mount isolation, and the Landlock LSM without requiring sudo or root privileges.

• User Namespaces (CLONE_NEWUSER): Maps the agent to an unprivileged identity so no root capabilities are available inside the boundary.
• Mount Isolation (CLONE_NEWNS): Creates an isolated mount table where synthetic fakes are bind-mounted over real secret paths and denied files are masked. Host files are never changed.
• IPC Isolation (CLONE_NEWIPC): Prevents the agent from reaching host SysV IPC and abstract sockets outside its namespace.
• Landlock LSM: Restricts filesystem access at the kernel LSM layer as a defense-in-depth layer beneath the namespace boundary.
• Memory Inspection Defense: Applies prctl(PR_SET_DUMPABLE, 0) to prevent unauthorized memory attachment, ptrace inspection, and /proc/<pid>/mem reading.
• Sensitive Path Masking: Read-only masking over /proc/kcore, /proc/sys, and /proc/self/environ.

Windows Developer Preview Architecture

On Windows (Windows 11 / Server 2022+), SecretHarbor executes inside a restricted developer preview environment utilizing Windows Job Objects, Restricted Security Tokens (with stripped privileges like SeDebugPrivilege), and Low Integrity Level execution.

Secret Virtualization Engine

The fatal flaw in traditional secret-stripping tools is that they break developer test runners. When a test suite (bun test, pytest, cargo test) executes, stripping API keys causes authentication errors, regex parser crashes, or syntax failures.

SecretHarbor solves this through Dual-Reality Capability Projection:

Synthetic Secret Generation Matrix

Shadow Workspace & Mount Virtualization

In the default mode: fake, your real secret files are never modified. The agent runs inside a per-session virtualized view:

1. macOS — Shadow Workspace: An ephemeral mirror of the project is created under the system temp directory. Non-secret files are hard-linked (so agent edits flow to the real project), secret files are replaced with format-preserving fakes, and secretharbor.yaml is exposed read-only.
2. Linux — Mount Virtualization: Inside the agent's mount namespace, synthetic fakes are bind-mounted over the real secret paths; only sandboxed processes see them.
3. Auto-Inject: Synthetic values from .env are merged into the agent's process environment, so process.env.<KEY> is always defined.
4. Humans keep real values: Your editor, your shell, and bun test / pytest / npm test run outside the sandbox and see the real .env, even while an agent session is active.

Because the real files are never swapped, a crash, kill -9, or reboot cannot leave fakes on disk. shb restore remains available only for legacy in-place swap sessions from pre-shadow-workspace versions.

Secret Brokering: Separating "Read" from "Use"

Developers frequently encounter a dilemma: an agent must run an automated end-to-end integration test against an external service, but giving the agent access to the API token allows it to exfiltrate or log the token.

SecretHarbor resolves this by separating the capability to inspect from the capability to use:

• Agent Context: The agent process only holds the synthetic token: STRIPE_KEY=sk_test_shb_fake_....
• Loopback Egress Proxy: Outbound HTTP requests to authorized destinations (e.g., api.stripe.com) pass through the local SecretHarbor capability broker.
• In-Flight Header Replacement: The broker inspects the request, validates destination policy, and swaps the fake token with the real credential in-flight on the egress socket.
• Zero Agent Memory Exposure: The real secret is never loaded into the agent's process memory, stack, or environment variables.

Ambient Environment & File Descriptor Sanitization

When a developer launches an AI agent from their terminal, the parent shell's environment variables leak ambient credentials into child processes. SecretHarbor executes deep sanitization prior to process launch:

Environment Variable Sanitization

The parent environment is filtered against both automated heuristic patterns (regex scanning for keys matching *_KEY, *_SECRET, *_TOKEN, *_PASSWORD) and explicit policy overrides:

AWS_ACCESS_KEY_ID       → Faked (AKIAIOSFODNN7SHBFAKE)
AWS_SECRET_ACCESS_KEY   → Faked (wJalrXUtnFEMI/K7MDENG/bPxRfiCYSHBEXAMPLE)
DATABASE_URL            → Faked (postgres://fake_agent:shb_sync@127.0.0.1:5432/test)
STRIPE_API_KEY          → Faked (sk_test_shb_fake_mocked...)
SSH_AUTH_SOCK           → Denied / Stripped
DOCKER_HOST             → Denied / Stripped
KUBECONFIG              → Denied / Stripped

Close-on-Exec (FD 3..1024) Protection

Parent shells often hold open file descriptors to private logs, sockets, or sensitive files. When a child process is spawned, POSIX standards inherit open descriptors unless FD_CLOEXEC is explicitly set. SecretHarbor iterates through all descriptors above standard I/O (FD 3 through 1024) and forcibly closes them before handing control to the agent.

Network Security & Domain Filtering

An agent with unconfined network egress can exfiltrate local source code or scan internal subnets. SecretHarbor configures transparent egress controls with three distinct protection presets:

Cloud Metadata & SSRF Defense

Cloud instance metadata services (169.254.169.254 on AWS, GCP, Azure, and DigitalOcean) hold IAM role credentials and node tokens. SecretHarbor drops all egress packets routed toward 169.254.169.254 regardless of the active preset.

Internal RFC 1918 subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16) are shielded to prevent rogue agents from scanning local LAN routers or intranet endpoints.

Local IPC & Docker Daemon Interception

Local Unix domain sockets represent a primary privilege escalation vector. An agent with read/write access to /var/run/docker.sock can spawn a privileged container mounted to the host root filesystem (-v /:/host), completely bypassing all OS security boundaries.

Capability Leasing Model (shb lease)

When an agent task requires running a Docker container (e.g. docker run -p 5432:5432 postgres), SecretHarbor intercepts the connection and prompts the human developer for authorization:

• Approval Dialog: The developer inspects the exact command and flags.
• Time-Bound Lease: Approved leases grant temporary access (default 10 minutes) via a filtered socket proxy.
• Flag Sanitization: Dangerous arguments (such as --privileged, --cap-add=ALL, and host root mounts -v /:/...) are automatically rejected.

Complete Command-Line Reference

SecretHarbor exposes a unified CLI surface (shb or alias secretharbor) designed for fast, human-friendly operation and scriptable CI/CD integration.

Supported Coding Agents & Adapters

SecretHarbor is agent-agnostic. While agent shims and aliases provide seamless ergonomics, the boundary is enforced below the process tree regardless of which model, runtime, or IDE is active:

# Protected — boundary applies to Cursor and all its agents
shb run -- cursor .

# Also protected after `shb init` registers the shim:
cursor .

# NOT protected — opened from Finder/Spotlight/Dock
# (double-clicking Cursor.app)

# Claude Code Native Launch (automatic shim after shb init)
claude

# Explicit launch with SecretHarbor runtime boundary
shb run -- claude

# Verify sandbox posture inside Claude Code session
$ shb status

# Launch Cursor Agent inside boundary
shb run -- cursor .

# If Cursor is already running without protection:
shb adopt --yes

# Google Antigravity Agent runtime integration
shb run -- agy

# Child subagents automatically inherit the kernel sandbox boundary

# Gemini CLI Agent execution
shb run -- gemini-cli

# OpenAI Codex runner
shb run -- codex run

# Aider terminal agent
shb run -- aider

# Cline VS Code extension agent
shb run -- cline

MCP (Model Context Protocol) Server Boundary Isolation

When an agent spawns child Model Context Protocol (MCP) servers (e.g. database connectors, filesystem tools, memory servers), those processes inherit the exact kernel boundary of the parent agent. MCP tools cannot circumvent the sandbox to access real credentials.

shb doctor & The 18 Adversarial Security Vectors

Security claims that cannot be tested are merely promises. shb doctor runs an automated, red-team attack suite simulating real-world exploit attempts directly against the running security boundary:

Configuration Specification (secretharbor.yaml)

Project policies are declared in secretharbor.yaml or .secretharbor/policy.yaml in the repository root:

# SecretHarbor Configuration File (v1)
# Documentation: https://secretharbor.dev/docs.html

version: 1

# Protection presets: standard | strict | permissive
# - standard:   secret files faked, sensitive env sanitized, network allowed, escape denied
# - strict:     all secrets denied, strict network denial, no escapes
# - permissive: obvious secrets faked, network allowed
protection: standard

# Default secret virtualization mode: fake | deny | allow
secrets:
  mode: fake

# Exceptions to default secret handling
exceptions:
  allow:
    - .env.example
  deny:
    - .env.production
    - secrets/**

# Outbound network domain policy (allowed by default; domains can be explicitly denied)
network:
  mode: allow
  # Optional: explicitly deny specific domains
  # deny:
  #   - telemetry.example.com

# Local IPC endpoints and daemon protection
ipc:
  unix_sockets:
    mode: deny
  abstract_sockets:
    mode: deny
  docker:
    mode: approval   # approval | deny | allow

# Sandbox escape controls (human approval required)
sandbox:
  escape: deny

Zero-Telemetry Guarantee & Cryptographic Security

Security tools must not become security liabilities. SecretHarbor is engineered with an uncompromising privacy architecture:

• 100% Local Execution: SecretHarbor never transmits source code, file names, environment keys, credentials, or audit logs to remote telemetry endpoints or cloud services.
• Local AES-256-GCM Vault: Credentials managed via shb secret are stored strictly on the local machine in ~/.secretharbor/vault.enc utilizing authenticated AES-256-GCM encryption with cryptographic keys derived from local machine salts or OS keychains.
• Redacted Local Audit Logs: Operational audit trails are written strictly to ~/.secretharbor/audit.log with automated real-time regex and entropy redaction.
• Fail-Closed Principle: If the kernel sandbox or virtualization layer encounters an initialization error, the process terminates immediately rather than failing open into an unprotected state.