Back to docs

Security Tool Pinning

Defense Layer: Cryptographic Tool Integrity Verification

Tool pinning is CBrowser's first line of defense against tool poisoning attacks. It creates a cryptographic fingerprint of each MCP tool when first encountered and alerts you if that tool changes unexpectedly.

Understanding the Threat

MCP tools are dynamic - they can be modified at any time by the MCP server. A malicious actor who gains access to an MCP server could:

  • Modify a tool's description to inject harmful instructions
  • Change a tool's parameter schema to capture sensitive data
  • Replace a legitimate tool with a malicious one

Tool pinning detects these changes by comparing cryptographic hashes before each invocation.

How Tool Pinning Works

SHA-256 Hash Generation

When CBrowser first encounters a tool, it generates a SHA-256 hash from three components:

HASH = SHA256(
    tool.name +
    tool.description +
    JSON.stringify(tool.inputSchema)
)

This creates a unique fingerprint that captures:

Component What It Catches
name Tool impersonation or replacement
description Injected instructions in descriptions
inputSchema Modified parameter definitions

Example Hash Calculation

import crypto from 'crypto';

function computeToolHash(tool) {
    const data = tool.name +
                 tool.description +
                 JSON.stringify(tool.inputSchema);

    return crypto
        .createHash('sha256')
        .update(data)
        .digest('hex');
}

// Example output:
// "a7f3b2c9d4e5f6a1b8c3d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0"

The Tool Manifest

All pinned tool hashes are stored in a manifest file.

File Location

~/.cbrowser/tool-manifest.json

Manifest Format

{
    "version": "1.0",
    "created": "2026-02-15T10:30:00Z",
    "lastUpdated": "2026-02-15T14:45:00Z",
    "tools": {
        "mcp__filesystem__read_file": {
            "hash": "a7f3b2c9d4e5f6a1b8c3d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0",
            "firstSeen": "2026-02-15T10:30:00Z",
            "lastVerified": "2026-02-15T14:45:00Z",
            "approvedBy": "auto",
            "serverName": "filesystem"
        },
        "mcp__browser__navigate": {
            "hash": "b8c3d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0a1b2c3d4e5f6a7b8",
            "firstSeen": "2026-02-15T10:32:00Z",
            "lastVerified": "2026-02-15T14:45:00Z",
            "approvedBy": "user",
            "serverName": "browser"
        }
    },
    "metadata": {
        "totalTools": 2,
        "autoApproved": 1,
        "userApproved": 1
    }
}

Manifest Fields Explained

Field Description
hash SHA-256 fingerprint of the tool
firstSeen When the tool was first encountered
lastVerified Most recent successful verification
approvedBy auto (first encounter) or user (manual approval)
serverName The MCP server providing this tool

CLI Commands

View Current Manifest

npx cbrowser show-manifest

Output:

Tool Manifest Summary
=====================
Location: ~/.cbrowser/tool-manifest.json
Total Tools: 47
Auto-approved: 42
User-approved: 5

Recent Tools:
  mcp__filesystem__read_file     [AUTO]   2026-02-15
  mcp__browser__navigate         [USER]   2026-02-15
  mcp__browser__screenshot       [AUTO]   2026-02-15

Detailed Manifest View

npx cbrowser show-manifest --detailed

Output:

Tool Manifest Details
=====================

mcp__filesystem__read_file
  Hash:         a7f3b2c9d4e5...
  First Seen:   2026-02-15T10:30:00Z
  Last Check:   2026-02-15T14:45:00Z
  Approved By:  auto
  Server:       filesystem

mcp__browser__navigate
  Hash:         b8c3d9e0f1a2...
  First Seen:   2026-02-15T10:32:00Z
  Last Check:   2026-02-15T14:45:00Z
  Approved By:  user
  Server:       browser

Approve a Changed Tool

When a tool's hash changes, you'll see a warning. To approve the new version:

npx cbrowser approve-tool mcp__browser__navigate

Output:

Tool Change Detected
====================
Tool: mcp__browser__navigate

Previous Hash: b8c3d9e0f1a2b3c4...
New Hash:      c9d0e1f2a3b4c5d6...

Changes detected in: description, inputSchema

Are you sure you want to approve this change? (y/N): y

Tool approved. New hash saved to manifest.

Approve with Diff View

npx cbrowser approve-tool mcp__browser__navigate --show-diff

This displays the exact changes between versions before asking for approval.

Reset Manifest

To start fresh (use with caution):

npx cbrowser reset-manifest

Output:

WARNING: This will delete all pinned tool hashes.
All tools will need to be re-verified on next use.

Are you sure? (type 'RESET' to confirm): RESET

Manifest reset. Backup saved to:
  ~/.cbrowser/tool-manifest.backup.2026-02-15T14-45-00.json

Export/Import Manifest

For team sharing or backup:

# Export
npx cbrowser show-manifest --export > team-manifest.json

# Import (merges with existing)
npx cbrowser import-manifest team-manifest.json

# Import (replaces existing)
npx cbrowser import-manifest team-manifest.json --replace

Verification Process

When a tool is invoked, CBrowser follows this verification flow:

1. Compute hash of incoming tool definition
         |
         v
2. Check manifest for existing entry
         |
    +----+----+
    |         |
    v         v
 [Found]   [Not Found]
    |         |
    v         v
3. Compare   Auto-approve
   hashes    (first use)
    |
    +--------+--------+
    |                 |
    v                 v
 [Match]          [Mismatch]
    |                 |
    v                 v
 Allow            BLOCK +
 execution        Alert user

Mismatch Alert Example

SECURITY ALERT: Tool Hash Mismatch
===================================
Tool: mcp__browser__navigate

This tool's definition has changed since it was last approved.
This could indicate:
  - A legitimate tool update
  - Tool poisoning attack
  - MCP server compromise

Previous hash: b8c3d9e0f1a2b3c4d5e6f7a8b9c0d1e2...
Current hash:  DIFFERENT_HASH_VALUE_HERE...

Action Required:
  To approve: npx cbrowser approve-tool mcp__browser__navigate
  To view diff: npx cbrowser approve-tool mcp__browser__navigate --show-diff

Tool invocation BLOCKED until resolved.

Security Benefits

What Tool Pinning Protects Against

Threat Protection Level
Tool definition tampering FULL - Any change detected
Instruction injection via description FULL - Description is hashed
Schema manipulation FULL - Schema is hashed
Tool impersonation FULL - Name + content mismatch
Man-in-the-middle attacks PARTIAL - Detects but doesn't prevent

Defense in Depth

Tool pinning works alongside other CBrowser security layers:

  1. Tool Pinning - Detects tool changes
  2. Injection Scanner - Detects malicious patterns
  3. Permission Zones - Limits tool capabilities
  4. Output Sanitization - Protects against response injection
  5. Audit Logging - Records all activity

Best Practices

For Individual Users

  1. Review new tools before first use
  2. Investigate mismatches - don't auto-approve
  3. Back up your manifest periodically
  4. Report suspicious changes to MCP server maintainers

For Teams

  1. Share a baseline manifest among team members
  2. Establish approval workflows for tool changes
  3. Monitor for simultaneous alerts (indicates server-side change)
  4. Include manifest in security audits

For MCP Server Operators

  1. Version your tools - document when changes occur
  2. Notify users before making breaking changes
  3. Sign tool definitions if your protocol supports it
  4. Keep a changelog for security-conscious users

Configuration Options

In ~/.cbrowser/config.json:

{
    "security": {
        "toolPinning": {
            "enabled": true,
            "autoApproveNew": true,
            "blockOnMismatch": true,
            "alertOnMismatch": true,
            "backupOnReset": true,
            "manifestPath": "~/.cbrowser/tool-manifest.json"
        }
    }
}
Option Default Description
enabled true Enable/disable tool pinning
autoApproveNew true Auto-approve first-seen tools
blockOnMismatch true Block execution on hash mismatch
alertOnMismatch true Show alert on mismatch
backupOnReset true Create backup before reset

Troubleshooting

"Tool not in manifest" for known tool

The tool name may have changed. Check with:

npx cbrowser show-manifest --search "browser"

Manifest file corrupted

Restore from backup:

cp ~/.cbrowser/tool-manifest.backup.*.json ~/.cbrowser/tool-manifest.json

Too many approval prompts

If a server frequently updates tools, you may want to:

  1. Contact the server maintainer
  2. Temporarily disable pinning for that server
  3. Use --auto-approve for trusted servers (not recommended)

Related Documentation

From the Blog