exec-guard

Safe command execution for AI agents with timeout control, 8KB ring buffer memory protection, background process management, and multi-agent sharing via HTTP...

Security Scan

The code and instructions match the skill's stated purpose (a command-execution and process-management service), but it exposes powerful capabilities (arbitrary system command execution, inherits host environment variables, and an unauthenticated HTTP multi-agent interface) that can leak secrets or allow remote interference if not carefully controlled.

Purpose & Capability

Name, description, and included code implement a command execution / background process manager with an HTTP API and CLI as advertised. Required items are proportional to the described function (child_process usage, ring buffer, tree-kill for process termination). No unrelated credentials or external services are requested.

Instruction Scope

Runtime instructions permit arbitrary system commands, background tasks, and an HTTP API that exposes process lists, logs, and terminate actions. The service inherits the host process environment and returns process output via HTTP endpoints — this can leak sensitive files or environment secrets if commands or output contain them. The SKILL.md and agent guide do not specify authentication, network binding restrictions, or advice to restrict exposure of the HTTP server.

Install Mechanism

No remote download/install spec is present; the package contains Node.js source and package files bundled in the skill. There is no install step that fetches code from arbitrary URLs. Risk from install mechanism is low, though running the included Node code will execute locally.

Credentials

The skill declares no required env vars, but its implementation merges process.env into child processes by default. That is functional for running commands but gives any invoked command access to all host environment variables (potentially including secrets). The ability to accept an 'env' override also allows callers to inject new sensitive values; neither behavior is unjustified for a command executor but broad and potentially dangerous without access controls.

Persistence & Privilege

The skill is not always-on and is user-invocable, and model invocation is allowed (default). While autonomous invocation is the platform default and not a defect alone, combining autonomous invocation with the ability to start an HTTP server and run arbitrary system commands increases blast radius. There is no documented authentication for the HTTP API or instructions to bind to localhost only.

Assessment

This skill appears to implement exactly what it claims — a general-purpose command executor and background process manager — which inherently grants the ability to run arbitrary system commands and read their outputs. Before installing or enabling it, consider: 1) Network exposure: run the HTTP mode only bound to localhost or behind a firewall and add authentication; the skill's docs do not describe auth. 2) Principle of least privilege: run inside an isolated container or dedicated service account to limit file and credential access. 3) Environment leakage: child processes inherit process.env — do not run it on hosts holding sensitive environment variables unless you accept the risk. 4) Audit and limits: set strict max-process, timeouts, and logging retention; review code for any hidden telemetry or externally contacting behavior (package files are present but verify dependencies in package-lock.json). 5) Source trust: there's no homepage and the owner is unknown — prefer packages from known authors or verify signatures. If you need this capability but want lower risk, restrict HTTP mode, require authentication, or use CLI-only invocation in an isolated environment. Additional information that would raise confidence: a known upstream repository/homepage, published release on a reputable host, and a documented authentication or binding configuration for the HTTP server.

exec-guard - AI Agent Command Execution Module

Safe and reliable system command execution for AI agents.

Quick Start

CLI Mode

echo '{"command": "ls -la"}' | node scripts/dist/index.js

HTTP Service Mode

node scripts/dist/index.js --server --port 8080
curl -X POST http://localhost:8080/exec -H "Content-Type: application/json" -d '{"command": "ls -la"}'

Core Capabilities

Capability	Description
Sync Execution	Execute command with timeout, wait for result
Background Execution	Start long tasks, get PID, query later
Watch Window	Confirm service startup before returning
8KB Ring Buffer	Head-Tail dual buffer prevents OOM
Process Management	Query status, get logs, terminate processes
Multi-Agent Sharing	HTTP service allows multiple agents to share state

API Reference

POST /exec

Execute a command:

{
  "command": "required - system command",
  "workingDir": "optional - working directory",
  "timeoutSeconds": "optional - default 30",
  "runInBackground": "optional - default false",
  "watchDurationSeconds": "optional - for service startup",
  "env": "optional - custom environment variables"
}

GET /process/:pid

Query process status.

GET /process/:pid/logs

Get process output logs.

DELETE /process/:pid

Terminate a process.

GET /processes

List all background processes.

Response Status

Status	Meaning
success	Command completed, exit code 0
failed	Command failed, non-zero exit
timeout	Command killed after timeout
killed	Process manually terminated
running	Background process active

Best Practices

1. Set reasonable timeout - Prevent stuck commands
2. Use watch window for services - Confirm startup success
3. Use background mode for long tasks - Training, data processing
4. Clean up processes - Terminate when done

Full Documentation

See references/AGENT_GUIDE.md for detailed usage guide and examples.

License

MIT