Plugin Sandboxing

Overview

Plugins extend profClaw with new tools, providers, and integrations. Because plugins run as JavaScript in the same process, they have significant power. The plugin security system enforces a permission model, scans code for dangerous patterns, and requires explicit trust grants before plugins can run.

Permission Model

Every plugin declares the permissions it needs in its manifest. profClaw only grants the minimum permissions required.

type PluginPermission =
  | 'exec'        // Shell command execution
  | 'filesystem'  // File read/write access
  | 'network'     // Outbound HTTP requests
  | 'system'      // System information access
  | 'browser'     // Browser automation
  | 'memory'      // Memory read/write access
  | 'tools'       // Register new tools

A plugin requesting only network and tools cannot access the filesystem or run shell commands.

Plugin Manifest

{
  "name": "my-weather-plugin",
  "version": "1.0.0",
  "description": "Real-time weather data",
  "main": "dist/index.js",
  "profclaw": {
    "permissions": ["network", "tools"],
    "minVersion": "2.0.0"
  }
}

Code Scanning

Before a plugin is loaded, the AuditScanner analyzes its code for dangerous patterns:

Pattern	Risk	Action
`child_process`, `exec()`, `spawn()`	CRITICAL	Block unless `exec` permission declared
`eval()`, `new Function("code")`	CRITICAL	Always blocked
`net.connect()`, raw sockets	CRITICAL	Always blocked
`fetch()`, `axios`	HIGH	Block unless `network` permission declared
`process.env.API_KEY`	HIGH	Warn - may be leaking credentials
`writeFileSync`	MEDIUM	Block unless `filesystem` permission declared
`process.exit()`	HIGH	Always blocked

If the scanner finds CRITICAL patterns that do not match declared permissions, the plugin is rejected at load time.

Trust Levels

Plugins are assigned one of three trust levels:

Trusted
Sandboxed
Blocked

Plugin has been explicitly reviewed and approved. All declared permissions are granted immediately.

profclaw plugins trust my-weather-plugin --level trusted

Only grant trusted to plugins you have reviewed yourself or that come from verified ClawHub publishers.

Plugin is installed but will not load. Use this to temporarily disable a plugin without uninstalling it.

profclaw plugins block suspicious-plugin

Installing Plugins

# Install from npm
profclaw plugins install profclaw-plugin-weather

# Install from a local directory
profclaw plugins install ./my-local-plugin/

# Install and trust immediately (after manual review)
profclaw plugins install profclaw-plugin-weather --trust

When installing, the scanner runs immediately:

Installing profclaw-plugin-weather@1.2.0...
Scanning plugin code...
  No dangerous patterns found.
  Declared permissions: network, tools
  Permission analysis: OK

Plugin installed in sandboxed mode.
To trust this plugin: profclaw plugins trust profclaw-plugin-weather

Plugin Allowlist

In allowlist security mode, plugins must also be on the plugin allowlist:

security:
  pluginAllowlist:
    - pluginId: "profclaw-plugin-weather"
      name: "Weather Plugin"
      version: "^1.0.0"
      permissions:
        - network
        - tools
      trusted: true
      addedAt: "2026-03-12"
      addedBy: "admin"

Managing Plugins

# List all installed plugins with trust status
profclaw plugins list

# Show plugin details and scan results
profclaw plugins info my-plugin

# Re-scan a plugin after update
profclaw plugins scan my-plugin

# Update a plugin
profclaw plugins update my-plugin

# Uninstall
profclaw plugins uninstall my-plugin

Writing Secure Plugins

When developing plugins, follow these rules:

Declare minimum permissions

Only request the permissions your plugin actually needs. Users will see and approve each permission.

Use the plugin SDK

Always use profClaw’s SDK for tool execution rather than calling shell commands directly. The SDK applies security policies.

Never hardcode credentials

Use context.env to access configuration values. Never embed API keys in code.

const apiKey = context.env.WEATHER_API_KEY;
if (!apiKey) return { available: false, reason: 'WEATHER_API_KEY not set' };

Handle errors safely

Catch all errors and return structured error responses. Never let unhandled exceptions crash the server.

Plugin SDK

Full plugin development API reference.

Audit Logging

Plugin load and scan events are audit-logged.

Configuration

Security

Integrations

Plugins

Architecture

Plugin Sandboxing

Overview

Permission Model

Plugin Manifest

Code Scanning

Trust Levels

Installing Plugins

Plugin Allowlist

Managing Plugins

Writing Secure Plugins

Plugin SDK

Audit Logging

​Overview

​Permission Model

​Plugin Manifest

​Code Scanning

​Trust Levels

​Installing Plugins

​Plugin Allowlist

​Managing Plugins

​Writing Secure Plugins

​Related Docs

Plugin SDK

Audit Logging

Overview

Permission Model

Plugin Manifest

Code Scanning

Trust Levels

Installing Plugins

Plugin Allowlist

Managing Plugins

Writing Secure Plugins

Related Docs