How andyj1/scga works
This repository is a research-training codebase for a black-box generative adversarial attack method called SCGA. Architecturally, it is not a deployed service; it is an offline PyTorch pipeline centered on generating adversarial perturbations, training a generator against surrogate classifiers, and evaluating transferability on multiple image datasets.
Main system boundaries
1. Training entrypoint
• train_BIA_ours.py is the primary top-level script.
• It orchestrates the full experiment: argument parsing, dataset selection, model construction, training, and evaluation.
• The README points to utee/parser.py for the supported CLI options, so the training behavior is configured centrally rather than through multiple scripts.
2. Dataset and data-loading layer
The repository separates generic dataset support from a specialized fine-grained dataset package.
• datasets/paths.py
- Defines the root data directory (DATA_ROOT_DIR), which is the filesystem boundary between code and local datasets.
• datasets/imagenet/
- Handles ImageNet-specific loading and label metadata.
- Contains dataset logic plus multiple model wrappers (alexnet.py, resnet.py, vgg.py, inception.py, squeezenet.py) and mapping files for class IDs and names.
- This indicates the project uses ImageNet both as a training/evaluation domain and as a label-resolution source.
• datasets/DCL_finegrained/
- A self-contained fine-grained dataset submodule for AIR, CUB, and Stanford Cars.
- Includes dataset definitions, transforms, configuration, model loading, and a dedicated training script.
- The presence of train.txt and test.txt files under each dataset folder indicates the loaders are driven by explicit split lists rather than only by folder structure.
- Files such as dataset.py, dataset_DCL.py, our_dataset.py, and LoadModel.py suggest this package includes custom data abstractions and model-loading support tailored to those datasets.
• Top-level datasets/train.py and datasets/eval.py
- These appear to be reusable dataset training/evaluation helpers, likely used by the main attack pipeline and/or for auxiliary classifier training.
Data flow through this layer:
• Raw images and split metadata are read from the dataset root.
• Dataset-specific loaders produce tensors and labels.
• Transform pipelines preprocess samples before they are fed into the generator/surrogate training loop.
3. Generator subsystem
• The generator/ directory contains the core attack model family.
• Implementations include:
- resnet.py
- resnet_gap.py
- resnet_nat.py
• These files suggest multiple generator variants based on ResNet-like backbones, probably differing in pooling strategy or normalization/architecture details.
• In the architecture of SCGA, the generator is the component that produces adversarial perturbations in a single forward pass at test time, which is the key efficiency advantage over iterative attacks.
Functional boundary:
• The generator is the “attack producer.”
• It takes preprocessed input images and emits perturbed outputs or perturbation tensors.
• It is the main object being optimized during training.
4. Surrogate model subsystem
• The surrogate/ directory contains the victim-side proxy classifiers used during training:
- Dense169.py
- Res152.py
- VGG16.py
- VGG19.py
• These are the surrogate networks against which the generator is optimized.
• They provide the loss signal that guides adversarial example generation when the true black-box target is unavailable.
Architectural role:
• Surrogates form the “black-box approximation” boundary.
• Training computes gradients or losses through these local substitute models, while deployment assumes transfer to an unseen target model.
5. SCGA-specific semantic-consistency mechanism
The README describes SCGA as an add-on that enforces semantic consistency by aligning early generator intermediate features to an EMA teacher.
Architecturally, this implies an internal training branch:
• The generator has intermediate feature activations that are monitored during training.
• An EMA teacher provides a stabilized reference representation.
• The training objective combines standard surrogate-driven attack loss with a semantic-alignment term.
• This mechanism affects only training; the README emphasizes no inference-time overhead.
Even though there is no dedicated top-level “teacher” module in the file tree, the method’s logic is embedded in the generator/training stack.
6. Shared preprocessing, transforms, and utilities
• Top-level transforms/
- Contains generic transform and functional utilities used across datasets and training flows.
• datasets/DCL_finegrained/transforms.py
- Dataset-specific transform logic for the fine-grained branch.
• utee/
- Utility layer for the experiment framework:
- Normalize.py for normalization
- logger.py for experiment logging
- metric.py for metrics
- misc.py for helper functions
- parser.py for CLI argument definitions
- selector.py for choosing models/components by name or config
- This layer acts as the shared infrastructure glue between the entrypoint, datasets, generator, and surrogate models.
Important evaluation and reporting behavior
The README mentions several evaluation metrics:
• ASR
• FR
• Accuracy
• ACR
That implies a dedicated evaluation path that computes attack outcomes from model predictions. In architectural terms:
• The generator output is evaluated against surrogate or target predictions.
• Metrics are computed to distinguish intended misclassification from accidental correction, which is important because ACR is intended to fix a blind spot in standard attack metrics.
Repository structure as a diagram-friendly view
• Top-level experiment driver
- train_BIA_ours.py
- configured by utee/parser.py
• Data layer
- datasets/paths.py
- datasets/imagenet/
- datasets/DCL_finegrained/
- top-level dataset helpers in datasets/train.py and datasets/eval.py
• Model layer
- attack generator implementations in generator/
- surrogate classifiers in surrogate/
• Shared infrastructure
- transforms/
- utee/
• Documentation and experiment metadata
- docs/
- environment.yaml
- README dataset instructions and installation guidance
Overall architecture summary
This repository is a modular adversarial-attack research pipeline. The central flow is:
• configuration and path setup
• dataset loading and preprocessing
• generator forward pass
• surrogate model loss computation
• SCGA semantic-consistency regularization during training
• metric computation and evaluation for black-box transferability
The main architectural separation is between:
• the attack generator,
• the surrogate classifiers used for training,
• the dataset-specific loaders and transforms,
• and the shared experiment utilities that bind everything together.
Main entry points: train_BIA_ours.py Train script · surrogate Surrogates · generator Generator · DCL_finegrained Fine-grained stack
Components 24
Training
Top-level experiment orchestration
- Train script · Main experiment driver for training and evaluation
train_BIA_ours.py
Data
Dataset roots, loaders, and preprocessing
- Data root · Defines the dataset root directory used by loaders
datasets/paths.py - Dataset train · Reusable training helper for dataset flows
datasets/train.py - Dataset eval · Reusable evaluation helper for dataset flows
datasets/eval.py - ImageNet stack · ImageNet loaders, metadata, and model wrappers
datasets/imagenet - Fine-grained stack · AIR, CUB, and Stanford Cars dataset submodule
datasets/DCL_finegrained - FG datasets · Custom dataset abstractions and split-driven loaders
datasets/DCL_finegrained/dataset.py - FG transforms · Dataset-specific transforms for the fine-grained branch
datasets/DCL_finegrained/transforms.py - FG model · Dataset-side model definitions and loading support
datasets/DCL_finegrained/model.py
Models
Attack generator and surrogate classifiers
- Generator · Produces adversarial perturbations for SCGA training and transfer
generator - Gen ResNet · ResNet-based generator backbone
generator/resnet.py - Gen GAP · Generator variant with GAP-based design
generator/resnet_gap.py - Gen NAT · Generator variant with natural/normalization-specific design
generator/resnet_nat.py - Surrogates · Local substitute models used to optimize black-box transfer
surrogate - Dense169 · DenseNet-style surrogate classifier
surrogate/Dense169.py - Res152 · ResNet-152 surrogate classifier
surrogate/Res152.py - VGG16 · VGG-16 surrogate classifier
surrogate/VGG16.py - VGG19 · VGG-19 surrogate classifier
surrogate/VGG19.py
Utilities
Shared experiment infrastructure
- CLI parser · Central argument and option definitions
utee/parser.py - Normalize · Input normalization helper
utee/Normalize.py - Selector · Chooses models and components by name or config
utee/selector.py - Logger · Experiment logging and reporting
utee/logger.py - Metrics · Metric computation for attack and transfer outcomes
utee/metric.py - Transforms · Repository-wide transform and functional utilities
transforms
Connections 27
- Train script → CLI parser: reads options · Training is configured through the shared CLI parser
- Train script → Data root: resolves data · Entrypoint uses the dataset root boundary
- Train script → Dataset train: loads data · Training flow uses reusable dataset helpers
- Train script → Dataset eval: evaluates · Evaluation flow computes attack outcomes
- Train script → Generator: builds generator · Main script constructs the attack model
- Train script → Surrogates: builds surrogates · Main script constructs local proxy classifiers
- Train script → Normalize: preprocesses · Input normalization is applied before model execution
- Train script → Transforms: transforms · Shared transforms support training data pipelines
- Train script → Logger: logs · Training and evaluation results are logged
- Train script → Metrics: reports · Attack metrics are computed during evaluation
- Train script → Selector: selects components · Component selection is centralized
- Generator → Gen ResNet: implements · One generator family variant
- Generator → Gen GAP: implements · One generator family variant
- Generator → Gen NAT: implements · One generator family variant
- Surrogates → Dense169: implements · One surrogate architecture
- Surrogates → Res152: implements · One surrogate architecture
- Surrogates → VGG16: implements · One surrogate architecture
- Surrogates → VGG19: implements · One surrogate architecture
- ImageNet stack → Transforms: uses · ImageNet data pipeline relies on shared transforms
- Fine-grained stack → FG datasets: contains · Fine-grained package provides custom loaders
- Fine-grained stack → FG transforms: contains · Fine-grained package provides preprocessing
- Fine-grained stack → FG model: contains · Fine-grained package provides dataset-side model support
- Dataset train → ImageNet stack: supports · Reusable training helpers operate over ImageNet-style datasets
- Dataset train → Fine-grained stack: supports · Reusable training helpers also support the fine-grained branch
- Dataset eval → Metrics: computes · Evaluation helper feeds attack metrics
- CLI parser → Selector: drives · CLI options determine selected components
- Normalize → Transforms: pairs with · Normalization complements the shared transform layer