Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,19 @@ level, not a CVSS score or an exploitability claim. Original status/confidence a
complete state remain properties; incomplete SARIF invocations are unsuccessful.
NDJSON ends with an explicit summary record, including empty results.

Each validated input also contributes a report envelope independently of result
rows: SARIF stores these under each matching tool/version run's
`properties.input_reports`; the NDJSON summary stores them in `reports`.
Each envelope retains public tool/version and profile, explicit completion,
`report_sha256` for the full canonicalized input, `evidence_sha256` for its
report-level metadata, and a privacy-projected `evidence` object. Canonical rule
snapshots and limitations therefore survive empty runs. Input filenames are never
published. Envelopes are sorted deterministically; 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;
retain the original private report to interpret hashed prose and field names.

Exit 0 means complete conversion with selected policy satisfied. `--fail-on`
findings, unknown or either returns 1 **after** successful output. Unknown includes
unsupported_runtime and source_discrepancy. Default none does not fail on findings.
Expand Down
2 changes: 1 addition & 1 deletion SHA256SUMS
Original file line number Diff line number Diff line change
@@ -1 +1 @@
a628d4f6b92a495e67a308bcd445e65fd08d532b5984446529e455f2d3dff071 scan_results_bridge.py
b4fe3135c6698d5830f5dcd75cf181397300964a98cbde1be8cedcec0b5c16f2 scan_results_bridge.py
28 changes: 24 additions & 4 deletions scan_results_bridge.py
Original file line number Diff line number Diff line change
Expand Up @@ -733,13 +733,26 @@ def normalize(report, profile, include_paths=False):
return deduplicate(normalized)


def to_sarif(rows, complete, completions=None):
def report_envelope(report, profile):
"""Project validated report metadata independently of its observation rows."""
tool = report['tool']
name, version = (tool['name'], tool['version']) if isinstance(tool, dict) else (tool, report['tool_version'])
evidence = {key: value for key, value in report.items() if key != 'results'}
return dict(schema_version='1.0', tool=name, tool_version=version,
input_schema=profile, complete=report['complete'],
report_sha256=digest(report), evidence_sha256=digest(evidence),
evidence=safe_evidence(evidence))


def to_sarif(rows, complete, completions=None, reports=None):
runs = []
groups = {}
for row in rows:
groups.setdefault((row['tool'],row['tool_version']),[]).append(row)
if completions:
for key in completions: groups.setdefault(key,[])
for report in reports or []:
groups.setdefault((report['tool'], report['tool_version']), [])
if not groups: groups[('scan-results-bridge',BRIDGE_VERSION)]=[]
for (name,version), records in sorted(groups.items()):
ids = sorted({r['rule_id'] for r in records})
Expand All @@ -754,7 +767,12 @@ def to_sarif(rows, complete, completions=None):
if row['location']:
result['locations']=[{'physicalLocation':{'artifactLocation':{'uri':quote(row['location']['path'],safe='/')},'region':{'startLine':row['location']['line']}}}]
results.append(result)
runs.append({'tool':{'driver':{'name':name,'version':version,'rules':rules}},'invocations':[{'executionSuccessful':completions.get((name,version),complete) if completions is not None else all(row['complete'] for row in records) if records else complete}], 'results':results})
run = {'tool':{'driver':{'name':name,'version':version,'rules':rules}},'invocations':[{'executionSuccessful':completions.get((name,version),complete) if completions is not None else all(row['complete'] for row in records) if records else complete}], 'results':results}
if reports is not None:
run['properties'] = {'input_reports': sorted(
[report for report in reports if (report['tool'], report['tool_version']) == (name, version)],
key=digest)}
runs.append(run)
return {'version':'2.1.0','$schema':SCHEMA_URI,'runs':runs}


Expand All @@ -781,12 +799,14 @@ def main(argv=None):
rows,complete,total=[],True,0
raw_count=0
completions={}
reports=[]
for path in args.input:
raw=_read_regular_file(path,4*1024**2)
total+=len(raw)
if total>16*1024**2: raise ContractError('Combined input byte limit')
value=json.loads(raw.decode('utf-8-sig'),object_pairs_hook=_unique_object,parse_constant=lambda _: (_ for _ in ()).throw(ContractError('Non-finite JSON')))
normalized=normalize(value,args.input_schema,args.include_relative_paths)
reports.append(report_envelope(value, args.input_schema))
raw_count+=len(value['results'])
if raw_count>10000:raise ContractError('Combined raw result limit')
rows.extend(normalized)
Expand All @@ -796,11 +816,11 @@ def main(argv=None):
if len(rows)>10000: raise ContractError('Combined result limit')
rows=deduplicate(rows)
if args.format=='sarif':
rendered=json.dumps(to_sarif(rows,complete,completions),ensure_ascii=False,sort_keys=True,indent=2,allow_nan=False)+'\n'
rendered=json.dumps(to_sarif(rows,complete,completions,reports),ensure_ascii=False,sort_keys=True,indent=2,allow_nan=False)+'\n'
else:
rendered=''.join(json.dumps(row,ensure_ascii=False,sort_keys=True,allow_nan=False)+'\n' for row in rows)
# Always include an explicit summary, including empty/incomplete conversions.
rendered+=json.dumps(dict(record_type='summary',schema_version='1.0',complete=complete,result_count=len(rows),observation_count=sum(row['occurrences'] for row in rows)),sort_keys=True)+'\n'
rendered+=json.dumps(dict(record_type='summary',schema_version='1.0',complete=complete,result_count=len(rows),observation_count=sum(row['occurrences'] for row in rows),reports=sorted(reports,key=digest)),sort_keys=True)+'\n'
if len(rendered.encode('utf-8'))>32*1024**2: raise ContractError('Output byte limit')
if args.output:
fd,name=tempfile.mkstemp(prefix='.bridge-',dir=args.output.parent)
Expand Down
83 changes: 83 additions & 0 deletions test_report_envelopes.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
"""Synthetic empty-report provenance regressions; no external access."""
import copy
import json
from pathlib import Path
import tempfile
import unittest
import test_bridge
from test_bridge import report


class ReportEnvelopeTests(unittest.TestCase):
cli = test_bridge.BridgeTests.cli
def convert(self, reports, fmt):
with tempfile.TemporaryDirectory() as directory:
args = []
for index, value in enumerate(reports):
path = Path(directory)/f'input-{index}.json'
path.write_text(json.dumps(value), encoding='utf-8')
args.extend(['--input', str(path)])
return self.cli(*args, '--format', fmt)

def envelopes(self, text, fmt):
if fmt == 'ndjson':
return json.loads(text.splitlines()[-1])['reports']
return [entry for run in json.loads(text)['runs']
for entry in run['properties']['input_reports']]

def test_empty_snapshot_and_limitation_changes_survive_both_formats(self):
first = report(); first['results'] = []
for field in ('snapshot', 'limitations'):
other = copy.deepcopy(first)
if field == 'snapshot': other['rules']['snapshot_id'] = 'synthetic-2'
else: other['limitations'] = ['Synthetic secret limitation SECRET']
for fmt in ('sarif', 'ndjson'):
code, left, _ = self.convert([first], fmt)
other_code, right, _ = self.convert([other], fmt)
self.assertEqual((0, 0), (code, other_code))
self.assertNotEqual(left, right)
self.assertNotEqual(self.envelopes(left, fmt), self.envelopes(right, fmt))
self.assertNotIn('SECRET', right)
self.assertNotIn('synthetic-2', right)

def test_multiple_empty_reports_are_attributable_deterministic_and_private(self):
first = report(); first['results'] = []
other = copy.deepcopy(first)
other['rules']['snapshot_id'] = 'synthetic-2'
other['limitations'] = ['https://private.invalid?token=SECRET']
for fmt in ('sarif', 'ndjson'):
code, text, _ = self.convert([first, other], fmt)
self.assertEqual(0, code)
entries = self.envelopes(text, fmt)
self.assertEqual(2, len(entries))
self.assertEqual(2, len({entry['report_sha256'] for entry in entries}))
self.assertTrue(all(entry['complete'] for entry in entries))
self.assertEqual(text, self.convert([other, first], fmt)[1])
self.assertEqual(text, self.convert([first, other], fmt)[1])
for secret in ('SECRET', 'private.invalid', 'input-0', 'input-1'):
self.assertNotIn(secret, text)

def test_empty_incomplete_envelope_preserves_exit_and_per_tool_completion(self):
first = report(); first['results'] = []
other = copy.deepcopy(first); other['complete'] = False
other['tool']['name'] = 'other-check'
for fmt in ('sarif', 'ndjson'):
code, text, _ = self.convert([first, other], fmt)
self.assertEqual(2, code)
entries = {entry['tool']: entry for entry in self.envelopes(text, fmt)}
self.assertTrue(entries['synthetic-check']['complete'])
self.assertFalse(entries['other-check']['complete'])
if fmt == 'sarif':
for run in json.loads(text)['runs']:
name = run['tool']['driver']['name']
self.assertEqual([entries[name]], run['properties']['input_reports'])
self.assertEqual(entries[name]['complete'], run['invocations'][0]['executionSuccessful'])

def test_duplicate_inputs_retain_report_multiplicity(self):
value = report(); value['results'] = []
for fmt in ('sarif', 'ndjson'):
code, text, _ = self.convert([value, value], fmt)
self.assertEqual(0, code)
entries = self.envelopes(text, fmt)
self.assertEqual(2, len(entries))
self.assertEqual(entries[0], entries[1])
14 changes: 13 additions & 1 deletion tools/validate_sarif.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,4 +14,16 @@
rows=c.normalize(report(status,source),'contract-v1.0',True)
validator.validate(c.to_sarif(rows,True))
validator.validate(c.to_sarif([],False))
print('Five synthetic SARIF variants validated against bundled official OASIS schema.')
first=report();first['results']=[]
second=report();second['results']=[];second['complete']=False
second['rules']['snapshot_id']='synthetic-2'
second['limitations']=['Synthetic private limitation']
for reports in ([first], [second], [first,second], [report(source=True),first]):
rows=[];completions={};envelopes=[]
for value in reports:
rows.extend(c.normalize(value,'contract-v1.0',True))
identity=(value['tool']['name'],value['tool']['version'])
completions[identity]=completions.get(identity,True) and value['complete']
envelopes.append(c.report_envelope(value,'contract-v1.0'))
validator.validate(c.to_sarif(rows,all(v['complete'] for v in reports),completions,envelopes))
print('Nine synthetic SARIF variants validated against bundled official OASIS schema.')
Loading