README_SUBMISSION.md

# CommitGuard  AI-Paced Security Review (Meta OpenEnv Hackathon)

> "Defense is on human time, offense is on AI time. CommitGuard closes that asymmetry."

##  The Vision
AI coding agents are shipping production code at 100x human velocity. Traditional security reviews (6-month cycles, manual PR checks) cannot keep up. **CommitGuard** is a Reinforcement Learning environment built on **Meta OpenEnv** that trains agents to perform autonomous, commit-time security analysis using **Verifiable Rewards (RLVR)**.

##  The Environment
CommitGuard turns code commits into a multi-step investigation game:
1.  **Analyze:** The agent performs Chain-of-Thought reasoning.
2.  **Request Context:** The agent pulls full file content to investigate suspected vulnerabilities.
3.  **Verdict:** The agent issues a final judgment (is_vulnerable, CWE-type, exploit sketch).



**Rewards:**

- +1.0 for correct binary verdict.

- +0.5 for correct CWE classification.

- Up to +0.5 (continuous float) for accurate exploit keyword matching.

- Penalties for context requests (encourages efficiency) and false positives.



##  Results & Learning Curves

We trained **Llama-3.2-3B-Instruct** using **GRPO** via TRL and Unsloth.



### 1. Training Reward Curve

![Reward Curve](plots/reward_curve.png)

*The reward curve shows the model learning to prioritize accuracy while maintaining investigation efficiency.*



### 2. Detection Accuracy: Baseline vs. Trained

![Accuracy Comparison](plots/baseline_vs_trained.png)

*Our trained agent improved detection accuracy from **50%** (baseline) to **74%**.*



### 3. Per-CWE Breakdown

![CWE Breakdown](plots/per_cwe.png)

*The model showed significant improvements in detecting **CWE-89 (SQL Injection)** and **CWE-119 (Buffer Overflow)**.*



##  Demo Video

[![Watch the Demo](https://img.shields.io/badge/YouTube-Watch%20Demo-red)](<LINK_TO_YOUTUBE>)

*Watch as a trained CommitGuard agent requests context to identify a complex privilege escalation vulnerability that the baseline model missed.*



##  Links

- **HF Space (Env):** [https://huggingface.co/spaces/Nitishkumar-ai/commitguard](https://huggingface.co/spaces/Nitishkumar-ai/commitguard)

- **Training Notebook:** [Link](<LINK_TO_NOTEBOOK>)

- **W&B Training Logs:** [Link](<LINK_TO_WANDB>)

- **HF Blog Post:** [Link](<LINK_TO_BLOG>)



##  Technical Stack

- **Framework:** Meta OpenEnv 0.1.13

- **RL Algorithm:** GRPO (Group Relative Policy Optimization)

- **Training:** TRL + Unsloth (4-bit LoRA)

- **Compute:** HF Jobs (A10G)



---

*Developed by Team CommitGuard: Niti, Deepak, Divyank*