# Security Middleware - Quick Start Guide

## What's New?

RooCode now supports enhanced security controls beyond `.rooignore`:

- **ASK Action**: Prompt for approval instead of just blocking
- **YAML Configuration**: More flexible than gitignore patterns
- **Three-Tier Hierarchy**: Enterprise → Global → Project → Custom
- **Regex Support**: Complex pattern matching
- **Command Protection**: Block terminal commands too

## Quick Setup

### 1. Enable Security Middleware

Create `.roo-security.yaml` in your project root:

```yaml
version: "1.0"
security:
    enabled: true
    rules:
        - pattern: "**/.env*"
          action: ASK
          description: "Environment files may contain secrets"
          askMessage: "Allow access to ${file}?"

        - pattern: "**/*.key"
          action: BLOCK
          description: "Private keys are blocked"
```

### 2. Global User Settings

Create `~/.roo-security.yaml` for personal defaults:

```yaml
version: "1.0"
security:
    enabled: true
    rules:
        - pattern: "**/.ssh/**"
          action: BLOCK
          description: "SSH directory protection"
```

### 3. Custom Overrides

Create `.roo-security-custom.yaml` for personal project overrides:

```yaml
version: "1.0"
security:
    enabled: true
    inheritRules: true
    rules:
        - pattern: ".env.local"
          action: ALLOW
          priority: 200
          description: "Allow local development env"
```

## Actions Explained

| Action    | Description              | Use Case                                |
| --------- | ------------------------ | --------------------------------------- |
| **BLOCK** | Deny access completely   | Sensitive files, production configs     |
| **ASK**   | Prompt user for approval | Files that might be needed occasionally |
| **ALLOW** | Explicitly allow access  | Override inherited blocks               |

## Pattern Examples

### Gitignore-style

- `*.log` - All log files
- `**/.env*` - Any .env file
- `config/*.json` - JSON files in config/

### Regular Expressions

- `/.*password.*/` - Files containing "password"
- `/.*\d{3}-\d{2}-\d{4}.*/` - SSN-like patterns

## Priority System

Higher numbers win when multiple patterns match:

- **1000+**: Enterprise/compliance (unchangeable)
- **100-999**: Important security rules
- **50-99**: Standard rules
- **1-49**: Suggestions

## Command Protection

Protect against terminal access:

```yaml
- pattern: "**/.env"
  action: BLOCK
  applyToCommands: true # Also blocks: cat .env
```

## Inheritance Control

```yaml
security:
    inheritRules: false # Don't inherit from parent configs
```

## Backward Compatibility

- `.rooignore` still works exactly as before
- `.rooignore` blocks take precedence over security rules
- You can use both systems together

## Examples

### Protect API Keys

```yaml
- pattern: "**/api_keys.*"
  action: BLOCK
  priority: 100
  description: "API keys must not be accessed"
```

### Ask for Database Access

```yaml
- pattern: "**/*.db"
  action: ASK
  priority: 80
  askMessage: "Database file ${file} - allow access?"
```

### Allow Test Files

```yaml
- pattern: "test/**"
  action: ALLOW
  priority: 50
  description: "Test files are safe"
```

## Configuration Files

| File                        | Location       | Purpose               | Priority  |
| --------------------------- | -------------- | --------------------- | --------- |
| `.roo-security.yaml`        | Project root   | Project rules         | Medium    |
| `.roo-security-custom.yaml` | Project root   | Personal overrides    | High      |
| `~/.roo-security.yaml`      | Home directory | User defaults         | Low       |
| Enterprise config           | Cloud/managed  | Organization policies | Highest\* |

\*Enterprise rules with `inheritRules: false` cannot be overridden

## Troubleshooting

### Rules not working?

1. Check `enabled: true` is set
2. Verify pattern syntax
3. Check priority values
4. Enable debug mode

### ASK prompts not appearing?

- Ensure VS Code extension is updated
- Check notification settings
- Verify pattern matches

## See Also

- [Full Documentation](./security-middleware.md)
- [Example Configurations](../examples/security-configs/)
- [Migration Guide](#migration-from-rooignore)

## Support

For issues or questions:

- GitHub Issues: [RooCodeInc/Roo-Code](https://github.com/RooCodeInc/Roo-Code/issues)
- Documentation: [Security Middleware Guide](./security-middleware.md)