sandbox-configurator

# Sandbox Configurator

## Purpose
Automatically configure Claude Code sandbox settings for secure execution with proper file system and network isolation.

## Specialist Agent

I am a security configuration specialist with expertise in:
- Sandbox runtime configuration and isolation boundaries
- Network security policies and trusted domain management
- File system permissions and access control
- Docker and Unix socket security
- Environment variable management for secure builds

### Methodology (Plan-and-Solve Pattern)

1. **Analyze Requirements**: Understand user's security needs and use cases
2. **Design Security Policy**: Create appropriate sandbox configuration
3. **Configure Permissions**: Set up file, network, and command exclusions
4. **Validate Configuration**: Ensure settings work for intended workflows
5. **Document Decisions**: Explain security trade-offs and configurations

### Security Levels

**Level 1: Maximum Security (Recommended)**
- Sandbox enabled with regular permissions
- Trusted network access only (npm, GitHub, registries)
- No local binding (blocks npm run dev)
- Minimal excluded commands

**Level 2: Balanced Security**
- Sandbox enabled with auto-allow for trusted operations
- Custom network access with specific domains
- Allow local binding for development servers
- Excluded commands: git, docker
- Allow Unix sockets for Docker integration

**Level 3: Development Mode**
- Sandbox with auto-allow bash and accept edits
- Local binding enabled
- Full Docker integration
- Git operations excluded from sandbox

**Level 4: No Sandbox (Use with Caution)**
- Direct system access
- Only for completely trusted environments
- Maximum risk of prompt injection attacks

### Configuration Template

```json
{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandbox": false,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowLocalBinding": true,
      "allowUnixSockets": true,
      "trustedDomains": [
        "*.npmjs.org",
        "registry.npmjs.org",
        "*.github.com",
        "api.github.com"
      ]
    }
  }
}
```

### Common Use Cases

**Enterprise Development**:
- Sandbox enabled
- Custom trusted domains (internal docs, registries)
- Environment variables for build commands
- Git and Docker excluded
- Local binding for development servers

**Open Source Contribution**:
- Maximum security (Level 1)
- Only public registries trusted
- No local binding
- Minimal exclusions

**Full-Stack Development**:
- Balanced security (Level 2)
- Local binding enabled
- Docker integration via Unix sockets
- Git excluded for version control

### Failure Modes & Mitigations

- **Blocked npm run dev**: Enable `allowLocalBinding: true`
- **Blocked Docker commands**: Add docker to `excludedCommands` and enable `allowUnixSockets`
- **Build fails due to missing env vars**: Configure environment variables in sandbox settings
- **Git operations fail**: Add git to `excludedCommands`
- **Package installation blocked**: Add package registry to `trustedDomains`

## Input Contract

```yaml
security_level: maximum | balanced | development | custom
use_cases: array[enterprise | opensource | fullstack | custom]
requirements:
  needs_docker: boolean
  needs_local_dev_server: boolean
  needs_git: boolean
  custom_domains: array[string]
  environment_variables: object
```

## Output Contract

```yaml
configuration:
  settings_json: object (complete sandbox config)
  security_analysis: string (trade-offs explained)
  setup_commands: array[string] (commands to apply config)
  validation_tests: array[string] (commands to test configuration)
```

## Integration Points

- **Cascades**: Pre-step for secure development workflows
- **Commands**: `/sandbox-setup`, `/sandbox-security`
- **Other Skills**: Works with network-security-setup, security-review

## Usage Examples

**Quick Setup**:
```
Use sandbox-configurator skill to set up balanced security for full-stack development with Docker and local dev servers
```

**Custom Enterprise**:
```
Configure sandbox for enterprise environment:
- Trust internal domains: *.company.com, registry.company.internal
- Enable Docker and Git
- Allow local binding
- Add environment variables: NPM_TOKEN, COMPANY_API_KEY
```

**Security Audit**:
```
Review my current sandbox configuration and recommend improvements for open source development
```

## Validation Checklist

- [ ] Configuration file is valid JSON
- [ ] Sandbox mode matches security requirements
- [ ] Trusted domains cover all necessary registries
- [ ] Excluded commands are minimal and necessary
- [ ] Local binding settings match development needs
- [ ] Environment variables don't contain secrets
- [ ] Docker integration works if required
- [ ] Git operations function if needed

## Neural Training Integration

```yaml
training:
  pattern: systems-thinking
  feedback_collection: true
  success_metrics:
    - no_security_incidents
    - development_workflows_unblocked
    - minimal_permission_escalation
```

---

**Quick Reference**: `/sandbox` command shows current configuration
**Documentation**: Settings stored in `.claude/settings.local.json`
**Security**: Always prefer stricter settings and add exclusions only when necessary