diff --git a/README.md b/README.md index cfb1260..d1a7317 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/SHA256SUMS b/SHA256SUMS index 92cbbc8..1a1b024 100644 --- a/SHA256SUMS +++ b/SHA256SUMS @@ -1 +1 @@ -a628d4f6b92a495e67a308bcd445e65fd08d532b5984446529e455f2d3dff071 scan_results_bridge.py +b4fe3135c6698d5830f5dcd75cf181397300964a98cbde1be8cedcec0b5c16f2 scan_results_bridge.py diff --git a/scan_results_bridge.py b/scan_results_bridge.py index 8cfa2fe..94336a0 100644 --- a/scan_results_bridge.py +++ b/scan_results_bridge.py @@ -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}) @@ -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} @@ -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) @@ -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) diff --git a/test_report_envelopes.py b/test_report_envelopes.py new file mode 100644 index 0000000..1deb5be --- /dev/null +++ b/test_report_envelopes.py @@ -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]) diff --git a/tools/validate_sarif.py b/tools/validate_sarif.py index 5d395c7..2fd86b6 100644 --- a/tools/validate_sarif.py +++ b/tools/validate_sarif.py @@ -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.')