The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: harden heredoc command filtering
dajiaohuange72191ba7408
diff --git a/scripts/hooks/gateguard-fact-force.js b/scripts/hooks/gateguard-fact-force.jsindex 2cd852a93..203092d64 100644--- a/scripts/hooks/gateguard-fact-force.js+++ b/scripts/hooks/gateguard-fact-force.js@@ -26,6 +26,7 @@ const crypto = require('crypto');const fs = require('fs');const path = require('path');const { extractCommandSubstitutions, extractSubshellGroups, extractBraceGroups } = require('../lib/shell-substitution');+const { stripHeredocBodies } = require('./gateguard-heredoc');// Session state — scoped per session to avoid cross-session races.const STATE_DIR = process.env.GATEGUARD_STATE_DIR || path.join(process.env.HOME || process.env.USERPROFILE || '/tmp', '.gateguard');@@ -151,168 +152,6 @@ function stripQuotedStrings(input) {return input.replace(/'(?:[^'\\]|\\.)*'/g, "''").replace(/"(?:[^"\\]|\\.)*"/g, '""');}-/**- * Find simple heredoc redirections on one complete shell command line.- * Anything ambiguous is rejected so the caller can fail closed and run the- * destructive checks against the original input. Supported delimiters are- * shell identifiers, either unquoted or wholly single/double quoted.- *- * @param {string} line- * @returns {{ delimiter: string, quoted: boolean, stripTabs: boolean }[] | null}- */-function findHeredocs(line) {- const heredocs = [];- let quote = null;- let escaped = false;-- for (let i = 0; i < line.length; i += 1) {- const ch = line[i];- if (escaped) {- escaped = false;- continue;- }- if (ch === '\\') {- escaped = true;- continue;- }- if (quote) {- if (ch === quote) quote = null;- continue;- }- if (ch === '"' || ch === "'") {- quote = ch;- continue;- }- if ((ch === '$' && line[i + 1] === '(' && line[i + 2] === '(') || (ch === '(' && line[i + 1] === '(')) {- // Arithmetic syntax also uses `<<`. Treat the complete input- // conservatively instead of trying to parse nested arithmetic here.- return null;- }- if (ch === '$' && line[i + 1] === '[') return null;- if (ch === '#' && (i === 0 || /[\s;&|()]/.test(line[i - 1]))) {- break;- }- if (ch !== '<' || line[i + 1] !== '<' || line[i + 2] === '<') {- continue;- }-- // `<<` is also an operator inside arithmetic and [[ ... ]] expressions.- // A partial shell parser cannot distinguish every nested form safely.- const prefix = line.slice(0, i);- if (prefix.includes('((') || prefix.includes('[[')) return null;-- i += 2;- const stripTabs = line[i] === '-';- if (stripTabs) i += 1;- while (i < line.length && /[ \t]/.test(line[i])) i += 1;-- let delimiter = '';- let quoted = false;- const delimiterQuote = line[i] === '"' || line[i] === "'" ? line[i] : null;- if (delimiterQuote) {- quoted = true;- const endQuote = line.indexOf(delimiterQuote, i + 1);- if (endQuote < 0) return null;- delimiter = line.slice(i + 1, endQuote);- i = endQuote;- } else {- const match = line.slice(i).match(/^[A-Za-z_][A-Za-z0-9_]*/);- if (!match) return null;- delimiter = match[0];- i += delimiter.length - 1;- }-- if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(delimiter)) return null;- const next = line[i + 1];- if (next && !/[\s;&|<>()]/.test(next)) return null;- heredocs.push({ delimiter, quoted, stripTabs });- }-- return quote || escaped ? null : heredocs;-}--/**- * Extract executable substitutions from an unquoted heredoc. Quote characters- * in its payload are literal and do not suppress expansion, so each unescaped- * `$(` or backtick is parsed from its own position rather than by feeding the- * complete payload through normal shell quote handling.- *- * @param {string[]} body- * @returns {string[]}- */-function extractHeredocCommandSubstitutions(body) {- const text = body.join('\n');- const substitutions = new Set();- let escaped = false;- for (let i = 0; i < text.length; i += 1) {- const ch = text[i];- if (escaped) {- escaped = false;- continue;- }- if (ch === '\\') {- escaped = true;- continue;- }- if (ch === '`' || (ch === '$' && text[i + 1] === '(')) {- for (const substitution of extractCommandSubstitutions(text.slice(i))) {- substitutions.add(substitution);- }- }- }- return [...substitutions];-}--/**- * Remove heredoc payload text before classifying the surrounding shell- * command. Prose in a heredoc is data, so matching it as a command produces- * false positives. Unquoted heredocs can still execute `$()` and backtick- * substitutions; retain the complete payload whenever either syntax appears.- * Quoted heredoc delimiters disable expansion, so their payload is fully inert.- * Ambiguous shell syntax returns the original input unchanged (fail closed).- *- * @param {string} input- * @returns {string}- */-function stripHeredocBodies(input) {- const raw = String(input || '');- const kept = [];- const pending = [];-- for (const line of raw.split(/\r?\n/)) {- if (pending.length > 0) {- const current = pending[0];- // Bash removes backslash-newline pairs in an unquoted heredoc before- // comparing delimiters. Preserve the original input when physical lines- // can be joined into a terminator or executable expansion.- if (!current.quoted && /\\$/.test(line)) return raw;- const delimiterLine = current.stripTabs ? line.replace(/^\t+/, '') : line;- if (delimiterLine === current.delimiter) {- if (!current.quoted) {- kept.push(...extractHeredocCommandSubstitutions(current.body));- }- pending.shift();- } else {- current.body.push(line);- }- continue;- }-- kept.push(line);- const heredocs = findHeredocs(line);- if (heredocs === null) return raw;- pending.push(...heredocs.map(heredoc => ({ ...heredoc, body: [] })));- }-- for (const current of pending) {- if (!current.quoted) {- kept.push(...extractHeredocCommandSubstitutions(current.body));- }- }-- return kept.join('\n');-}-/*** Promote subshell delimiters to top-level segment separators so the* destructive check applies inside `$(...)` and backtick subshells.diff --git a/scripts/hooks/gateguard-heredoc.js b/scripts/hooks/gateguard-heredoc.jsnew file mode 100644index 000000000..57cd6f459--- /dev/null+++ b/scripts/hooks/gateguard-heredoc.js@@ -0,0 +1,172 @@+'use strict';++const { extractCommandSubstitutions } = require('../lib/shell-substitution');++/**+ * Recognize the deliberately narrow passive sink supported by this parser.+ * Shell operators and substitutions make the payload's destination ambiguous,+ * so every other form retains the original input for fail-closed checks.+ *+ * @param {string} line+ * @returns {boolean}+ */+function isProvenPassiveHeredocLine(line) {+ const trimmed = line.trim();+ return /^cat(?=\s|[<>])/.test(trimmed) && !/[;&|()`]/.test(trimmed);+}++/**+ * Parse a heredoc delimiter after a verified `<<` operator.+ *+ * @param {string} line+ * @param {number} operatorIndex+ * @returns {{ heredoc: { delimiter: string, quoted: boolean, stripTabs: boolean }, endIndex: number } | null}+ */+function parseHeredocDelimiter(line, operatorIndex) {+ let endIndex = operatorIndex + 2;+ const stripTabs = line[endIndex] === '-';+ if (stripTabs) endIndex += 1;+ while (endIndex < line.length && /[ \t]/.test(line[endIndex])) endIndex += 1;++ let delimiter = '';+ let quoted = false;+ const delimiterQuote = line[endIndex] === '"' || line[endIndex] === "'" ? line[endIndex] : null;+ if (delimiterQuote) {+ quoted = true;+ const closingQuote = line.indexOf(delimiterQuote, endIndex + 1);+ if (closingQuote < 0) return null;+ delimiter = line.slice(endIndex + 1, closingQuote);+ endIndex = closingQuote;+ } else {+ const match = line.slice(endIndex).match(/^[A-Za-z_][A-Za-z0-9_]*/);+ if (!match) return null;+ delimiter = match[0];+ endIndex += delimiter.length - 1;+ }++ if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(delimiter)) return null;+ const next = line[endIndex + 1];+ if (next && !/[\s;&|<>()]/.test(next)) return null;+ return { heredoc: { delimiter, quoted, stripTabs }, endIndex };+}++/**+ * Find simple heredoc redirections on one complete shell command line.+ * Anything ambiguous returns null so the caller can fail closed.+ *+ * @param {string} line+ * @returns {{ delimiter: string, quoted: boolean, stripTabs: boolean }[] | null}+ */+function findHeredocs(line) {+ const heredocs = [];+ let quote = null;+ let escaped = false;+ for (let i = 0; i < line.length; i += 1) {+ const ch = line[i];+ if (quote === "'") {+ if (ch === "'") quote = null;+ continue;+ }+ if (escaped) {+ escaped = false;+ continue;+ }+ if (ch === '\\') {+ escaped = true;+ continue;+ }+ if (quote === '"') {+ if (ch === quote) quote = null;+ continue;+ }+ if (ch === '"' || ch === "'") {+ quote = ch;+ continue;+ }+ if ((ch === '$' && line[i + 1] === '(' && line[i + 2] === '(') || (ch === '(' && line[i + 1] === '(')) return null;+ if (ch === '$' && line[i + 1] === '[') return null;+ if (ch === '#' && (i === 0 || /[\s;&|()]/.test(line[i - 1]))) break;+ if (ch !== '<' || line[i + 1] !== '<') continue;+ if (line[i + 2] === '<') return null;+ const prefix = line.slice(0, i);+ if (prefix.includes('((') || prefix.includes('[[')) return null;+ const parsed = parseHeredocDelimiter(line, i);+ if (!parsed) return null;+ heredocs.push(parsed.heredoc);+ i = parsed.endIndex;+ }+ return quote || escaped ? null : heredocs;+}++/**+ * Extract executable substitutions from an unquoted heredoc. Quote characters+ * in its payload are literal and do not suppress expansion.+ *+ * @param {string[]} body+ * @returns {string[]}+ */+function extractHeredocCommandSubstitutions(body) {+ const text = body.join('\n');+ const substitutions = new Set();+ let escaped = false;+ for (let i = 0; i < text.length; i += 1) {+ const ch = text[i];+ if (escaped) {+ escaped = false;+ continue;+ }+ if (ch === '\\') {+ escaped = true;+ continue;+ }+ if (ch === '`' || (ch === '$' && text[i + 1] === '(')) {+ for (const substitution of extractCommandSubstitutions(text.slice(i))) {+ substitutions.add(substitution);+ }+ }+ }+ return [...substitutions];+}++/**+ * Remove heredoc payload text before classifying the surrounding shell+ * command. Prose in a heredoc is data, so matching it as a command produces+ * false positives. Unquoted heredocs can still execute `$()` and backtick+ * substitutions; retain only those substitution bodies for classification and+ * drop the remaining payload text. Quoted heredoc payloads are fully inert.+ * Ambiguous shell syntax returns the original input unchanged (fail closed).+ *+ * @param {string} input+ * @returns {string}+ */+function stripHeredocBodies(input) {+ const raw = String(input || '');+ const kept = [];+ const pending = [];+ let completedHeredoc = false;+ for (const line of raw.split(/\r?\n/)) {+ if (pending.length > 0) {+ const current = pending[0];+ if (!current.quoted && /\\$/.test(line)) return raw;+ const delimiterLine = current.stripTabs ? line.replace(/^\t+/, '') : line;+ if (delimiterLine === current.delimiter) {+ if (!current.quoted) kept.push(...extractHeredocCommandSubstitutions(current.body));+ pending.shift();+ if (pending.length === 0) completedHeredoc = true;+ } else {+ current.body.push(line);+ }+ continue;+ }+ if (completedHeredoc && line.trim()) return raw;+ kept.push(line);+ const heredocs = findHeredocs(line);+ if (heredocs === null) return raw;+ if (heredocs.length > 0 && !isProvenPassiveHeredocLine(line)) return raw;+ pending.push(...heredocs.map(heredoc => ({ ...heredoc, body: [] })));+ }+ if (pending.length > 0) return raw;+ return kept.join('\n');+}++module.exports = { stripHeredocBodies };diff --git a/tests/hooks/gateguard-fact-force.test.js b/tests/hooks/gateguard-fact-force.test.jsindex 477fa28f8..b5b18cf8c 100644--- a/tests/hooks/gateguard-fact-force.test.js+++ b/tests/hooks/gateguard-fact-force.test.js@@ -1522,6 +1522,71 @@ function runTests() {passed++;else failed++;+ if (+ test('handles multiple heredoc redirections in declaration order', () => {+ expectAllow(+ [+ "cat <<ONE <<'TWO'",+ 'DELETE FROM sessions is documentation here.',+ 'ONE',+ '$(rm -rf /tmp/example-only)',+ 'TWO'+ ].join('\n'),+ 'multiple heredoc redirections'+ );+ })+ )+ passed++;+ else failed++;++ if (+ test('fails closed when a shell consumes the heredoc payload', () => {+ for (const command of [+ ['bash <<EOF', 'rm -rf /tmp/shell-input-target', 'EOF'].join('\n'),+ ["sh <<'EOF'", 'git reset --hard', 'EOF'].join('\n'),+ ['cat <<EOF | sh', 'rm -rf /tmp/piped-shell-target', 'EOF'].join('\n'),+ ["cat > /tmp/review-script <<'EOF'", 'rm -rf /tmp/persisted-target', 'EOF', 'bash /tmp/review-script'].join('\n')+ ]) {+ expectDestructiveDeny(command, 'shell-executed heredoc payload');+ }+ })+ )+ passed++;+ else failed++;++ if (+ test('does not rescan a here-string as a heredoc', () => {+ expectDestructiveDeny(+ ['cat <<<EOF', 'rm -rf /tmp/here-string-followup'].join('\n'),+ 'command after here-string'+ );+ })+ )+ passed++;+ else failed++;++ if (+ test('uses shell-correct single-quote escaping while finding heredocs', () => {+ expectDestructiveDeny(+ ["echo 'a\\'X'<<EOF 'Y'b\\'", 'rm -rf /tmp/quoted-followup'].join('\n'),+ 'command after quoted non-heredoc text'+ );+ })+ )+ passed++;+ else failed++;++ if (+ test('fails closed on an unclosed heredoc body', () => {+ expectDestructiveDeny(+ ['cat <<EOF', 'rm -rf /tmp/unclosed-heredoc'].join('\n'),+ 'unclosed heredoc body'+ );+ })+ )+ passed++;+ else failed++;+if (test('still denies destructive commands after a heredoc terminator', () => {expectDestructiveDeny(