How nahyan0077/secure-code-analyzer-model works
1. This repository is a single-purpose machine learning system for binary vulnerability detection in C/C++ source code. Its main architectural boundary is between offline model development and online inference/explanation. The core artifact is a fine-tuned BERT-base classifier with an optimized decision threshold.
2. The data pipeline lives under src/data/. dataset_loader.py is the ingestion boundary for code samples and labels, while preprocessing.py performs code-specific normalization before tokenization. The README indicates that preprocessing is tailored to source code, including camelCase splitting and operator normalization, which materially affects model quality.
3. Model lifecycle code is split across src/model/. train.py handles training, evaluate.py computes performance metrics, predict.py is the inference entry point, and model_loader.py abstracts loading the trained model and tokenizer artifacts. This separation makes the training pipeline, evaluation pipeline, and runtime prediction path distinct.
4. The classifier itself is not a vanilla transformer-only setup; the README describes an optimized BERT-base with an MLP classifier head and class-imbalance handling. That means the architecture is likely: tokenized code input → BERT encoder → task-specific head → logits/probability → calibrated threshold decision.
5. Decision calibration is its own step. scripts/calibrate_threshold.py suggests the raw model score is not used directly; instead, a threshold is tuned to trade off recall vs precision for security triage. This is an important architectural boundary because the final “vulnerable / not vulnerable” output depends on calibration, not just the base classifier score.
6. Serving is implemented as an API layer in src/api/. main.py is the service entry point and schemas.py defines request/response contracts. The API accepts code plus a threshold override, runs the inference pipeline, and returns a vulnerability report rather than only a class label.
7. Explainability is a separate subsystem under src/explainability/. shap_explainer.py, lime_explainer.py, and global_explainer.py generate local and global token-level explanations, while visualizer.py renders them. This means the system is designed to expose both prediction and rationale, not just classification results.
8. There is an additional visualization path for demos and analysis. src/utils/visualizer.py, generate_plots.py, and src/model/predict.py with --visualize or --attention produce saved artifacts such as SHAP heatmaps, attention maps, and training/evaluation plots. Outputs are written to reports/plots/, which makes reporting a first-class part of the architecture.
9. Reporting artifacts are kept in reports/, including metrics.json and model_card.md. These serve as the handoff point between evaluation and documentation, and they also feed plot generation and presentation workflows. The repository even includes a presentation deck, reinforcing that analysis outputs are meant for human review.
10. Configuration and platform concerns are centralized in configs/config.py and src/utils/. device.py likely handles CPU/GPU selection, logger.py standardizes logging, and utils/visualizer.py supports shared plotting code. The project is packaged with pyproject.toml and uv.lock, and operationalized through Makefile targets such as setup, training, and development serving.
Main entry points: predict.py Prediction · train.py Training · preprocessing.py Preprocess code · device.py Runtime utils
Components 18
Data pipeline
Ingests and normalizes C/C++ code samples for model consumption.
- Dataset loader · Loads code samples and labels for offline and evaluation workflows.
src/data/dataset_loader.py - Preprocess code · Code-aware normalization such as camelCase splitting and operator normalization.
src/data/preprocessing.py
Model lifecycle
Training, evaluation, loading, prediction, and threshold calibration.
- Training · Fine-tunes the vulnerability classifier on prepared code data.
src/model/train.py - Evaluation · Computes validation/test metrics for the classifier.
src/model/evaluate.py - Prediction · Runs model inference and optional visualization on new code input.
src/model/predict.py - Model loader · Loads trained model and tokenizer artifacts for runtime use.
src/model/model_loader.py - BERT classifier · Fine-tuned BERT-base encoder with task-specific MLP head and class-imbalance handling.
- Threshold tuning · Converts raw scores into the final vulnerable/not-vulnerable decision.
scripts/calibrate_threshold.py
Serving API
Online request/response boundary for vulnerability inference.
- API service · Online service boundary for vulnerability analysis requests.
src/api/main.py - API schemas · Defines request and response payloads for inference and reports.
src/api/schemas.py
Explainability
Token-level and global explanation generation plus rendering.
- SHAP explainer · Generates token-level SHAP explanations for predictions.
src/explainability/shap_explainer.py - LIME explainer · Generates alternative local explanations for code inputs.
src/explainability/lime_explainer.py - Global explainer · Summarizes model behavior across datasets or sample sets.
src/explainability/global_explainer.py - XAI visualizer · Renders explanation artifacts such as heatmaps and token highlights.
src/explainability/visualizer.py
Reporting and ops
Shared runtime utilities, plotting, and persisted evaluation artifacts.
- Runtime utils · Shared device selection and logging helpers used across runtime paths.
src/utils/device.py - Plot utils · Shared plotting and saved-artifact helpers for reports and demos.
src/utils/visualizer.py - Plot generation · Produces training, evaluation, and explanation plots.
generate_plots.py - Reports · Persisted metrics and model card handoff for human review.
reports/metrics.json
Connections 24
- Dataset loader → Preprocess code: raw samples · Loads labeled code before normalization.
- Preprocess code → Training: token-ready data · Feeds normalized code into training.
- Preprocess code → Evaluation: eval data · Prepares code for metric computation.
- Preprocess code → Prediction: input code · Normalizes online inference input.
- Training → BERT classifier: fine-tunes · Produces the task-specific classifier artifact.
- BERT classifier → Model loader: model artifact · Loaded later for inference and serving.
- Model loader → Prediction: infer · Provides the trained model and tokenizer at runtime.
- Training → Threshold tuning: validation scores · Uses held-out performance to select a decision threshold.
- Threshold tuning → Prediction: decision rule · Maps probability output to final label.
- Evaluation → Reports: metrics · Persists evaluation results and model summary artifacts.
- Training → Reports: training outputs · Feeds documentation and reporting artifacts.
- API schemas → API service: contracts · Defines the service payload boundary.
- API service → Prediction: serve inference · Routes requests into the prediction pipeline.
- Prediction → SHAP explainer: optional xai · Can emit SHAP explanations for predictions.
- Prediction → LIME explainer: optional xai · Can emit LIME explanations for predictions.
- Prediction → Global explainer: analysis · Feeds explanation workflows beyond single-sample inference.
- SHAP explainer → XAI visualizer: render · Produces visual explanation artifacts.
- LIME explainer → XAI visualizer: render · Produces visual explanation artifacts.
- Global explainer → XAI visualizer: render · Visualizes aggregate explanation outputs.
- Plot utils → Plot generation: shared plots · Supports report and demo plot generation.
- Plot generation → Reports: save artifacts · Writes generated plots and analysis outputs.
- Runtime utils → Training: device/logging · Shared runtime support for training execution.
- Runtime utils → Prediction: device/logging · Shared runtime support for inference execution.
- Runtime utils → API service: service support · Shared runtime support for the API service.