Security Guide

August 22, 2026 · View on GitHub

Complete security documentation for The Construct CLI, including container security, secret redaction, and best practices.

Table of Contents

Security Overview

The Construct CLI provides multiple layers of security:

  1. Container Isolation: Agents run in isolated containers
  2. MicroVM Isolation: Optional hardware-level isolation via dedicated guest kernels (backend = "microvm")
  3. Network Isolation: Optional network modes (permissive/strict/offline)
  4. Secret Redaction: Experimental feature to hide secrets from agents
  5. Ephemeral Sandboxes: Clean slate on every run
  6. No Path Escape: Agents cannot access files outside project root
  7. Build Verification: Cryptographic verification of releases

Container Security

Container User

Default password: construct

Purpose: Allows sudo access when running interactive commands

Security implications:

  • ⚠️ Warning: If you expose container to untrusted networks (port forwarding, bridge mode), change the password

Change password:

construct sys set-password

Container Isolation

What agents cannot do:

  • Access files outside the project directory
  • Escape the container filesystem
  • Access host system processes (by default)
  • Persist data across runs (without explicit configuration)

What agents CAN do:

  • Read/write project files
  • Make network requests (subject to network mode)
  • Execute commands within container
  • Access mounted volumes (home, SSH agent, etc.)

User Context

Default behavior: Run commands as construct user inside container

Alternative: Run as host user (when possible)

[sandbox]
exec_as_host_user = true

Benefits:

  • File ownership matches host user
  • Better integration with host permissions
  • Prevents root-owned files in project

Seccomp Relaxation (Headless Browsers)

Default: Docker applies a seccomp filter (mode 2) to every container, blocking syscalls the kernel profile doesn't whitelist.

Problem: Headless browser automation tools (Chrome/Chromium via agent-browser, Playwright, CDP extensions) need syscalls the default profile blocks (clone3 with namespace flags, seccomp(2) BPF install, ptrace for the browser's own sandbox). Result: every persistent browser launch dies with Trace/breakpoint trap (SIGTRAP).

Opt-in fix:

[sandbox]
disable_seccomp = true

This emits security_opt: [seccomp:unconfined] in the generated override. After enabling, run construct build to regenerate the image/override and restart the container.

Tradeoff: seccomp:unconfined removes a kernel-level syscall-restriction layer. It is a deliberate security reduction, scoped to users who run browsers in-container. Default-off preserves isolation for everyone else. An alternative is a Chrome-tailored seccomp JSON profile (whitelist only the needed syscalls) if you need tighter control than full unconfined.

MicroVM Isolation (Experimental Backend)

Overview

When backend = "microvm" is enabled in [runtime], Construct runs agents inside microVMs using microsandbox rather than shared-kernel OCI containers.

Threat Model Difference

  • Container isolation (Docker/Podman): Agents share the host kernel. An escape vulnerability in the Linux kernel directly compromises the host operating system.
  • MicroVM isolation (msb): Each agent runs within a separate Linux guest kernel managed by hardware hypervisors (Apple Hypervisor.framework on macOS, KVM on Linux). An escape requires both a guest kernel exploit and a hypervisor vulnerability.

Security Guarantees

  • Separate Guest Kernel: No shared syscall table or shared kernel namespaces with the host.
  • Fail-Closed Egress: Network policy is enforced at the hypervisor boundary in addition to in-guest iptables filtering.
  • Resource Limits: Sandboxes allocate 4 vCPUs and 4096 MiB RAM by default, preventing host resource exhaustion.
  • Controlled Bridges: Guest-to-host bridges (clipboard, host-exec, SSH agent proxy, loopback relays) authenticate via per-session tokens and only communicate over dedicated local listeners. Detailed analysis: docs/ARCHITECTURE-DESIGN.md.

Secret Redaction

Overview

Experimental feature that prevents LLM agents from seeing raw secrets in project files and environment variables.

What gets protected:

  • ✅ Project files with secrets (.env, config files, credentials)
  • ✅ Environment variables with secret names
  • ✅ Agent output from Construct-controlled subprocesses
  • ✅ .git directory (when enabled)

What's NOT protected (V1):

  • ❌ Secrets already in git history
  • ❌ Binary/archive files
  • ❌ Provider API calls (requires proxy, V2)
  • ❌ Malicious host-side tools outside Construct

Enablement

Required: Set environment gate

export CONSTRUCT_EXPERIMENT_HIDE_SECRETS=1

Configure: Enable in config.toml

[security]
hide_secrets = true
hide_secrets_mask_style = "hash"

How It Works

  1. Workspace Isolation: Agent runs in isolated workspace (OverlayFS/APFS)
  2. File Redaction: Secrets replaced with CONSTRUCT_REDACTED_<HASH>
  3. Env Masking: Secret env vars masked before injection
  4. Read-Only Sessions: Agent writes don't persist to real project

Configuration Options

[security]
hide_secrets = true                    # Master switch
hide_secrets_mask_style = "hash"       # hash | fixed
hide_secrets_deny_paths = []           # Force-scan these files
hide_secrets_allow_paths = []          # Never redact these files (dangerous!)
hide_secrets_passthrough_vars = []      # Never mask these env vars
hide_secrets_report = true              # Show scan report
hide_git_dir = true                     # Hide .git directory

Allowlist caution: Files in hide_secrets_allow_paths will NOT be redacted. Use sparingly.

Use Cases

✅ Good for:

  • Debugging API code without exposing API keys
  • Code review of authentication logic
  • Working with sensitive projects

❌ NOT for:

  • Workflows requiring direct API calls (agent needs real keys)
  • Tools that read credentials files (AWS CLI, kubectl)
  • Use hide_secrets_allow_paths for specific files or disable mode

Complete guide: Hide Secrets Mode

Security Best Practices

✅ DO

1. Use Network Isolation

[network]
mode = "strict"  # For sensitive work
allowed_domains = ["*.anthropic.com"]

2. Enable Secret Redaction

export CONSTRUCT_EXPERIMENT_HIDE_SECRETS=1

3. Mount Home Selectively

[sandbox]
mount_home = false  # Default is more secure

4. Review Allowlists

# Check what you're allowing through
construct sys doctor

5. Keep Construct Updated

construct sys self-update

6. Use Provider Keys Securely

[claude.cc.custom]
ANTHROPIC_AUTH_TOKEN = "${CUSTOM_API_KEY}"  # Reference env var

❌ DON'T

1. Expose Container to Untrusted Networks

# Avoid port forwarding to public internet
construct --publish 8080:80  # Risky on public networks

2. Add All Config Files to Allowlist

[security]
# DON'T DO THIS - defeats the purpose
hide_secrets_allow_paths = ["config/*", ".env*"]

3. Commit Real Secrets to Git

  • Even with hide-secrets enabled, git history contains secrets
  • Use environment variables instead
  • Use secret management tools (1Password, Vault, etc.)

4. Use yolo_all = true in Untrusted Environments

[agents]
yolo_all = true  # Agents run without confirmation

5. Ignore Security Warnings

# Pay attention to warnings about:
# - Insecure runtime detection
# - Configuration validation failures
# - Security feature limitations

Security Expectations

What Construct Secures

Filesystem isolation:

  • ✅ Agents cannot escape project directory
  • ✅ No access to host system files (unless mounted)
  • ✅ Temporary filesystem (ephemeral containers)

Network isolation:

  • ✅ Optional network modes (permissive/strict/offline)
  • ✅ Domain/IP allowlists and blocklists
  • ✅ Configurable per-command network modes

Secret protection (with hide-secrets):

  • ✅ Project files redacted before agent sees them
  • ✅ Environment variables masked
  • ✅ Stream output masked for subprocesses
  • ✅ .git directory hidden

What Construct Does NOT Secure

Agent behavior:

  • ❌ Construct cannot prevent agents from making malicious API calls
  • ❌ Cannot prevent agents from exploiting vulnerabilities in called services
  • ❌ Cannot prevent agents from exfiltrating data through allowed channels

Host security:

  • ❌ Does not secure your host machine
  • ❌ Does not protect against host-side malware
  • ❌ Does not prevent direct access to your files (outside Construct)

Provider security:

  • ❌ Does not secure your API keys
  • ❌ Does not prevent API key theft if you expose them
  • ❌ Does not validate provider security practices

User responsibility:

  • 🔒 Keep your API keys secure
  • 🔒 Use strong, unique passwords
  • 🔒 Enable 2FA on provider accounts
  • 🔒 Review agent code before running (if untrusted)
  • 🔒 Don't run untrusted agents with sensitive data
  • 🔒 Keep Construct updated

Shared Responsibility Model

Construct secures:

  • Container isolation
  • Network boundaries
  • File system access
  • Secret visibility (with hide-secrets)

You secure:

  • Your API keys and credentials
  • Your host machine
  • Your provider accounts
  • Your network infrastructure
  • Your data classification

Build Integrity

Verified Builds

All releases built via GitHub Actions CI/CD:

  • ✅ Automated builds prevent tampering
  • ✅ No manual builds
  • ✅ Reproducible builds traceable to source commits
  • ✅ Comprehensive testing on every build
  • ✅ SHA256 checksums for verification

Verify Downloads

Always verify release artifacts:

# Download checksum from release notes
# Compare with downloaded binary
sha256sum construct

# Should match checksum in release notes

Download from official sources only:

Troubleshooting

Security Warnings

"Container running with default password"

Issue: Security scanner detected default container password

Solution: Change container password

construct sys set-password

"Hide-secrets mode is experimental"

Issue: Feature is experimental and may have limitations

Solution: Understand limitations before use

  • Read Hide Secrets Guide
  • Use in development environments first
  • Report issues via GitHub Issues

"Allowlisted files will be visible to agents"

Issue: Files in hide_secrets_allow_paths bypass redaction

Solution: Review allowlist entries

# Check what's allowlisted
construct sys doctor

# Remove unnecessary allowlist entries
# Edit ~/.config/construct-cli/config.toml

Security Auditing

Check your security posture:

# Run security diagnostics
construct sys doctor

# Check what's mounted
construct --mount | grep -v construct

# Review configuration
construct sys config

Review audit logs:

# Hide-secrets audit logs (V2)
construct sys security audit verify

# Session reports
ls ~/.config/construct-cli/security/sessions/

Reporting Security Issues

Found a security vulnerability?

  1. Do NOT open a public GitHub issue
  2. Send responsible disclosure via:
    • GitHub Security Advisory (private)
    • Email to project maintainers
  3. Include:
    • Vulnerability description
    • Steps to reproduce
    • Impact assessment
    • Suggested fix (if known)

Response timeline:

  • Acknowledgment within 48 hours
  • Fix timeline based on severity
  • Public disclosure after fix is released

Security References

Next Steps

  • Review your current security setup
  • Enable appropriate security features for your use case
  • Keep Construct and dependencies updated
  • Follow security best practices

Getting Help

Security questions: