Offline conversion of CompleteTech security checker JSON reports into SARIF 2.1.0 or NDJSON, with a privacy-preserving default projection.
- 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
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.
- 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.
jsonschemais needed only for the optional development check of emitted SARIF.
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 --helpKeep unrelated reports out of commits.
The tool uses supplied local evidence only. It does not contact targets or execute the software being assessed.
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]]
| 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 defaults to stdout. An existing
--outputfile is refused unless--forceis 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.
| 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.
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:
- Published tool versions must use the public numeric
major.minor.patchformat, including canonical reports and empty runs. Free-form version labels are rejected before output because they can contain private metadata. - Every result must carry
exploitability: not_tested. Threat metadata is kept separate from it, and no input status becomes confirmed exploitation. - Confidence is retained when its vocabulary matches; otherwise it is
unknown. - The original evidence receives a deterministic digest for local reconciliation.
- Canonical version assessments are retained explicitly.
- Legacy adapters validate the consumed envelope, status, exploitability and version fields. They do not claim validation of every unused legacy report field.
Output is deterministic: results, rules and report envelopes are ordered stably, no timestamp is generated, and all output is JSON escaped. Non-finite numbers, including overflowing JSON exponents, fail before publication.
- One run per tool and version, each with its own combined completion state. This includes tools whose input reports have no result rows. An incomplete run is marked with an unsuccessful invocation.
- Triage level:
warningforpotentially_affected,precondition_presentandlikely_exposed;noteforunknown, unsupported, fixed or mitigated observations. This is a triage level, not a CVSS score or an exploitability claim. - Original status, confidence and completion state remain in result properties.
- Source locations are emitted only when qualifying evidence exists and paths are opted in. Valid Unicode paths are percent-encoded in URIs.
- Each result carries a
checkerIdentity/v1partial fingerprint.
One JSON object per observation, followed by an explicit summary record, which
is also written for empty or incomplete conversions. The summary includes
complete, result_count, observation_count and the report envelopes
(reports).
Each validated input also contributes a report envelope independently of its result
rows. SARIF stores these under each matching run's properties.input_reports; the
NDJSON summary stores them in reports.
An envelope retains:
- the public tool, version and input profile;
- explicit completion state;
report_sha256, a digest of the full canonicalized input;evidence_sha256, a digest of the report-level metadata; and- a privacy-projected
evidenceobject.
Canonical rule snapshots and limitations therefore survive empty runs. Input filenames are never published. Repeated identical inputs remain repeated, and differing inputs remain attributable by digest. These are content identities, not authenticity or deployed-patch attestations. Report metadata uses the same structural privacy projection as observation evidence.
Fingerprints combine tool, rule, private asset identity, component instance and reported source location. They use the stable component name, not its version/build assessment, and exclude status, run time and input ordering. When reported, same-line source candidate ordinals and hashed input-artifact identities disambiguate fingerprints without inventing source columns.
- Identity is preserved across status changes at the same location.
- Moving a line or changing an asset identifier changes the fingerprint. This is not semantic code matching.
- Exact projected duplicates collapse into one row with an
occurrencescount. - Conflicting statuses or evidence remain separate observations. Full component metadata, sources and canonical rule snapshot metadata are part of the projected evidence, so different snapshots and conflicts do not deduplicate.
- Corroborating source records at the same path and line retain one unambiguous location.
- The raw combined-result limit applies before deduplication.
Default exports use a structural privacy projection. Asset labels, URLs, paths, arbitrary object keys, evidence prose, versions, secrets and original remediation text are replaced by SHA-256 identifiers. Known evidence kinds and states, confidence, booleans, numbers and uncertainty survive, as do public tool and rule identifiers, which SARIF requires. Exported remediation directs the reader to the original private report and vendor guidance.
This deliberately omits raw prose rather than claiming a regex can remove every possible credential. Retain the original report securely to interpret the projected evidence, including hashed prose and field names. Hashes are linkable and dictionary-guessable; they are not anonymous identifiers. Canonical report limitations are included in the privately projected evidence digest.
Relative source paths are omitted unless --include-relative-paths is set. That
switch explicitly permits publishing those reported paths, so review filenames for
secrets before enabling it.
- Only bounded relative paths with integer source lines from source evidence qualify.
- Inventory paths, network URLs and missing locations never produce fabricated code locations.
- Absolute paths, drive or URL schemes, backslashes, empty or traversal components and control characters are rejected as locations.
- Numeric observations, including reported line numbers in projected evidence, remain visible even without the opt-in; publishing the path still requires it.
| Limit | Value |
|---|---|
| Input files per invocation | 20 |
| Size per input / combined inputs | 4 MiB / 16 MiB |
| JSON nesting depth | 40 |
| JSON nodes per input | 250,000 |
| Characters per string | 16,384 |
| Combined results | 10,000 |
| Output size | 32 MiB |
Exceeding a limit fails with exit 2; nothing is silently truncated. Local inputs and output directories should be stable and controlled by the operator. This is not a service hardened against a concurrent hostile filesystem.
- Statuses describe reported metadata, not tested behavior.
exploitabilitystaysnot_testedand no result confirms exploitation or safety. fixed_version_reportedrecords what a checker reported. It is not a verified deployed patch.unknown,unsupported_runtimeandsource_discrepancypreserve uncertainty; they are not clean results. Treat them as needing review, for example with--fail-on unknown.- Hashes and fingerprints are content identities, not proof of authenticity.
- Schema validation checks SARIF format only. It does not prove GitHub ingestion or live code-scanning display, and no upload or production acceptance was performed.
Run the tests (local only, synthetic reports only, no third-party dependencies):
python -m unittest -v
python scan_results_bridge.py --helpThe unmodified official OASIS schema is bundled under schemas/ with its original
license terms (OASIS-LICENSE.md). An optional
development check uses jsonschema. CI runs it locally against the bundled schema
for source, inventory-only, Unicode, findings, unknown, and empty or incomplete
runs. Tests fetch no remote schema references.
python -m pip install jsonschema==4.25.1
python tools/validate_sarif.pySources: OASIS SARIF schema, GitHub SARIF support.
Read AGENTS.md, CONTRIBUTING.md and
SECURITY.md first. Keep the tool standalone, standard-library only
and offline, and preserve uncertainty, bounds, the privacy projection, stable
fingerprints, input protection and atomic output. Before merge, run
python -m unittest -v, python scan_results_bridge.py --help and
git diff --check; GitHub Copilot review and exact-head hosted CI are required.
Report vulnerabilities privately as described in SECURITY.md, using synthetic reproductions only.
Code is available under AGPL-3.0 or a separate commercial license from
CompleteTech LLC; see LICENSING.md. The bundled OASIS SARIF schema
keeps its upstream license under schemas/.
No logo or trademark license is granted by the code license. The CompleteTech LLC
names, logos and repository artwork under docs/images/ remain brand assets;
see BRAND_ASSETS.md.
