# Joern query runner - how to invoke each script and read the output

These are the Cyclops v2 **dataflow-confirmation** scripts. Each takes a source path, builds (or

loads) a CPG, and runs `reachableByFlows` source→sink taint queries for one sink class.

> A `FINDING:` line is a **reachable dataflow path = HYPOTHESIS at SOURCE_CONFIRMED**. It is **never**

> a finding. Only the dynamic oracle (crash / popped shell / captured secret) promotes it. See

> `README.md` and `vault/00-doctrine/SEVERITY-GATE.md`.

## Binary

```

/opt/joern/joern-cli/joern        # symlinked to `joern` on the forge box

```

## Invoke one script against a target

```bash

joern --script /shared/projects/cyclops-v2/brain/joern-queries/<script>.sc \

      --param inputPath=/abs/path/to/target/src \

      --param projectName=mytarget        # optional; defaults per-script

```

`importCode` auto-detects the language (C/C++, Java/JVM, JS/TS, Python, Go, …). Point `inputPath` at

the repo root (or the relevant subtree). First run builds the CPG (slow on large trees); the

`projectName` workspace is cached under `~/.joern/workspace` for reuse.

### Scripts and what each targets

| Script | Languages | Sink class (SEVERITY-GATE family) |

|---|---|---|

| `c-memory-corruption.sc` | C/C++ | strcpy/memcpy/sprintf/alloca/int-overflow-alloc/array-index (F1 RCE, F7) |

| `deserialization-rce.sc` | Python / Java / JS | pickle/yaml/torch/joblib/ObjectInputStream/node-serialize (F1) |

| `command-injection.sc` | Py / JS / Java / C | os.system/subprocess(shell=True)/child_process/Runtime.exec/eval (F1) |

| `path-traversal.sc` | Py / JS / Java / C | open/sendFile/extractall(zip-slip)/fopen (F7) |

| `ssrf.sc` | Py / JS / Java / C | requests/axios/fetch/urllib/curl tainted URL (F7) |

| `template-injection.sc` | Py / JS / Java | render_template_string/Handlebars.compile/Freemarker (F1 SSTI) |

| `js-electron-rce.sc` | JS/TS | ipcMain handler arg / custom-protocol arg → exec/eval/shell (F1) |

## Reading the output

Each script prints machine-parseable lines on stdout:

```

CANDIDATE_SINK: <file>:<line> class=<class> code=<sink call source text>

CANDIDATE_SINKS[<class>]=<n>

FINDING: <file>:<line> class=<class> source=<tainted source code> sink=<sink code>

DATAFLOW_PATHS[<class>]=<n>

CONFIG_CANDIDATE: <file>:<line> class=<class> code=<...>     # electron only

SCAN_COMPLETE[<script>]

```

- **`CANDIDATE_SINK` / `CANDIDATE_SINKS[..]`** - the sink call exists in the code. No taint proven

  yet. This is the same signal the semgrep fast-pass gives; useful when dataflow under-resolves

  (e.g. Python dynamic dispatch). Feed to manual review / the oracle's "reachability unknown" queue.

- **`FINDING` / `DATAFLOW_PATHS[..]`** - Joern found a taint path from an untrusted source to the

  sink. The class suffix tells you the source set: `<-input` (IO/web/CLI calls), `<-argv` (C main),

  `<-io` / `<-params` (dynamic-lang IO calls vs entrypoint parameters), `<-ipc` / `<-proto` /

  `<-anyparam` (electron). `[metadata-reachable]` on an SSRF line means the path can reach a cloud

  metadata host - prioritize.

- **`DATAFLOW_PATHS[..]=0` with `CANDIDATE_SINKS[..]>0`** - sink present but no taint path resolved.

  Do **not** discard: dataflow can under-approximate (see limitations). Keep as a lower-priority

  candidate for the oracle.

### Parse to JSONL (example)

```bash

joern --script .../command-injection.sc --param inputPath=/t/src 2>/dev/null \

 | grep '^FINDING:' \

 | sed -E 's/^FINDING: ([^ ]+) class=([^ ]+) source=(.*) sink=(.*)$/{"loc":"\1","class":"\2","source":"\3","sink":"\4"}/' \

 > candidates.jsonl

```

Then hand `candidates.jsonl` to the orchestrator, which routes each to the dynamic oracle for proof.

## Batch all scripts over a target

```bash

TGT=/abs/path/to/target/src

for s in c-memory-corruption deserialization-rce command-injection path-traversal ssrf template-injection js-electron-rce; do

  echo "### $s"

  joern --script /shared/projects/cyclops-v2/brain/joern-queries/$s.sc --param inputPath="$TGT" 2>/dev/null \

    | grep -E '^(FINDING|DATAFLOW_PATHS|CANDIDATE_SINKS|SCAN_COMPLETE)'

done

```

(The C and electron scripts no-op cleanly on the wrong language - empty candidate sets - so running

the full sweep is safe; only the language-matching ones produce output.)

## Limitations / fallbacks (honesty)

- **Python / JS dynamic dispatch & aliasing.** `from pickle import loads as L; L(x)` or attribute

  calls through variables can hide the sink from `.name(...)`. The deser/cmdi/ssti/path scripts

  therefore match **both** the method name and the full call `.code` regex, and always print

  `CANDIDATE_SINK`. Inter-procedural taint through deep callback chains may still under-resolve -

  the candidate list is the safety net.

- **`shell=True` for subprocess** is not cheaply readable as a keyword value across Joern versions.

  We flag all subprocess sinks and add a `py-subprocess-shelltrue` refinement that looks for a

  literal `True`/`sh` argument near the call. Treat subprocess FINDINGs without confirmed

  `shell=True` as lower confidence.

- **Array-index OOB & pure integer overflow** are not first-class taint sinks; the C script

  approximates them via index operators and allocator size args. Lower confidence - the oracle's

  ASan run is the arbiter.

- **Electron inline arrow callbacks** may not always resolve via `MethodRef` in every Joern JS

  frontend version; `js-electron-rce.sc` adds an `<-anyparam` over-approximation source as a net.

- **Over-approximation is intentional.** More candidate paths = more hypotheses. The gate is the

  oracle, not the query. A noisy candidate list is acceptable; a missed sink is not.