> ## Documentation Index
> Fetch the complete documentation index at: https://docs.profclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin Sandboxing

> Plugin permission model, code scanning, trust levels, and security review process.

## 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.

```typescript theme={null}
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

```json theme={null}
{
  "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:

> [tab] Trusted
>
> Plugin has been explicitly reviewed and approved. All declared permissions are granted immediately.
>
> ```bash theme={null}
> profclaw plugins trust my-weather-plugin --level trusted
> ```
>
> Only grant `trusted` to plugins you have reviewed yourself or that come from verified ClawHub publishers.

> [tab] Sandboxed
>
> Plugin runs with its declared permissions but additional constraints:
>
> * Network calls go through SSRF guard
> * Filesystem access goes through FsGuard
> * No access to internal profClaw state beyond the plugin SDK
> * Resource limits applied (memory, CPU)
>
> This is the **default for newly installed plugins**.

> [tab] Blocked
>
> Plugin is installed but will not load. Use this to temporarily disable a plugin without uninstalling it.
>
> ```bash theme={null}
> profclaw plugins block suspicious-plugin
> ```

## Installing Plugins

```bash theme={null}
# 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:

```yaml theme={null}
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

```bash theme={null}
# 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.

```typescript theme={null}
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.

## Related Docs

> [card] [Plugin SDK](https://docs.profclaw.ai/plugins/sdk.md)
>
> Full plugin development API reference.

> [card] [Audit Logging](https://docs.profclaw.ai/security/audit.md)
>
> Plugin load and scan events are audit-logged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.