Sovereign 8s.is mirror of standardgalactic/AuditGain
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-07-22 18:34:32 +08:00
config Initial commit: AuditGain framework implementation 2026-03-20 18:37:13 +08:00
data Initial commit: AuditGain framework implementation 2026-03-20 18:37:13 +08:00
models Initial commit: AuditGain framework implementation 2026-03-20 18:37:13 +08:00
utils Initial commit: AuditGain framework implementation 2026-03-20 18:37:13 +08:00
evaluate.py Initial commit: AuditGain framework implementation 2026-03-20 18:37:13 +08:00
README.md Align README with revised manuscript 2026-07-22 18:34:32 +08:00
requirements.txt Initial commit: AuditGain framework implementation 2026-03-20 18:37:13 +08:00
train.py Initial commit: AuditGain framework implementation 2026-03-20 18:37:13 +08:00

AuditGain

Critical Risk Node Identification in Enterprise Resource Planning Heterogeneous Knowledge Graphs

This repository contains the source implementation, configuration file, training and evaluation scripts, public benchmark instructions, and synthetic ERP graph generator accompanying the AuditGain manuscript.

Architecture

AuditGain consists of four hierarchical modules:

  1. DiGRAF Layer — Graph-adaptive diffeomorphic activation functions (CPAB) that learn node-specific nonlinear transformations conditioned on local graph topology.
  2. Adaptive GAT — LSTM-enhanced multi-head graph attention that captures temporal ordering of neighbors for risk propagation modeling.
  3. LSTN — Location-Sensing Transformer Network that maps node embeddings to a spectral-coordinate-guided grid and applies deformable attention.
  4. External Memory Network — Spectral clustering-based memory with attention read/write for long-range context aggregation.

Project Structure

AuditGain/
├── config/
│   └── default.yaml          # Hyperparameters used by the reference implementation
├── data/
│   ├── __init__.py
│   └── dataset.py             # Dataset class + synthetic data generator
├── models/
│   ├── __init__.py
│   ├── auditgain.py           # Main AuditGain model (integrates all modules)
│   ├── adaptive_gat.py        # LSTM-enhanced Graph Attention Network
│   ├── digraf.py              # DiGRAF: graph-adaptive CPAB activation
│   ├── lstn.py                # Location-Sensing Transformer Network
│   ├── memory.py              # External Memory with spectral clustering
│   └── losses.py              # Focal loss + graph Laplacian regularization
├── utils/
│   ├── __init__.py
│   └── metrics.py             # F1, AUC-ROC, AP, Recall@k
├── train.py                   # Training script (Algorithm 1)
├── evaluate.py                # Evaluation script
├── requirements.txt           # Python dependencies
└── README.md                  # This file

Environment Setup

Prerequisites

  • Python >= 3.10
  • CUDA >= 11.8 (for GPU training; CPU also supported)
  • OS: Linux / Windows / macOS
# Using conda
conda create -n auditgain python=3.10 -y
conda activate auditgain

# Or using venv
python -m venv venv
source venv/bin/activate        # Linux/macOS
# venv\Scripts\activate         # Windows

Step 2: Install PyTorch

Install PyTorch 2.1+ matching your CUDA version. Visit pytorch.org for the exact command.

# Example: CUDA 11.8
pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cu118

# Example: CPU only
pip install torch==2.1.0 torchvision==0.16.0 torchaudio==2.1.0 --index-url https://download.pytorch.org/whl/cpu

Step 3: Install PyTorch Geometric

PyG dependencies must match your PyTorch and CUDA versions:

# Find the correct wheel URL at: https://data.pyg.org/whl/
pip install torch-scatter torch-sparse -f https://data.pyg.org/whl/torch-2.1.0+cu118.html
pip install torch-geometric

Step 4: Install remaining dependencies

pip install -r requirements.txt

Dependency Summary

Package Version Purpose
torch >= 2.1.0 Deep learning framework
torch-geometric >= 2.4.0 Graph neural network library
torch-scatter >= 2.1.2 Efficient scatter operations for PyG
torch-sparse >= 0.6.18 Sparse matrix operations for PyG
numpy >= 1.24.0 Numerical computing
scipy >= 1.11.0 Spectral clustering (eigendecomposition)
scikit-learn >= 1.3.0 K-Means clustering, evaluation metrics
pyyaml >= 6.0 Configuration file parsing
tqdm >= 4.66.0 Progress bars
pandas >= 2.1.0 Data manipulation
matplotlib >= 3.8.0 Visualization
seaborn >= 0.13.0 Statistical visualization

Quick Start

1. Run on synthetic data (no real data needed)

python train.py --synthetic --runs 1

This generates a synthetic ERP heterogeneous knowledge graph and trains AuditGain on it. Use this to verify that the code runs correctly.

2. Run AuditGain-Lite (faster, no LSTN)

python train.py --synthetic --no-lstn --runs 1

3. Train on your own data

Prepare your data as a .pt file with the following structure (see data/dataset.py for details):

data_dict = {
    "x_dict": {"Transaction": tensor, "Account": tensor, ...},  # node features
    "edge_index": tensor,       # [2, E]
    "edge_type": tensor,        # [E]
    "node_type_ids": tensor,    # [N]
    "node_types_map": dict,     # {"Transaction": 0, "Account": 1, ...}
    "node_types_list": list,    # ["Transaction", "Account", ...]
    "labels": tensor,           # [N], -1 for unlabeled, 0/1 for normal/risky
    "timestamps": tensor,       # [N]
    "degrees": tensor,          # [N]
    "train_mask": tensor,       # [N] boolean
    "val_mask": tensor,         # [N] boolean
    "test_mask": tensor,        # [N] boolean
    "total_nodes": int,
    "feat_dims": dict,          # {"Transaction": 16, ...}
}
torch.save(data_dict, "my_data.pt")

Then train:

python train.py --data my_data.pt --config config/default.yaml --runs 10

4. Evaluate a trained model

python evaluate.py --data my_data.pt --checkpoint results/model.pt

Key Hyperparameters

All hyperparameters are in config/default.yaml and follow the manuscript setting:

Parameter Value Description
hidden_dim 128 Shared hidden dimension d
num_gat_layers 3 Number of Adaptive GAT layers L
num_heads 8 Attention heads K
lstm_hidden_dim 128 LSTM hidden size
digraf_intervals 8 CPAB intervals B
lstn_blocks 2 LSTN encoder/decoder blocks M
num_clusters 16 Spectral clusters C
memory_momentum 0.99 Memory EMA momentum μ
learning_rate 5e-4 Initial learning rate
weight_decay 1e-5 L2 regularization
dropout 0.3 Dropout rate
focal_gamma 2.0 Focal loss focusing parameter γ
reg_lambda 0.01 Graph Laplacian regularization weight λ
epochs 200 Training epochs

Model Variants

Variant Modules Params Notes
AuditGain (Full) DiGRAF + Adaptive GAT + LSTN + Memory ~3.42M Best performance
AuditGain-Lite DiGRAF (B=4) + Adaptive GAT + Memory ~2.45M Use --no-lstn flag
AuditGain-Core Adaptive GAT + Type-Specific Features ~1.68M Minimal variant

Data Note

The three proprietary ERP audit datasets (ERP-Audit-A/B/C) used in the manuscript cannot be released due to NDA restrictions. The synthetic data generator (data/dataset.py) produces graphs with similar structural properties for code validation. We also provide public benchmark instructions for:

Hardware Requirements

  • GPU: NVIDIA GPU with >= 8GB VRAM (A100 80GB used in the manuscript)
  • CPU: Supported but significantly slower
  • RAM: >= 16GB recommended

Training time (ERP-Audit-A, 156K nodes, A100 GPU):

  • AuditGain: ~15.6s/epoch, ~52 min total
  • AuditGain-Lite: ~10.3s/epoch, ~34 min total

Citation

If you use this code in your research, please cite the accompanying manuscript:

@misc{chen2026auditgain,
  title={Critical Risk Node Identification in Enterprise Resource Planning Heterogeneous Knowledge Graphs},
  author={Chen, Ruizhe and Chen, Jiajun},
  year={2026},
  note={Manuscript submitted for publication}
}

License

This project is released under the MIT License.