fix: emit consistent defaults for FOSSA fields with no Socket source

Adds customRiskScore: None to vulnerability entries (FOSSA samples
include this field, sometimes null). Documents all gap fields and their
defaults in the module docstring. Locks the new key in EXPECTED_VULNERABILITY_KEYS.

Author: flowstate

socketsecurity/fossa_compat.py

@@ -1,3 +1,36 @@
+"""FOSSA-compat output shaping for `--legal-format fossa`.
+
+Builds two artifacts whose top-level shapes mirror real FOSSA pipeline outputs:
+
+  fossa-analyze.json  — wrapper of {project, vulnerability, licensing, quality},
+                        where `project` is the raw `fossa analyze --json` shape and
+                        the three arrays are FOSSA /api/v2/issues-shaped items.
+  fossa-sbom.json     — `fossa report --json attribution` shape: 5 top-level keys
+                        (copyrightsByLicense, deepDependencies, directDependencies,
+                        licenses, project).
+
+Fields without a Socket data source are emitted as documented defaults:
+
+  vulnerability[]:
+    epss               -> {score: None, percentile: None}
+    cvssVector         -> None
+    exploitability     -> None
+    cveStatus          -> None
+    published          -> None
+    containerLayers    -> {base: 0, other: 0}
+    customRiskScore    -> None
+    remediation.partialFixDistance, completeFixDistance -> None  (semver-distance TBD)
+    projects[].scannedAt, analyzedAt, firstFoundAt      -> None
+
+  dependencies[] (SBOM):
+    description, downloadUrl, projectUrl -> ""
+    hash, isGolang                       -> None  (always null in real FOSSA samples)
+    notes                                -> []
+
+  Top-level SBOM:
+    copyrightsByLicense -> {}  (would require parsing attribText for `Copyright (c)` lines)
+    licenses            -> {}  (would require bundling SPDX license body texts)
+"""
 from __future__ import annotations
 
 from typing import Any, Iterable, Optional
@@ -238,6 +271,7 @@ def _build_vulnerability_entry(
         "exploitability": props.get("exploitability"),
         "epss": _build_epss(props),
         "cpes": _extract_string_list(props.get("cpes")),
+        "customRiskScore": None,
     }
 
 

tests/unit/test_fossa_compat.py

@@ -13,6 +13,7 @@
     "containerLayers",
     "cpes",
     "createdAt",
+    "customRiskScore",
     "cve",
     "cveStatus",
     "cwes",
@@ -237,6 +238,46 @@ def test_analyze_payload_empty_diff_yields_empty_arrays():
     assert payload["quality"] == []
 
 
+def test_vulnerability_gap_fields_emit_known_defaults():
+    """Fields with no Socket data source emit documented null/empty defaults."""
+    from socketsecurity.fossa_compat import _build_vulnerability_entry
+    issue = Issue(
+        type="criticalCVE",
+        severity="high",
+        key="x",
+        pkg_type="pypi",
+        pkg_name="x",
+        pkg_version="1.0",
+        props={},
+    )
+    package = Package(
+        type="pypi",
+        name="x",
+        version="1.0",
+        id="pip+x$1.0",
+        score={},
+        alerts=[],
+        direct=True,
+    )
+    project = {"branch": "m", "id": "a$x", "project": "a", "projectId": "a", "revision": "x", "url": "u"}
+    entry = _build_vulnerability_entry(issue, package, project, index=1)
+    # Documented gap fields:
+    assert entry["epss"] == {"score": None, "percentile": None}
+    assert entry["cvssVector"] is None
+    assert entry["exploitability"] is None
+    assert entry["cveStatus"] is None
+    assert entry["published"] is None
+    assert entry["containerLayers"] == {"base": 0, "other": 0}
+    assert entry["remediation"]["partialFixDistance"] is None
+    assert entry["remediation"]["completeFixDistance"] is None
+    assert "customRiskScore" in entry
+    assert entry["customRiskScore"] is None
+    proj_entry = entry["projects"][0]
+    assert proj_entry["scannedAt"] is None
+    assert proj_entry["analyzedAt"] is None
+    assert proj_entry["firstFoundAt"] is None
+
+
 def test_vulnerability_version_ranges_sourced_from_socket_fields():
     """affectedVersionRanges/patchedVersionRanges come from Socket's singular fields, wrapped."""
     from socketsecurity.fossa_compat import _build_vulnerability_entry