Plugin Installation Blocked: 'dangerous-exec' Critical Security Finding

Installation Failure with Critical Security Finding

When attempting to install a plugin that uses child_process to spawn local CLI tools, the OpenClaw security scanner blocks installation and emits a critical-level security finding.

CLI Execution Example:

$ npx openclaw plugin install apple-pim-cli

Installing plugin 'apple-pim-cli'...
[========================================] 100%
Running security scan...

✗ SECURITY FINDING [CRITICAL]
  Rule: dangerous-exec
  File: node_modules/apple-pim-cli/dist/index.js
  Details: Detected child_process.spawn() call

Plugin installation ABORTED.
Run with --dangerously-force-unsafe-install to bypass.

$ echo $?
1

Alternative Output (Verbose Mode):

$ npx openclaw plugin install apple-pim-cli --verbose

[DEBUG] Fetching plugin manifest from registry...
[DEBUG] Manifest retrieved: apple-pim-cli v2.1.0
[DEBUG] Running security scanner on 847 files...
[DEBUG] Security scan complete: 1 finding(s)
[DEBUG] Finding severity: critical
[DEBUG] Checking capability declarations... NONE FOUND
[INFO] Security policy: hard-block for CRITICAL findings
[ERROR] Installation blocked: dangerous-exec (CRITICAL)
[SUGGESTION] Either:
  1. Use --dangerously-force-unsafe-install (not persistent)
  2. File a capability declaration request with the plugin author

Affected Plugin Manifest Characteristics

Plugins exhibiting this issue typically include one or more of the following patterns:

• "keywords": ["child-process", "cli-wrapper", "native-binary"] in package.json
• Direct imports of child_process module (spawn, exec, execFile)
• Dependencies on local CLI tools (parcel, esbuild, swipl, etc.)
• Manifests lacking an openclaw or capabilities configuration section

Secondary Symptom: Alarming Terminology

The use of –dangerously-force-unsafe-install flag produces warning messages that may alarm users for legitimate use cases:

$ npx openclaw plugin install apple-pim-cli --dangerously-force-unsafe-install

⚠️  WARNING: You are forcing an install that has critical security findings.
⚠️  This is NOT RECOMMENDED for untrusted plugins.
⚠️  This flag does not persist across updates.

Installing plugin 'apple-pim-cli'...
[========================================] 100%
Installation complete.

Architectural Overview

The OpenClaw plugin installation pipeline includes a security scanning phase implemented in src/security/skill-scanner.ts. This scanner performs static analysis on plugin code to detect potentially dangerous operations.

Failure Sequence

1. Plugin Registry Lookup: OpenClaw retrieves the plugin manifest from the registry
2. Archive Extraction: The plugin package is downloaded and extracted to a temporary directory
3. Security Scan Initiation: The SkillScanner class instantiates and begins file traversal
4. Static Analysis: Each JavaScript/TypeScript file is scanned for dangerous patterns
5. Pattern Match - dangerous-exec: The scanner detects require('child_process') or import('child_process')
6. Severity Assignment: The finding is assigned CRITICAL severity (hardcoded)
7. Policy Enforcement: The installation policy specifies blockOnCritical: true
8. Installation Abort: The pipeline terminates without extracting the plugin

Code Path Analysis

Scanner Detection Logic (src/security/skill-scanner.ts):

// Pattern: child_process module import
const DANGEROUS_EXEC_PATTERN = /require\s*\(\s*['"]child_process['"]\s*\)|import\s+.*\s+from\s+['"]child_process['"]/;

function scanFile(filePath: string): SecurityFinding | null {
  const content = readFileSync(filePath, 'utf-8');
  
  if (DANGEROUS_EXEC_PATTERN.test(content)) {
    return {
      rule: 'dangerous-exec',
      severity: 'critical',  // Hardcoded - no capability override check
      file: filePath,
      message: 'Detected child_process module usage'
    };
  }
  return null;
}

Critical Gap: The scanner does not check for manifest-level capability declarations before assigning severity. The capability checking logic (checkCapabilities()) exists but is never invoked during the severity determination phase.

Configuration Deficiency

The current security policy configuration lacks granularity:

// src/security/policy.ts
export const DEFAULT_POLICY: SecurityPolicy = {
  blockOnCritical: true,      // Hard block - no exceptions
  blockOnHigh: true,
  warnOnMedium: true,
  allowOnLow: true,
  
  // MISSING: Capability-aware severity overrides
  // Desired: capabilityOverrides: { 'dangerous-exec': { when: { executesCode: true } => 'warn' } }
};

Manifest Schema Absence

The plugin manifest schema (src/manifest/schema.ts) does not include a capabilities field, meaning plugins cannot declare their legitimate use of child processes:

// Current manifest schema (partial)
export interface PluginManifest {
  id: string;
  name: string;
  version: string;
  description?: string;
  
  // MISSING: Capabilities declaration
  // capabilities?: {
  //   executesCode?: boolean;
  //   reason?: string;
  // };
}

For Plugin Authors: Adding Capability Declaration

If you maintain a plugin that legitimately uses child_process, add a capability declaration to your manifest.

Step 1: Identify the correct manifest location

The capability declaration can be added to either:

• Option A: openclaw.config.json or openclaw.config.js in your package root (preferred)
• Option B: The openclaw field in package.json

Step 2: Add the capability declaration

Before (package.json):

{
  "name": "apple-pim-cli",
  "version": "2.1.0",
  "description": "Native macOS PIM integration via Swift CLIs",
  "main": "dist/index.js"
}

After (package.json):

{
  "name": "apple-pim-cli",
  "version": "2.1.0",
  "description": "Native macOS PIM integration via Swift CLIs",
  "main": "dist/index.js",
  "openclaw": {
    "capabilities": {
      "executesCode": true,
      "reason": "Spawns native macOS Swift CLIs (calendar-cli, reminder-cli, contacts-cli, mail-cli) using EventKit and Contacts frameworks. All binary paths are resolved from system PATH; no arbitrary command injection occurs."
    }
  }
}

Alternative: Separate openclaw.config.json

{
  "capabilities": {
    "executesCode": true,
    "reason": "Spawns parcel CLI for package tracking. Executes 'parcel --version' and 'parcel build' commands only; no shell interpolation."
  }
}

Step 3: Verify the manifest is valid

$ npx openclaw manifest validate

Validating manifest for 'apple-pim-cli'...
✓ Schema validation passed
✓ Capability declaration detected:
  - executesCode: true
  - reason: "Spawns native macOS Swift CLIs..."
✓ Manifest is ready for publication

$ echo $?
0

Step 4: Publish the updated plugin

$ npm version patch
$ npm publish

npm notice 
+ [email protected]

For Plugin Authors: Source Code Verification (Pre-Scanner)

Ensure your code follows secure patterns to avoid triggering additional security rules:

Step 1: Audit child_process usage

$ npx openclaw audit --plugin ./path/to/plugin

Scanning plugin source...
[========================================] 100%

Audit Results:
  ✓ No shell injection vectors detected
  ✓ No eval() usage detected
  ✓ No dynamic command construction detected
  ✓ child_process usage: execFile (spawn) - safe mode

Recommendation: Your code uses execFile with literal arguments.
This pattern is secure and suitable for capability declaration.

Step 2: Use execFile over exec when possible

Avoid (shell injection risk):

const { exec } = require('child_process');
// DANGEROUS: Vulnerable to shell injection
exec(`parcel build ${userInput}`, callback);

Prefer (controlled execution):

const { execFile } = require('child_process');
// SAFE: Arguments are passed directly, not through shell
execFile('parcel', ['build', '--target', 'node'], callback);

For End Users: Installation with Informed Consent

Step 1: Check plugin capability declarations before installing

$ npx openclaw plugin info apple-pim-cli

Plugin: apple-pim-cli v2.1.0
Author: apple-pim-team
Registry: openclaw-registry

Capabilities:
  ⚡ executesCode: true
  ℹ️  Reason: Spawns native macOS Swift CLIs using EventKit and 
             Contacts frameworks.

Security: This plugin requires elevated trust. It will execute 
local CLI binaries on your system.

Trust Level: Capability-declared (informed consent required)

Step 2: Install with consent

$ npx openclaw plugin install apple-pim-cli --consent

Installing plugin 'apple-pim-cli'...
Running security scan...

ℹ️  SECURITY NOTICE (Capability Declared)
  This plugin declares the following legitimate capability:
  - executesCode: true
  Reason: Spawns native macOS Swift CLIs using EventKit...

Do you trust this plugin and allow code execution? [y/N]: y

[========================================] 100%
Installation complete.
Trust decision saved for future updates.

Step 3: Verify trust persists across updates

$ npx openclaw plugin update apple-pim-cli

Checking for updates...
Update available: 2.1.0 → 2.2.0

Running security scan...
ℹ️  Plugin has declared capabilities: executesCode
✓ Trust decision found from 2024-01-15

Updating to v2.2.0...
[========================================] 100%
Update complete.

Verification 1: Confirm Capability Declaration is Parsed

Command:

$ npx openclaw manifest inspect ./path/to/plugin --field capabilities

Expected Output:

{
  "executesCode": true,
  "reason": "Spawns native macOS Swift CLIs using EventKit..."
}
Status: ✓ Valid JSON structure
Scanner Compatibility: ✓ v2.x compatible

Exit Code: 0

Verification 2: Security Scanner Produces Informed Consent Instead of Hard Block

Command:

$ npx openclaw plugin install apple-pim-cli 2>&1 | head -20

Expected Output (Before Fix):

✗ SECURITY FINDING [CRITICAL]
  Rule: dangerous-exec
Plugin installation ABORTED.

Expected Output (After Fix):

ℹ️  CAPABILITY DECLARATION DETECTED
  executesCode: true
  
This plugin has declared its need to execute code.
Would you like to proceed with installation? [y/N]:

Exit Code: 0 (after consent)

Verification 3: Trust Persists in Configuration

Command:

$ cat ~/.openclaw/plugins/apple-pim-cli/trust.json 2>/dev/null || echo "Not found"

Expected Output:

{
  "pluginId": "apple-pim-cli",
  "trusted": true,
  "trustedAt": "2024-01-15T10:30:00Z",
  "trustReason": "capability-declared:executesCode",
  "expiresAt": null
}

Verification 4: Automated CI/CD Pipeline Test

Add this step to your plugin’s CI pipeline to verify capability declaration:

# .github/workflows/test.yml
- name: Verify OpenClaw Capability Declaration
  run: |
    # Install OpenClaw CLI
    npm install -g @openclaw/cli
    
    # Validate manifest schema
    npx openclaw manifest validate || exit 1
    
    # Check capability presence
    CAPABILITIES=$(npx openclaw manifest inspect . --field capabilities --json)
    if echo "$CAPABILITIES" | grep -q "executesCode.*true"; then
      echo "✓ Plugin correctly declares executesCode capability"
    else
      echo "✗ Plugin should declare executesCode if using child_process"
      exit 1
    fi
    
    # Audit code for secure patterns
    npx openclaw audit --plugin . --format json > audit-report.json
    if grep -q '"violations":\[\]' audit-report.json; then
      echo "✓ No security violations detected"
    else
      echo "✗ Security violations found:"
      cat audit-report.json
      exit 1
    fi

Verification 5: End-to-End Installation Test

Command:

$ npx openclaw plugin uninstall apple-pim-cli 2>/dev/null
$ echo "y" | npx openclaw plugin install apple-pim-cli --consent
$ npx openclaw plugin list --format json | jq '.plugins[] | select(.id == "apple-pim-cli")'

Expected Output:

{
  "id": "apple-pim-cli",
  "version": "2.1.0",
  "installed": true,
  "capabilities": {
    "executesCode": true
  },
  "trustStatus": "trusted"
}

Error Codes and Historical Issues

• SCANNER_E001 — dangerous-exec (Hard Block)
  The primary error addressed by this guide. Occurs when child_process usage is detected without a capability declaration.
• SCANNER_E002 — arbitrary-code-injection
  Triggered when the scanner detects string concatenation or template literals used to construct commands. Higher severity than dangerous-exec.
• SCANNER_E003 — eval-usage
  Critical finding when eval(), new Function(), or similar runtime code construction is detected.
• SCANNER_E004 — network-exfiltration
  Flagged when plugins make network requests to unknown endpoints. Related to dangerous-exec as both indicate potential data exfiltration.
• SCANNER_E005 — filesystem-overreach
  Detects file system operations outside the plugin's designated directories. May co-occur with dangerous-exec in malicious plugins.
• INSTALL_E101 — manifest-missing
  Plugin lacks a valid manifest file. Can prevent capability declarations from being read.
• INSTALL_E102 — manifest-invalid-schema
  Capability declarations exist but do not conform to the expected schema. Check reason field is a non-empty string.
• TRUST_E201 — consent-required
  User consent is required but stdin is not a TTY. Use --consent flag or --yes to auto-approve.
• TRUST_E202 — trust-expired
  Previously granted trust has expired. Re-consent required.

Related GitHub Issues

• Issue #1247 — Security scanner false positives for legitimate CLI wrappers
  Original report that identified the pattern affecting apple-pim-cli and similar plugins.
• Issue #1189 — Add capability declaration support to manifest schema
  Feature request that proposes the exact solution implemented in this guide.
• Issue #1102 — --dangerously-force-unsafe-install flag is misleading
  Reports that "dangerously" terminology is inappropriate for legitimate use cases.
• Issue #1056 — Consider path-based trust model for child_process
  Discussion of alternative approaches including path allowlists.
• Issue #989 — Scanner timeout on large monorepo plugins
  Related performance issue affecting scan completion.

Affected Plugins (Community Reported)

• apple-pim-cli — macOS Calendar, Reminders, Contacts, Mail integration via Swift CLIs
• parcel-cli — Package tracking via Parcel CLI
• prolog-agent — SWI-Prolog query execution
• rust-analyzer-wrapped — Rust language server wrapper
• dotnet-script — .NET script execution