# anssi-fr/ascad architecture

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

- Interactive diagram: https://gitdiagram.com/anssi-fr/ascad
- Repository: https://github.com/anssi-fr/ascad

## Overview

ASCAD is a side-channel-analysis benchmark and companion toolkit. The main workflow takes raw trace data and parameters to generate a labeled HDF5 database, trains a neural model on its profiling traces, then evaluates predictions on attack traces by ranking candidate AES key bytes. Documented campaign variants cover fixed- and variable-key ATMEGA traces and variable-key STM32 traces; multilabel generation and model evaluation are additional capabilities. The graph reflects the README and shown source excerpts; unsampled campaign-specific implementation details are not inferred.

Main entry points: [`ASCAD_test_models.py`](https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.py) (Evaluation runner), [`ASCAD_train_models.py`](https://github.com/anssi-fr/ascad/blob/master/ASCAD_train_models.py) (Training runner), [`ASCAD_generate.py`](https://github.com/anssi-fr/ascad/blob/master/ASCAD_generate.py) (ASCAD generator), [`ATMEGA_AES_v1`](https://github.com/anssi-fr/ascad/tree/master/ATMEGA_AES_v1) (ATMEGA campaigns)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Trace preparation"]
  node_generator["ASCAD generator<br/>[ASCAD_generate.py]"]
  node_labeling["Trace labeling<br/>[ASCAD_generate.py]"]
  node_hdf5db[("ASCAD HDF5")]
end

subgraph group_learning["Model training"]
  node_trainer["Training runner"]
  node_data_loader["ASCAD loader"]
  node_architectures["Neural architectures"]
  node_training["Model fitting"]
  node_model["Trained model"]
end

subgraph group_analysis["Attack evaluation"]
  node_tester["Evaluation runner"]
  node_attack_loader["Attack data loader"]
  node_prediction["Model predictions"]
  node_rank["Key-byte ranking"]
  node_results["Rank plot"]
end

subgraph group_campaigns["Campaign datasets"]
  node_campaigns_atmega[("ATMEGA campaigns")]
  node_campaigns_stm32[("STM32 campaign")]
end

node_user(("Analyst"))
node_raw[("Raw trace HDF5")]

node_user -->|"runs with parameters"| node_generator
node_raw -->|"provides traces"| node_generator
node_generator -->|"extracts and labels"| node_labeling
node_labeling -->|"writes profiling and attack sets"| node_hdf5db
node_campaigns_atmega -.->|"campaign data"| node_raw
node_campaigns_stm32 -.->|"campaign data"| node_raw
node_user -->|"runs with parameters"| node_trainer
node_hdf5db -->|"loads profiling traces"| node_data_loader
node_trainer -->|"loads data"| node_data_loader
node_trainer -->|"selects architecture"| node_architectures
node_trainer -->|"starts fitting"| node_training
node_training -->|"saves model"| node_model
node_user -->|"runs with parameters"| node_tester
node_tester -->|"loads model"| node_model
node_tester -->|"loads attack data"| node_attack_loader
node_hdf5db -->|"provides attack traces"| node_attack_loader
node_tester -->|"predicts traces"| node_prediction
node_tester -->|"computes key ranks"| node_rank
node_prediction -->|"supplies probabilities"| node_rank
node_rank -->|"plots rank curve"| node_results

click node_generator "https://github.com/anssi-fr/ascad/blob/master/ASCAD_generate.py"
click node_labeling "https://github.com/anssi-fr/ascad/blob/master/ASCAD_generate.py"
click node_campaigns_atmega "https://github.com/anssi-fr/ascad/tree/master/ATMEGA_AES_v1"
click node_campaigns_stm32 "https://github.com/anssi-fr/ascad/tree/master/STM32_AES_v2"
click node_trainer "https://github.com/anssi-fr/ascad/blob/master/ASCAD_train_models.py"
click node_data_loader "https://github.com/anssi-fr/ascad/blob/master/ASCAD_train_models.py"
click node_architectures "https://github.com/anssi-fr/ascad/blob/master/ASCAD_train_models.py"
click node_training "https://github.com/anssi-fr/ascad/blob/master/ASCAD_train_models.py"
click node_tester "https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.py"
click node_attack_loader "https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.py"
click node_prediction "https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.py"
click node_rank "https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.py"
click node_results "https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.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_generator,node_labeling,node_hdf5db toneBlue
class node_trainer,node_data_loader,node_architectures,node_training,node_model,node_raw toneAmber
class node_tester,node_attack_loader,node_prediction,node_rank,node_results toneMint
class node_campaigns_atmega,node_campaigns_stm32 toneRose
class node_user toneIndigo
```

## Components

### Trace preparation

- [ASCAD generator](https://github.com/anssi-fr/ascad/blob/master/ASCAD_generate.py): `ASCAD_generate.py`
- [Trace labeling](https://github.com/anssi-fr/ascad/blob/master/ASCAD_generate.py): `ASCAD_generate.py`
- **ASCAD HDF5**

### Model training

- [Training runner](https://github.com/anssi-fr/ascad/blob/master/ASCAD_train_models.py): `ASCAD_train_models.py`
- [ASCAD loader](https://github.com/anssi-fr/ascad/blob/master/ASCAD_train_models.py): `ASCAD_train_models.py`
- [Neural architectures](https://github.com/anssi-fr/ascad/blob/master/ASCAD_train_models.py): `ASCAD_train_models.py`
- [Model fitting](https://github.com/anssi-fr/ascad/blob/master/ASCAD_train_models.py): `ASCAD_train_models.py`
- **Trained model**

### Attack evaluation

- [Evaluation runner](https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.py): `ASCAD_test_models.py`
- [Attack data loader](https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.py): `ASCAD_test_models.py`
- [Model predictions](https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.py): `ASCAD_test_models.py`
- [Key-byte ranking](https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.py): `ASCAD_test_models.py`
- [Rank plot](https://github.com/anssi-fr/ascad/blob/master/ASCAD_test_models.py): `ASCAD_test_models.py`

### Campaign datasets

- [ATMEGA campaigns](https://github.com/anssi-fr/ascad/tree/master/ATMEGA_AES_v1): `ATMEGA_AES_v1`
- [STM32 campaign](https://github.com/anssi-fr/ascad/tree/master/STM32_AES_v2): `STM32_AES_v2`

### Other components

- **Analyst**
- **Raw trace HDF5**

## Connections

- Analyst → ASCAD generator: runs with parameters (evidence: `Readme.md`)
- Raw trace HDF5 → ASCAD generator: provides traces (evidence: `Readme.md`)
- ASCAD generator → Trace labeling: extracts and labels (evidence: `ASCAD_generate.py`)
- Trace labeling → ASCAD HDF5: writes profiling and attack sets (evidence: `ASCAD_generate.py`)
- ATMEGA campaigns → Raw trace HDF5: campaign data (evidence: `Readme.md`)
- STM32 campaign → Raw trace HDF5: campaign data (evidence: `Readme.md`)
- Analyst → Training runner: runs with parameters (evidence: `Readme.md`)
- ASCAD HDF5 → ASCAD loader: loads profiling traces (evidence: `ASCAD_train_models.py`)
- Training runner → ASCAD loader: loads data (evidence: `ASCAD_train_models.py`)
- Training runner → Neural architectures: selects architecture (evidence: `ASCAD_train_models.py`)
- Training runner → Model fitting: starts fitting (evidence: `ASCAD_train_models.py`)
- Model fitting → Trained model: saves model (evidence: `ASCAD_train_models.py`)
- Analyst → Evaluation runner: runs with parameters (evidence: `Readme.md`)
- Evaluation runner → Trained model: loads model (evidence: `ASCAD_test_models.py`)
- Evaluation runner → Attack data loader: loads attack data (evidence: `ASCAD_test_models.py`)
- ASCAD HDF5 → Attack data loader: provides attack traces (evidence: `ASCAD_test_models.py`)
- Evaluation runner → Model predictions: predicts traces (evidence: `ASCAD_test_models.py`)
- Evaluation runner → Key-byte ranking: computes key ranks (evidence: `ASCAD_test_models.py`)
- Model predictions → Key-byte ranking: supplies probabilities (evidence: `ASCAD_test_models.py`)
- Key-byte ranking → Rank plot: plots rank curve (evidence: `ASCAD_test_models.py`)