Safety & Permissions¶

SuperQode implements a comprehensive safety model to ensure secure operation while allowing agents to perform effective tool-based coding tasks. This document describes the security architecture, permission system, and safety guarantees.

Overview¶

SuperQode's safety model is built on these principles:

1. Sandbox-First - All testing happens in isolated environments
2. Least Privilege - Agents only get permissions they need
3. Human-in-the-Loop - Dangerous operations require approval
4. Revert Guarantee - Original code is always preserved
5. Audit Trail - All actions are logged and traceable

Permission Levels¶

SuperQode defines four permission levels for tool operations:

Safe Operations¶

Operations that cannot cause harm:

• Reading files
• Searching code
• Listing directories
• Viewing git history
• Running linters (read-only)

Moderate Operations¶

Operations limited to the sandbox:

• Editing files (in workspace)
• Creating new files (in workspace)
• Running tests
• Installing dev dependencies

Dangerous Operations¶

Operations requiring explicit approval:

• Executing shell commands
• Network requests to external URLs
• Modifying configuration files
• Git operations (commit, push)
• Package installation
• System file access

Blocked Operations¶

Operations that are never allowed:

• Accessing credentials/secrets
• Modifying files outside workspace
• Executing as root/admin
• Network access to internal services
• Deleting critical system files

Permission Rules Engine¶

The permission rules engine (permissions/rules.py) evaluates each tool call:

Tool Call Request
       │
       ▼
┌──────────────────┐
│ Permission Rules │
│     Engine       │
└────────┬─────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
 Allowed   Requires
           Approval
              │
              ▼
       ┌──────────────┐
       │ User Prompt  │
       │  (Y/N/Always)│
       └──────────────┘

Rule Configuration¶

Permission rules can be configured in superqode.yaml:

permissions:
  # Default permission level
  default_level: moderate

  # Tool-specific overrides
  tools:
    shell:
      level: dangerous
      require_approval: true
      allowed_commands:
        - pytest
        - npm test
        - cargo test
      blocked_commands:
        - rm -rf
        - sudo
        - curl | bash

    file_write:
      level: moderate
      allowed_paths:
        - "**/*.py"
        - "**/*.js"
        - "**/*.ts"
      blocked_paths:
        - ".env*"
        - "**/*.pem"
        - "**/*.key"

    network:
      level: dangerous
      allowed_domains:
        - github.com
        - pypi.org
      blocked_domains:
        - localhost
        - "*.internal"

Dangerous Operation Detection¶

The danger detection system (danger.py) identifies potentially harmful operations:

Detection Categories¶

Detection Rules¶

# Example danger patterns
DANGEROUS_PATTERNS = [
    r"rm\s+-rf\s+/",           # Recursive delete from root
    r"sudo\s+",                 # Privilege escalation
    r">\s*/etc/",               # Write to system config
    r"curl.*\|\s*bash",         # Pipe to shell
    r"chmod\s+777",             # World-writable
    r"eval\s*\(",               # Dynamic code execution
]

Approval Workflow¶

When a dangerous operation is detected, SuperQode prompts for approval:

┌─────────────────────────────────────────────────────────────┐
│  ⚠️  Dangerous Operation Detected                           │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Tool: shell                                                 │
│  Command: npm install axios                                  │
│  Reason: Package installation may modify dependencies       │
│                                                              │
│  [Y] Allow once                                             │
│  [A] Always allow for this session                          │
│  [N] Deny                                                    │
│  [?] Show more details                                       │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Approval Options¶

Approval Memory¶

Approved operations are remembered for the session:

# Session approval state
approvals:
  shell:
    - pattern: "npm test"
      approved: true
    - pattern: "pytest"
      approved: true
  file_write:
    - pattern: "tests/**/*.py"
      approved: true

Sandbox Isolation¶

The sandbox system (safety/sandbox.py) provides isolation:

Isolation Mechanisms¶

Sandbox Guarantees¶

1. File Isolation - Changes only affect the sandbox copy
2. Git Protection - Cannot commit/push from sandbox
3. Process Isolation - Subprocesses inherit restrictions
4. Network Isolation - Optional network restrictions

Sandbox Configuration¶

sandbox:
  # Isolation mode: worktree, snapshot
  mode: snapshot

  # Preserve sandbox on error for debugging
  preserve_on_error: false

  # Network restrictions
  network:
    enabled: true
    allow_localhost: true
    allowed_hosts:
      - "*.github.com"
      - "*.pypi.org"

Local Command Sandbox (OS-level)¶

Beyond the permission gate, SuperQode can confine every shell command using the operating system's own isolation so that even an auto-approved command cannot write outside the workspace or reach the network. This is enforced by the OS, not by string matching.

Backends¶

If no backend is available, commands run unconfined and SuperQode says so.

Modes¶

Select a mode with the SUPERQODE_SANDBOX environment variable (or the :sandbox <mode> command in the TUI):

# Confine writes to the project, keep network for installs
SUPERQODE_SANDBOX=workspace-write superqode

# Strict read-only analysis: no writes, no network
SUPERQODE_SANDBOX=read-only superqode

In the TUI, :sandbox shows the active mode, backend, and whether a sandbox is currently applied; :sandbox workspace-write switches modes for the session.

Command Safety Classification¶

Every shell command is classified before it runs, which lets SuperQode auto-run safe commands (no prompt) while still gating risky ones:

The classifier is obfuscation-aware: commands are canonicalised before analysis, so \rm, '/bin/rm', and r""m are still recognised as rm, and dynamic constructs ($(...), backticks, eval, pipe-to-shell) can never be classified Safe.

This is what removes prompt fatigue - you are no longer asked to approve every ls or git status, only the operations that actually carry risk.

Network Allowlist Policy¶

Network commands are checked against a domain allowlist so trusted installs run without prompts while arbitrary egress is gated:

The built-in allowlist covers common registries and source hosts - PyPI, npm, crates.io, Go/Ruby proxies, GitHub/GitLab/Bitbucket, container registries, and OS package mirrors. So pip install requests, npm install, and git clone https://github.com/... run automatically, while curl https://evil.com is gated.

# Trust an internal mirror and hard-deny anything else
SUPERQODE_NET_ALLOW=mirror.corp SUPERQODE_NET_STRICT=1 superqode

Safety Warnings¶

The warning system (safety/warnings.py) alerts users to potential issues:

Warning Levels¶

Common Warnings¶

• Large File Changes - Modifying files over 1000 lines
• Binary Files - Attempting to edit binary files
• Test Failures - Tests failing after modifications
• Resource Usage - High memory/CPU consumption
• Long Running - Session exceeding time limits

Audit Trail¶

All operations are logged for audit:

{
  "timestamp": "2024-01-15T10:30:45Z",
  "session_id": "session-abc123",
  "operation": "shell",
  "command": "pytest tests/",
  "permission_level": "moderate",
  "approved": true,
  "approved_by": "auto",
  "duration_ms": 1234,
  "result": "success"
}

Audit Log Location¶

.superqode/
├── audit/
│   ├── session-abc123.jsonl
│   └── session-def456.jsonl

Best Practices¶

For Users¶

1. Review Approvals - Don't blindly approve all operations
2. Use Quick Mode First - Start with limited scope
3. Check Artifacts - Review suggested changes before applying
4. Set Allowed Lists - Configure allowed commands/paths

For CI/CD¶

1. Use worktree isolation - Full isolation in pipelines
2. Disable Approvals - Use --no-interactive with pre-approved lists
3. Set Time Limits - Prevent runaway sessions
4. Audit Logs - Archive audit trails for compliance

Configuration Example¶

# Production-safe configuration
permissions:
  default_level: moderate

  tools:
    shell:
      require_approval: true
      allowed_commands:
        - pytest
        - npm test
        - cargo test
        - go test
      blocked_patterns:
        - "rm -rf"
        - "curl | bash"
        - sudo

    file_write:
      blocked_paths:
        - ".env*"
        - "*.pem"
        - "*.key"
        - "secrets/**"

sandbox:
  mode: worktree
  network:
    enabled: true
    allowed_hosts:
      - "github.com"
      - "pypi.org"

Related Documentation¶

• Configuration Reference - Full config options