SIS CLI

Scan & Automation Guide

sis scan runs analysis for a file or directory. It records findings, decisions and analysis limits; a successful command or a Clean verdict does not certify universal safety.

One file

sis scan sample.html
sis scan sample.html --analysis-profile deep --format json --emit json=report.json

--analysis-profile quick|standard|deep|strict selects breadth/parser presets. Depth is separate from permission to execute sandboxed script and from compiled providers; see sis docs scan-config.

Machine output and side files

--format selects stdout: text, json, jsonl, jsonl-findings or sarif. JSON is the report object. Directory JSONL contains per-input summary entries; single-file JSONL contains bare finding records. Directory findings-only JSONL adds path/finding envelopes. These shapes are not interchangeable with full report objects for correlation/diff readers. Diagnostics go to stderr. Preserve them when investigating partial analysis or a failed command.

sis scan sample.html --format json --emit json=report.json --emit sarif=report.sarif
sis scan sample.html --format json --emit workspace=workspace.json --emit semantic-snapshot=snapshot.json

--emit KIND=PATH writes additional artefacts from the same run. A workspace or semantic snapshot is a projection with its own schema, not an interchangeable report for every query consumer. The report JSON itself carries a versioned semantic_snapshot section (typed evidence and interpretation accounting) and a top-level source_report_id that binds the section to the report; the standalone snapshot file is built from the same source and is the interchange form. sis docs verdict explains the coverage and evidence fields.

CI gate, with output retained

status=0
sis scan sample.html --format json --emit sarif=report.sarif --fail-on suspicious > report.json || status=$?
case "$status" in
  0) echo 'Scan completed without the requested malware gate firing.' ;;
  1) echo 'Gate or pre-analysis failure; inspect report.json and stderr.' >&2 ;;
  *) echo 'Usage or execution failure; inspect stderr.' >&2 ;;
esac
exit "$status"

--fail-on anomalous|suspicious|malicious is a malware-verdict gate for files or directories. The JSON/SARIF recipe shown here writes its requested outputs before a gate returns exit 1. Directory findings-only output currently returns before JSON/SARIF side files are written; do not combine that stdout mode with those side files or assume they exist. Other unverified output combinations require checking their actual artefacts. A requested gate returns exit 1. Errors returned by the normal single-file analysis path use exit 3, but pre-analysis setup and streaming failures can also use exit 1; usage errors normally exit 2. Exit 1 alone therefore does not prove a detection or gate trip. A wrapper must also check that valid report artefacts exist; missing output is not a clean scan. There is no universal numeric exit ladder across all commands.

sis scan sample.html --format json --fail-on-axis ingest-unsafe

This separate gate trips on hidden_instruction and poisoning_likely. It does not refuse indeterminate or instruction_bearing outcomes. It also ignores directive-like phrasing in visible prose, which is reported only as a non-verdict fact in facts; the analyser detects hidden or transformed instruction carriers and does not judge the meaning of visible text, and a clean result is not proof of absence. Use the strict assessment recipe in sis docs assess when uncertainty must block ingestion.

Directory scan and follow-up

sis scan intake --glob '*.html' --format jsonl > summaries.jsonl
sis query findings --path intake --glob '*.html' --format jsonl

For scanning, the positional accepts a directory; querying uses --path. Keep per-file failures and coverage limits in the batch records. A directory run returns exit 1 when any recorded member label trips either requested gate; summary/side output is retained. Member errors/timeouts do not independently trip these label gates; a partial timeout report can retain labels that do trip them. Inspect errors, partial reports and missing labels even when the directory exits 0. This aggregate gate still does not refuse indeterminate ingestion risk.

sis scan intake --glob '*.html' --format json --emit json=batch.json --fail-on-axis ingest-unsafe

Inspect per-member labels/errors and stderr counts to distinguish an aggregate gate from execution failures. A directory exit 0 is not proof that all content or uncertainty was measured. sis docs batch explains full-report capture for correlation and comparison.

Read a saved result

sis query findings --from-report report.json --format json
sis explain verdict --from-report report.json --json
sis query '**' --from-report report.json --format json

These projections read the saved report without rerunning detectors. A missing report exits 4 (FILE_READ_ERROR), an unparseable report exits 2 (REPORT_PARSE_ERROR), a report whose embedded analysis artefact is absent, unavailable, tampered or unbound exits 2 (PERSISTED_ANALYSIS_REFUSED; a report saved by an older build has no semantic_snapshot section and must be rescanned), and an unsupported projection also exits 2 (UNSUPPORTED_IN_REPORT_MODE), told apart by .result.error_code (the refusal is named in .result.context.refusal); each still prints its structured error envelope on stdout, so $? and .result.error_code agree. For a findings projection, this Bash check rejects an error envelope:

set -o pipefail
sis query findings --from-report report.json --format json | jq -e '.result | type == "array"'

Live queries and sis report analyse again; they are not replay of that saved run. Byte/text terminals and PDF object queries need a live context. policy.active describes current process policy, even in report mode; read the saved report’s policy field for its original provenance. See sis docs query.