Defense Layer: Granular Access Control

CBrowser implements a five-zone permission system that categorizes tools by their potential impact. Each zone has different confirmation requirements and restrictions, ensuring dangerous operations require explicit user approval.

The Five-Zone System

CBrowser classifies every tool into one of five security zones based on its potential impact:

Zone	Color	Confirmation	Description
GREEN	Safe	Never	Read-only, no side effects
YELLOW	Caution	Never	Minimal side effects, reversible
ORANGE	Warning	Once per session	Moderate impact, requires review
RED	Danger	Every invocation	High impact, destructive potential
BLACK	Blocked	N/A	Never executed, always blocked

Zone Definitions

GREEN Zone - Safe Operations

Characteristics:

Read-only operations
No external side effects
No data modification
No network writes

Default GREEN Tools:

mcp__browser__screenshot
mcp__browser__get_text
mcp__browser__get_attribute
mcp__filesystem__read_file
mcp__filesystem__list_directory
mcp__filesystem__file_info

User Experience:

[GREEN] Reading file: /home/user/document.txt
        Result: 2,456 bytes read

No confirmation required. Executes immediately.

YELLOW Zone - Low Risk

Characteristics:

Minimal side effects
Changes are reversible
Local scope only
No sensitive data access

Default YELLOW Tools:

mcp__browser__navigate
mcp__browser__scroll
mcp__browser__click
mcp__browser__hover
mcp__filesystem__create_directory
mcp__filesystem__copy_file

User Experience:

[YELLOW] Navigating to: https://example.com
         Result: Page loaded in 234ms

No confirmation required. Logged for audit.

ORANGE Zone - Moderate Risk

Characteristics:

Modifies data
May have external effects
Potentially difficult to reverse
Accesses sensitive paths

Default ORANGE Tools:

mcp__browser__fill
mcp__browser__submit_form
mcp__filesystem__write_file
mcp__filesystem__rename_file
mcp__browser__set_cookie

User Experience:

[ORANGE] Write file: /home/user/config.json (1,234 bytes)
         This action modifies files.

         Approve for this session? [y/N/always/never]: y

         Result: File written successfully

Requires confirmation once per session.

RED Zone - High Risk

Characteristics:

Destructive operations
Irreversible actions
Sensitive data access
External network writes

Default RED Tools:

mcp__browser__execute_script
mcp__filesystem__delete_file
mcp__filesystem__delete_directory
mcp__browser__clear_storage
mcp__network__post_request

User Experience:

[RED] DELETE FILE: /home/user/important_data.csv

      WARNING: This action cannot be undone.

      Are you sure? Type 'DELETE' to confirm: DELETE

      Result: File deleted

Requires confirmation for EVERY invocation.

BLACK Zone - Blocked

Characteristics:

Explicitly forbidden
Known dangerous operations
User-banned tools
Quarantined tools

Default BLACK Tools:

(None by default - user configured)

User Experience:

[BLACK] BLOCKED: mcp__untrusted__dangerous_tool

        This tool has been blocked from execution.
        Reason: User-configured block

        To unblock: npx cbrowser set-tool-zone mcp__untrusted__dangerous_tool RED

Never executes. Always blocked.

Default Zone Assignments

CBrowser ships with sensible defaults based on tool behavior analysis:

Browser Tools

Tool	Default Zone	Rationale
`navigate`	YELLOW	Changes page state, reversible
`screenshot`	GREEN	Read-only
`click`	YELLOW	Triggers actions
`fill`	ORANGE	Submits data
`execute_script`	RED	Arbitrary code execution
`clear_storage`	RED	Destroys data

Filesystem Tools

Tool	Default Zone	Rationale
`read_file`	GREEN	Read-only
`list_directory`	GREEN	Read-only
`write_file`	ORANGE	Creates/modifies files
`delete_file`	RED	Destroys data
`delete_directory`	RED	Destroys data recursively

Network Tools

Tool	Default Zone	Rationale
`get_request`	YELLOW	Read-only HTTP
`post_request`	RED	Sends data externally
`upload_file`	RED	Sends files externally

User Override Configuration

Customize zone assignments in ~/.cbrowser/tool-permissions.json:

{
    "version": "1.0",
    "overrides": {
        "mcp__browser__fill": {
            "zone": "RED",
            "reason": "Elevated due to form submission sensitivity",
            "setBy": "user",
            "setAt": "2026-02-15T14:30:00Z"
        },
        "mcp__filesystem__write_file": {
            "zone": "YELLOW",
            "reason": "Lowered for trusted automation scripts",
            "setBy": "user",
            "setAt": "2026-02-15T14:35:00Z"
        },
        "mcp__untrusted__*": {
            "zone": "BLACK",
            "reason": "Block all tools from untrusted server",
            "setBy": "user",
            "setAt": "2026-02-15T14:40:00Z"
        }
    },
    "metadata": {
        "lastModified": "2026-02-15T14:40:00Z",
        "totalOverrides": 3
    }
}

Override Fields

Field	Description
`zone`	Target zone (GREEN, YELLOW, ORANGE, RED, BLACK)
`reason`	Human-readable justification
`setBy`	Who made the change (user, admin, system)
`setAt`	When the change was made

Wildcard Patterns

Override multiple tools with patterns:

{
    "mcp__untrusted__*": {
        "zone": "BLACK",
        "reason": "Block all tools from untrusted server"
    },
    "mcp__*__delete_*": {
        "zone": "RED",
        "reason": "All delete operations require confirmation"
    }
}

CLI Commands

View Current Zone Assignments

npx cbrowser list-tool-zones

Output:

Tool Zone Assignments
=====================

GREEN (Safe - No confirmation):
  mcp__browser__screenshot
  mcp__browser__get_text
  mcp__filesystem__read_file
  mcp__filesystem__list_directory

YELLOW (Caution - Logged):
  mcp__browser__navigate
  mcp__browser__scroll
  mcp__browser__click

ORANGE (Warning - Session confirmation):
  mcp__browser__fill          [USER OVERRIDE]
  mcp__filesystem__write_file

RED (Danger - Always confirm):
  mcp__browser__execute_script
  mcp__filesystem__delete_file

BLACK (Blocked):
  mcp__untrusted__* (wildcard)

Summary: 12 GREEN, 8 YELLOW, 5 ORANGE, 4 RED, 1 BLACK pattern

Set Tool Zone

npx cbrowser set-tool-zone mcp__browser__fill RED

Output:

Zone Change
===========
Tool: mcp__browser__fill
From: ORANGE (default)
To:   RED (user override)

This means: Every invocation will require confirmation

Confirm? [y/N]: y

Zone updated. Change logged to audit.

Set Zone with Reason

npx cbrowser set-tool-zone mcp__filesystem__write_file YELLOW --reason "Trusted automation environment"

Bulk Zone Assignment

# Set all tools from a server
npx cbrowser set-tool-zone "mcp__untrusted__*" BLACK

# Set by pattern
npx cbrowser set-tool-zone "mcp__*__delete_*" RED

Reset to Defaults

# Reset single tool
npx cbrowser reset-tool-zones mcp__browser__fill

# Reset all overrides
npx cbrowser reset-tool-zones --all

Output:

Reset Tool Zones
================

Resetting mcp__browser__fill
  From: RED (user override)
  To:   ORANGE (default)

Reset complete. Backup saved to:
  ~/.cbrowser/tool-permissions.backup.2026-02-15.json

View Zone for Specific Tool

npx cbrowser get-tool-zone mcp__browser__fill

Output:

Tool Zone Details
=================

Tool: mcp__browser__fill
Zone: RED

Source: User Override
Reason: Elevated due to form submission sensitivity
Set by: user
Set at: 2026-02-15T14:30:00Z

Default zone: ORANGE

The --force Flag

For automation scenarios, the --force flag bypasses confirmation prompts.

Usage

npx cbrowser run-automation --force

Behavior by Zone

Zone	Normal	With --force
GREEN	Execute	Execute
YELLOW	Execute	Execute
ORANGE	Confirm once	Execute (no confirm)
RED	Confirm every time	Execute (no confirm)
BLACK	Block	Still blocked

Important: --force never bypasses BLACK zone blocks.

Force Mode Logging

When --force is used, audit logs include additional fields:

{
    "invocation": {
        "forceMode": true,
        "skippedConfirmation": true,
        "normalZoneAction": "requireConfirmation"
    }
}

Restricting Force Mode

Disable force mode in config:

{
    "security": {
        "allowForceMode": false
    }
}

Or restrict to specific zones:

{
    "security": {
        "forceMode": {
            "allowedZones": ["ORANGE"],
            "deniedZones": ["RED"]
        }
    }
}

Zone Escalation

When security events occur, zones may be automatically escalated.

Automatic Escalation Triggers

Event	Action
Injection pattern detected	Escalate to BLACK
Hash mismatch	Escalate to RED
Multiple failed invocations	Escalate one level
Rate limit exceeded	Temporary RED

Escalation Notification

[SECURITY] Tool zone escalated
            Tool: mcp__browser__fill
            From: ORANGE
            To:   RED
            Reason: Multiple validation failures

            Override with: npx cbrowser set-tool-zone mcp__browser__fill ORANGE --confirm-security-override

Session Approvals

ORANGE zone tools require approval once per session.

How Session Approvals Work

First invocation:
[ORANGE] Write file: /home/user/output.txt
         Approve for this session? [y/N/always/never]:

Response options:
  y      - Approve this invocation only
  N      - Deny this invocation
  always - Approve all ORANGE for this session
  never  - Deny all ORANGE for this session

View Session Approvals

npx cbrowser session-approvals

Output:

Session Approval Status
=======================
Session: sess_abc123
Started: 2026-02-15T14:00:00Z

Approved ORANGE tools (no further prompts):
  mcp__filesystem__write_file
  mcp__browser__fill

Denied ORANGE tools (auto-reject):
  (none)

RED tools always require confirmation.

Clear Session Approvals

# Clear all approvals (requires re-confirmation)
npx cbrowser session-approvals --clear

# Clear specific tool
npx cbrowser session-approvals --revoke mcp__filesystem__write_file

Examples

Lockdown Mode

Block all write operations:

npx cbrowser set-tool-zone "mcp__*__write_*" BLACK
npx cbrowser set-tool-zone "mcp__*__delete_*" BLACK
npx cbrowser set-tool-zone "mcp__*__create_*" BLACK
npx cbrowser set-tool-zone "mcp__*__post_*" BLACK

Trust Specific Server

Allow tools from a verified server to run with reduced friction:

npx cbrowser set-tool-zone "mcp__verified_server__*" YELLOW --reason "Verified internal server"

Audit Mode

Set everything to RED for complete visibility:

npx cbrowser set-tool-zone "mcp__*" RED --reason "Audit mode - confirming all operations"

Development vs Production

Use environment-specific configs:

# Development (more permissive)
CBROWSER_ENV=development npx cbrowser ...

# Production (stricter)
CBROWSER_ENV=production npx cbrowser ...

With config:

{
    "environments": {
        "development": {
            "defaultZone": "YELLOW",
            "allowForceMode": true
        },
        "production": {
            "defaultZone": "RED",
            "allowForceMode": false
        }
    }
}

Best Practices

For Individual Users

Start with defaults - They're based on security analysis
Escalate, don't reduce - Prefer moving tools to higher zones
Document reasons - Always provide --reason for overrides
Review periodically - Check your overrides quarterly

For Teams

Share zone configs - Use version-controlled config files
Standardize by role - Developers vs operators may need different zones
Log zone changes - Track who changed what and why
Audit force usage - Monitor --force flag usage

For Automation

Use --force sparingly - Only for verified, tested workflows
Never force BLACK tools - If blocked, investigate why
Consider service accounts - Separate permissions for automation
Monitor escalations - Auto-escalation indicates problems

Troubleshooting

Tool Stuck at Wrong Zone

Check for conflicts:

npx cbrowser get-tool-zone mcp__tool_name --show-inheritance

Wildcard Not Matching

Test your pattern:

npx cbrowser test-pattern "mcp__server__*"

Force Mode Not Working

Check if disabled:

npx cbrowser config get security.allowForceMode

Security Per Tool Permissions

The Five-Zone System

Zone Definitions

GREEN Zone - Safe Operations

YELLOW Zone - Low Risk

ORANGE Zone - Moderate Risk

RED Zone - High Risk

BLACK Zone - Blocked

Default Zone Assignments

Browser Tools

Filesystem Tools

Network Tools

User Override Configuration

Override Fields

Wildcard Patterns

CLI Commands

View Current Zone Assignments

Set Tool Zone

Set Zone with Reason

Bulk Zone Assignment

Reset to Defaults

View Zone for Specific Tool

The --force Flag

Usage

Behavior by Zone

Force Mode Logging

Restricting Force Mode

Zone Escalation

Automatic Escalation Triggers

Escalation Notification

Session Approvals

How Session Approvals Work

View Session Approvals

Clear Session Approvals

Examples

Lockdown Mode

Trust Specific Server

Audit Mode

Development vs Production

Best Practices

For Individual Users

For Teams

For Automation

Troubleshooting

Tool Stuck at Wrong Zone

Wildcard Not Matching

Force Mode Not Working

Related Documentation

From the Blog