Roo-Code/docs/security-middleware.md

RooCode Security Middleware

Overview

The RooCode Security Middleware provides enhanced, granular file access control beyond the traditional .rooignore functionality. It introduces a flexible YAML-based configuration system with support for ASK actions (prompting users for approval), regex patterns, and a three-tier configuration hierarchy.

Key Features

1. ASK Action Support

Instead of just blocking file access, the middleware can prompt users for approval before allowing access to sensitive files.

2. YAML Configuration

More flexible and readable configuration format compared to gitignore-style patterns.

3. Three-Tier Configuration Hierarchy

• Enterprise: Organization-wide policies (cannot be overridden)
• Global: User-level defaults (~/.roo-security.yaml)
• Project: Project-specific rules (.roo-security.yaml)
• Custom: Personal overrides (.roo-security-custom.yaml)

4. Regex Pattern Support

In addition to gitignore-style patterns, supports regular expressions for complex matching.

5. Rule Priority System

Fine-grained control over which rules take precedence when multiple patterns match.

Configuration File Format

Basic Structure

version: "1.0"
security:
    enabled: true
    inheritRules: true # Whether to inherit rules from higher levels
    defaultAction: ALLOW # Default when no rules match (ALLOW, BLOCK, or ASK)
    askMessagePrefix: "Security check" # Prefix for ASK prompts

    rules:
        - pattern: "**/.env*" # Gitignore-style pattern
          action: ASK # ALLOW, BLOCK, or ASK
          priority: 90 # Higher numbers = higher priority
          description: "Environment files may contain secrets"
          askMessage: "Access to ${file} requires approval" # Custom prompt
          applyToCommands: true # Also check terminal commands

Pattern Types

1. Gitignore-style patterns:

   • *.log - Match all log files
   • **/.env* - Match .env files in any directory
   • src/**/*.test.js - Match test files in src

2. Regular expressions (enclosed in forward slashes):

   • /.*\.secret\..*/ - Match files with .secret. in the name
   • /.*[Ss][Ss][Nn].*\d{3}-\d{2}-\d{4}.*/ - Match potential SSN patterns

Configuration Hierarchy

1. Enterprise Configuration

• Managed by organization administrators
• Cannot be overridden by lower levels
• Typically enforces compliance requirements (GDPR, HIPAA, PCI-DSS)

2. Global Configuration

• Located at ~/.roo-security.yaml
• User's personal default security settings
• Applies to all projects unless overridden

3. Project Configuration

• Located at project-root/.roo-security.yaml
• Project-specific security rules
• Can inherit or override global rules

4. Custom Configuration

• Located at project-root/.roo-security-custom.yaml
• Personal overrides for the current project
• Highest priority (except for enterprise rules with inheritRules: false)

Rule Evaluation Order

1. Rules are evaluated from Custom → Project → Global → Enterprise
2. Within each level, rules are sorted by priority (highest first)
3. First matching rule determines the action
4. If no rules match, the defaultAction is applied

Actions

BLOCK

Completely prevents access to the file. The operation fails with an error message.

- pattern: "**/.ssh/**"
  action: BLOCK
  description: "SSH keys must not be accessed"

ASK

Prompts the user for approval before allowing access. If approved, access is granted; if denied, access is blocked.

- pattern: "**/*.key"
  action: ASK
  askMessage: "File ${file} appears to be a private key. Allow access?"

ALLOW

Explicitly allows access to the file. Useful for overriding inherited rules.

- pattern: "test/fixtures/**"
  action: ALLOW
  description: "Test fixtures are safe to access"

Integration with .rooignore

The Enhanced Security Middleware maintains full backward compatibility with .rooignore:

1. .rooignore patterns are always evaluated first
2. Files blocked by .rooignore cannot be allowed by security rules
3. Security middleware adds additional layers of protection

Usage Examples

Example 1: Protecting Sensitive Files

# .roo-security.yaml
version: "1.0"
security:
    enabled: true
    rules:
        - pattern: "**/production.yml"
          action: BLOCK
          priority: 100
          description: "Production configuration"

        - pattern: "**/*.pem"
          action: ASK
          priority: 90
          askMessage: "Certificate file ${file} - approve access?"

Example 2: Development Overrides

# .roo-security-custom.yaml
version: "1.0"
security:
    enabled: true
    inheritRules: true
    rules:
        # Override project rule for local development
        - pattern: ".env.local"
          action: ALLOW
          priority: 200
          description: "Local development environment"

Example 3: Enterprise Compliance

# Enterprise configuration (managed centrally)
version: '1.0'
security:
  enabled: true
  inheritRules: false  # Cannot be overridden
  rules:
    - pattern: "**/pii/**"
      action: BLOCK
      priority: 1000
      description: "GDPR compliance - PII protection"

    - pattern: "/.*credit.*card.*\d{4}.*/"
      action: BLOCK
      priority: 1000
      description: "PCI-DSS compliance"

Command-Line Access Control

The middleware also validates terminal commands that attempt to read files:

rules:
    - pattern: "**/.env*"
      action: BLOCK
      applyToCommands: true # Also blocks: cat .env, type .env, etc.

Supported commands:

• Unix: cat, less, more, head, tail, grep, awk, sed
• PowerShell: Get-Content, gc, type, Select-String, sls

API Usage

TypeScript Integration

import { EnhancedRooIgnoreController } from "./core/ignore/EnhancedRooIgnoreController"
import { SecurityEvaluation } from "./core/security/types"

// Initialize with security middleware
const controller = new EnhancedRooIgnoreController(projectPath, {
	enableSecurityMiddleware: true,
	askHandler: async (evaluation: SecurityEvaluation) => {
		// Show prompt to user
		const approved = await vscode.window.showWarningMessage(evaluation.message, "Allow", "Deny")
		return approved === "Allow"
	},
	securityOptions: {
		debug: true,
		globalConfigPath: "~/.roo-security.yaml",
	},
})

// Initialize (loads configurations)
await controller.initialize()

// Check file access (async for proper ASK handling)
const result = await controller.validateAccessAsync("config/secrets.yml")
if (!result.allowed) {
	if (result.requiresApproval) {
		console.log("File requires approval:", result.evaluation?.message)
	} else {
		console.log("File access blocked:", result.evaluation?.message)
	}
}

// Check command execution
const cmdResult = await controller.validateCommandAsync("cat .env")
if (!cmdResult.allowed) {
	console.log("Command blocked:", cmdResult.evaluation?.message)
}

Statistics and Monitoring

// Get security statistics
const stats = controller.getSecurityStats()
console.log(`Total evaluations: ${stats.totalEvaluations}`)
console.log(`Blocked: ${stats.blockedCount}`)
console.log(`Asked: ${stats.askedCount}`)
console.log(`Allowed: ${stats.allowedCount}`)

// Export configuration
const yamlConfig = await controller.exportSecurityConfig("project")
console.log("Current project config:", yamlConfig)

// Import new configuration
await controller.importSecurityConfig(newYamlContent, "custom")

Best Practices

1. Start with Defaults

Begin with sensible defaults at the global level, then add project-specific rules as needed.

2. Use Priority Wisely

• 1000: Critical security rules (enterprise/compliance)
• 100-999: Important project rules
• 50-99: Standard rules
• 1-49: Low-priority suggestions

3. Provide Clear Messages

Always include descriptive askMessage and description fields to help users understand why access is being controlled.

4. Test Your Rules

Use the custom configuration file to test new rules before adding them to project or global configs.

5. Regular Expressions

Use regex patterns sparingly and test thoroughly. They're powerful but can have performance implications.

6. Command Protection

Enable applyToCommands: true for truly sensitive files to prevent command-line access.

Migration from .rooignore

The security middleware is fully backward compatible. To migrate:

1. Keep your .rooignore file as-is
2. Create .roo-security.yaml for new rules
3. Gradually move patterns from .rooignore to YAML configs
4. Use ASK action for files that need conditional access

Troubleshooting

Rules Not Being Applied

1. Check that enabled: true is set
2. Verify file paths are relative to project root
3. Check rule priority - higher priority rules match first
4. Enable debug mode to see evaluation details

ASK Prompts Not Showing

1. Ensure askHandler is configured in the controller
2. Check that the UI component is properly connected
3. Verify the pattern matches the file path

Performance Issues

1. Avoid overly complex regex patterns
2. Limit the number of rules per configuration level
3. Use gitignore-style patterns when possible

Security Considerations

1. Enterprise rules should be immutable and audited
2. Sensitive patterns should use BLOCK, not ASK
3. Regular expressions should be carefully reviewed for ReDoS vulnerabilities
4. Custom configurations should be excluded from version control if they contain sensitive patterns

Future Enhancements

• Cloud-based enterprise configuration management
• Audit logging for all security decisions
• Machine learning-based sensitive data detection
• Integration with secret scanning tools
• Role-based access control (RBAC)
• Time-based access rules
• Contextual rules based on git branch or environment