# sudiptomaity2005/trojannet-gnn architecture

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

- Interactive diagram: https://gitdiagram.com/sudiptomaity2005/trojannet-gnn
- Repository: https://github.com/sudiptomaity2005/trojannet-gnn

## Overview

TrojanNet-GNN detects and localizes hardware Trojans in gate-level netlists without requiring golden references. Its main workflow parses circuits into graphs, simulates behavioral activity, forms graph features, and applies GraphSAGE embeddings with cost-sensitive classifiers; evaluation uses cross-family leave-one-circuit-out testing. The repository also includes TARMAC trigger-vector generation as a separate capability. Some model and evaluation implementations were not excerpted, so those branches reflect README descriptions rather than inspected call paths.

Main entry points: [`src/data_preparation/parser.py`](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/data_preparation/parser.py) (Netlist graph parser), [`src/data_preparation/rs232_pipeline.py`](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/data_preparation/rs232_pipeline.py) (Circuit dataset pipelines), [`src/models/colab_feature_engineering.py`](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/colab_feature_engineering.py) (Behavioral and topology features), [`src/models/colab_gnn_ml_classifiers.py`](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/colab_gnn_ml_classifiers.py) (Hybrid feature vector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Circuit preparation"]
  node_parser["Netlist graph parser<br/>[parser.py]"]
  node_sim["Logic simulator<br/>[simulator.py]"]
  node_pipelines["Circuit dataset pipelines<br/>[rs232_pipeline.py]"]
  node_datasets[("Benchmark graph datasets")]
end

subgraph group_detection["Trojan detection"]
  node_features["Behavioral and topology features"]
  node_graphsage["GraphSAGE encoder"]
  node_hybrid["Hybrid feature vector"]
  node_ensemble["Cost-sensitive classifiers"]
  node_localization["Trojan gate localization"]
end

subgraph group_evaluation["Evaluation"]
  node_loco["Cross-family LOCO evaluation"]
  node_results["Detection metrics"]
end

subgraph group_tarmac["TARMAC triggers"]
  node_tarmac["TARMAC trigger generator<br/>[tarmac.py]"]
  node_tarmacopt["Optimized TARMAC"]
  node_experiments["TARMAC experiments<br/>[run_experiments.py]"]
  node_trigger_vectors["Trigger test vectors"]
end

node_user(("Security researcher"))
node_netlists["Gate-level netlists"]

node_user -->|"provides circuits"| node_netlists
node_netlists -->|"parsed into graph"| node_parser
node_parser -->|"supplies graph"| node_sim
node_pipelines -->|"builds circuit graph"| node_parser
node_pipelines -->|"simulates circuits"| node_sim
node_pipelines -->|"exports features"| node_datasets
node_datasets -->|"provides graph data"| node_features
node_features -->|"encodes topology"| node_graphsage
node_features -->|"combines features"| node_hybrid
node_graphsage -->|"provides embeddings"| node_hybrid
node_hybrid -->|"classifies gates"| node_ensemble
node_ensemble -->|"predicts Trojan gates"| node_localization
node_localization -->|"evaluated across folds"| node_loco
node_loco -->|"reports metrics"| node_results
node_user -->|"runs experiments"| node_experiments
node_experiments -->|"calls generator"| node_tarmacopt
node_tarmac -->|"uses netlist parser"| node_parser
node_tarmac -->|"generates vectors"| node_trigger_vectors
node_tarmacopt -->|"generates vectors"| node_trigger_vectors

click node_parser "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/data_preparation/parser.py"
click node_sim "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/data_preparation/simulator.py"
click node_pipelines "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/data_preparation/rs232_pipeline.py"
click node_features "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/colab_feature_engineering.py"
click node_graphsage "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/colab_gnn_script.py"
click node_hybrid "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/colab_gnn_ml_classifiers.py"
click node_ensemble "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/colab_gnn_ml_classifiers.py"
click node_localization "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/localization_pipeline.py"
click node_datasets "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/data_preparation/generate_gnn_datasets.py"
click node_loco "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/run_strict_loco_6classifiers.py"
click node_results "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/scripts/colab_multiseed_loco_eval.py"
click node_tarmac "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/TARMAC_trigger_activation/tarmac.py"
click node_tarmacopt "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/TARMAC_trigger_activation/tarmac_optimized.py"
click node_experiments "https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/TARMAC_trigger_activation/run_experiments.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_parser,node_sim,node_pipelines,node_datasets toneBlue
class node_features,node_graphsage,node_hybrid,node_ensemble,node_localization toneAmber
class node_loco,node_results toneMint
class node_tarmac,node_tarmacopt,node_experiments,node_trigger_vectors toneRose
class node_user,node_netlists toneIndigo
```

## Components

### Circuit preparation

- [Netlist graph parser](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/data_preparation/parser.py): `src/data_preparation/parser.py`
- [Logic simulator](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/data_preparation/simulator.py): `src/data_preparation/simulator.py`
- [Circuit dataset pipelines](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/data_preparation/rs232_pipeline.py): `src/data_preparation/rs232_pipeline.py`
- [Benchmark graph datasets](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/data_preparation/generate_gnn_datasets.py): `src/data_preparation/generate_gnn_datasets.py`

### Trojan detection

- [Behavioral and topology features](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/colab_feature_engineering.py): `src/models/colab_feature_engineering.py`
- [GraphSAGE encoder](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/colab_gnn_script.py): `src/models/colab_gnn_script.py`
- [Hybrid feature vector](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/colab_gnn_ml_classifiers.py): `src/models/colab_gnn_ml_classifiers.py`
- [Cost-sensitive classifiers](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/colab_gnn_ml_classifiers.py): `src/models/colab_gnn_ml_classifiers.py`
- [Trojan gate localization](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/localization_pipeline.py): `src/models/localization_pipeline.py`

### Evaluation

- [Cross-family LOCO evaluation](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/src/models/run_strict_loco_6classifiers.py): `src/models/run_strict_loco_6classifiers.py`
- [Detection metrics](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/scripts/colab_multiseed_loco_eval.py): `scripts/colab_multiseed_loco_eval.py`

### TARMAC triggers

- [TARMAC trigger generator](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/TARMAC_trigger_activation/tarmac.py): `TARMAC_trigger_activation/tarmac.py`
- [Optimized TARMAC](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/TARMAC_trigger_activation/tarmac_optimized.py): `TARMAC_trigger_activation/tarmac_optimized.py`
- [TARMAC experiments](https://github.com/sudiptomaity2005/trojannet-gnn/blob/main/TARMAC_trigger_activation/run_experiments.py): `TARMAC_trigger_activation/run_experiments.py`
- **Trigger test vectors**

### Other components

- **Security researcher**
- **Gate-level netlists**

## Connections

- Security researcher → Gate-level netlists: provides circuits
- Gate-level netlists → Netlist graph parser: parsed into graph
- Netlist graph parser → Logic simulator: supplies graph (evidence: `src/data_preparation/rs232_pipeline.py`)
- Circuit dataset pipelines → Netlist graph parser: builds circuit graph (evidence: `src/data_preparation/rs232_pipeline.py`)
- Circuit dataset pipelines → Logic simulator: simulates circuits (evidence: `src/data_preparation/rs232_pipeline.py`)
- Circuit dataset pipelines → Benchmark graph datasets: exports features (evidence: `src/data_preparation/rs232_pipeline.py`)
- Benchmark graph datasets → Behavioral and topology features: provides graph data
- Behavioral and topology features → GraphSAGE encoder: encodes topology
- Behavioral and topology features → Hybrid feature vector: combines features
- GraphSAGE encoder → Hybrid feature vector: provides embeddings
- Hybrid feature vector → Cost-sensitive classifiers: classifies gates (evidence: `src/models/colab_gnn_ml_classifiers.py`)
- Cost-sensitive classifiers → Trojan gate localization: predicts Trojan gates
- Trojan gate localization → Cross-family LOCO evaluation: evaluated across folds
- Cross-family LOCO evaluation → Detection metrics: reports metrics
- Security researcher → TARMAC experiments: runs experiments (evidence: `TARMAC_trigger_activation/run_experiments.py`)
- TARMAC experiments → Optimized TARMAC: calls generator (evidence: `TARMAC_trigger_activation/run_experiments.py`)
- TARMAC trigger generator → Netlist graph parser: uses netlist parser (evidence: `TARMAC_trigger_activation/tarmac.py`)
- TARMAC trigger generator → Trigger test vectors: generates vectors
- Optimized TARMAC → Trigger test vectors: generates vectors
