Code Property Graph

Code Property Graphs — Joern/Semgrep extraction, AI vulnerability enrichment, risk scoring.

This package depends on AWS GraphRAG Toolkit (graphrag-toolkit-lexical-graph) for graph storage, vector indexing, and retrieval.

Installation

pip install graphrag-codeproperty-graph

Dependencies

• graphrag-document-graph>=3.0.8 — Document graph infrastructure (typed nodes, Cypher builders, multi-tenancy)

This package does not depend on bona.

Dependency Chain

graphrag-codeproperty-graph
└── graphrag-document-graph>=3.0.8
    └── graphrag-toolkit-lexical-graph>=3.18.0  (AWS foundation)
        ├── Neptune graph storage
        ├── OpenSearch Serverless vector indexing
        └── Entity resolution & retrieval

Quick Start

Python API Example

from codeproperty_graph import DeltaIngestor, CPGNode, CPGEdge, GraphDiff

# Delta ingestion — only writes to Neptune when code actually changed
ingestor = DeltaIngestor(bucket="graphrag-artifacts-705909755305")

result = await ingestor.ingest(
    repo="my-service",
    job_id="build-456",
    tenant_id="tenant_abc123",
    nodes_data=joern_nodes,
    edges_data=joern_edges,
    nodes_path="s3://bucket/cpg-exports/my-service/build-456/nodes.json",
    edges_path="s3://bucket/cpg-exports/my-service/build-456/edges.json",
    graph_store=neptune_store,
    write_fn=batch_write_function,
)

# result: {"status": "SKIPPED"} or {"status": "INGESTED", "delta": "+5 -2 ~3 =150"}

Graph Diff — Compare CPG States

from codeproperty_graph import GraphDiff, CPGNode

# Compare current vs previous code analysis
diff = GraphDiff.compare(
    current_nodes=current_cpg_nodes,
    previous_nodes=previous_cpg_nodes,
)

print(f"Added: {len(diff.added)}")
print(f"Removed: {len(diff.removed)}")
print(f"Modified: {len(diff.modified)}")
print(f"Unchanged: {len(diff.unchanged)}")

Manifest Management

from codeproperty_graph import ManifestManager

# Track CPG state per repository in S3
manager = ManifestManager(bucket="graphrag-artifacts-705909755305")

# Save manifest after successful ingestion
await manager.save(repo="my-service", job_id="build-456", signatures=method_signatures)

# Load previous manifest for diff comparison
previous = await manager.load(repo="my-service")

Package Structure

src/codeproperty_graph/
├── __init__.py           # Public API: CPGNode, CPGEdge, DeltaIngestor, etc.
├── models.py             # CPGNode, CPGEdge, Manifest — Joern-specific types
├── graph_diff.py         # Compare two CPG states by method signature
├── manifest_manager.py   # S3-backed state tracking per repository
├── delta_ingestor.py     # Skip-or-replace orchestration with tenant purge
└── tenant_ops.py         # Clean lifecycle management (delete_tenant)

Integration

Architecture Stack

┌─────────────────────────────────────────────────────┐
│         codeproperty-graph (this package)            │
│  Joern/Semgrep CPG, delta ingestion, risk scoring   │
├─────────────────────────────────────────────────────┤
│              document-graph                          │
│  Node, Edge, CypherBuilder, PipelineExecutor        │
│  Multi-tenancy, batch operations                    │
├─────────────────────────────────────────────────────┤
│     graphrag-toolkit-lexical-graph (foundation)     │
│  GraphStore, Neptune writer, AOSS writer            │
│  Lexical indexing, entity resolution, retrieval     │
└─────────────────────────────────────────────────────┘

Delta Logic

1. Joern exports CPG → nodes.json + edges.json
2. Extract METHOD node signatures: {full_name: hash}
3. Compare against previous manifest in S3
4. If identical → SKIP (no Neptune writes, saves cost)
5. If changed → INGEST full graph under new tenant, purge old tenant, update manifest

With Document Graph

Code Property Graph uses document-graph for typed property graph primitives:

# document-graph provides the graph write infrastructure
from graphrag_toolkit.document_graph.graph_build.cypher_builder import CypherBuilder
from graphrag_toolkit.document_graph import Node, Edge

# codeproperty-graph adds CPG-specific semantics on top
from codeproperty_graph import CPGNode, CPGEdge

Contributing

See CONTRIBUTING.md for development setup, testing, and PR guidelines.

License

MIT — see LICENSE for details.

See NOTICE for third-party acknowledgments.