@clear-capabilities/agentic-security-scanner 0.186.2 → 0.188.0

package/src/language/haskell-guards.js

@@ -30,7 +30,7 @@ const FAMILY_BY_CWE = { 'CWE-22': 'path', 'CWE-918': 'url', 'CWE-78': 'cmd', 'CW
 
 const isStr = (e) => e && e.kind === 'literal' && typeof e.value === 'string';
 
-function identNames(e, out = new Set(), depth = 0) {
+export function identNames(e, out = new Set(), depth = 0) {
   if (!e || typeof e !== 'object' || depth > 30) return out;
   if (e.kind === 'ident' && e.name && !(e.hs && e.hs.functionRef)) out.add(e.name);
   for (const k of ['left', 'right', 'object', 'value', 'callee']) if (e[k] && typeof e[k] === 'object') identNames(e[k], out, depth + 1);
@@ -44,6 +44,8 @@ const mentions = (e, vars) => { for (const n of identNames(e)) if (vars.has(n))
 /** Classify a condition over the value `vars`. -> {safeWhen, kind, families, needsCanon?, subject} | null */
 export function classifyCondition(c, vars, derived = new Set()) {
   if (!c || typeof c !== 'object') return null;
+  // The IR lowers `&&` / `||` to a `logical` node (`and` / `or`); a `binary` node is kept for the same operators from other lowerings.
+  if (c.kind === 'logical' && (c.op === 'and' || c.op === 'or')) return classifyCondition({ kind: 'binary', op: c.op === 'and' ? '&&' : '||', left: c.left, right: c.right }, vars, derived);
   if (c.kind === 'binary') {
     if (c.op === '&&') { const a = classifyCondition(c.left, vars, derived); const b = classifyCondition(c.right, vars, derived); return [a, b].find((x) => x && x.safeWhen === true) || null; }
     if (c.op === '||') { const a = classifyCondition(c.left, vars, derived); const b = classifyCondition(c.right, vars, derived); return [a, b].find((x) => x && x.safeWhen === false) || null; }
@@ -72,8 +74,12 @@ export function classifyCondition(c, vars, derived = new Set()) {
   }
   // `uriRegName a `elem` ["api.example.com"]` where `a` was parsed from the checked URL: the host is on an allow-list, which is the
   // URL family's control. Only a HOST accessor over a value derived from the checked one counts (a path or query allow-list does not).
-  if ((IS_ELEM.has(name) || NOT_ELEM.has(name)) && a[0] && a[0].kind === 'call' && /(?:^|\.)(?:uriRegName|uriAuthority|getHost)$/.test(a[0].callee || '') && a[0].args && a[0].args[0] && a[0].args[0].kind === 'ident'
-      && (vars.has(a[0].args[0].name) || derived.has(a[0].args[0].name)) && a[1] && a[1].kind === 'array' && a[1].elements.length && a[1].elements.every(isStr)) {
+  // The list may be written inline (a literal list of strings) or be a named constant (`allowedHosts`): either way it must not be built from the
+  // checked value, or the check would compare the value with itself.
+  const fixedList = (l) => l && ((l.kind === 'array' && l.elements.length && l.elements.every((x) => isStr(x) || (x && x.kind === 'call' && /(?:^|\.)(?:pack|fromString)$/.test(x.callee || '') && x.args && x.args.length === 1 && isStr(x.args[0]))))
+    || (l.kind === 'ident' && !mentions(l, vars) && !mentions(l, derived)));
+  if ((IS_ELEM.has(name) || NOT_ELEM.has(name)) && a[0] && a[0].kind === 'call' && /(?:^|\.)(?:uriRegName|uriAuthority|getHost|host|hostName)$/.test(a[0].callee || '') && a[0].args && a[0].args[0] && a[0].args[0].kind === 'ident'
+      && (vars.has(a[0].args[0].name) || derived.has(a[0].args[0].name)) && fixedList(a[1])) {
     return { safeWhen: IS_ELEM.has(name), kind: 'host-allow-list', families: ['url'], subject: a[0].args[0].name };
   }
   if ((IS_ELEM.has(name) || NOT_ELEM.has(name)) && a[0] && a[0].kind === 'ident' && vars.has(a[0].name) && !mentions(a[1], vars)) {
@@ -112,7 +118,7 @@ const exprChildren = (e) => {
 };
 
 // Find the sink call at `line` with callee `callee`; returns [{ nodeId, facts, call }].
-function findSites(fn, callee, line) {
+export function findSites(fn, callee, line) {
   const sites = [];
   const visit = (e, nodeId, facts, depth) => {
     if (!e || typeof e !== 'object' || depth > 60) return;
@@ -264,6 +270,62 @@ function isCanonical(fn, name) {
   return false;
 }
 
+// A hand-written HTML escaper: a project function (or one of its local helpers) that spells out the entities for `<`, `>` and `&`. Recognised by
+// what the code does (it produces those entity strings), never by its name. Kept per IR build.
+const ESCAPERS = new WeakMap();
+const ENTITY = { lt: /&lt;|&#0*60;|&#x0*3c;/i, gt: /&gt;|&#0*62;|&#x0*3e;/i, amp: /&amp;|&#0*38;|&#x0*26;/i };
+function stringLiteralsOf(fn) {
+  const out = [];
+  const visit = (e, depth) => {
+    if (!e || typeof e !== 'object' || depth > 60) return;
+    if (e.kind === 'literal' && typeof e.value === 'string') out.push(e.value);
+    for (const [, c] of exprChildren(e)) visit(c, depth + 1);
+    if (Array.isArray(e.branches)) for (const b of e.branches) visit(b, depth + 1);   // the arms of a conditional or a multi-clause function
+  };
+  for (const n of nodeList(fn)) { for (const k of ['source', 'value', 'cond']) visit(n[k], 0); if (Array.isArray(n.args)) for (const a of n.args) visit(a, 0); }
+  return out;
+}
+export function htmlEscapers(perFile) {
+  if (!perFile || typeof perFile !== 'object') return new Set();
+  let hit = ESCAPERS.get(perFile);
+  if (hit) return hit;
+  hit = new Set();
+  for (const ir of Object.values(perFile)) {
+    const fns = ir.functions || [];
+    // local helpers and lambdas record their parent's qid: one pass groups them, so the whole file costs one visit per function
+    const children = new Map();
+    for (const fn of fns) { const par = fn.hs && fn.hs.parent; if (par) { if (!children.has(par)) children.set(par, []); children.get(par).push(fn); } }
+    const lits = new Map();
+    const litsOf = (fn, depth = 0) => {
+      if (lits.has(fn.qid)) return lits.get(fn.qid);
+      let out = stringLiteralsOf(fn);
+      if (depth < 8) for (const c of children.get(fn.qid) || []) out = out.concat(litsOf(c, depth + 1));
+      lits.set(fn.qid, out);
+      return out;
+    };
+    for (const fn of fns) {
+      if (!fn.name || fn.name.endsWith('.<module>') || (fn.hs && (fn.hs.kind === 'closure' || fn.hs.kind === 'local-function'))) continue;
+      const all = litsOf(fn);
+      if (all.some((l) => ENTITY.lt.test(l)) && all.some((l) => ENTITY.gt.test(l)) && all.some((l) => ENTITY.amp.test(l))) hit.add(fn.name);
+    }
+  }
+  ESCAPERS.set(perFile, hit);
+  return hit;
+}
+
+/** Every occurrence of a variable inside `e` is an argument of an escaper (or a value an escaper call produced): nothing raw reaches the sink. */
+function allUsesEscaped(fn, e, escapers, depth = 0) {
+  if (!e || typeof e !== 'object' || depth > 40) return true;
+  if (e.kind === 'call' && escapers.has(e.callee)) return true;     // whatever it receives is escaped
+  if (e.kind === 'ident') {
+    if (e.hs && e.hs.functionRef) return true;
+    const defs = nodeList(fn).filter((n) => n.kind === 'assign' && n.target === e.name && n.source);
+    return defs.length > 0 && defs.every((n) => n.source.kind === 'call' && escapers.has(n.source.callee));
+  }
+  for (const [, c] of exprChildren(e)) if (!allUsesEscaped(fn, c, escapers, depth + 1)) return false;
+  return true;
+}
+
 /**
  * Judge one finding. Mutates it when a dominating, family-appropriate guard refutes the flow.
  * @returns {{status:'refuted'|'weak-guard'|'none', guard?:object}}
@@ -289,7 +351,16 @@ export function judgeFinding(f, perFile) {
     const derived = derivedFrom(fn, vars);   // values built FROM the checked one (`a` in `Just a <- parseURI url`)
     const facts = [...site.facts, ...cfgBranchFacts(fn, site.nodeId), ...exitGuardFacts(fn, site.nodeId)];
     let refuted = null;
+    if (fam === 'xss') {
+      const escapers = htmlEscapers(perFile);
+      const calls = [];
+      const find = (e, d) => { if (!e || typeof e !== 'object' || d > 40) return; if (e.kind === 'call' && escapers.has(e.callee)) calls.push(e); for (const [, c] of exprChildren(e)) find(c, d + 1); };
+      find(argExpr, 0);
+      for (const n of nodeList(fn)) if (n.kind === 'assign' && n.source && identNames(argExpr).has(n.target)) find(n.source, 0);
+      if (calls.length && allUsesEscaped(fn, argExpr, escapers)) refuted = { kind: 'html-escaper', line: calls[0].line || fn.line, subject: calls[0].callee };
+    }
     for (const fact of facts) {
+      if (refuted) break;
       const cls = classifyCondition(fact.cond, vars, derived);
       if (!cls || cls.safeWhen !== fact.when) continue;
       if (!(cls.families.includes('*') || cls.families.includes(fam))) continue;          // wrong-context control
@@ -346,7 +417,10 @@ export function promoteShellInterpreter(f, perFile) {
     if (!isStr(prog) || !SHELLS.test(prog.value) || !list || list.kind !== 'array') continue;
     const flag = list.elements.findIndex((e) => isStr(e) && SHELL_C.test(e.value));
     if (flag < 0) continue;
-    if (list.elements.slice(flag + 1).some((e) => e && e.kind !== 'literal')) {
+    // `sh -c SCRIPT arg0 arg1 ..`: only the SCRIPT is parsed by the shell. The elements after it are the positional parameters ($0, $1, ...), plain
+    // data to a script that does not interpolate them into code; a tainted script is injection, tainted positionals are judged by `quotedPositionals`.
+    const script = list.elements[flag + 1];
+    if (script && script.kind !== 'literal') {
       f.cwe = 'CWE-78'; f.severity = 'critical'; f.vuln = 'OS Command Injection (shell interpreter -c)';
       f.id = String(f.id).replace('cwe-88', 'cwe-78'); f.shellInterpreter = prog.value;
       return true;
@@ -355,12 +429,65 @@ export function promoteShellInterpreter(f, perFile) {
   return false;
 }
 
+/**
+ * `callProcess "sh" ["-c", "gzip -9 -- \"$1\"", "sh", target]`: the script is a constant and the tainted value is a positional parameter the
+ * script expands INSIDE DOUBLE QUOTES after `--`. The shell does not re-parse a quoted expansion, and `--` ends the program's option parsing, so
+ * neither shell nor option injection is possible through it. A reference that is unquoted, quoted with single quotes, or not preceded by `--` is not
+ * covered: the finding stays. Returns the control or null.
+ */
+export function quotedPositionals(f, perFile) {
+  if (!f || f.cwe !== 'CWE-88' || !PROCESS_FNS.has(f.callee)) return null;
+  const ir = perFile && perFile[f.file];
+  const fn = ir && f._funcQid && ir.functions.find((x) => x.qid === f._funcQid);
+  if (!fn) return null;
+  const sites = findSites(fn, f.callee, f.line);
+  if (!sites.length) return null;
+  for (const site of sites) {
+    const [prog, list] = site.call.args || [];
+    if (!isStr(prog) || !SHELLS.test(prog.value) || !list || list.kind !== 'array') return null;
+    const flag = list.elements.findIndex((e) => isStr(e) && SHELL_C.test(e.value));
+    const script = flag >= 0 ? list.elements[flag + 1] : null;
+    if (!isStr(script)) return null;
+    // a tainted element BEFORE the script (or the script itself) is not a positional parameter
+    if (list.elements.slice(0, flag + 2).some((e) => e && e.kind !== 'literal')) return null;
+    // the literal keeps the Haskell string's own escapes (`\"`, `\\`, `\n`): decode them to get the text the shell receives
+    const text = script.value.replace(/\\(["'\\ntr])/g, (m, c) => ({ n: '\n', t: '\t', r: '\r' }[c] || c));
+    let dq = false; let sq = false; let seenDashes = false;
+    for (let i = 0; i < text.length; i++) {
+      const ch = text[i];
+      if (ch === '\\' && !sq) { i++; continue; }
+      if (ch === "'" && !dq) { sq = !sq; continue; }
+      if (ch === '"' && !sq) { dq = !dq; continue; }
+      if (!dq && !sq && ch === '-' && text[i + 1] === '-' && /\s/.test(text[i + 2] || ' ') && (i === 0 || /\s/.test(text[i - 1]))) { seenDashes = true; continue; }
+      if (ch === '$' && !sq) {
+        const rest = text.slice(i + 1);
+        if (/^(?:[0-9]|\{[0-9]+\}|[@*]|\{[@*]\})/.test(rest)) {
+          if (!dq || !seenDashes) return null;
+        } else if (/^[A-Za-z_(`{]/.test(rest)) { return null; }   // another expansion or a command substitution: not judged here
+      }
+      if (ch === '`' && !sq) return null;
+    }
+    return { kind: 'quoted-positional-parameters' };
+  }
+  return null;
+}
+
 /** Applies judgeFinding to every Haskell taint finding. Returns counts. */
 export function applyHaskellGuards(findings, perFile) {
   const stats = { refuted: 0, weak: 0 };
   for (const f of findings || []) {
     if (!f || f.parser !== 'IR-TAINT') continue;
     try { promoteShellInterpreter(f, perFile); } catch { /* judged as an argument-injection below */ }
+    try {
+      const qp = quotedPositionals(f, perFile);
+      if (qp && !f._quotedPositionals) {
+        f._quotedPositionals = true; f.severity = 'info';
+        f.controls = [...(f.controls || []), { kind: 'quoted-positional-parameters', evidenceKind: 'source' }];
+        f.guardNote = { kind: 'quoted-positional-parameters', reason: 'the script is a constant and expands the tainted value only inside double quotes after "--"; the shell does not re-parse it and the program stops reading options' };
+        stats.weak++;
+        continue;
+      }
+    } catch { /* judged below */ }
     try {
       const ot = optionTerminator(f, perFile);
       if (ot && !f._optionTerminated) {

package/src/language/haskell-ir.js

@@ -27,7 +27,7 @@ import { createHash } from 'node:crypto';
 import { parseSyntax, groupDecls, patternVars } from './haskell-syntax.js';
 import { preprocessForSyntax } from './haskell-parser.js';
 import { deriveCppContext } from './haskell-cpp.js';
-import { isKnownApi, isSourceApi, qualifyAmbiguous } from './haskell-models.js';
+import { isKnownApi, isSourceApi, qualifyAmbiguous, handlerFrameworkOf } from './haskell-models.js';
 
 export const HS_IR_LIMITS = Object.freeze({
   maxExprDepth: 200,
@@ -50,9 +50,14 @@ const HOF = {
   forM_: { fn: 1, coll: 0, kind: 'traverse_' }, for_: { fn: 1, coll: 0, kind: 'traverse_' },
   filter: { fn: 0, coll: 1, kind: 'filter' },
   foldr: { fn: 0, seed: 1, coll: 2, kind: 'fold' }, foldl: { fn: 0, seed: 1, coll: 2, kind: 'fold' }, "foldl'": { fn: 0, seed: 1, coll: 2, kind: 'fold' },
+  foldM: { fn: 0, seed: 1, coll: 2, kind: 'fold', monadic: true }, foldM_: { fn: 0, seed: 1, coll: 2, kind: 'fold', monadic: true },
+  zipWith: { fn: 0, coll: 1, coll2: 2, kind: 'map' }, zipWithM: { fn: 0, coll: 1, coll2: 2, kind: 'traverse' }, zipWithM_: { fn: 0, coll: 1, coll2: 2, kind: 'traverse_' },
   sequence: { coll: 0, kind: 'sequence' }, sequenceA: { coll: 0, kind: 'sequence' }, sequence_: { coll: 0, kind: 'sequence' },
 };
 
+// Predicates that accept only letters and digits (Data.Char): a string filtered by one holds nothing else.
+const CHAR_CLASS = new Set(['Data.Char.isAlphaNum', 'Data.Char.isAlpha', 'Data.Char.isDigit', 'Data.Char.isHexDigit', 'Data.Char.isOctDigit', 'Data.Char.isLetter', 'Data.Char.isNumber']);
+
 const ARITH = new Set(['+', '-', '*', '/', '^', '**', '==', '/=', '<', '<=', '>', '>=', '!!', '%']);
 
 const unknownExpr = (hs) => (hs ? { kind: 'unknown', hs } : { kind: 'unknown' });
@@ -84,7 +89,7 @@ function sigInfo(tokens, sig) {
       else if (depth === 0 && t.t === 'rop' && t.v === '->') { argTypes.push(tokens.slice(start, i).map((x) => x.v).join(' ')); start = i + 1; }
     }
   }
-  return { arity, returnsIO: !!first && first.t === 'con' && first.v === 'IO', text: tokens.slice(sig.ta, sig.tb).map((t) => t.v).join(' '), argTypes };
+  return { arity, returnsIO: !!first && first.t === 'con' && first.v === 'IO', text: tokens.slice(sig.ta, sig.tb).map((t) => t.v).join(' '), argTypes, resultText: tokens.slice(resStart, sig.tb).map((t) => t.v).join(' ') };
 }
 
 // Parameters of an EXPORTED function whose declared type is text-like: the caller supplies that text, and nothing in the
@@ -92,10 +97,72 @@ function sigInfo(tokens, sig) {
 // request or stdin read: the finding says so). A function without a signature, a non-exported function and a parameter
 // of any other type (a connection, a number, a record) are never sources.
 const TEXT_LIKE = /^\(?\s*(?:Maybe\s+)?(?:String|Text|ByteString|FilePath|URI|Url|URL|\[\s*Char\s*\]|\[\s*(?:String|Text)\s*\])\s*\)?$/;
-function callerControlledParams(fn, sig, exported) {
+// Parameters of an exported function whose declared type is a container or text (a list, a map, a set, a sequence, a vector, a string):
+// a PARTIAL function (`maximum`, `head`, `Map.!`) applied to one fails on the empty or missing case the caller can supply. Wider than
+// TEXT_LIKE on purpose, and used only by the partial-function rule, never as an injection source.
+const COLLECTION_LIKE = /^\(?\s*(?:Maybe\s+)?(?:\[.*\]|(?:Map|HashMap|IntMap|Set|HashSet|IntSet|Seq|Vector|Text|String|ByteString)\b.*)\)?$/;
+function inputParams(fn, sig, exported) {
+  if (!exported || !sig || !Array.isArray(sig.argTypes) || !Array.isArray(fn.params)) return [];
+  const out = [];
+  sig.argTypes.forEach((t, i) => { const name = fn.params[i]; if (name && (TEXT_LIKE.test(t) || COLLECTION_LIKE.test(t))) out.push(name); });
+  return out;
+}
+function callerControlledParams(fn, sig, exported, imports) {
   if (!exported || !sig || !Array.isArray(sig.argTypes) || !Array.isArray(fn.params)) return [];
   const out = [];
-  sig.argTypes.forEach((t, i) => { const name = fn.params[i]; if (name && TEXT_LIKE.test(t)) out.push({ index: i, name, decorator: 'hs:caller-controlled' }); });
+  // The result type is the part of the signature after the last top-level arrow; a function returning a framework handler value gets its text
+  // parameters labelled as request input, any other exported function keeps the weaker caller-controlled label.
+  const handler = handlerFrameworkOf(imports, sig.resultText);
+  const decorator = handler ? handler.decorator : 'hs:caller-controlled';
+  sig.argTypes.forEach((t, i) => { const name = fn.params[i]; if (name && TEXT_LIKE.test(t)) out.push({ index: i, name, decorator }); });
+  return out;
+}
+
+// A Servant endpoint written as a function (`server acct rowId = ...` for `type API = AuthProtect "jwt" :> Capture "id" Int :> Get ..`): its parameters are
+// the values the API type takes from the request, in order of appearance. Only a single-endpoint API can be paired with one function by position (several
+// endpoints are joined with `:<|>` and each handler is its own function, which the handler-result rule already covers). A parameter is a request source
+// when its API combinator reads the request (capture, query, header, body) and its declared type is text; an authenticated principal is not.
+const SERVANT_READS = new Set(['Capture', "Capture'", 'QueryParam', "QueryParam'", 'QueryParams', 'Header', "Header'", 'ReqBody', "ReqBody'"]);
+const SERVANT_PRINCIPAL = new Set(['AuthProtect', 'BasicAuth', 'Auth']);
+function servantEndpointParams(mod, fn, sig, exported) {
+  if (!exported || !sig || !sig.resultText || !Array.isArray(fn.params) || !fn.params.length) return [];
+  const m = /^\s*(?:Server|ServerT)\s+([A-Z][A-Za-z0-9_']*)\b/.exec(sig.resultText);
+  if (!m || !mod.imports.some((i) => /^Servant(?:\.|$)/.test(i.module))) return [];
+  const td = (mod.parse.typeDecls || []).find((d) => d.name === m[1]);
+  if (!td) return [];
+  const T = mod.parse.tokens;
+  const slice = T.slice(td.a, td.b);
+  const eq = slice.findIndex((t) => t.t === 'rop' && t.v === '=');
+  if (eq < 0) return [];
+  const split = (tokens, sep) => {
+    const parts = [[]]; let depth = 0;
+    for (const t of tokens) {
+      if (t.t === 'sp' && (t.v === '(' || t.v === '[')) depth++;
+      if (t.t === 'sp' && (t.v === ')' || t.v === ']')) depth--;
+      if (depth === 0 && t.t === 'op' && t.v === sep) { parts.push([]); continue; }
+      parts[parts.length - 1].push(t);
+    }
+    return parts;
+  };
+  const body = slice.slice(eq + 1);
+  if (split(body, ':<|>').filter((p) => p.length).length !== 1) return [];
+  const out = [];
+  let idx = 0;
+  for (const part of split(body, ':>').filter((p) => p.length)) {
+    const head = part[0];
+    if (!head || head.t !== 'con') continue;
+    const isPrincipal = SERVANT_PRINCIPAL.has(head.v);
+    if (!isPrincipal && !SERVANT_READS.has(head.v)) continue;
+    const name = fn.params[idx];
+    idx++;
+    if (isPrincipal || !name) continue;
+    // the carried type is what follows the name string (or the content-type list for a body): its text decides whether it is text
+    const lastStr = part.map((t) => t.t).lastIndexOf('str');
+    let rest = part.slice(lastStr >= 0 ? lastStr + 1 : 1);
+    if (/^ReqBody/.test(head.v)) { const close = rest.findIndex((t) => t.t === 'sp' && t.v === ']'); rest = close >= 0 ? rest.slice(close + 1) : rest; }
+    const type = rest.map((t) => t.v).join(' ').trim();
+    if (type && TEXT_LIKE.test(type.replace(/^\[\s*(.*)\s*\]$/, '[ $1 ]').replace(/\s+/g, ' '))) out.push({ index: idx - 1, name, decorator: 'hs:handler-param:servant' });
+  }
   return out;
 }
 
@@ -197,6 +264,7 @@ function resolveGlobalUncached(proj, mod, name, qual, depth, seen) {
   const hits = [];
   const wildcard = [];
   let unknownReason = null;
+  let unknownCandidates = null;
   for (const imp of visibleImports(mod, name, qual)) {
     const target = proj.modules.get(imp.module);
     if (target) {
@@ -207,7 +275,7 @@ function resolveGlobalUncached(proj, mod, name, qual, depth, seen) {
         const owner = r.kind === 'def' ? (r.def.kind === 'field' ? (proj.modules.get(r.mod)?.cons.get(r.def.con)?.type) : r.def.kind === 'method' ? r.def.cls : null) : null;
         if (!owner || !(imp.typeAll || []).includes(owner)) continue;
       }
-      if (r.kind === 'unknown') unknownReason = r.reason; else hits.push(r);
+      if (r.kind === 'unknown') { unknownReason = r.reason; if (r.candidates) unknownCandidates = r.candidates; } else hits.push(r);
     } else if (qual || (imp.items && !imp.hiding && imp.items.includes(name))) hits.push({ kind: 'external', module: imp.module, name, certain: true });
     else wildcard.push(imp.module);   // includes `import M (T(..))` of a module we cannot read: possible, never certain
   }
@@ -215,7 +283,7 @@ function resolveGlobalUncached(proj, mod, name, qual, depth, seen) {
   const distinct = [...new Map(hits.map((r) => [keyOf(r), r])).values()];
   if (distinct.length === 1) return distinct[0];
   if (distinct.length > 1) return { kind: 'unknown', reason: 'ambiguous-import', candidates: distinct.map(keyOf) };
-  if (unknownReason) return { kind: 'unknown', reason: unknownReason };
+  if (unknownReason) return unknownCandidates ? { kind: 'unknown', reason: unknownReason, candidates: unknownCandidates } : { kind: 'unknown', reason: unknownReason };
   if (!qual && PRELUDE.has(name)) return { kind: 'builtin', module: 'Prelude', name };
   if (wildcard.length) return { kind: 'external', module: wildcard.length === 1 ? wildcard[0] : null, candidates: wildcard, name, certain: false };
   return { kind: 'unknown', reason: qual ? 'unknown-qualifier' : 'unbound-name' };
@@ -363,6 +431,25 @@ function inlinableBody(fnAst) {
   return acc.ok ? { params: c.pats.map((p) => p.name), body: c.rhs.body } : null;
 }
 
+// A point-free alias: `tidy = takeFileName`, `clean = trim . takeFileName`. A zero-argument binding whose whole right-hand side is a
+// function name or a composition of function names IS the function it names, so applying it is applying them. Without this the
+// application is an unresolved call, and a sanitizer (or a sink) reached through the alias loses its identity.
+// Returns the right-hand side AST and the unqualified names it mentions, or null for anything else (guards, where, any other form).
+function aliasBodyOf(fnAst) {
+  if (!fnAst || fnAst.clauses.length !== 1) return null;
+  const c = fnAst.clauses[0];
+  if (c.pats.length || !c.rhs || (c.rhs.guards && c.rhs.guards.length) || (c.rhs.where && c.rhs.where.length) || !c.rhs.body) return null;
+  const names = [];
+  const ok = (e) => {
+    const x = unparen(e);
+    if (!x) return false;
+    if (x.t === 'var') { if (!x.qual) names.push(x.name); return x.name !== fnAst.name; }
+    if (x.t === 'op' && x.op === '.' && !x.qual) return ok(x.l) && ok(x.r);
+    return false;
+  };
+  return ok(c.rhs.body) ? { body: c.rhs.body, names } : null;
+}
+
 // ── per-function lowering ────────────────────────────────────────────────────
 class FnLowerer {
   constructor(proj, mod, fnInfo, scopes) {
@@ -429,6 +516,10 @@ class FnLowerer {
       case 'app': return this.lowerApp(e.f, e.args, ln);
       case 'op': return this.lowerOp(e, ln);
       case 'neg': return { kind: 'binary', op: '-', left: { kind: 'literal', value: 0 }, right: this.lowerExpr(e.e, ln) };
+      // `read s :: Int`: the value is a number, so it is a clean constant for the taint engine. The lowered inner expression rides on `hs.inner`, which the rule and web
+      // analyses read (an unsafe coercion in it, the id it names), exactly as they read `hs.selector`. (A sanitizer call would be wrong here: the engine's sanitizer label is per expression, so a
+      // number in `"kill " ++ show n ++ name` would mark the tainted `name` sanitized too.)
+      case 'typed': return { kind: 'literal', value: 0, hs: { numeric: e.type, inner: this.lowerExpr(e.e, ln) } };
       case 'tuple': return { kind: 'array', elements: e.items.map((x) => this.lowerExpr(x, ln)), hs: { tuple: true } };
       case 'list': return { kind: 'array', elements: e.items.map((x) => this.lowerExpr(x, ln)) };
       case 'range': return { kind: 'array', elements: e.items.map((x) => this.lowerExpr(x, ln)), hs: { range: true } };
@@ -494,6 +585,7 @@ class FnLowerer {
       return { kind: 'ident', name: this.canonical(r), hs: { functionRef: r.qid } };
     }
     if (r.kind === 'param' || r.kind === 'local') return { kind: 'ident', name: e.name };
+    if (r.kind === 'unknown' && r.reason === 'ambiguous-import') for (const q of r.candidates || []) this.noteRef(q, 'ambiguous-import', ln);
     const lib = libraryName(r, e.name, e.qual);
     const viaReg = lib.viaRegistry ? { viaRegistry: true, certain: false } : {};
     // A modelled SOURCE action named as a value (`getLine >>= f`, `fmap g getLine`) yields untrusted data
@@ -526,7 +618,9 @@ class FnLowerer {
     }
     if (f.t === 'rsec') return this.lowerOp({ t: 'op', op: f.op, qual: f.qual, l: argAsts[0], r: f.e, line: ln }, ln);
     if (f.t === 'lsec') return this.lowerOp({ t: 'op', op: f.op, qual: f.qual, l: f.e, r: argAsts[0], line: ln }, ln);
-    if (f.t === 'lam') return this.betaReduce(f, argAsts, ln);
+    if (f.t === 'lam') return this.betaReduce(f, argAsts, ln, via);
+    // `m >>= \case ...`: a \case applied to its argument is a case on that argument, run here (not a call of an unknown lifted function)
+    if (f.t === 'lamcase') return this.betaReduce({ params: [{ t: 'pvar', name: '$lc' }], body: { t: 'case', scrut: { t: 'var', name: '$lc', qual: null }, alts: f.alts, line: ln }, line: ln }, argAsts, ln, via);
     if (f.t === 'var') return this.applyVar(f, argAsts, ln, via);
     if (f.t === 'con') {
       const cons = this.mod.cons.get(f.name) || this.proj.findCon(f.name);
@@ -539,11 +633,14 @@ class FnLowerer {
     return { kind: 'call', callee: '<indirect>', args: [fv, ...argAsts.map((a) => this.lowerExpr(a, ln))], hs: { status: 'unknown', reason: 'computed-function', via } };
   }
 
-  betaReduce(lam, argAsts, ln) {
+  betaReduce(lam, argAsts, ln, via) {
     const n = Math.min(lam.params.length, argAsts.length);
     this.push();
     try {
-      for (let i = 0; i < n; i++) this.bindPattern(lam.params[i], this.lowerExpr(argAsts[i], ln), ln);
+      // `action >>= \x -> k` and `f <$> action` RUN the action and hand its result to the lambda, even when the lambda ignores it (`\_ -> k`):
+      // the action is executed where it is sequenced, not only where its result is used.
+      const runs = via === 'bind' || via === 'fmap' || via === 'applicative';
+      for (let i = 0; i < n; i++) this.bindPattern(lam.params[i], this.lowerExpr(argAsts[i], ln), ln, runs ? { executed: true } : undefined);
       if (lam.params.length > argAsts.length) return { kind: 'array', elements: argAsts.map((a) => this.lowerExpr(a, ln)), hs: { partial: { remaining: lam.params.length - argAsts.length }, closure: true } };
       const body = this.lowerExpr(lam.body, ln);
       if (argAsts.length > n) return { kind: 'call', callee: '<indirect>', args: [body, ...argAsts.slice(n).map((a) => this.lowerExpr(a, ln))], hs: { status: 'unknown', reason: 'result-applied' } };
@@ -558,11 +655,30 @@ class FnLowerer {
       const out = this.lowerHof(f.name, argAsts, ln);
       if (out) return out;
     }
+    // `maybe d f m` and `either f g e` apply a function to the value inside: `f` (and `g`) are called with it, so a sink passed as the function
+    // (`maybe (pure ()) callCommand mc`) is reached by the value. The result is whichever branch ran.
+    if ((r.kind === 'builtin' || r.kind === 'external') && ((f.name === 'maybe' && argAsts.length >= 3) || (f.name === 'either' && argAsts.length >= 3))) {
+      // The scrutinee is examined whichever branch runs, so it is the condition of a two-way branch (an ignored payload, `\\_ -> ..`, still reads it).
+      const scrut = this.lowerExpr(argAsts[2], ln);
+      const inner = { t: 'lowered', expr: scrut };
+      return f.name === 'maybe'
+        ? this.branch(scrut, ln, () => this.lowerApp(argAsts[1], [inner], ln, f.name), () => this.lowerExpr(argAsts[0], ln))
+        : this.branch(scrut, ln, () => this.lowerApp(argAsts[1], [inner], ln, f.name), () => this.lowerApp(argAsts[0], [inner], ln, f.name));
+    }
+    // Selectors and combinators over a tuple that is written out: `fst (a, b)` is `a`, `const x y` is `x`, `uncurry f (a, b)` is `f a b`.
+    if ((r.kind === 'builtin' || r.kind === 'external') && !f.qual) {
+      const tup = (a) => { const u = unparen(a); return u && u.t === 'tuple' && u.items.length === 2 ? u.items : null; };
+      if ((f.name === 'fst' || f.name === 'snd') && argAsts.length === 1 && tup(argAsts[0])) return this.lowerExpr(tup(argAsts[0])[f.name === 'fst' ? 0 : 1], ln);
+      if (f.name === 'const' && argAsts.length === 2) { this.lowerExpr(argAsts[1], ln); return this.lowerExpr(argAsts[0], ln); }
+      if (f.name === 'uncurry' && argAsts.length === 2 && tup(argAsts[1])) return this.lowerApp(argAsts[0], tup(argAsts[1]), ln, via);
+    }
     if (r.kind === 'def' && r.def.kind === 'field' && argAsts.length >= 1) {
       const obj = this.lowerExpr(argAsts[0], ln);
       const mem = { kind: 'member', object: obj, prop: r.name };
       return argAsts.length === 1 ? mem : { kind: 'call', callee: '<indirect>', args: [mem, ...argAsts.slice(1).map((a) => this.lowerExpr(a, ln))], hs: { status: 'unknown', reason: 'field-applied' } };
     }
+    const viaAlias = this.applyAlias(r, argAsts, ln, via);
+    if (viaAlias) return viaAlias;
     let args = argAsts.map((a) => this.lowerExpr(a, ln));
     // `lookup key table` returns an element OF the table: the key chooses which, it is not where the value comes from. Only the table
     // flows to the result, so a constant table gives a constant result however tainted the key is.
@@ -611,6 +727,10 @@ class FnLowerer {
       if (IO_NAMES.has(f.name)) this.sawIO = true;
     } else {
       hs.status = 'unknown'; hs.reason = r.reason || 'unresolved'; hs.effect = 'unknown';
+      // An import that two modules both satisfy (the Posix and Windows variants of one module behind a CPP conditional, two re-exports of
+      // one name) is a call to ONE of them, which one is not decided here. Each candidate is referenced, so none of them reads as a
+      // function nothing in the project uses.
+      if (r.reason === 'ambiguous-import') for (const q of r.candidates || []) this.noteRef(q, 'ambiguous-import', ln);
     }
     if (hs.status === 'resolved' || hs.status === 'typeclass') {
       const ctxTargets = args.map((a) => argTargets(a));
@@ -635,6 +755,39 @@ class FnLowerer {
     return { kind: 'ident', name: t, hs: { sourceTemp: call.callee } };
   }
 
+  // Apply a point-free alias (see aliasBodyOf) as the function(s) it names. The names are looked up where the alias was DEFINED; a
+  // local binding of one of them at the use site would capture it, so that case is left to the ordinary (unresolved) call.
+  applyAlias(r, argAsts, ln, via) {
+    let alias = null; let calleeMod = this.mod;
+    if (r.kind === 'local' && r.alias) alias = r.alias;
+    else if (r.kind === 'def' && r.def.kind === 'fun' && r.def.arity === 0) {
+      calleeMod = this.proj.modules.get(r.mod);
+      alias = calleeMod ? aliasBodyOf(calleeMod.groups.funs.find((f) => f.name === r.name)) : null;
+    }
+    if (!alias || (this.inlineDepth || 0) >= INLINE_MAX_DEPTH) return null;
+    if (alias.names.some((n) => this.lookupLocal(n))) return null;
+    const savedMod = this.mod;
+    // Only an alias of LIBRARY functions is expanded. A project function keeps its own summary and call-graph node, and
+    // expanding it here would replace the edge to it with edges to what it calls.
+    this.mod = calleeMod;
+    const libraryOnly = alias.names.every((n) => { const k = this.resolve(n, null).kind; return k === 'external' || k === 'builtin'; });
+    this.mod = savedMod;
+    if (!libraryOnly) return null;
+    // Arguments belong to the CALLER: lower them here, once, then hand them over as already-lowered expressions.
+    const lowered = argAsts.map((a) => ({ t: 'lowered', expr: this.lowerExpr(a, ln) }));
+    const savedOverride = this.lineOverride;
+    this.lineOverride = this.lineOverride || ln;
+    this.inlineDepth = (this.inlineDepth || 0) + 1;
+    this.mod = calleeMod;
+    // The alias is still CALLED here: keep its call-graph edge, exactly as an inlined function body does.
+    if (r.kind === 'def') (this.inlinedCalls ||= []).push({ site: null, callee: this.canonical(r), args: [], line: ln, hs: { status: 'resolved', target: r.qid, effect: 'unknown', inlined: true, ...(via ? { via } : {}) } });
+    try { return this.lowerApp(alias.body, lowered, ln); } finally {
+      this.mod = savedMod;
+      this.lineOverride = savedOverride;
+      this.inlineDepth -= 1;
+    }
+  }
+
   // Substitute lowered arguments into a small pure callee body. Returns null when the callee is not inlinable.
   tryInline(r, loweredArgs, ln, via) {
     const calleeMod = this.proj.modules.get(r.mod);
@@ -673,19 +826,31 @@ class FnLowerer {
   // Bounded collection/traversal summaries. Returns null to fall back to a plain call.
   lowerHof(name, argAsts, ln) {
     const spec = HOF[name];
-    const need = Math.max(spec.fn === undefined ? 0 : spec.fn, spec.coll) + 1;
+    const need = Math.max(spec.fn === undefined ? 0 : spec.fn, spec.coll, spec.coll2 === undefined ? 0 : spec.coll2) + 1;
     if (argAsts.length < need || (spec.seed !== undefined && argAsts.length < 3)) return null;
     const coll = this.lowerExpr(argAsts[spec.coll], ln);
     const elem = { kind: 'member', object: coll, prop: '[]' };
+    // a function of two collections (`zipWithM_ f xs ys`): it is applied to an element of each
+    const el2 = spec.coll2 !== undefined && argAsts[spec.coll2] ? { t: 'lowered', expr: { kind: 'member', object: this.lowerExpr(argAsts[spec.coll2], ln), prop: '[]' } } : null;
     if (spec.kind === 'sequence') { this.sawIO = true; return coll; }
     const fnAst = argAsts[spec.fn];
     const el = { t: 'lowered', expr: elem };
     if (spec.kind === 'fold') {
       const seed = this.lowerExpr(argAsts[spec.seed], ln);
       const step = this.lowerApp(fnAst, [spec.fn === 0 && (name === 'foldr') ? el : { t: 'lowered', expr: seed }, name === 'foldr' ? { t: 'lowered', expr: seed } : el], ln, name);
+      if (spec.monadic) this.sawIO = true;
       return mkUnion(seed, step);
     }
-    const res = this.lowerApp(fnAst, [el], ln, name);
+    const res = this.lowerApp(fnAst, el2 ? [el, el2] : [el], ln, name);
+    // `filter isAlphaNum s` keeps only letters and digits: no quote, separator, dot or markup character survives, so nothing in the result
+    // can change the meaning of a command, a query, a path or a page. A predicate that merely drops some characters (`/= ';'`) is not that.
+    if (spec.kind === 'filter') {
+      const pf = unparen(fnAst);
+      if (pf && pf.t === 'var') {
+        const pr = this.resolve(pf.name, pf.qual);
+        if ((pr.kind === 'external' || pr.kind === 'builtin') && CHAR_CLASS.has(libraryName(pr, pf.name, pf.qual).name)) return { kind: 'literal', value: '', hs: { charClassFilter: pf.name } };
+      }
+    }
     if (spec.kind === 'filter') {
       this.cfg.add('if', ln, { cond: res, hs: { via: 'filter' } });
       return coll;
@@ -920,6 +1085,14 @@ class FnLowerer {
   processDecls(decls, bodyAsts, ln) {
     if (!decls.length) return;
     const g = groupDecls(decls);
+    // `let run = \x -> ...` is a function of one parameter written in lambda form: treat it as `run x = ...` so a call `run c` is resolved and analysed
+    // for the value it is given, instead of being an unknown call of a local value.
+    g.funs = g.funs.map((f) => {
+      if (f.clauses.length !== 1) return f;
+      const c = f.clauses[0];
+      const body = c.pats.length === 0 && c.rhs && !(c.rhs.guards && c.rhs.guards.length) && !(c.rhs.where && c.rhs.where.length) ? unparen(c.rhs.body) : null;
+      return body && body.t === 'lam' && body.params.every((p) => p && p.t === 'pvar') ? { ...f, clauses: [{ ...c, pats: body.params, rhs: { ...c.rhs, body: body.body } }] } : f;
+    });
     const scope = this.scopes[this.scopes.length - 1];
     const parent = this.info.parentName || this.info.name;
     for (const f of g.funs) {
@@ -940,6 +1113,9 @@ class FnLowerer {
       const rhsAsts = f.clauses.map((c) => c.rhs);
       const others = siblingAsts.filter((a) => a && !rhsAsts.includes(a));
       this.bindLazy([f.name], () => this.lowerRhs(f.clauses[0].rhs, f.line || ln), bodyAsts, others, strict, f.line || ln);
+      // bindLazy declares a plain local; a point-free alias keeps what it names so applying it resolves to that function.
+      const alias = aliasBodyOf(f);
+      if (alias && !alias.names.some((n) => this.lookupLocal(n))) scope.set(f.name, { kind: 'local', alias });
     }
     for (const pb of g.patbinds) {
       const names = patternVars(pb.pat);
@@ -1162,8 +1338,11 @@ function lowerTopFunction(proj, mod, fun, def) {
   const kind = def.arity > 0 ? 'function' : (sig && sig.returnsIO) || fun.name === 'main' ? 'io-action' : 'value';
   const exported = !mod.exports || mod.exports.some((x) => x.kind === 'var' && x.name === fun.name || x.kind === 'module' && x.name === mod.name);
   const fn = L.finishFn({ kind, arity: def.arity, effect: sig ? (sig.returnsIO ? 'io' : 'pure') : (L.sawIO ? 'io' : 'unknown'), sig: sig ? sig.text : null, exported });
-  const ann = callerControlledParams(fn, sig, exported);
+  const ann = callerControlledParams(fn, sig, exported, mod.imports.map((i) => i.module));
+  for (const a of servantEndpointParams(mod, fn, sig, exported)) if (!ann.some((x) => x.name === a.name)) ann.push(a);
   fn.hs.textParams = ann.map((a) => a.name);
+  fn.hs.paramSources = ann.map((a) => ({ name: a.name, decorator: a.decorator }));
+  fn.hs.inputParams = inputParams(fn, sig, exported);
   // Parameters of an exported function whose type is a record DECLARED IN THE PROJECT: the lineage view treats each such
   // parameter as a source of that record's fields (a customer record handed to an entry point), field by field.
   const recTypes = proj.recordTypes();
@@ -1282,7 +1461,13 @@ function buildHaskellIRUncached(fileContents) {
   const reached = new Set();
   for (const e of callGraph.edges || []) if (e && e.callee) reached.add(e.callee);
   for (const fn of callGraph.functions.values()) for (const r of (fn.hs && fn.hs.refs) || []) if (r && r.target) reached.add(r.target);
-  for (const fn of callGraph.functions.values()) if (reached.has(fn.qid)) { if (fn.paramAnnotations) delete fn.paramAnnotations; if (fn.hs && fn.hs.recordParams) fn.hs.recordParams = []; }
+  assignEntryRoles(proj, callGraph);
+  for (const fn of callGraph.functions.values()) {
+    // `reached`: something in the analysed code calls or references this function, so its parameters take their values from THOSE callers
+    // (which the taint engine follows) and not from an unknown outside one. Rules that reason about "caller-supplied" text read it.
+    if (fn.hs) fn.hs.reached = reached.has(fn.qid);
+    if (reached.has(fn.qid)) { if (fn.paramAnnotations) delete fn.paramAnnotations; if (fn.hs && fn.hs.recordParams) fn.hs.recordParams = []; }
+  }
   return { perFile, callGraph, modules: proj.modules, diagnostics: proj.diagnostics, project: proj };
 }
 
@@ -1296,6 +1481,36 @@ function incomplete(proj, mod, f, err) {
   proj.diagnostics.push({ file: mod.file, line: f.line, kind: 'ir-lowering-failure', detail: String(err && err.message) });
 }
 
+// ── entry roles ──────────────────────────────────────────────────────────────
+// Who is on the other end of the program's inputs depends on what kind of program the function belongs to. A function reachable from a
+// `main` whose reachable modules import no server framework or socket library belongs to a command-line program: whoever runs it supplies its
+// arguments, environment, standard input and the files it is pointed at. One reachable from a `main` that imports a server framework (a WAI,
+// Scotty, Servant, Yesod, Snap, Happstack or Spock application, a socket listener) belongs to a service, whose inputs come from its clients.
+// A function no `main` reaches is `library`: its callers are unknown. The call graph is incomplete (an unresolved call ends a path), so a
+// function the walk does not reach is `library`, never `cli`.
+const SERVER_IMPORT = /^(?:Network\.Wai|Web\.Scotty|Servant|Yesod|Snap|Happstack\.Server|Web\.Spock)(?:\.|$)|^Network\.(?:Socket|Simple\.TCP|Run\.TCP|HTTP\.Server)$/;
+export function assignEntryRoles(proj, callGraph) {
+  const out = new Map();
+  for (const e of callGraph.edges || []) if (e && e.callee && e.caller) { if (!out.has(e.caller)) out.set(e.caller, []); out.get(e.caller).push(e.callee); }
+  const mains = [];
+  for (const fn of callGraph.functions.values()) if (fn.hs && fn.hs.module && fn.name === `${fn.hs.module}.main`) mains.push(fn);
+  const cli = new Set(); const service = new Set();
+  for (const m of mains) {
+    const seen = new Set([m.qid]);
+    const todo = [m.qid];
+    while (todo.length) { const q = todo.pop(); for (const c of out.get(q) || []) if (!seen.has(c)) { seen.add(c); todo.push(c); } }
+    const mods = new Set();
+    for (const q of seen) { const f = callGraph.functions.get(q); if (f && f.hs && f.hs.module) mods.add(f.hs.module); }
+    let isService = false;
+    for (const name of mods) { const mi = proj.modules.get(name); if (mi && (mi.imports || []).some((i) => SERVER_IMPORT.test(i.module))) { isService = true; break; } }
+    for (const q of seen) (isService ? service : cli).add(q);
+  }
+  for (const fn of callGraph.functions.values()) {
+    if (!fn.hs) continue;
+    fn.hs.entryRole = service.has(fn.qid) ? 'service' : (cli.has(fn.qid) ? 'cli' : 'library');
+  }
+}
+
 // ── call graph ───────────────────────────────────────────────────────────────
 function buildHaskellCallGraph(perFile, proj) {
   const functions = new Map();