guardrails-lite

1// Guardrails Lite as a Claude Code mod (Claude Code 2.1.287+).
2import { evaluate } from './lite-core.mjs'
3
4const RESERVED = new Set(['tool', 'tool_use_id', 'consent', 'agentId'])
5
6/** Turn a mod tool.call event into the {tool_name, tool_input} shape the core takes. */
7export function toHookInput(e) {
8  const tool_input = {}
9  for (const k of Object.keys(e ?? {})) if (!RESERVED.has(k)) tool_input[k] = e[k]
10  return { tool_name: String(e?.tool ?? ''), tool_input }
11}
12
13/** Returns the deny reason, or null to let the call through. */
14export function decide(e) {
15  const d = evaluate(toHookInput(e))
16  return d ? d.reason : null
17}
18
19export function register(on) {
20  on('tool.call', async ($, e, next) => {
21    let reason
22    try {
23      reason = decide(e)
24    } catch (err) {
25      // Fail closed: if the check itself errors, deny the call rather than let it through unchecked.
26      const msg = err && err.message ? err.message : String(err)
27      process.stderr.write(`Guardrails Lite: internal error while checking a tool call, denying it: ${msg}\n`)
28      return { deny: `Guardrails Lite: internal error while checking this call (${msg}), so it was denied. Ask the user to run it, or report the error.` }
29    }
30    if (reason) return { deny: reason }
31    return next(e)
32  }).catch(onHookFailure)
33}
34
35/**
36 * .catch handler: Claude Code calls it when the tool.call hook above throws, times out
37 * or returns a bad shape. Before next ran, deny the call; after, keep the result next produced.
38 */
39export async function onHookFailure($, e, next) {
40  if (next && next.called) return next(e)
41  const kind = (next && next.error && next.error.kind) || 'unknown'
42  return { deny: `Guardrails Lite: the check failed (${kind}), so this call was denied. Ask the user to run it, or report the error.` }
43}
44

1// Guardrails Lite: pure decision logic. No dependencies. Node 18+.
2// Three checks: secret .env reads, git force push, rm -rf on /, ~ or $HOME.
3// Every check is linear-time: split on separators/whitespace, then Set lookups,
4// startsWith and simple anchored regexes with no nested quantifiers.
5// Inputs over MAX_INPUT (64 K characters) are denied unchecked so a huge input can't stall the check.
6
7export const MAX_INPUT = 64 * 1024
8
9const READERS = new Set(['cat', 'less', 'more', 'head', 'tail', 'bat', 'nl', 'strings', 'grep', 'rg', 'awk', 'sed', 'cp', 'scp', 'base64', 'xxd', 'source', '.'])
10
11/** True for .env, .env.local, path/to/.env.production; false for .env.example/.sample/.template. */
12export function isSecretEnvName(name) {
13  let t = String(name).replace(/\\/g, '/').replace(/^@+/, '').replace(/^["']+|["']+$/g, '')
14  const slash = t.lastIndexOf('/')
15  if (slash >= 0) t = t.slice(slash + 1)
16  if (t === '.env' || t === '.env*' || t === '.env.*') return true
17  if (!t.startsWith('.env.')) return false
18  const parts = t.slice(5).split('.')
19  if (parts.some((p) => !/^[\w*-]+$/.test(p))) return false
20  return !['example', 'sample', 'template'].includes(parts[parts.length - 1].toLowerCase())
21}
22
23function segments(cmd) {
24  return cmd.split(/[;&|\n]+/).map((s) => s.trim().split(/\s+/).filter(Boolean))
25}
26
27function forcePush(w) {
28  const gp = w.findIndex((x, i) => x === 'git' && w[i + 1] === 'push')
29  if (gp < 0) return false
30  return w.slice(gp + 2).some((x) => x === '-f' || x.startsWith('--force') || (x.startsWith('-') && !x.startsWith('--') && x.includes('f')) || (x.startsWith('+') && x.length > 1))
31}
32
33const RM_TARGETS = new Set(['/', '/*', '~', '~/', '~/*', '$HOME', '$HOME/', '$HOME/*', '${HOME}', '${HOME}/', '${HOME}/*', '"$HOME"', '"${HOME}"'])
34function rmRecursiveRootOrHome(w) {
35  const r = w.indexOf('rm')
36  if (r < 0) return false
37  const args = w.slice(r + 1)
38  const recursive = args.some((x) => x === '--recursive' || (x.startsWith('-') && !x.startsWith('--') && /[rR]/.test(x)))
39  return recursive && args.some((x) => RM_TARGETS.has(x))
40}
41
42function readsSecretFile(w) {
43  const r = w.findIndex((x) => READERS.has(x))
44  return r >= 0 && w.slice(r + 1).some(isSecretEnvName)
45}
46
47const deny = (reason) => ({ decision: 'deny', reason })
48
49/**
50 * @param {{tool_name: string, tool_input: Record<string, any>}} input
51 * @returns {{decision: 'deny', reason: string} | null}
52 */
53export function evaluate(input) {
54  const tool = String(input?.tool_name ?? '')
55  const ti = input?.tool_input ?? {}
56
57  if (tool === 'Read' || tool === 'Grep' || tool === 'Glob') {
58    const targets = [ti.file_path, ti.path, tool === 'Glob' ? ti.pattern : undefined, ti.glob].filter((x) => typeof x === 'string')
59    for (const t of targets) {
60      if (t.length > MAX_INPUT) return deny('Guardrails Lite: the path or pattern is too large to check.')
61      if (t.split(/[\s,{}]+/).some(isSecretEnvName)) return deny(`Guardrails Lite: reading ${t} is blocked because .env files hold secrets. Use .env.example for variable names, or ask the user for the specific value.`)
62    }
63    return null
64  }
65
66  if (tool === 'Bash') {
67    const cmd = typeof ti.command === 'string' ? ti.command : ''
68    if (cmd.length > MAX_INPUT) return deny(`Guardrails Lite: the command is over ${MAX_INPUT / 1024} K characters, too large to check.`)
69    for (const w of segments(cmd)) {
70      if (forcePush(w)) return deny('Guardrails Lite: force push needs the user\'s explicit approval. Ask the user to run it.')
71      if (rmRecursiveRootOrHome(w)) return deny('Guardrails Lite: recursive rm on /, ~ or $HOME is blocked. Ask the user to run it.')
72      if (readsSecretFile(w)) return deny('Guardrails Lite: this command would print or copy a secret .env file. Use .env.example instead.')
73    }
74  }
75  return null
76}
77