scan-results-bridge

Offline conversion of CompleteTech security checker JSON reports into SARIF 2.1.0 or NDJSON, with a privacy-preserving default projection.

Contents

• Overview
• Requirements
• Quick start
• Offline workflow
• Usage
• Input contracts
• Output formats
• Privacy and evidence
• Limits
• Interpreting results
• Development
• Contributing and security
• License and brand assets

Overview

scan_results_bridge.py reads existing local JSON reports and writes SARIF 2.1.0 or NDJSON. It is optional: individual checkers do not depend on it.

• Offline. It never scans targets, executes code, loads packages, reads credentials, or uploads data. No HEC/syslog transport or credential configuration is implemented.
• Metadata only. It converts supplied local evidence. Every observation keeps exploitability: not_tested; nothing it emits confirms exploitation, and a reported fixed version is never a verified deployed patch or a safety claim.
• Private by default. Asset labels, URLs, paths, evidence prose and similar values are replaced by SHA-256 identifiers unless you opt in to publishing relative source paths. See Privacy and evidence.
• Fails closed. Unsupported tools or versions and malformed or contradictory input exit 2 rather than producing a partial conversion.

Requirements

• Python 3.10 or later (CI runs 3.10 and 3.14 on Linux, Windows and macOS).
• Nothing to install: one standalone file, standard library only.
• jsonschema is needed only for the optional development check of emitted SARIF.

Quick start

The bundled example is synthetic.

# Convert a report to SARIF (the output file must not already exist)
python scan_results_bridge.py --input examples/report.json --format sarif --output report.sarif

# NDJSON to stdout, publishing reported relative source paths
python scan_results_bridge.py --input examples/report.json --format ndjson --include-relative-paths

# A legacy node2shell-check report (placeholder file name), failing CI on findings or unknowns
python scan_results_bridge.py --input node-report.json --input-schema node2shell-v1 --fail-on either

# Run the tests and show all options
python -m unittest -v
python scan_results_bridge.py --help

Keep unrelated reports out of commits.

Offline workflow

The tool uses supplied local evidence only. It does not contact targets or execute the software being assessed.

Usage

python scan_results_bridge.py --input REPORT [--input REPORT ...]
    [--input-schema PROFILE] [--format {sarif,ndjson}] [--include-relative-paths]
    [--fail-on {none,findings,unknown,either}] [--output FILE [--force]]

Options

Option	Meaning
--input FILE	Required. An existing report JSON file; repeat for up to 20 inputs.
--input-schema PROFILE	Input contract; default contract-v1.0. One profile applies to every input in the invocation.
--format {sarif,ndjson}	Output format; default sarif.
--include-relative-paths	Opt in to publishing valid reported source paths. Inventory-derived locations are never published. See Privacy and evidence.
--fail-on {none,findings,unknown,either}	Policy exit code 1 after successful output; default none. See Exit codes.
--output FILE	Write to a new file instead of stdout.
--force	Replace an existing --output file atomically. Never replaces an input or the checker itself.

Output and interruption

• Output defaults to stdout. An existing --output file is refused unless --force is given.
• The checker and every input are protected from being overwritten, including through symlink or hardlink aliases, even with --force.
• The whole report is rendered before anything is published, and file output is published atomically.
• Malformed, unsupported or over-limit input is rejected before any output.
• Interruption exits 130 and the output is not retried. Interrupted stdout, or an interrupt at the file commit boundary, may leave an incomplete or indeterminate publication; verify or discard it.

Exit codes

Code	Meaning
0	Conversion succeeded, every input reported complete: true, and the selected --fail-on policy is satisfied.
1	Conversion succeeded and was written, but --fail-on matched.
2	Operational failure: malformed, unsupported or over-limit input, protected or unwritable output, or an input that reports complete: false. An incomplete input is still converted and written before the exit, and is marked incomplete in the output.
130	Interrupted.

--fail-on policies:

Policy	Exit 1 when the output contains
none (default)	Never.
findings	potentially_affected, precondition_present or likely_exposed.
unknown	unknown, unsupported_runtime or source_discrepancy.
either	Either of the above.

A policy exit never suppresses results. Exit code 2 takes precedence over 1. Operational failures are distinct from assessment results.

Input contracts

Select the profile explicitly with --input-schema; one profile applies to all inputs in an invocation. Unsupported tools or versions and malformed or contradictory canonical evidence fail closed with exit 2. The canonical validator is bundled from Sharp's common contract under the same code license; no installed shared package is required.

Profile	Input
contract-v1.0 (default)	Complete schema 1.0 object with tool/rules/results, including semantic evidence-reference validation
node2shell-v1	Legacy unversioned node2shell-check tool_version 1.0.0 JSON; named adapter only, not a universal schema
copyescape-v1.1	copyescape-check schema_version 1.1
vm2-v1.1	vm2-nesting-check report_schema_version 1.1
simplegit-v1.1	simplegit-rce-check report_schema_version 1.1
atlassian-v1	atlassian-cve-2026-21589-check integer schema_version 1
flowise-v1	flowise-cve-2026-69254-check integer schema_version 1; version_status maps to normalized status

Common to all profiles: