audit, advisories and doctors/setup work

datasets/golden-pairs/README.md

@@ -0,0 +1,45 @@
+# Golden Pairs Corpus
+
+Golden pairs are curated binary pairs (original vs patched) used to validate binary-diff logic.
+Binaries are stored outside git; this folder tracks metadata, hashes, and reports only.
+
+## Layout
+
+```
+datasets/golden-pairs/
+  index.json
+  CVE-2022-0847/
+    metadata.json
+    original/
+      vmlinux
+      vmlinux.sha256
+      vmlinux.sections.json
+    patched/
+      vmlinux
+      vmlinux.sha256
+      vmlinux.sections.json
+    diff-report.json
+    advisories/
+      USN-5317-1.txt
+```
+
+## File Conventions
+
+- `metadata.json` follows `docs/schemas/golden-pair-v1.schema.json`.
+- `index.json` follows `docs/schemas/golden-pairs-index.schema.json`.
+- `*.sha256` contains a single lowercase hex digest, no prefix.
+- `*.sections.json` contains section hash output from the ELF hash extractor.
+- `diff-report.json` is produced by `golden-pairs diff`.
+
+## Adding a Pair
+
+1. Create a `CVE-YYYY-NNNN/metadata.json` with required fields.
+2. Fetch binaries via `golden-pairs mirror CVE-...`.
+3. Generate section hashes for each binary.
+4. Run `golden-pairs diff CVE-...` and review `diff-report.json`.
+5. Update `index.json` with status and summary counts.
+
+## Offline Notes
+
+- Use cached package mirrors or `file://` sources for air-gapped runs.
+- Keep hashes and timestamps deterministic; always use UTC ISO-8601 timestamps.