Add Neo4j output writer for Surfactant SBOM exports

[willis89pr]

Summary

This PR adds a built-in Neo4j output writer that exports Surfactant/CyTRICS SBOM data into a Neo4j graph database. It also adds a standalone import script for loading an existing SBOM JSON directly into Neo4j.

The writer exports logical SBOM relationships separately from filesystem topology. Logical relationships come from sbom.graph, while filesystem/path topology comes from sbom.fs_tree; mirrored path/symlink edges in sbom.graph are filtered out to avoid duplicate Neo4j relationships.

This PR also improves generate-time logging around input/output plugin selection, filtered logical relationship counts, total graph counts, filesystem tree counts, and SBOM output writing.

What changed

• Added surfactant/output/neo4j_writer.py

  • Implements a neo4j output plugin.
  • Exports SBOM data into Neo4j using stable node and relationship IDs.
  • Creates/uses a uniqueness constraint on :SBOMEntity(id) to make repeated imports of the same content idempotent.
  • Exports logical relationships from sbom.graph.
  • Filters path nodes and symlink/path edges mirrored into sbom.graph so filesystem topology is not exported twice.
  • Exports filesystem topology from sbom.fs_tree.
  • Writes a JSON import summary to the requested output file.
  • Separates logical_graph_edges, fs_tree_edges, and installed_at_edges in the import summary.
  • Supports batching through NEO4J_BATCH_SIZE.
  • Validates NEO4J_BATCH_SIZE so invalid, zero, or negative values fail clearly.

• Added scripts/load_sbom_to_neo4j.py

  • Provides a standalone CLI for importing an existing CyTRICS SBOM JSON file into Neo4j.
  • Reads Neo4j connection settings from environment variables.
  • Supports --database and --batch-size CLI options.
  • Validates --batch-size so zero or negative values fail clearly.
  • Handles a missing Neo4j Python driver with a clear install message.
  • Prints an import summary after completion.

• Registered the Neo4j writer in surfactant/plugin/manager.py

  • Makes the writer available through the normal Surfactant plugin registration path.

• Improved logging in surfactant/cmd/generate.py

  • Logs selected input/output plugins.
  • Logs whether a new SBOM is created or an existing SBOM is loaded.
  • Logs software counts, filtered logical relationship counts, total graph counts, and filesystem tree counts before writing.
  • Logs when SBOM output writing starts and finishes.

Neo4j graph model

The writer maps SBOM data into these node labels:

• :SBOM:SBOMEntity
• :Software:SBOMEntity
• :Path:SBOMEntity
• :Hash:SBOMEntity
• :GraphEntity:SBOMEntity

Logical SBOM relationships from sbom.graph are written using sanitized NetworkX edge keys as Neo4j relationship types.

Filesystem/path edges mirrored into sbom.graph are intentionally skipped during logical relationship export. sbom.fs_tree is treated as the authoritative source for filesystem topology.

Filesystem relationships from sbom.fs_tree are written as:

• FS_CONTAINS
• SYMLINK
• HAS_CONTENT_HASH

Software install-location relationships are written as:

• INSTALLED_AT

Each node and relationship includes stable IDs derived from the SBOM UUID and source graph data, so imports can be safely re-run without creating duplicate graph entities.

Usage

Using the output plugin through surfactant generate:

export NEO4J_URI=neo4j://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=your-password

surfactant generate \
  --skip_gather \
  --skip_relationships \
  --output_format neo4j \
  empty-context.json \
  neo4j-import-summary.json \
  existing-sbom.json

Using the standalone loader:

export NEO4J_URI=neo4j://localhost:7687
export NEO4J_USER=neo4j
export NEO4J_PASSWORD=your-password

python scripts/load_sbom_to_neo4j.py existing-sbom.json

Optional environment variables:

export NEO4J_DATABASE=neo4j
export NEO4J_BATCH_SIZE=1000

The standalone loader also supports equivalent CLI options:

python scripts/load_sbom_to_neo4j.py \
  --database neo4j \
  --batch-size 1000 \
  existing-sbom.json

Testing

• Verified Python syntax with:

python -m py_compile \
  scripts/load_sbom_to_neo4j.py \
  surfactant/cmd/generate.py \
  surfactant/plugin/manager.py \
  surfactant/output/neo4j_writer.py

• Ran an end-to-end import against a local Neo4j instance through the neo4j output writer:

surfactant --log-level INFO generate \
  --skip_gather \
  --skip_relationships \
  --output_format neo4j \
  . \
  neo4j-import-summary.json \
  <existing-sbom.json>

• Verified the large-SBOM import completed and Neo4j database counts matched the prepared import rows:

software=58491
paths=80438
hashes=58491
nodes=197421
relationships=293577
logical_graph_edges=7970
fs_tree_edges=152719
installed_at_edges=74397
database_nodes_for_bom=197421
database_relationships_for_bom=293577

• Verified logical graph edges were exported separately from filesystem topology:

USES=1977
CONTAINS=5993
logical_graph_edges=7970

FS_CONTAINS=76383
HAS_CONTENT_HASH=72041
SYMLINK=4295
fs_tree_edges=152719

• Not run: full automated test suite.

Notes for reviewers

The Neo4j Python driver is required at runtime for the new writer and standalone loader. Both entry points now handle a missing driver with a clear error message, but this PR does not add dependency metadata for neo4j to the project packaging configuration.

Imports are idempotent for repeated imports of the same SBOM content because nodes and relationships use stable IDs. This PR does not implement replace/sync behavior for removing stale Neo4j entities if a later import uses the same bomUUID but omits entities that were imported previously.

[github-actions]

✅ No SBOM Changes Detected

_{For commit 8843037 (Run 27221309320)
Compared against commit 8bd7c79 (Run 27221185739)}