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

• Security Overview
• Container Security
• Secret Redaction
• Security Best Practices
• Security Expectations
• Build Integrity
• Troubleshooting

The Construct CLI provides multiple layers of security:

1. Container Isolation: Agents run in isolated containers
2. Network Isolation: Optional network modes (permissive/strict/offline)
3. Secret Redaction: Experimental feature to hide secrets from agents
4. Ephemeral Containers: Clean slate on every run
5. No Path Escape: Agents cannot access files outside project root
6. Build Verification: Cryptographic verification of releases

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

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

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

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

Required: Set environment gate

export CONSTRUCT_EXPERIMENT_HIDE_SECRETS=1

Configure: Enable in config.toml

[security]
hide_secrets = true
hide_secrets_mask_style = "hash"

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

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

✅ 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

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

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

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

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

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

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

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:

• GitHub Releases
• Homebrew (official tap)
• Official install scripts

"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

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/

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

• Hide Secrets Mode - Experimental secret redaction
• Installation Guide - Secure installation practices
• Configuration Guide - Security configuration options
• Architecture Design - Security architecture

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

Security questions:

• GitHub Issues: github.com/EstebanForge/construct-cli/issues
• Documentation: See docs/
• Release notes: Check GitHub Releases for security updates