fallow security

CLI reference for fallow security. Surface opt-in local security candidates for agent or human verification.

Surface local security candidates for verification. Two rule families ship: the graph-structural client-server-leak (a "use client" file that directly reads, or transitively imports a module that reads, a non-public process.env secret), and the data-driven tainted-sink catalogue (syntactic dangerous-sink candidates across a catalogue of CWE categories). Both default to off and run only under fallow security.

Findings are candidates, not confirmed vulnerabilities. Fallow reports a structural trace so an agent or human can verify whether the value can actually reach client-bundled code.

fallow security

Options

Output

Flag	Description
-f, --format <FORMAT>	Output format: human (default), json, or sarif
-q, --quiet	Suppress progress output
--summary	Show a compact human summary instead of per-finding detail
--ci	CI mode: equivalent to --format sarif --fail-on-issues --quiet
--fail-on-issues	Exit with code 1 if security candidates are found
--sarif-file <PATH>	Write SARIF output to a file in addition to the primary output
--legacy-envelope	Emit JSON without the top-level kind discriminator for one migration cycle

Scoping

Flag	Description
-r, --root <PATH>	Project root directory (default: current working directory)
-c, --config <PATH>	Path to config file (default: auto-detected)
--changed-since <REF> (alias: --base)	Only report candidates whose client anchor or trace hops touch files changed since a git ref
--diff-file <PATH>	Narrow candidates to added hunks on the client anchor or import trace. Secret-source hops use file-level retention because member-access spans are not yet stored. Use - to read from stdin.
--diff-stdin	Read the unified diff from stdin
-w, --workspace <PATTERNS>	Scope output to selected workspace packages
--changed-workspaces <REF>	Scope output to workspace packages touched since the given git ref

Performance

Flag	Description
--no-cache	Disable incremental caching
--threads <N>	Number of parser threads

Rule: client-server-leak

The detector starts at files with a top-level "use client" directive and walks static imports. It reports a candidate when the client boundary can reach a module that reads a non-public process.env value.

Public-by-convention env values are excluded:

Public prefix	Example
NODE_ENV	process.env.NODE_ENV
NEXT_PUBLIC_*	process.env.NEXT_PUBLIC_API_URL
VITE_*	process.env.VITE_API_URL
NUXT_PUBLIC_*	process.env.NUXT_PUBLIC_SITE_URL
REACT_APP_*	process.env.REACT_APP_API_URL
PUBLIC_*	process.env.PUBLIC_SITE_URL
GATSBY_*	process.env.GATSBY_SITE_URL
EXPO_PUBLIC_*	process.env.EXPO_PUBLIC_API_URL
STORYBOOK_*	process.env.STORYBOOK_THEME

Dynamic import() edges that the graph cannot follow are counted in the output as unresolved edge files. A clean finding list with a non-zero unresolved count is not a clean bill.

Rule: tainted-sink (catalogue)

A data-driven catalogue of syntactic sink candidates. Where client-server-leak is a graph-reachability rule, tainted-sink flags a call, member assignment, or tagged template that reaches a non-literal argument at a known dangerous sink. A fully literal argument never fires.

All catalogue findings carry kind: "tainted-sink" plus a category (the catalogue id) and a cwe number. The catalogue ships these categories:

Category	CWE	Sink shape
dangerous-html	79	innerHTML / outerHTML / insertAdjacentHTML / dangerouslySetInnerHTML
template-escape-bypass	79	template-engine SafeString(...) wrapping a non-literal value
command-injection	78	child_process exec / execSync / spawn / spawnSync (import-provenance gated)
code-injection	94	eval / vm.runInNewContext
dynamic-module-load	95	dynamic require(...)
sql-injection	89	query / execute with concatenation or interpolation, raw escape hatches (sql.raw, Prisma unsafe raw, Knex raw, sequelize.literal)
ssrf	918	fetch / got / ky / needle / request / axios / superagent / undici / http(s).request
path-traversal	22	path.join / path.resolve / node:fs path methods / route sendFile
header-injection	113	response setHeader / writeHead
open-redirect	601	res.redirect / location.href / location.assign / window.open
mass-assignment	915	source-backed Object.assign(target, source)
weak-crypto	327	runtime-selectable hash or cipher algorithm
deprecated-cipher	327	crypto.createCipher / createDecipher (no IV, MD5-based KDF)
insecure-randomness	338	crypto.pseudoRandomBytes(...)
unsafe-buffer-alloc	1188	Buffer.allocUnsafe / allocUnsafeSlow (uninitialized memory)
unsafe-deserialization	502	js-yaml load / node-serialize
prototype-pollution	1321	__proto__ writes and recursive merge sources
zip-slip	22	archive extraction destination paths
nosql-injection	943	Mongo / Mongoose query object passthrough
ssti	1336	template engine compile / render calls
xxe	611	XML parse calls
xpath-injection	643	xpath.select / select1 with a non-literal expression
webview-injection	94	react-native-webview injectJavaScript(...) / injectedJavaScript= (enabler-gated)
angular-trusted-html	79	Angular bypassSecurityTrust* (enabler-gated)
nextjs-open-redirect	601	Next.js redirect / permanentRedirect (enabler-gated)
dom-document-write	79	document.write / document.writeln
jquery-html	79	jQuery .html(value) (enabler-gated)
route-send-file	22	Express / Fastify / Hono route sendFile (enabler-gated)

These are deliberately conservative candidates: a non-literal argument is a signal to verify, not proof of a vulnerability. Fallow does not prove the value is attacker-controlled or reaches the sink unsanitized. Verification is the agent’s job.

Sink-shaped nodes whose callee cannot be resolved to a static path (dynamic dispatch, computed members, aliased bindings) are counted in the output as unresolved_callee_sites. As with client-server-leak, a clean finding list with a non-zero count is not a clean bill.

Enabling categories

Both tainted-sink and client-server-leak default to off and are surfaced only by fallow security (never under bare fallow or the audit gate). Scope which catalogue categories run with security.categories in config:

{
  "security": {
    "categories": {
      "include": ["dangerous-html", "command-injection"],
      "exclude": []
    }
  }
}

With both lists empty (the default) every category is active.

Suppression

Suppress a known false positive at file level. Each rule has its own token:

// fallow-ignore-file security-client-server-leak
"use client";

// fallow-ignore-file security-sink
const el = document.querySelector(".out");
el.innerHTML = render(userInput);

One security-sink token covers every catalogue category. Use suppression only after verifying that the value cannot reach the sink unsanitized, for example because the input is a trusted constant, server-only, or sanitized upstream.

JSON output

--format json emits a typed root envelope with kind: "security" unless --legacy-envelope is set.

{
  "kind": "security",
  "schema_version": "1",
  "security_findings": [],
  "unresolved_edge_files": 0,
  "unresolved_callee_sites": 0
}

Each finding includes kind, path, line, col, evidence, trace, and actions. tainted-sink findings additionally carry category (the catalogue id, for example "dangerous-html") and cwe (the category’s CWE number); client-server-leak findings omit both.

Examples

Basic scan

fallow security