Plugin Development

Deeprotection supports external extensibility via a robust plugin system. Plugins are external scripts that can inspect, block, or transform commands before execution.

Plugin Directory Structure

Drop your plugins into /etc/deeprotection/plugins/<plugin-name>/:

/etc/deeprotection/plugins/
  example-plugin/
    plugin.json
    entrypoint_script

Plugin Manifest (plugin.json)

{
  "id": "example-plugin",
  "name": "Example Plugin",
  "version": "1.0.0",
  "author": "Jane Doe",
  "description": "Description of what the plugin does.",
  "enabled": true,
  "entrypoint": "entrypoint_script"
}

Plugin Invocation Model

The command string is passed to the plugin via:

• stdin — the full command string
• Environment variable — DPSHELL_COMMAND

Exit Codes

Code	Meaning
0	Allow the command (stdout ignored)
1	Block the command
2	Replace the command; stdout must contain the new command string

Any other exit code, timeout (>5 seconds), or spawn failure results in fail-open (allow original command, warn to stderr).

Execution Order

Plugins are run synchronously in the order they were discovered (directory scan order). The command may be transformed by each plugin in sequence.

Example Plugin (Bash)

#!/bin/bash
# /etc/deeprotection/plugins/my-plugin/entrypoint_script

COMMAND=$(cat)

# Block any command containing "dangerous"
if echo "$COMMAND" | grep -q "dangerous"; then
    exit 1
fi

# Replace "echo" with "printf"
if echo "$COMMAND" | grep -q "^echo "; then
    echo "${COMMAND/echo/printf}"
    exit 2
fi

# Allow by default
exit 0

Plugin Timeout

Plugins have a 5-second timeout. If a plugin does not exit within this window, it is terminated with SIGKILL, and the original command is allowed (fail-open) with a warning to stderr.