SIS CLI
Explain & Trace Guide
Three read-only surfaces answer “why?” without changing scan output. Reach for them before reading runner/detector/policy code by hand.
| Question | Command |
|---|---|
| Why did this finding score / what is its evidence? | sis explain <input> <finding-id> |
| What finding kinds can format X produce? | sis explain-format <format> |
| Why was this file analysed as format X / why did a handler or detector run or not? | sis explain-detection <file> |
The structured verdict decision trace is available separately via sis scan <file> --decision-trace.
sis explain <input> <finding-id>
Expands one finding into evidence, metadata, object references, and lineage.
sis explain sample.docx <finding-id>
sis explain sample.pdf <finding-id> --config scan-config.toml
Finding IDs are content hashes, of the form sis-<64 hex> (e.g. sis-103db1f2254c…) — not
sequential identifiers. Get the exact ID from query JSON:
sis query sample.docx findings --json | jq -r '.result.findings[].id'
Then pass the full ID (no prefix matching). Because explain re-runs analysis, the ID is a
function of the scan conditions: if the originating scan used a non-default --config or runtime
policy, pass the same --config, or the ID will not resolve. On a miss, explain prints the
fingerprint and candidate set so you can see why.
sis explain-format <format>
Static enumeration of the finding kinds a format’s detectors can emit, with severity, confidence,
intent wiring, and a score-inert flag (rated/contracted kinds that feed no intent signal). Answers
“what can format X produce” without a sample.
sis explain-format pdf
sis explain-format lnk --json
--json returns format, format_specific_detectors, format_specific_kinds,
universal_detectors, universal_kinds. Format tags: pdf, html, hta, rtf, ooxml, one,
mht, ole, lnk, pe, elf, iso, zip, js, vbs, ps1, sh, wsf, css, … (see
sis docs formats).
sis explain-detection <file>
Runs a traced scan and renders the detection decision path: which root format was detected and why,
which handlers ran or were skipped (with the reason), and which detectors ran or were skipped
(scope_mismatch / fast_excluded / deep_only / timeout_truncated). Always recomputes; never
consults the scan cache.
sis explain-detection sample.bin
sis explain-detection sample.bin --json # { detected_root, file, steps }
Use it when a sample was analysed as the “wrong” format, or when a detector you expected did not run.
Related guides
sis docs investigate·sis docs query·sis docs verdict- (detector contract, coverage gaps)