From 7173406841ba193a89d20fa1fadde8175235ed9d Mon Sep 17 00:00:00 2001
From: "factory-droid[bot]"
 <138933559+factory-droid[bot]@users.noreply.github.com>
Date: Sun, 30 Nov 2025 07:35:55 +0000
Subject: [PATCH] docs: add hooks example with bash command validator

Adds a complete example demonstrating PreToolUse hooks for validating
bash commands, including sample settings.

- Use printf instead of echo for reliable handling of command strings
- Fix regex patterns to properly match literal asterisks
---
 examples/hooks/bash-validator.sh     | 96 ++++++++++++++++++++++++++++
 examples/hooks/settings-example.json | 15 +++++
 2 files changed, 111 insertions(+)
 create mode 100755 examples/hooks/bash-validator.sh
 create mode 100644 examples/hooks/settings-example.json

diff --git a/examples/hooks/bash-validator.sh b/examples/hooks/bash-validator.sh
new file mode 100755
index 0000000..48db028
--- /dev/null
+++ b/examples/hooks/bash-validator.sh
@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+#
+# Bash Command Validator Hook for Droid
+#
+# This PreToolUse hook validates bash commands before execution,
+# blocking potentially dangerous operations and providing feedback.
+#
+# Exit codes:
+#   0 - Allow the command
+#   2 - Block the command (with feedback to Droid)
+#
+# Usage:
+#   Register this script as a PreToolUse hook with matcher "Bash"
+#
+
+set -euo pipefail
+
+# Read the JSON input from stdin
+INPUT=$(cat)
+
+# Extract the command using jq
+COMMAND=$(printf '%s\n' "$INPUT" | jq -r '.tool_input.command // empty')
+
+if [[ -z "$COMMAND" ]]; then
+    exit 0
+fi
+
+# Define blocked patterns (customize these for your needs)
+BLOCKED_PATTERNS=(
+    # Dangerous file operations
+    'rm -rf /'
+    'rm -rf ~'
+    'rm -rf [*]'
+    'rm -rf /[*]'
+    '> /dev/sda'
+    'mkfs\.'
+    'dd if=.* of=/dev/'
+    
+    # Fork bombs and resource exhaustion
+    ':\(\)\{.*\}:'
+    'fork bomb'
+    
+    # Privilege escalation without explicit approval
+    'chmod 777'
+    'chmod -R 777'
+    
+    # Network exfiltration patterns
+    'curl .* \| bash'
+    'wget .* \| bash'
+    'curl .* \| sh'
+    'wget .* \| sh'
+    
+    # Sensitive file access
+    '/etc/shadow'
+    '/etc/passwd'
+    '\.ssh/id_'
+    
+    # History/credential manipulation
+    'history -c'
+    'export.*PASSWORD'
+    'export.*SECRET'
+    'export.*API_KEY'
+)
+
+# Define warning patterns (allow but notify)
+WARNING_PATTERNS=(
+    'sudo'
+    'su -'
+    'chmod'
+    'chown'
+    'kill -9'
+    'pkill'
+    'killall'
+)
+
+# Check for blocked patterns
+for pattern in "${BLOCKED_PATTERNS[@]}"; do
+    if printf '%s\n' "$COMMAND" | grep -qiE "$pattern"; then
+        echo "BLOCKED: Command matches dangerous pattern: $pattern"
+        echo "Command was: $COMMAND"
+        echo ""
+        echo "If this command is necessary, please modify it to be safer or request manual execution."
+        exit 2
+    fi
+done
+
+# Check for warning patterns (log but allow)
+for pattern in "${WARNING_PATTERNS[@]}"; do
+    if printf '%s\n' "$COMMAND" | grep -qiE "$pattern"; then
+        echo "WARNING: Command uses potentially sensitive operation: $pattern" >&2
+        # Continue execution but log the warning
+    fi
+done
+
+# Command passed validation
+exit 0
diff --git a/examples/hooks/settings-example.json b/examples/hooks/settings-example.json
new file mode 100644
index 0000000..b57fd4d
--- /dev/null
+++ b/examples/hooks/settings-example.json
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$FACTORY_PROJECT_DIR\"/.factory/hooks/bash-validator.sh"
+          }
+        ]
+      }
+    ]
+  }
+}