freeharness 0.4.1

package/canonical/hooks/freeharness-security-guidance.mjs

@@ -0,0 +1,164 @@
+// FreeHarness PreToolUse security guidance.
+// Scans the content an Edit/Write/MultiEdit is about to put on disk for patterns that
+// are common vulnerability sinks and returns the matching reminders as additional
+// context. Advisory only: it never blocks (no permissionDecision) and always exits 0,
+// so the agent decides with the warning in view. Reads the hook payload from stdin.
+
+const JS = /\.(js|jsx|ts|tsx|mjs|cjs|mts|cts|vue|svelte)$/i;
+const PY = /\.(py|pyi|ipynb)$/i;
+const DOC = /\.(md|mdx|txt|rst|json|ya?ml)$/i;
+const GO = /\.go$/i;
+
+/**
+ * Pattern catalogue. `when` gates a rule on the target path (default: not a doc file);
+ * `test` is a regex over the new content. Reminders name the risk and the safer form.
+ */
+const RULES = [
+  {
+    id: "shell-exec-js",
+    when: (p) => JS.test(p),
+    test: /\bchild_process\.exec\b|\bexecSync\s*\(|(?<![\w.])exec\s*\(/,
+    reminder: "child_process.exec/execSync run through a shell: interpolated input becomes command injection. Use execFile/spawn with an argument array.",
+  },
+  {
+    id: "shell-exec-py",
+    when: (p) => PY.test(p),
+    test: /\bos\.system\s*\(|\bfrom\s+os\s+import\s+system\b|subprocess\.(run|call|Popen|check_output|check_call)\([^)]*shell\s*=\s*True/,
+    reminder: "os.system / subprocess(shell=True) are command-injection sinks. Pass a list of arguments without a shell.",
+  },
+  {
+    id: "shell-exec-go",
+    when: (p) => GO.test(p),
+    test: /exec\.Command\(\s*"(sh|bash|\/bin\/sh|\/bin\/bash)"/,
+    reminder: "exec.Command through sh/bash -c re-enables shell interpretation. Call the program directly with its arguments.",
+  },
+  {
+    id: "dynamic-code",
+    test: /(?<![\w.])eval\s*\(|\bnew\s+Function\s*\(/,
+    reminder: "eval / new Function execute arbitrary code. Parse data with JSON.parse or ast.literal_eval; use a safe expression evaluator for formulas. If intentional, say why in a comment.",
+  },
+  {
+    id: "dom-xss",
+    when: (p) => JS.test(p) || /\.html?$/i.test(p),
+    test: /\.innerHTML\s*=|\.outerHTML\s*=|insertAdjacentHTML\s*\(|document\.write\s*\(|dangerouslySetInnerHTML/,
+    reminder: "Writing raw HTML into the DOM is an XSS sink. Prefer textContent / DOM builders; if HTML is required, sanitize it first (DOMPurify).",
+  },
+  {
+    id: "unsafe-deserialization",
+    when: (p) => PY.test(p),
+    test: /(?<!\w)(pickle|cPickle|cloudpickle|dill)\.(loads?|Unpickler)\b|\bmarshal\.loads?\b|\bshelve\.open\b|\bjoblib\.load\b|read_pickle\s*\(|allow_pickle\s*=\s*True|\byaml\.(unsafe_load|load)\s*\((?![^)\n]{0,80}\bSafe)|\btorch\.load\s*\((?![^)\n]*weights_only\s*=\s*True)/,
+    reminder: "Unpickling / yaml.load / torch.load(weights_only=False) execute code embedded in the data. Use JSON or a schema-validated parser; yaml.safe_load; torch.load(weights_only=True).",
+  },
+  {
+    id: "xml-external-entities",
+    when: (p) => PY.test(p),
+    test: /\bxml\.(etree|dom|sax)\b|\blxml\.etree\.(parse|fromstring)\b/,
+    reminder: "The standard XML parsers expand external entities. Parse untrusted XML with defusedxml or disable entity resolution.",
+  },
+  {
+    id: "sql-string-build",
+    test: /(execute|executemany|raw|query|cursor\.execute)\s*\(\s*(f["']|["'][^"'\n]*["']\s*(\+|%)\s*\w|`[^`]*\$\{)/,
+    reminder: "SQL built by string formatting or concatenation is injectable. Bind parameters (placeholders) and keep identifiers on an allow-list.",
+  },
+  {
+    id: "path-traversal",
+    test: /(open|readFile|readFileSync|writeFile|writeFileSync|send_file|sendFile|os\.path\.join|path\.join|Path)\s*\([^)\n]*(req(uest)?\.(params|query|body|args|form)|user_input|filename\b|file_name\b)/,
+    reminder: "A path built from request input can escape the intended directory. Resolve it, then verify it stays under the allowed root, or map ids to files instead.",
+  },
+  {
+    id: "hardcoded-secret",
+    test: /(?:api[_-]?key|secret|password|passwd|token|private[_-]?key|client[_-]?secret)\s*[:=]\s*["'][A-Za-z0-9_\-\/+=]{12,}["']|\bsk-[A-Za-z0-9]{20,}\b|\bAKIA[0-9A-Z]{16}\b|-----BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY-----/i,
+    reminder: "This looks like a credential in source. Load secrets from the environment or a vault at runtime and keep this value out of the repository and its history.",
+  },
+  {
+    id: "tls-verification-off",
+    test: /\bverify\s*=\s*False\b|rejectUnauthorized\s*:\s*false|InsecureSkipVerify\s*:\s*true|NODE_TLS_REJECT_UNAUTHORIZED\s*=\s*["']?0|ssl\._create_unverified_context|check_hostname\s*=\s*False/,
+    reminder: "Disabling TLS verification allows man-in-the-middle. Trust the CA of a dev certificate instead of turning verification off.",
+  },
+  {
+    id: "weak-crypto",
+    test: /\bcrypto\.(createCipher|createDecipher)\b|\bAES\.MODE_ECB\b|\bmodes\.ECB\s*\(|["']aes-\d+-ecb["']|\b(md5|sha1)\s*\([^)]*(password|secret)/i,
+    reminder: "createCipher without IV, AES-ECB, and MD5/SHA-1 for secrets are broken constructions. Use AES-GCM (createCipheriv) and a password KDF (argon2/scrypt/bcrypt).",
+  },
+  {
+    id: "actions-untrusted-input",
+    when: (p) => /\.github\/workflows\/.*\.ya?ml$/.test(p),
+    test: /\$\{\{\s*github\.(event\.(issue|pull_request|comment|review|review_comment|commits|head_commit|client_payload|pages)|head_ref)/,
+    reminder: "Expanding github.event fields inside run: is script injection. Pass the value through env: and quote the variable in the shell.",
+  },
+  {
+    id: "prompt-untrusted-interpolation",
+    test: /(f["'][^"'\n]*(system|instructions?|prompt)[^"'\n]*\{[^}\n]*(user|input|document|page|html|tool_output|result|content)[^}\n]*\}|(system_prompt|SystemMessage|role\s*[:=]\s*["']system["'][^\n]*content\s*[:=])[^\n]*(\+|\$\{|\.format\(|f["']))/i,
+    reminder: "Untrusted text is being interpolated into a system prompt or instruction template. Delimit it as data (tagged block), sanitize it, and keep the decision logic outside the model.",
+  },
+  {
+    id: "llm-output-executed",
+    test: /(exec|eval|subprocess\.run|os\.system|execSync|cursor\.execute|\.query)\s*\([^)\n]*(completion|response|llm|model_output|generated|\.content\b|choices\[)/i,
+    reminder: "Model output is reaching an execution sink (shell, eval, SQL). Validate it against a schema or allow-list first; never run generated text directly.",
+  },
+];
+
+/**
+ * Collects the text an editing tool is about to write.
+ * @param {string} tool Tool name from the hook payload.
+ * @param {Record<string, unknown>} input The tool_input object.
+ * @returns {string} Concatenated new content (empty when there is none).
+ */
+function newContent(tool, input) {
+  if (tool === "Write") return String(input.content ?? "");
+  if (tool === "Edit") return String(input.new_string ?? "");
+  if (tool === "MultiEdit" && Array.isArray(input.edits)) {
+    return input.edits.map((e) => String((e && e.new_string) ?? "")).join("\n");
+  }
+  return "";
+}
+
+/**
+ * Runs the catalogue against one write and returns the matching reminders.
+ * @param {string} filePath Target path (used for language gating).
+ * @param {string} content Text about to be written.
+ * @returns {{id: string, reminder: string}[]} Matched rules in catalogue order.
+ */
+export function scan(filePath, content) {
+  const p = String(filePath).replace(/\\/g, "/");
+  const out = [];
+  for (const r of RULES) {
+    const gate = r.when ? r.when(p) : !DOC.test(p);
+    if (gate && r.test.test(content)) out.push({ id: r.id, reminder: r.reminder });
+  }
+  return out;
+}
+
+function main() {
+  let data = "";
+  process.stdin.on("data", (c) => (data += c));
+  process.stdin.on("end", () => {
+    let j;
+    try {
+      j = JSON.parse(data);
+    } catch {
+      process.exit(0);
+    }
+    const tool = j.tool_name || "";
+    if (!/^(Write|Edit|MultiEdit)$/.test(tool)) process.exit(0);
+    const ti = j.tool_input || {};
+    const file = ti.file_path || ti.path || "";
+    const hits = scan(file, newContent(tool, ti));
+    if (hits.length === 0) process.exit(0);
+    const lines = hits.map((h) => `- [${h.id}] ${h.reminder}`);
+    process.stdout.write(
+      JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext:
+            `FreeHarness security guidance for ${file || "this edit"} (advisory, not blocking):\n` +
+            lines.join("\n") +
+            "\nIf the pattern is intentional and safe, state why in a short comment and proceed.",
+        },
+      }),
+    );
+    process.exit(0);
+  });
+}
+
+if (process.argv[1] && /freeharness-security-guidance\.mjs$/.test(process.argv[1])) main();