# ocyberlab/bingraph architecture

> Architecture diagram of the GitHub repository ocyberlab/bingraph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ocyberlab/bingraph
- Repository: https://github.com/ocyberlab/bingraph

## Overview

BinGraph turns binary executables into function-level code property graphs, encodes and stores them, then compares graph pairs with learned models for vulnerability-related analysis. Its main workflow spans extraction, normalization/storage, pair preparation, model training, and evaluation; CVE matching is a separate analysis branch. The README documents additional ablation and graph-statistics experiments. Some implementation details are only described in the README or represented by unsampled files, so the graph omits uncertain internal wiring rather than inferring it.

Main entry points: [`data/dot_graph/0-cpg.dot`](https://github.com/ocyberlab/bingraph/blob/main/data/dot_graph/0-cpg.dot) (Raw CPG graphs), [`Model_wcb/Training.py`](https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Training.py) (Model training), [`data/cpg/arm-clang-O0-libz.so.1.2.7.1_cpg.bin`](https://github.com/ocyberlab/bingraph/blob/main/data/cpg/arm-clang-O0-libz.so.1.2.7.1_cpg.bin) (Function graph store), [`Evaluation/CVE/CVE_matching.py`](https://github.com/ocyberlab/bingraph/blob/main/Evaluation/CVE/CVE_matching.py) (CVE matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extract["CPG extraction"]
  node_extractor["CPG extraction"]
  node_client["Joern client"]
  node_rawcpg["Raw CPG graphs<br/>[0-cpg.dot]"]
end

subgraph group_encode["Encoding and storage"]
  node_normalizer["Graph normalization<br/>[bin_cpg_wo_cb.py]"]
  node_ablation["Ablation extraction<br/>[bin_cpg.py]"]
  node_hdf5encoder["HDF5 encoding<br/>[hdf5_encoding.py]"]
  node_graphstore[("Function graph store")]
end

subgraph group_learn["Pair learning"]
  node_loader["Pair preparation<br/>[Dataloader.py]"]
  node_dataset["Graph pairs<br/>[Training.py]"]
  node_model["Graph model<br/>[Model.py]"]
  node_training["Model training<br/>[Training.py]"]
  node_metrics["Training metrics"]
  node_alternate["No-ablation model<br/>[Model.py]"]
end

subgraph group_evaluate["Evaluation and analysis"]
  node_cvematch["CVE matching<br/>[CVE_matching.py]"]
  node_histogram["HDF5 histograms<br/>[histograms_hdf5.py]"]
  node_graphmetrics["Graph metrics<br/>[graph_metrics.py]"]
  node_cveoutput["CVE matches<br/>[CVE_matching.py]"]
end

node_user(("Analyst"))
node_binaries["Binary executables"]
node_joern["Joern"]
node_cvedata[("CVE service")]

node_user -->|"starts extraction"| node_extractor
node_binaries -->|"supplies binaries"| node_extractor
node_extractor -->|"requests CPGs"| node_client
node_client -->|"queries"| node_joern
node_joern -->|"produces graphs"| node_rawcpg
node_rawcpg -->|"reads graphs"| node_normalizer
node_normalizer -->|"stores encoded graphs"| node_graphstore
node_rawcpg -.->|"reads graphs"| node_ablation
node_ablation -.->|"stores ablation data"| node_graphstore
node_graphstore -->|"loads functions"| node_loader
node_loader -->|"forms labeled pairs"| node_dataset
node_dataset -->|"supplies batches"| node_training
node_training -->|"updates weights"| node_model
node_training -->|"records scores"| node_metrics
node_user -->|"starts training"| node_training
node_training -.->|"trains variant"| node_alternate
node_user -->|"starts matching"| node_cvematch
node_cvedata -.->|"provides CVEs"| node_cvematch
node_rawcpg -->|"reads function names"| node_cvematch
node_cvematch -->|"writes matches"| node_cveoutput
node_graphstore -->|"reads graph data"| node_histogram
node_rawcpg -->|"reads DOT graphs"| node_graphmetrics

click node_extractor "https://github.com/ocyberlab/bingraph/blob/main/Feature_Extraction/bin_cpg_extraction.py"
click node_client "https://github.com/ocyberlab/bingraph/blob/main/utils/process/cpg_client_wrapper.py"
click node_rawcpg "https://github.com/ocyberlab/bingraph/blob/main/data/dot_graph/0-cpg.dot"
click node_normalizer "https://github.com/ocyberlab/bingraph/blob/main/Feature_Extraction/bin_cpg_wo_cb.py"
click node_ablation "https://github.com/ocyberlab/bingraph/blob/main/Feature_Extraction/bin_cpg.py"
click node_hdf5encoder "https://github.com/ocyberlab/bingraph/blob/main/Feature_Extraction/hdf5_encoding.py"
click node_graphstore "https://github.com/ocyberlab/bingraph/blob/main/data/cpg/arm-clang-O0-libz.so.1.2.7.1_cpg.bin"
click node_loader "https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Dataloader.py"
click node_dataset "https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Training.py"
click node_model "https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Model.py"
click node_training "https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Training.py"
click node_metrics "https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Metrics_evaluator.py"
click node_alternate "https://github.com/ocyberlab/bingraph/blob/main/Model/Model.py"
click node_cvematch "https://github.com/ocyberlab/bingraph/blob/main/Evaluation/CVE/CVE_matching.py"
click node_histogram "https://github.com/ocyberlab/bingraph/blob/main/Evaluation/Histograms/histograms_hdf5.py"
click node_graphmetrics "https://github.com/ocyberlab/bingraph/blob/main/Evaluation/Layers/graph_metrics.py"
click node_cveoutput "https://github.com/ocyberlab/bingraph/blob/main/Evaluation/CVE/CVE_matching.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_extractor,node_client,node_rawcpg toneBlue
class node_normalizer,node_ablation,node_hdf5encoder,node_graphstore,node_cvedata toneAmber
class node_loader,node_dataset,node_model,node_training,node_metrics,node_alternate toneMint
class node_cvematch,node_histogram,node_graphmetrics,node_cveoutput toneRose
class node_user,node_binaries,node_joern toneIndigo
```

## Components

### CPG extraction

- [CPG extraction](https://github.com/ocyberlab/bingraph/blob/main/Feature_Extraction/bin_cpg_extraction.py): `Feature_Extraction/bin_cpg_extraction.py`
- [Joern client](https://github.com/ocyberlab/bingraph/blob/main/utils/process/cpg_client_wrapper.py): `utils/process/cpg_client_wrapper.py`
- [Raw CPG graphs](https://github.com/ocyberlab/bingraph/blob/main/data/dot_graph/0-cpg.dot): `data/dot_graph/0-cpg.dot`

### Encoding and storage

- [Graph normalization](https://github.com/ocyberlab/bingraph/blob/main/Feature_Extraction/bin_cpg_wo_cb.py): `Feature_Extraction/bin_cpg_wo_cb.py`
- [Ablation extraction](https://github.com/ocyberlab/bingraph/blob/main/Feature_Extraction/bin_cpg.py): `Feature_Extraction/bin_cpg.py`
- [HDF5 encoding](https://github.com/ocyberlab/bingraph/blob/main/Feature_Extraction/hdf5_encoding.py): `Feature_Extraction/hdf5_encoding.py`
- [Function graph store](https://github.com/ocyberlab/bingraph/blob/main/data/cpg/arm-clang-O0-libz.so.1.2.7.1_cpg.bin): `data/cpg/arm-clang-O0-libz.so.1.2.7.1_cpg.bin`

### Pair learning

- [Pair preparation](https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Dataloader.py): `Model_wcb/Dataloader.py`
- [Graph pairs](https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Training.py): `Model_wcb/Training.py`
- [Graph model](https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Model.py): `Model_wcb/Model.py`
- [Model training](https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Training.py): `Model_wcb/Training.py`
- [Training metrics](https://github.com/ocyberlab/bingraph/blob/main/Model_wcb/Metrics_evaluator.py): `Model_wcb/Metrics_evaluator.py`
- [No-ablation model](https://github.com/ocyberlab/bingraph/blob/main/Model/Model.py): `Model/Model.py`

### Evaluation and analysis

- [CVE matching](https://github.com/ocyberlab/bingraph/blob/main/Evaluation/CVE/CVE_matching.py): `Evaluation/CVE/CVE_matching.py`
- [HDF5 histograms](https://github.com/ocyberlab/bingraph/blob/main/Evaluation/Histograms/histograms_hdf5.py): `Evaluation/Histograms/histograms_hdf5.py`
- [Graph metrics](https://github.com/ocyberlab/bingraph/blob/main/Evaluation/Layers/graph_metrics.py): `Evaluation/Layers/graph_metrics.py`
- [CVE matches](https://github.com/ocyberlab/bingraph/blob/main/Evaluation/CVE/CVE_matching.py): `Evaluation/CVE/CVE_matching.py`

### Other components

- **Analyst**
- **Binary executables**
- **Joern**
- **CVE service**

## Connections

- Analyst → CPG extraction: starts extraction
- Binary executables → CPG extraction: supplies binaries
- CPG extraction → Joern client: requests CPGs
- Joern client → Joern: queries
- Joern → Raw CPG graphs: produces graphs
- Raw CPG graphs → Graph normalization: reads graphs
- Graph normalization → Function graph store: stores encoded graphs
- Raw CPG graphs → Ablation extraction: reads graphs
- Ablation extraction → Function graph store: stores ablation data
- Function graph store → Pair preparation: loads functions
- Pair preparation → Graph pairs: forms labeled pairs
- Graph pairs → Model training: supplies batches
- Model training → Graph model: updates weights
- Model training → Training metrics: records scores
- Analyst → Model training: starts training
- Model training → No-ablation model: trains variant
- Analyst → CVE matching: starts matching
- CVE service → CVE matching: provides CVEs
- Raw CPG graphs → CVE matching: reads function names
- CVE matching → CVE matches: writes matches
- Function graph store → HDF5 histograms: reads graph data
- Raw CPG graphs → Graph metrics: reads DOT graphs