Spaces:
Configuration error
Configuration error
File size: 3,354 Bytes
e4f3d12 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 | # CommitGuard - Project Context & Instructions
This file provides the foundational context and operational mandates for the **CommitGuard** project, a Meta OpenEnv RL environment for commit-time vulnerability detection.
## Project Overview
CommitGuard is a specialized RL environment designed to train LLM agents (primarily **Llama-3.2-3B-Instruct**) to identify exploitable vulnerabilities in single-file code commits. It uses **Reinforcement Learning from Verifiable Rewards (RLVR)**, where rewards are grounded in dataset truth (Devign) rather than LLM judgment.
- **Goal:** Close the asymmetry between AI-paced code generation and human-paced security review.
- **Core Framework:** Meta OpenEnv (v0.2.3+).
- **Training Algorithm:** GRPO via TRL + Unsloth.
- **Dataset:** Preprocessed Devign (C-based commits, <80 LOC).
## Building and Running
### Environment Server
The server is built with FastAPI and can be run locally or via Docker.
- **Install:** `pip install -e .`
- **Run Local:** `server` (Runs on `http://localhost:8000`)
- **Run Docker:** `docker build -t commitguard . && docker run -p 8000:8000 commitguard`
- **Health Check:** `curl http://localhost:8000/health`
### Training & Evaluation
- **Train (GRPO):** `python scripts/train_grpo.py`
- **Baseline Curve:** `python scripts/run_and_plot_baseline.py --episodes 200`
- **Test:** `pytest` (Standard Python testing)
## Development Conventions & Mandates
### 1. The "No-Leak" Rule (Critical)
The agent must **NEVER** see ground truth labels (`is_vulnerable`, `cwe`, etc.).
- **Constraint:** Observations and HTTP responses must never contain label fields.
- **Verification:** `tests/test_no_leak.py` must remain green at all times.
### 2. Action Format (XML-Tagged)
Models must emit actions in XML format to ensure robust parsing.
- **Structure:** `<action><action_type>...</action_type>...</action>`
- **Types:** `request_context`, `analyze`, `verdict`.
### 3. Systematic Documentation (`.agent/`)
This project uses a structured `.agent/` directory for internal state and contracts. Always consult these before changes:
- `.agent/project_context.md`: Single source of truth for project state.
- `.agent/architecture.md`: Technical contracts and schemas.
- `.agent/test_contracts.md`: Merge-blocking requirements.
### 4. Deadline Operations (Hackathon Mode)
- **Scope Freeze:** Midnight Saturday IST. No new features after this point.
- **Pivots:** If technical blockers arise (e.g., OOM, slow queues), immediately use the pre-approved fallbacks documented in `prd.md` and `.agent/project_context.md`.
## Directory Structure
- `commitguard_env/`: Core environment logic, FastAPI server, and reward modeling.
- `scripts/`: Training entrypoints, preprocessing scripts, and GCE runbooks.
- `data/`: Dataset placeholders (`devign_filtered.jsonl`) and CWE mapping.
- `plots/`: Generated reward curves and performance artifacts.
- `tests/`: Smoke tests, reward validation, and leak detection.
- `.agent/`: High-priority architectural and process documentation.
## Key Endpoints
- `POST /reset`: Initialize episode, returns diff + available files.
- `POST /step`: Submit XML action, returns `{observation, reward, done, info}`.
- `GET /health`: Server status.
- `GET /state`: Episode metadata (safe for agent logs).
|