How thivakar101/code-vulnerability-guardian works
Purpose and Entry Points
Code Vulnerability Guardian is a local web-based source-code security scanner. It combines fast regex detection with local-LLM review, and includes a separate LoRA fine-tuning pipeline for vulnerability-focused model adaptation. Runtime entry points are app.py for the Flask service and finetune.py for training.
Web Application Boundary
The Flask backend serves the scanner UI, accepts uploaded source files or ZIP archives, orchestrates analysis, and returns findings to the browser. The presentation layer is deliberately thin:
• app.py
• templates/index.html
• static/style.css
The browser is an operator interface, not the analysis engine; upload handling and model routing remain server-side.
Stage 1: Static Heuristic Scan
The backend performs an immediate rule-based pass over submitted source content. This layer targets recognizable high-risk patterns such as dynamic execution, shell-command invocation, embedded secrets, unsafe deserialization, and weak cryptography. Its purpose is low-latency, deterministic findings before AI analysis.
• app.py
Stage 2: Local LLM Security Review
After heuristic scanning, the backend submits code/context to a local LLM provider, described as Ollama with models such as Llama 3. The expected result is structured security analysis containing summary, severity, and remediation information. This is an external-process/service boundary: availability and output quality depend on the locally running model service rather than Flask itself.
• app.py
Scan Data Flow
User upload flows from the HTML interface into Flask. Flask processes individual code files or expands ZIP contents, applies regex rules, then coordinates deep LLM review. Results are returned to the UI for visual inspection and security-assistant interaction. The main control-flow owner is:
• app.py
• templates/index.html
Fine-Tuning Pipeline
finetune.py is an offline ML workflow, separate from request-time scanning. It loads vulnerability training records, tokenizes them, trains a causal language model using PEFT/LoRA, and writes adapter artifacts/checkpoints. The default proof-of-concept model is CPU-friendly DialoGPT-small; the design can be retargeted to Llama-family models with CUDA and appropriate LoRA target modules.
• finetune.py
• data.jsonl
• cpu_finetune/adapter_model.safetensors
Model Artifacts and Training State
The repository contains a completed/exported adapter plus resumable checkpoints. The root adapter directory is the likely inference-ready fine-tune output; checkpoint directories retain optimizer, scheduler, tokenizer, and trainer state for continuing training.
• cpu_finetune/adapter_config.json
• cpu_finetune/checkpoint-25/trainer_state.json
• cpu_finetune/checkpoint-50/optimizer.pt
Runtime and Infrastructure
Request-time infrastructure is Python/Flask plus HTTP communication to a local Ollama-hosted LLM. Training requires PyTorch, Hugging Face Transformers/Datasets, and PEFT; CPU execution is supported for the default model, while larger Llama training requires CUDA-capable GPU infrastructure. Dependency declarations are centralized in:
• requirements.txt
• verifygpusupport.py
Main entry points: finetune.py LoRA training workflow · app.py Flask scanner service · index.html Scanner UI · requirements.txt Dependencies
Components 18
Request-time scanner
Local Flask application and scan stages.
- Scanner UI
templates/index.html - UI styles
static/style.css - Flask scanner service · Owns uploads, scan orchestration, and result responses.
app.py - Source upload · Individual source files or ZIP archives.
- ZIP expansion
app.py - Regex heuristic scan · Fast deterministic checks for risky code patterns.
app.py - Scan findings · Combined heuristic and LLM results for the operator.
app.py
Local model service
LLM review runs outside the Flask process.
- Ollama service · Locally running model-service boundary.
- Security review · Returns summary, severity, and remediation.
app.py
Offline fine-tuning
Separate LoRA adaptation workflow.
- Vulnerability records
data.jsonl - LoRA training workflow · Tokenizes records and trains a causal language model.
finetune.py - Base causal model · Defaults to CPU-friendly DialoGPT-small; can target Llama models.
finetune.py - Exported LoRA adapter · Likely inference-ready fine-tune output.
cpu_finetune/adapter_model.safetensors - Adapter configuration
cpu_finetune/adapter_config.json - Resumable checkpoints · Retains trainer, optimizer, scheduler, and tokenizer state.
cpu_finetune/checkpoint-25/trainer_state.json - Optimizer state
cpu_finetune/checkpoint-50/optimizer.pt - GPU capability check · Supports deciding CPU versus CUDA training.
verifygpusupport.py
Other components
- Dependencies · Declares Flask, training, and ML dependencies.
requirements.txt
Connections 19
- UI styles → Scanner UI: styles
- Scanner UI → Source upload: submits
- Source upload → Flask scanner service: received by
- Flask scanner service → ZIP expansion: expands ZIPs
- Flask scanner service → Regex heuristic scan: scans source
- Flask scanner service → Security review: requests deep review
- Security review → Ollama service: uses HTTP
- Regex heuristic scan → Scan findings: deterministic findings
- Security review → Scan findings: structured analysis
- Scan findings → Scanner UI: renders results
- Vulnerability records → LoRA training workflow: loads records
- Base causal model → LoRA training workflow: adapted with LoRA
- LoRA training workflow → Exported LoRA adapter: exports
- LoRA training workflow → Adapter configuration: writes
- LoRA training workflow → Resumable checkpoints: saves state
- LoRA training workflow → Optimizer state: persists optimizer
- GPU capability check → LoRA training workflow: guides hardware mode
- Dependencies → Flask scanner service: supports
- Dependencies → LoRA training workflow: supports