Security considerations and vulnerability reporting for Substrate.

Command Tracing Security:

• Log files created with 0600 permissions (user-only access)
• Comprehensive credential redaction for sensitive arguments
• SHA-256 binary fingerprinting for integrity verification
• Emergency bypass mechanism for recovery scenarios

Path Security:

• SHIM_ORIGINAL_PATH validation prevents directory inclusion attacks
• Binary resolution with permission verification
• Protection against PATH injection attacks

Process Security:

• Proper signal handling and process group management
• PTY security with terminal state restoration
• Session correlation prevents command confusion

World-Based Isolation:

• Default-on worlds for Linux and macOS (Lima) with overlay/copy-diff handling
• Network scoping via nftables (best-effort) and named namespaces
• Resource limits via cgroups v2 with graceful degradation when unavailable
• Future: Additional seccomp hardening and Windows parity improvements (the current WSL backend is functional but experimental)

Policy Enforcement:

• YAML-based policies with allow/deny/isolate rules (observe mode by default)
• Command pattern matching via glob-like rules
• Roadmap: opt-in enforcement, approvals in CLI flows, and hot-reload behind optional watcher feature

Agent Security:

• world-agent REST/WS endpoints with span-level audit logging
• Roadmap: per-agent execution budgets, scope tokens, and richer telemetry export

DO NOT create public GitHub issues for security vulnerabilities.

Instead, use GitHub's private vulnerability reporting

Required Information:

• Vulnerability description
• Steps to reproduce
• Impact assessment
• Affected versions
• Suggested mitigation

Optional Information:

• Proof of concept code
• Exploit scenarios
• Recommended fixes

• Initial Response: Within 48 hours
• Assessment: Within 7 days
• Fix Development: Varies by severity
• Public Disclosure: After fix is available

Installation Security:

• Build from source when possible
• Verify binary checksums
• Use official releases only
• Keep dependencies updated

Runtime Security:

• Review log files regularly
• Use credential redaction (avoid SHIM_LOG_OPTS=raw in production)
• Ensure log size bounds via built-in rotation (TRACE_LOG_MAX_MB/TRACE_LOG_KEEP). Use external tooling for archival/backup if required.
• Monitor for unexpected command patterns

Environment Security:

• Protect SHIM_ORIGINAL_PATH from untrusted directories
• Secure log file permissions (0600)
• Regular integrity verification of shim binaries
• Use emergency bypass only when necessary

Code Security:

• Never log sensitive information directly
• Use anyhow::Result for error handling
• Validate all external inputs
• Follow principle of least privilege

Testing Security:

• Test credential redaction patterns
• Verify file permission handling
• Test signal safety
• Validate error handling paths

• Absolute Path Bypass: Commands invoked with absolute paths skip shimming
• Shell Builtin Limitation: Built-ins in non-substrate shells aren't captured
• Log Atomicity: Large entries may interleave in high-concurrency scenarios
• Host System Trust: Relies on host system security for binary integrity

• Use relative command names when possible
• Implement external log analysis for builtin detection
• Monitor for log integrity issues
• Harden host system security appropriately

Phase 4 security worlds will address:

• Complete command interception via world isolation
• Comprehensive filesystem and network controls
• Reduced dependency on host system security
• Advanced audit capabilities with tamper detection

Layer 1: Command interception and logging Layer 2: Credential redaction and data protection Layer 3: Binary integrity verification Layer 4: Emergency bypass and recovery mechanisms

Future Layers: Layer 5: World-based isolation and sandboxing Layer 6: Policy-based access controls Layer 7: Graph-based anomaly detection

In Scope:

• Malicious command execution
• Credential exposure in logs
• Binary tampering
• PATH manipulation attacks

Out of Scope:

• Host system compromise
• Kernel vulnerabilities
• Hardware attacks
• Social engineering

• Personal Data: Command lines may contain personal information
• Credentials: Automatic redaction with bypass option
• Audit Trails: Comprehensive logging for compliance requirements
• Data Retention: Built-in rotation limits on-disk size; use external archival/backup to meet retention policies.

Substrate supports compliance with:

• SOC 2 Type II (audit trail requirements)
• ISO 27001 (security management)
• GDPR (data protection, where applicable)
• Industry-specific requirements (depending on usage)

For security-related questions or concerns:

• General: Create a GitHub discussion
• Vulnerabilities: Use private reporting channels
• Compliance: Contact maintainers for specific requirements