+332

chook.mjs

reviewed

··· 1 1 + #!/usr/bin/env node 2 2 + 3 3 + import { readFileSync } from "fs"; 4 4 + import { appendFileSync, openSync, closeSync, writeFileSync } from "fs"; 5 5 + import { resolve } from "path"; 6 6 + 7 7 + // --- Config loading --- 8 8 + 9 9 + function loadConfig(configPath) { 10 10 + const text = readFileSync(configPath, "utf-8"); 11 11 + return parseTOML(text); 12 12 + } 13 13 + 14 14 + // Minimal TOML parser sufficient for our config format 15 15 + function parseTOML(text) { 16 16 + const config = { allow: [], deny: [], audit: {} }; 17 17 + let currentSection = null; 18 18 + let currentObj = null; 19 19 + 20 20 + for (const rawLine of text.split("\n")) { 21 21 + const line = rawLine.replace(/#.*$/, "").trim(); 22 22 + if (!line) continue; 23 23 + 24 24 + // Array of tables: [[allow]] or [[deny]] 25 25 + const arrayMatch = line.match(/^\[\[(\w+)\]\]$/); 26 26 + if (arrayMatch) { 27 27 + const key = arrayMatch[1]; 28 28 + if (!config[key]) config[key] = []; 29 29 + currentObj = {}; 30 30 + config[key].push(currentObj); 31 31 + currentSection = "array"; 32 32 + continue; 33 33 + } 34 34 + 35 35 + // Table: [audit] 36 36 + const tableMatch = line.match(/^\[(\w+)\]$/); 37 37 + if (tableMatch) { 38 38 + const key = tableMatch[1]; 39 39 + if (!config[key]) config[key] = {}; 40 40 + currentObj = config[key]; 41 41 + currentSection = "table"; 42 42 + continue; 43 43 + } 44 44 + 45 45 + // Key = value 46 46 + const kvMatch = line.match(/^(\w+)\s*=\s*(.+)$/); 47 47 + if (kvMatch && currentObj) { 48 48 + const [, key, rawVal] = kvMatch; 49 49 + currentObj[key] = parseValue(rawVal.trim()); 50 50 + } 51 51 + } 52 52 + 53 53 + return config; 54 54 + } 55 55 + 56 56 + function parseValue(val) { 57 57 + // String (double-quoted) 58 58 + if (val.startsWith('"') && val.endsWith('"')) { 59 59 + // Handle TOML escape sequences 60 60 + return val.slice(1, -1).replace(/\\(.)/g, (_, c) => { 61 61 + if (c === "n") return "\n"; 62 62 + if (c === "t") return "\t"; 63 63 + if (c === "\\") return "\\"; 64 64 + if (c === '"') return '"'; 65 65 + return c; 66 66 + }); 67 67 + } 68 68 + // Single-quoted (literal, no escapes) 69 69 + if (val.startsWith("'") && val.endsWith("'")) { 70 70 + return val.slice(1, -1); 71 71 + } 72 72 + // Boolean 73 73 + if (val === "true") return true; 74 74 + if (val === "false") return false; 75 75 + // Number 76 76 + if (/^-?\d+(\.\d+)?$/.test(val)) return Number(val); 77 77 + return val; 78 78 + } 79 79 + 80 80 + // --- Rule compilation --- 81 81 + 82 82 + function compileRules(ruleConfigs) { 83 83 + return ruleConfigs.map((rc) => ({ 84 84 + tool: rc.tool, 85 85 + reason: rc.reason || null, 86 86 + restrict_to_cwd: rc.restrict_to_cwd === true, 87 87 + file_path_regex: rc.file_path_regex ? new RegExp(rc.file_path_regex) : null, 88 88 + file_path_exclude_regex: rc.file_path_exclude_regex 89 89 + ? new RegExp(rc.file_path_exclude_regex) 90 90 + : null, 91 91 + command_regex: rc.command_regex ? new RegExp(rc.command_regex) : null, 92 92 + command_exclude_regex: rc.command_exclude_regex 93 93 + ? new RegExp(rc.command_exclude_regex) 94 94 + : null, 95 95 + subagent_type: rc.subagent_type || null, 96 96 + prompt_regex: rc.prompt_regex ? new RegExp(rc.prompt_regex) : null, 97 97 + prompt_exclude_regex: rc.prompt_exclude_regex 98 98 + ? new RegExp(rc.prompt_exclude_regex) 99 99 + : null, 100 100 + })); 101 101 + } 102 102 + 103 103 + // --- Matching --- 104 104 + 105 105 + function checkFieldWithExclude(value, mainRegex, excludeRegex) { 106 106 + if (!mainRegex) return false; 107 107 + if (!mainRegex.test(value)) return false; 108 108 + if (excludeRegex && excludeRegex.test(value)) return false; 109 109 + return true; 110 110 + } 111 111 + 112 112 + function checkFilePath(filePath, rule, cwd) { 113 113 + if (!filePath) return false; 114 114 + // resolve to absolute to neutralize ../ tricks 115 115 + const resolved = resolve(filePath); 116 116 + if (rule.restrict_to_cwd) { 117 117 + const cwdPrefix = cwd.endsWith("/") ? cwd : cwd + "/"; 118 118 + if (!resolved.startsWith(cwdPrefix) && resolved !== cwd) return false; 119 119 + } 120 120 + if (rule.file_path_regex) { 121 121 + if (!rule.file_path_regex.test(resolved)) return false; 122 122 + } 123 123 + if (rule.file_path_exclude_regex && rule.file_path_exclude_regex.test(resolved)) { 124 124 + return false; 125 125 + } 126 126 + // restrict_to_cwd alone (no regex) is a valid match 127 127 + if (!rule.restrict_to_cwd && !rule.file_path_regex) return false; 128 128 + return true; 129 129 + } 130 130 + 131 131 + function checkRule(rule, toolName, toolInput, cwd) { 132 132 + if (rule.tool !== toolName) return null; 133 133 + 134 134 + let autoReason = null; 135 135 + 136 136 + switch (toolName) { 137 137 + case "Read": 138 138 + case "Write": 139 139 + case "Edit": 140 140 + case "MultiEdit": 141 141 + case "Glob": { 142 142 + const filePath = toolInput.file_path || toolInput.notebook_path; 143 143 + if (checkFilePath(filePath, rule, cwd)) { 144 144 + autoReason = `Matched rule for ${toolName} with file_path: ${filePath}`; 145 145 + } 146 146 + break; 147 147 + } 148 148 + case "Bash": { 149 149 + const command = toolInput.command; 150 150 + if ( 151 151 + command && 152 152 + checkFieldWithExclude( 153 153 + command, 154 154 + rule.command_regex, 155 155 + rule.command_exclude_regex, 156 156 + ) 157 157 + ) { 158 158 + autoReason = `Matched rule for Bash with command: ${command}`; 159 159 + } 160 160 + break; 161 161 + } 162 162 + case "Task": { 163 163 + if (rule.subagent_type && toolInput.subagent_type) { 164 164 + if (rule.subagent_type === toolInput.subagent_type) { 165 165 + autoReason = `Matched rule for Task with subagent_type: ${toolInput.subagent_type}`; 166 166 + } 167 167 + } 168 168 + if (!autoReason && toolInput.prompt) { 169 169 + if ( 170 170 + checkFieldWithExclude( 171 171 + toolInput.prompt, 172 172 + rule.prompt_regex, 173 173 + rule.prompt_exclude_regex, 174 174 + ) 175 175 + ) { 176 176 + autoReason = "Matched rule for Task with prompt pattern"; 177 177 + } 178 178 + } 179 179 + break; 180 180 + } 181 181 + case "NotebookEdit": { 182 182 + const nbPath = toolInput.notebook_path; 183 183 + if (checkFilePath(nbPath, rule, cwd)) { 184 184 + autoReason = `Matched rule for NotebookEdit with path: ${nbPath}`; 185 185 + } 186 186 + break; 187 187 + } 188 188 + } 189 189 + 190 190 + if (!autoReason) return null; 191 191 + return rule.reason || autoReason; 192 192 + } 193 193 + 194 194 + function checkRules(rules, toolName, toolInput, cwd) { 195 195 + for (const rule of rules) { 196 196 + const reason = checkRule(rule, toolName, toolInput, cwd); 197 197 + if (reason) return reason; 198 198 + } 199 199 + return null; 200 200 + } 201 201 + 202 202 + // --- Auditing --- 203 203 + 204 204 + function truncateStrings(value, maxLen = 256) { 205 205 + if (typeof value === "string") { 206 206 + return value.length <= maxLen ? value : value.slice(0, maxLen) + "…"; 207 207 + } 208 208 + if (Array.isArray(value)) { 209 209 + return value.map((v) => truncateStrings(v, maxLen)); 210 210 + } 211 211 + if (value && typeof value === "object") { 212 212 + const out = {}; 213 213 + for (const [k, v] of Object.entries(value)) { 214 214 + out[k] = truncateStrings(v, maxLen); 215 215 + } 216 216 + return out; 217 217 + } 218 218 + return value; 219 219 + } 220 220 + 221 221 + function audit(auditConfig, input, decision, reason) { 222 222 + if (!auditConfig?.audit_file) return; 223 223 + const level = auditConfig.audit_level || "matched"; 224 224 + if (level === "off") return; 225 225 + if (level === "matched" && decision === "passthrough") return; 226 226 + 227 227 + const entry = { 228 228 + timestamp: new Date().toISOString(), 229 229 + session_id: input.session_id, 230 230 + tool_name: input.tool_name, 231 231 + tool_input: truncateStrings(input.tool_input), 232 232 + decision, 233 233 + ...(reason ? { reason } : {}), 234 234 + cwd: input.cwd, 235 235 + }; 236 236 + 237 237 + try { 238 238 + appendFileSync(auditConfig.audit_file, JSON.stringify(entry) + "\n"); 239 239 + } catch (e) { 240 240 + process.stderr.write(`chook: audit write failed: ${e.message}\n`); 241 241 + } 242 242 + } 243 243 + 244 244 + // --- Hook output --- 245 245 + 246 246 + function makeOutput(decision, reason) { 247 247 + return { 248 248 + hookSpecificOutput: { 249 249 + hookEventName: "PreToolUse", 250 250 + permissionDecision: decision, 251 251 + permissionDecisionReason: reason || "", 252 252 + }, 253 253 + suppressOutput: true, 254 254 + }; 255 255 + } 256 256 + 257 257 + // --- CLI --- 258 258 + 259 259 + const args = process.argv.slice(2); 260 260 + const command = args[0]; 261 261 + 262 262 + if (command === "validate") { 263 263 + const configIdx = args.indexOf("--config"); 264 264 + const configPath = configIdx >= 0 ? args[configIdx + 1] : null; 265 265 + if (!configPath) { 266 266 + console.error("Usage: chook validate --config <path>"); 267 267 + process.exit(1); 268 268 + } 269 269 + try { 270 270 + const config = loadConfig(resolve(configPath)); 271 271 + const denyRules = compileRules(config.deny || []); 272 272 + const allowRules = compileRules(config.allow || []); 273 273 + console.log("Configuration is valid!"); 274 274 + console.log(` Deny rules: ${denyRules.length}`); 275 275 + console.log(` Allow rules: ${allowRules.length}`); 276 276 + console.log(` Audit file: ${config.audit?.audit_file || "(none)"}`); 277 277 + console.log(` Audit level: ${config.audit?.audit_level || "matched"}`); 278 278 + } catch (e) { 279 279 + console.error(`Invalid config: ${e.message}`); 280 280 + process.exit(1); 281 281 + } 282 282 + } else if (command === "run") { 283 283 + const configIdx = args.indexOf("--config"); 284 284 + const configPath = configIdx >= 0 ? args[configIdx + 1] : null; 285 285 + if (!configPath) { 286 286 + console.error("Usage: chook run --config <path>"); 287 287 + process.exit(1); 288 288 + } 289 289 + 290 290 + try { 291 291 + const config = loadConfig(resolve(configPath)); 292 292 + const denyRules = compileRules(config.deny || []); 293 293 + const allowRules = compileRules(config.allow || []); 294 294 + 295 295 + // Read JSON from stdin 296 296 + const stdin = readFileSync(0, "utf-8"); 297 297 + const input = JSON.parse(stdin); 298 298 + 299 299 + const toolName = input.tool_name; 300 300 + const toolInput = input.tool_input; 301 301 + const cwd = input.cwd; 302 302 + 303 303 + // Check deny first 304 304 + const denyReason = checkRules(denyRules, toolName, toolInput, cwd); 305 305 + if (denyReason) { 306 306 + audit(config.audit, input, "deny", denyReason); 307 307 + process.stdout.write(JSON.stringify(makeOutput("deny", denyReason))); 308 308 + process.exit(0); 309 309 + } 310 310 + 311 311 + // Check allow 312 312 + const allowReason = checkRules(allowRules, toolName, toolInput, cwd); 313 313 + if (allowReason) { 314 314 + audit(config.audit, input, "allow", allowReason); 315 315 + process.stdout.write(JSON.stringify(makeOutput("allow", allowReason))); 316 316 + process.exit(0); 317 317 + } 318 318 + 319 319 + // Passthrough - no output 320 320 + audit(config.audit, input, "passthrough", null); 321 321 + } catch (e) { 322 322 + process.stderr.write(`chook error: ${e.message}\n`); 323 323 + process.exit(1); 324 324 + } 325 325 + } else { 326 326 + console.error("Usage: chook <run|validate> --config <path>"); 327 327 + console.error(""); 328 328 + console.error("Commands:"); 329 329 + console.error(" run Run as PreToolUse hook (reads JSON from stdin)"); 330 330 + console.error(" validate Validate a TOML configuration file"); 331 331 + process.exit(1); 332 332 + }

+86

example.toml

reviewed

··· 1 1 + [audit] 2 2 + audit_file = "/tmp/chook-audit.json" 3 3 + # off | matched | all 4 4 + audit_level = "matched" 5 5 + 6 6 + # === DENY RULES (checked first) === 7 7 + 8 8 + [[deny]] 9 9 + tool = "Bash" 10 10 + command_regex = "^rm .*-rf" 11 11 + reason = "Recursive force-delete is blocked. Use rm on specific files, or ask the user to run this manually." 12 12 + 13 13 + [[deny]] 14 14 + tool = "Bash" 15 15 + command_regex = "^sudo " 16 16 + reason = "sudo is not allowed. Find an alternative that doesn't require elevated privileges." 17 17 + 18 18 + [[deny]] 19 19 + tool = "Read" 20 20 + file_path_regex = "\\.(env|secret|pem|key)$" 21 21 + reason = "Reading secrets/credentials is blocked. Use environment variables or ask the user to provide the needed values." 22 22 + 23 23 + [[deny]] 24 24 + tool = "Write" 25 25 + file_path_regex = "\\.(env|secret|pem|key)$" 26 26 + reason = "Writing secrets/credentials is blocked. Ask the user to create or update this file manually." 27 27 + 28 28 + # Block shell metacharacters in commands — run each command separately or use a package.json script 29 29 + [[deny]] 30 30 + tool = "Bash" 31 31 + command_regex = "&|;|\\||`|\\$\\(" 32 32 + reason = "Chained/piped commands are not auto-approved. Run each command independently as separate Bash calls, or define a script in package.json and run that instead." 33 33 + 34 34 + # === ALLOW RULES (checked after deny) === 35 35 + 36 36 + # Allow file ops within the cwd tree where Claude was started 37 37 + [[allow]] 38 38 + tool = "Read" 39 39 + restrict_to_cwd = true 40 40 + file_path_exclude_regex = "\\.\\." 41 41 + 42 42 + [[allow]] 43 43 + tool = "Write" 44 44 + restrict_to_cwd = true 45 45 + file_path_exclude_regex = "\\.\\." 46 46 + 47 47 + [[allow]] 48 48 + tool = "Edit" 49 49 + restrict_to_cwd = true 50 50 + file_path_exclude_regex = "\\.\\." 51 51 + 52 52 + [[allow]] 53 53 + tool = "Glob" 54 54 + restrict_to_cwd = true 55 55 + 56 56 + # Always allow /tmp access 57 57 + [[allow]] 58 58 + tool = "Read" 59 59 + file_path_regex = "^/tmp/" 60 60 + 61 61 + [[allow]] 62 62 + tool = "Write" 63 63 + file_path_regex = "^/tmp/" 64 64 + 65 65 + [[allow]] 66 66 + tool = "Edit" 67 67 + file_path_regex = "^/tmp/" 68 68 + 69 69 + [[allow]] 70 70 + tool = "Glob" 71 71 + file_path_regex = "^/tmp/" 72 72 + 73 73 + # Allow safe bash commands (no shell injection) 74 74 + [[allow]] 75 75 + tool = "Bash" 76 76 + command_regex = "^(git |npm |node |npx |bun |cargo |make |ls |cat |head |tail |wc |find |grep |rg |which |echo |pwd |mkdir |cp |mv |touch |chmod |brew |gh )" 77 77 + command_exclude_regex = "&|;|\\||`|\\$\\(" 78 78 + 79 79 + # Allow subagents 80 80 + [[allow]] 81 81 + tool = "Task" 82 82 + subagent_type = "Explore" 83 83 + 84 84 + [[allow]] 85 85 + tool = "Task" 86 86 + subagent_type = "Plan"