# darkmodepdf/xran-ransomware-lab architecture

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

- Interactive diagram: https://gitdiagram.com/darkmodepdf/xran-ransomware-lab
- Repository: https://github.com/darkmodepdf/xran-ransomware-lab

## Overview

RanEval is a ransomware-behavior research workspace, with a current native Windows streaming fixture demo and historical Linux, EN2025, and XRan research tracks. The documented demo workflow is to run harmless workers, inspect model alerts, and independently check generated-file integrity; the README says workers continue after alerts and the demo does not restore files. The graph includes the principal runtime and research modules named in the source index. Some demo/UI and collector wiring is not present in the supplied tree or excerpts, so those relationships are not inferred.

Main entry points: [`src/raneval/core.py`](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/core.py) (Trace and model contracts), [`src/raneval/context_score.py`](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/context_score.py) (Context GRU scoring), [`scripts/benchmark_linux_context.py`](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/benchmark_linux_context.py) (Context benchmark), [`src/raneval/windows_stream.py`](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/windows_stream.py) (Streaming inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_native["Native Windows"]
  node_event_schema["Windows event schema<br/>[windows_events.py]"]
  node_stream_inference["Streaming inference<br/>[windows_stream.py]"]
  node_native_model["Native behavior model<br/>[windows_native.py]"]
  node_native_model_v1["Native model v1"]
  node_native_training["Native model fitting"]
end

subgraph group_sequence["Sequence Research"]
  node_sequence_contracts["Trace and model contracts<br/>[core.py]"]
  node_sequence_training["Sequence training<br/>[train.py]"]
  node_sequence_scoring["Sequence replay scoring<br/>[score.py]"]
  node_expanded_research["Expanded experiments<br/>[expanded.py]"]
end

subgraph group_context["Linux Context"]
  node_context_features["Context features<br/>[context.py]"]
  node_context_scoring["Context GRU scoring<br/>[context_score.py]"]
  node_process_scoring["Process scoring<br/>[process_score.py]"]
  node_linux_observation["Linux observation<br/>[observe_linux.py]"]
  node_process_observation["Process observation<br/>[observe_process.py]"]
  node_linux_benchmark["Linux benchmarking<br/>[benchmark_linux.py]"]
  node_linux_context_benchmark["Context benchmark"]
  node_linux_refit["Linux GRU refit<br/>[refit_linux_gru.py]"]
end

subgraph group_xran["XRan Research"]
  node_xran_data["XRan feature preparation<br/>[xran_data.py]"]
  node_xran_models["XRan model definitions<br/>[xran_models.py]"]
  node_xran_metrics["XRan metrics<br/>[xran_metrics.py]"]
  node_xran_training["XRan training<br/>[train_xran.py]"]
  node_xran_evaluation["XRan evaluation<br/>[evaluate_xran.py]"]
end

subgraph group_datasets["Research Data"]
  node_en2025_prep["EN2025 preparation<br/>[prepare_en2025.py]"]
  node_linux_data_prep["Linux benchmark preparation"]
end

node_user(("Demo user"))
node_workers["Harmless workers"]
node_integrity["File integrity check"]
node_docker["Docker inference"]

node_user -->|"runs"| node_workers
node_workers -->|"run beside"| node_docker
node_user -->|"checks files"| node_integrity
node_stream_inference -->|"uses schema"| node_event_schema
node_stream_inference -->|"dispatches v2"| node_native_model
node_stream_inference -->|"dispatches v1"| node_native_model_v1
node_native_training -->|"uses"| node_stream_inference
node_native_training -->|"fits"| node_native_model
node_native_training -->|"fits"| node_native_model_v1
node_sequence_training -->|"uses contracts"| node_sequence_contracts
node_sequence_scoring -->|"uses model"| node_sequence_contracts
node_expanded_research -->|"uses contracts"| node_sequence_contracts
node_expanded_research -->|"uses training"| node_sequence_training
node_expanded_research -->|"uses scoring"| node_sequence_scoring
node_context_scoring -->|"builds context"| node_context_features
node_context_scoring -->|"uses model"| node_sequence_contracts
node_process_scoring -->|"uses"| node_context_scoring
node_process_scoring -->|"uses"| node_sequence_scoring
node_linux_observation -->|"scores with"| node_context_scoring
node_process_observation -->|"scores with"| node_process_scoring
node_linux_benchmark -->|"uses"| node_sequence_contracts
node_linux_benchmark -->|"uses"| node_sequence_training
node_linux_context_benchmark -->|"uses"| node_context_features
node_linux_context_benchmark -->|"scores with"| node_context_scoring
node_linux_context_benchmark -->|"uses"| node_sequence_contracts
node_linux_context_benchmark -->|"uses"| node_sequence_scoring
node_linux_refit -->|"uses"| node_sequence_contracts
node_linux_refit -->|"uses"| node_sequence_training
node_xran_training -->|"uses"| node_xran_metrics
node_xran_training -->|"uses"| node_xran_models
node_xran_evaluation -->|"prepares inputs"| node_xran_data
node_xran_evaluation -->|"evaluates with"| node_xran_metrics
node_xran_evaluation -->|"evaluates"| node_xran_models

click node_event_schema "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/windows_events.py"
click node_stream_inference "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/windows_stream.py"
click node_native_model "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/windows_native.py"
click node_native_model_v1 "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/windows_native_v1.py"
click node_native_training "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/train_windows_native.py"
click node_sequence_contracts "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/core.py"
click node_sequence_training "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/train.py"
click node_sequence_scoring "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/score.py"
click node_expanded_research "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/expanded.py"
click node_context_features "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/context.py"
click node_context_scoring "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/context_score.py"
click node_process_scoring "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/process_score.py"
click node_linux_observation "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/observe_linux.py"
click node_process_observation "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/observe_process.py"
click node_linux_benchmark "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/benchmark_linux.py"
click node_linux_context_benchmark "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/benchmark_linux_context.py"
click node_linux_refit "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/refit_linux_gru.py"
click node_xran_data "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/xran_data.py"
click node_xran_models "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/xran_models.py"
click node_xran_metrics "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/xran_metrics.py"
click node_xran_training "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/train_xran.py"
click node_xran_evaluation "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/evaluate_xran.py"
click node_en2025_prep "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/prepare_en2025.py"
click node_linux_data_prep "https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/prepare_linux_benchmark.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_event_schema,node_stream_inference,node_native_model,node_native_model_v1,node_native_training,node_user toneBlue
class node_sequence_contracts,node_sequence_training,node_sequence_scoring,node_expanded_research toneAmber
class node_context_features,node_context_scoring,node_process_scoring,node_linux_observation,node_process_observation,node_linux_benchmark,node_linux_context_benchmark,node_linux_refit toneMint
class node_xran_data,node_xran_models,node_xran_metrics,node_xran_training,node_xran_evaluation,node_workers toneRose
class node_en2025_prep,node_linux_data_prep,node_integrity,node_docker toneIndigo
```

## Components

### Native Windows

- [Windows event schema](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/windows_events.py): `src/raneval/windows_events.py`
- [Streaming inference](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/windows_stream.py): `src/raneval/windows_stream.py`
- [Native behavior model](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/windows_native.py): `src/raneval/windows_native.py`
- [Native model v1](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/windows_native_v1.py): `src/raneval/windows_native_v1.py`
- [Native model fitting](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/train_windows_native.py): `scripts/train_windows_native.py`

### Sequence Research

- [Trace and model contracts](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/core.py): `src/raneval/core.py`
- [Sequence training](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/train.py): `src/raneval/train.py`
- [Sequence replay scoring](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/score.py): `src/raneval/score.py`
- [Expanded experiments](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/expanded.py): `src/raneval/expanded.py`

### Linux Context

- [Context features](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/context.py): `src/raneval/context.py`
- [Context GRU scoring](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/context_score.py): `src/raneval/context_score.py`
- [Process scoring](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/process_score.py): `src/raneval/process_score.py`
- [Linux observation](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/observe_linux.py): `src/raneval/observe_linux.py`
- [Process observation](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/observe_process.py): `src/raneval/observe_process.py`
- [Linux benchmarking](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/benchmark_linux.py): `scripts/benchmark_linux.py`
- [Context benchmark](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/benchmark_linux_context.py): `scripts/benchmark_linux_context.py`
- [Linux GRU refit](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/refit_linux_gru.py): `scripts/refit_linux_gru.py`

### XRan Research

- [XRan feature preparation](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/xran_data.py): `src/raneval/xran_data.py`
- [XRan model definitions](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/xran_models.py): `src/raneval/xran_models.py`
- [XRan metrics](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/xran_metrics.py): `src/raneval/xran_metrics.py`
- [XRan training](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/src/raneval/train_xran.py): `src/raneval/train_xran.py`
- [XRan evaluation](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/evaluate_xran.py): `scripts/evaluate_xran.py`

### Research Data

- [EN2025 preparation](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/prepare_en2025.py): `scripts/prepare_en2025.py`
- [Linux benchmark preparation](https://github.com/darkmodepdf/xran-ransomware-lab/blob/main/scripts/prepare_linux_benchmark.py): `scripts/prepare_linux_benchmark.py`

### Other components

- **Demo user**
- **Harmless workers**
- **File integrity check**
- **Docker inference**

## Connections

- Demo user → Harmless workers: runs (evidence: `README.md`)
- Harmless workers → Docker inference: run beside (evidence: `README.md`)
- Demo user → File integrity check: checks files (evidence: `README.md`)
- Streaming inference → Windows event schema: uses schema (evidence: `src/raneval/windows_stream.py`)
- Streaming inference → Native behavior model: dispatches v2 (evidence: `src/raneval/windows_stream.py`)
- Streaming inference → Native model v1: dispatches v1 (evidence: `src/raneval/windows_stream.py`)
- Native model fitting → Streaming inference: uses (evidence: `scripts/train_windows_native.py`)
- Native model fitting → Native behavior model: fits (evidence: `scripts/train_windows_native.py`)
- Native model fitting → Native model v1: fits (evidence: `scripts/train_windows_native.py`)
- Sequence training → Trace and model contracts: uses contracts (evidence: `src/raneval/train.py`)
- Sequence replay scoring → Trace and model contracts: uses model (evidence: `src/raneval/score.py`)
- Expanded experiments → Trace and model contracts: uses contracts (evidence: `src/raneval/expanded.py`)
- Expanded experiments → Sequence training: uses training (evidence: `src/raneval/expanded.py`)
- Expanded experiments → Sequence replay scoring: uses scoring (evidence: `src/raneval/expanded.py`)
- Context GRU scoring → Context features: builds context (evidence: `src/raneval/context_score.py`)
- Context GRU scoring → Trace and model contracts: uses model (evidence: `src/raneval/context_score.py`)
- Process scoring → Context GRU scoring: uses (evidence: `src/raneval/process_score.py`)
- Process scoring → Sequence replay scoring: uses (evidence: `src/raneval/process_score.py`)
- Linux observation → Context GRU scoring: scores with (evidence: `src/raneval/observe_linux.py`)
- Process observation → Process scoring: scores with (evidence: `src/raneval/observe_process.py`)
- Linux benchmarking → Trace and model contracts: uses (evidence: `scripts/benchmark_linux.py`)
- Linux benchmarking → Sequence training: uses (evidence: `scripts/benchmark_linux.py`)
- Context benchmark → Context features: uses (evidence: `scripts/benchmark_linux_context.py`)
- Context benchmark → Context GRU scoring: scores with (evidence: `scripts/benchmark_linux_context.py`)
- Context benchmark → Trace and model contracts: uses (evidence: `scripts/benchmark_linux_context.py`)
- Context benchmark → Sequence replay scoring: uses (evidence: `scripts/benchmark_linux_context.py`)
- Linux GRU refit → Trace and model contracts: uses (evidence: `scripts/refit_linux_gru.py`)
- Linux GRU refit → Sequence training: uses (evidence: `scripts/refit_linux_gru.py`)
- XRan training → XRan metrics: uses (evidence: `src/raneval/train_xran.py`)
- XRan training → XRan model definitions: uses (evidence: `src/raneval/train_xran.py`)
- XRan evaluation → XRan feature preparation: prepares inputs (evidence: `scripts/evaluate_xran.py`)
- XRan evaluation → XRan metrics: evaluates with (evidence: `scripts/evaluate_xran.py`)
- XRan evaluation → XRan model definitions: evaluates (evidence: `scripts/evaluate_xran.py`)
