Clawshell 0.1.0

Human-in-the-loop security layer. Intercepts high-risk commands and requires push notification approval.

Security Scan

The skill claims to provide a human-in-the-loop shell interceptor but includes no implementation and tells you to run npm install against an odd package.json — this mismatch and the instruction to fetch remote code make it suspicious.

Purpose & Capability

The SKILL.md promises a clawshell_bash tool that intercepts and mediates shell commands, but the skill bundle contains no executable, no implementation files, and no install spec. It declares node and Pushover env vars (which are consistent with sending push notifications), but there is no local code to actually perform interception; instead the README instructs the operator to run `npm install` to fetch dependencies — an unexpected shift of responsibility and a mismatch between described capability and provided artifacts.

Instruction Scope

Runtime instructions tell the operator/agent to run `npm install` in the skill directory and to add clawshell_bash to TOOLS.md so the agent uses it for all shell execution. Those steps implicitly require downloading and executing third-party code to implement the promised behavior. The instructions also suggest writing secrets to a .env file and modifying the agent's TOOLS.md (which affects global agent behavior). The instructions do not provide implementation details or safe validation steps before executing remote code.

Install Mechanism

There is no declared install spec, but the SKILL.md explicitly instructs running `npm install`. The included package.json is minimal and depends on a package named `package-lock.json` (odd and unexpected). The lock files point to a public npm package — instructing an operator to run `npm install` will fetch code from the public registry, which can execute arbitrary install scripts. Because the skill bundle contains no local implementation, running npm install is the only way to obtain the runtime code — that introduces a download-from-registry risk that is not vetted by the skill metadata.

Credentials

The two required env vars (CLAWSHELL_PUSHOVER_USER and CLAWSHELL_PUSHOVER_TOKEN) are consistent with the stated use of Pushover for approval notifications. The SKILL.md also mentions optional Telegram variables (CLAWSHELL_TELEGRAM_*), which are not declared as required — this is a minor inconsistency but not by itself malicious. Requiring push-notification credentials is proportional to the described functionality, but exposing those credentials to unreviewed code (via npm install) would be risky.

Persistence & Privilege

The skill does not request always:true, does not request system-wide config changes programmatically in its metadata, and is user-invocable only. The SKILL.md asks you to manually edit TOOLS.md to route shell commands through clawshell_bash, which is a manual, visible change rather than a hidden privilege escalation. Autonomous invocation is allowed (the platform default) but is not combined with other high-privilege flags.

What to consider before installing

This skill is internally inconsistent: it promises a shell-intercepting tool but supplies no implementation and tells you to run `npm install` to fetch code from the registry. Do NOT run npm install or provide your Pushover (or other) tokens until you verify the runtime code. Steps to consider before installing: - Ask the publisher for the source code or a trusted release (git repo or release tarball) and verify it matches the SKILL.md behavior. - Inspect the actual JavaScript code and any install scripts (preinstall/postinstall) before running npm install. - If you must test, run it in a fully isolated sandbox with no access to real credentials and no network access to sensitive hosts. - Prefer skills that include their implementation or a verifiable release URL; avoid running npm install based on an opaque package.json/lock that appears malformed. - If you install, do not store production Pushover tokens in the .env file until the code has been audited; create a test token instead. Given the mismatch between claim and artifacts, proceed cautiously — the skill is suspicious but not provably malicious without further inspection.

ClawShell

Human-in-the-loop security layer for OpenClaw. ClawShell intercepts shell commands before execution, analyzes their risk level, and requires your explicit approval (via push notification) for dangerous operations.

How it works

1. The agent calls clawshell_bash instead of bash
2. ClawShell analyzes the command against built-in and configurable risk rules
3. Based on risk level:
   • Critical (e.g. rm -rf /, fork bombs) — automatically blocked
   • High (e.g. rm -rf, curl to external URLs, credential access) — sends a push notification and waits for your approval
   • Medium (e.g. npm install, git push) — logged and allowed
   • Low (e.g. ls, cat, git status) — allowed
4. All decisions are logged to logs/clawshell.jsonl

Tools

clawshell_bash

Secure replacement for bash. Analyzes command risk and executes only if safe or approved.

Parameters:

• command (string, required) — The shell command to execute
• workingDir (string, optional) — Working directory (defaults to cwd)

Returns: { exitCode, stdout, stderr }

High-risk commands will block until you approve or reject via push notification. Critical commands are rejected immediately.

clawshell_status

Returns current ClawShell state: pending approval requests and recent decisions.

Parameters: none

clawshell_logs

Returns recent log entries for audit and debugging.

Parameters:

• count (number, optional) — Number of entries to return (default: 20)

Setup

1. Install dependencies

cd /app/workspace/skills/clawshell
npm install

2. Configure Pushover notifications

Create a Pushover application at https://pushover.net/apps/build and add your keys to .env:

CLAWSHELL_PUSHOVER_USER=your-user-key
CLAWSHELL_PUSHOVER_TOKEN=your-app-token

Alternatively, configure Telegram instead:

CLAWSHELL_TELEGRAM_BOT_TOKEN=your-bot-token
CLAWSHELL_TELEGRAM_CHAT_ID=your-chat-id

3. Add to TOOLS.md

Add the following to your OpenClaw TOOLS.md so the agent uses ClawShell for shell commands:

## Shell Access

Use `clawshell_bash` for ALL shell command execution. Do not use `bash` directly.
ClawShell will analyze commands for risk and require human approval for dangerous operations.

Available tools:
- `clawshell_bash(command, workingDir)` — Execute a shell command with risk analysis
- `clawshell_status()` — Check pending approvals and recent decisions
- `clawshell_logs(count)` — View recent audit log entries

Configuration

ClawShell reads configuration from environment variables (CLAWSHELL_*) with fallback to config.yaml.

Variable	Default	Description
CLAWSHELL_PUSHOVER_USER	—	Pushover user key
CLAWSHELL_PUSHOVER_TOKEN	—	Pushover app token
CLAWSHELL_TELEGRAM_BOT_TOKEN	—	Telegram bot token (alternative)
CLAWSHELL_TELEGRAM_CHAT_ID	—	Telegram chat ID (alternative)
CLAWSHELL_TIMEOUT_SECONDS	300	Seconds to wait for approval before auto-reject
CLAWSHELL_LOG_DIR	logs/	Directory for JSONL log files
CLAWSHELL_LOG_LEVEL	info	Log verbosity: debug, info, warn, error
CLAWSHELL_BLOCKLIST	—	Comma-separated extra blocked commands
CLAWSHELL_ALLOWLIST	—	Comma-separated extra allowed commands

Custom rules can also be defined in config.yaml under rules.blocklist and rules.allowlist using exact strings, globs, or regex patterns.

Limitations

• Not a security guarantee. LLMs can encode, split, or obfuscate commands to bypass pattern matching.
• Defense-in-depth only. Use alongside OpenClaw's sandbox mode, not as a replacement.
• Approval latency. High-risk commands block execution until you respond or the timeout expires.

Always ask your AI to scan any skill or software for security risks.