Skip to main content

​
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:
PatternRiskAction
child_process, exec(), spawn()CRITICALBlock unless exec permission declared
eval(), new Function("code")CRITICALAlways blocked
net.connect(), raw socketsCRITICALAlways blocked
fetch(), axiosHIGHBlock unless network permission declared
process.env.API_KEYHIGHWarn - may be leaking credentials
writeFileSyncMEDIUMBlock unless filesystem permission declared
process.exit()HIGHAlways 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:
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.

​
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:
1

Declare minimum permissions

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

Use the plugin SDK

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

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' };
4

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.