Plugin Security and Architecture

Plugin Security and Architecture

Ash supports compiled native plugins and executables installed in ~/.ash/plugins/. These plugins expand the toolset available to the AI alongside Python scripts in ~/.ash/tools/ and standard allowlisted Unix commands.

Architecture Overview

1. Isolated Subprocess Boundary

Ash executes plugins via direct operating system subprocess execution (execve) without invoking a shell. This architectural boundary provides:

• Process & Memory Isolation: A buggy, panicking, or leaking plugin cannot corrupt the memory space of Ash or crash the persistent connection broker.
• Direct I/O Capture: Standard output and standard error are captured with bounded limits (controlled by ASH_TOOL_OUTPUT_MAX, default 8192 bytes).
• Timeouts & Signal Management: Plugins run under a strict execution deadline (controlled by ASH_TOOL_TIMEOUT, default 15s). When cancelled or timed out, Ash delivers SIGTERM to the process group.

2. Symmetrical Access Control (.ash_allow and .ash_deny)

Plugin access is governed by the symmetrical allow/deny system:

• ~/.ash/.ash_allow: Contains allowed executables. The standalone directive $PLUGINS_DIR_LIST automatically permits eligible executable binaries discovered in ~/.ash/plugins/.
• ~/.ash/.ash_deny: Explicitly blocks designated commands, tools, or plugins. Denials always take precedence over allowlist rules: if a plugin is present in both .ash_allow and .ash_deny, it is unconditionally blocked.
• Environment Overrides: ASH_ALLOW and ASH_DENY override the respective configuration files for ephemeral or automated runs.

3. Strict Mode Lockdown (ASH_STRICT=1)

Under strict security mode (ASH_STRICT=1):

• Wildcard expansion of $PLUGINS_DIR_LIST is suppressed.
• Only plugins explicitly enumerated by name in .ash_allow (and not blocked in .ash_deny) can be executed.
• Untrusted tool evidence is filtered for prompt-injection patterns.

Security Threat Model & Considerations

When installing third-party plugins or authoring custom plugins, consider the following security principles:

1. User Privileges: Plugins run under the UID/GID of the user invoking Ash. Never install plugins from untrusted sources without inspecting their source code.
2. Deterministic CLI Argument Handling: Plugins must parse CLI flags directly from argv without passing unsanitized arguments to shell wrappers or child processes.
3. No Shell Metacharacter Execution: Ash blocks shell metacharacters (&, ;, |, $(), backticks, redirection) before invoking tools and plugins.
4. Structured Logging Integration: Plugins can write diagnostic telemetry to ASH_LOG_FILE using structured slog format and unique Event/Error Identifiers (EID).