Add legal artifact presets, FOSSA-compatible outputs

[lelia]

Summary

Introduces a compliance-oriented --legal workflow to socketcli and an opt-in --legal-format fossa mode for producing FOSSA-compatible artifact shapes.

Changes

The --legal workflow enables license generation and default artifact output for:

• socket-report.json
• socket-summary.txt
• socket-report-link.txt
• socket-sbom.json
• socket-license.json

The new --legal-format fossa mode adapts those outputs to match the structural shapes the real FOSSA CLI emits — captured from a UiPath Azure DevOps FOSSA pipeline as reference (CE-199):

• fossa-analyze.json — the composed wrapper FOSSA pipelines actually produce: {project, vulnerability[], licensing[], quality[]}. The project sub-object is the 6-key fossa analyze --json shape with id formatted as <projectLocator>$<revision>. vulnerability[] items follow the /api/v2/issues shape (28 fields including source, depths, statuses, projects[], remediation, metrics, epss, etc.).
• fossa-sbom.json — the fossa report --json attribution shape: 5 top-level keys (copyrightsByLicense, deepDependencies, directDependencies, licenses, project). Per-Dependency entries are the 14-key FOSSA attribution shape, with attribution text sourced from Package.licenseAttrib[].attribText, direct/deep partitioning by Package.direct, and dependencyPaths as <ancestor> > <package> chains computed from topLevelAncestors.
• FOSSA-like default filenames: fossa-analyze.json, fossa-test.txt, fossa-link.txt, fossa-sbom.json. The Socket-side --sbom-file slot is suppressed in fossa mode (the FOSSA "SBOM" artifact is the attribution payload).
• Consistent JSON formatting: both JSON outputs written with indent=2.

Adds

• Explicit file output support for JSON reports, summary text, and report links
• Hardened legal artifact generation for sparse scan paths so artifact creation completes safely even when SBOM/package data is incomplete

Documented gaps

Fields with no Socket data source are emitted as consistent documented defaults (see module docstring at top of socketsecurity/fossa_compat.py). Examples: vulnerability[].epss, cvssVector, exploitability, cveStatus, published, customRiskScore, project timestamps, semver-distance labels; per-dependency description, downloadUrl, projectUrl, hash, isGolang, notes, otherLicenses; top-level copyrightsByLicense and licenses body-text map. partialFix and completeFix collapse to the same value since Socket has only one fix-version concept.

Testing

• Unit test coverage for:
  • --legal and --legal-format defaults
  • FOSSA-compatible analyze report shape (top-level keysets, vulnerability/licensing/quality item shapes)
  • FOSSA attribution shape (5 top-level keys, 14-field per-Dependency entries, direct/deep partitioning, dependency-path computation, license attribution sourcing with fallback chain)
  • Sparse-data scenarios
• Structural parity tests (tests/unit/test_fossa_parity.py) that load real FOSSA artifacts captured from the UiPath pipeline (committed to tests/fixtures/fossa/) and assert our builder output's keysets match at every level (top-level, project, dependency). These guard against future drift from FOSSA's actual shape.
• 232 unit tests passing.

Test plan

• Unit tests pass (uv run pytest tests/)
• Structural parity tests assert keyset equality against real FOSSA fixtures
• Manual end-to-end against a real Socket scan with --legal-format fossa and confirm outputs satisfy the customer's validation pipeline gate (file exists, non-empty, parseable JSON for the two JSON files)

[github-actions]

🚀 Preview package published!

Install with:

pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple socketsecurity==2.2.89.dev4

Docker image: socketdev/cli:pr-199

[github-actions]

❌ Version Check Failed

Please increment...

[lelia]

Eric Hibbs (@flowstate) review notes:

• resolve the existing merge conflicts (pyproject.toml, uv.lock, socketsecurity/__init__.py)
• sanitize any customer references/artifacts (eg. tests/fixtures/fossa/README.md‎)
• the --legal-format fossa format only includes new_alerts (plus unchanged_alerts with --strict-blocking enabled) which could under-represent full findings compared to the typical FOSSA pipeline
  • affected areas: _iter_selected_issues(), build_fossa_report_payload())
  • this could create a parity risk for FOSSA users expecting project-wide issue sets
• README phrasing doesn't match the FOSSA SBOM shape - the code uses directDependencies / deepDependencies instead of a single dependencies key (L159 of README)
  • affected areas: fossa_compat.py and test_fossa_parity.py
  • this could cause confusion for users integrating against the schema