Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,325 @@
+---
+base_model: meta-llama/Llama-3.1-8B-Instruct
+library_name: peft
+model_name: corvus-v2-8b
+license: llama3.1
+gated: true
+extra_gated_heading: "Acknowledge license to access Corvus v2"
+extra_gated_description: "Access is automatically approved after you confirm the license and intended defensive use."
+extra_gated_button_content: "Agree and get access"
+extra_gated_prompt: "By requesting access, you agree to the Llama 3.1 Community License, confirm you will use Corvus v2 for defensive vulnerability triage, and consent to share your contact details with CVERiskPilot."
+extra_gated_fields:
+  Organization: text
+  Role:
+    type: select
+    options:
+      - Security Engineer
+      - Security Leader
+      - Developer
+      - Researcher
+      - Consultant / MSSP
+      - Student
+      - Other
+  Intended use:
+    type: select
+    options:
+      - Internal vulnerability triage
+      - Client service delivery
+      - Research
+      - Evaluation / benchmarking
+      - Education
+      - Other
+  Deployment preference:
+    type: select
+    options:
+      - Local workstation
+      - Self-hosted GPU server
+      - Cloud VM / container
+      - Comparing before platform purchase
+      - Other
+  I have read and agree to the Llama Community License terms: checkbox
+  I understand Corvus v2 is for defensive vulnerability triage and not offensive security operations: checkbox
+language:
+  - en
+tags:
+  - security
+  - vulnerability-triage
+  - cybersecurity
+  - compliance
+  - lora
+  - qlora
+  - sft
+  - transformers
+  - trl
+  - gguf
+pipeline_tag: text-generation
+datasets:
+  - custom
+model_type: llama
+quantized_by: llama-cpp-python
+---
+
+# Corvus v2 — Vulnerability Triage Model
+
+**Corvus v2** is a fine-tuned Llama 3.1 8B model that produces structured triage decisions for software vulnerabilities. Given CVE data, CVSS scores, EPSS probability, KEV listing status, and asset context, it outputs a JSON decision with priority, recommended action, reasoning, and confidence score.
+
+Built by [CVERiskPilot](https://cveriskpilot.com) — 100% Veteran Owned, Texas, USA.
+
+## Why This Exists
+
+Offensive AI is accelerating. AI fuzzers are finding thousands of zero-days across every major codebase. The scanning problem is being solved. The triage problem is getting 10x harder.
+
+Security teams are drowning in findings they can't prioritize fast enough. Attackers exploit in 5 days. Defenders patch in 209. That gap gets worse every quarter.
+
+Corvus doesn't find vulnerabilities. It decides what to do about them — at machine speed, on local hardware, with no data leaving your environment.
+
+## Model Details
+
+| Property | Value |
+|----------|-------|
+| Base model | `meta-llama/Llama-3.1-8B-Instruct` |
+| Fine-tuning method | QLoRA (r=16, alpha=32, dropout=0.05) |
+| Training examples | 50,000+ labeled vulnerability triage decisions |
+| Training compute | 8x NVIDIA A100 (Vertex AI), ~1.2 hours |
+| Priority accuracy | 94.8% |
+| Full match (priority + action) | 82.7% |
+| Training loss (final) | 0.461 |
+| Throughput | 11.9 samples/sec |
+
+### Available Formats
+
+| Format | Size | Use Case |
+|--------|------|----------|
+| `corvus-v2-f16.gguf` | 16 GB | Maximum quality, needs 16GB+ VRAM |
+| `corvus-v2-q4km.gguf` | 4.6 GB | Recommended — fits 8GB GPU, minimal quality loss |
+
+## Intended Use
+
+**Use this model for:** Prioritizing and triaging software vulnerabilities in security operations workflows. Deciding which CVEs need immediate attention vs. scheduled patching vs. risk acceptance.
+
+**Do not use this model for:** Generating exploits, finding vulnerabilities, offensive security operations, or any purpose that could harm system security. This is a defensive triage tool.
+
+**Human oversight required:** Model outputs are recommendations, not autonomous decisions. All triage decisions should be reviewed by a qualified security professional before action.
+
+## Output Format
+
+Corvus outputs structured JSON with five fields:
+
+```json
+{
+  "severityOverride": "EPSS in top 1% with active exploitation — upgrading from MEDIUM to CRITICAL",
+  "priority": "CRITICAL",
+  "recommendedAction": "PATCH_IMMEDIATELY",
+  "reasoning": "CVE-2024-XXXXX affects the authentication module in a production-facing service. EPSS score of 0.94 indicates high exploitation probability. Listed in CISA KEV with a remediation deadline. The affected package is a direct dependency with no available workaround. Asset is internet-facing with access to PII.",
+  "confidenceScore": 0.92
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `severityOverride` | `string \| null` | Explanation if the model's priority differs from raw CVSS severity |
+| `priority` | `string` | `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW` |
+| `recommendedAction` | `string` | One of 6 actions (see below) |
+| `reasoning` | `string` | Detailed explanation referencing specific technical factors |
+| `confidenceScore` | `number` | 0.0 to 1.0 — model's confidence in the decision |
+
+### Action Taxonomy
+
+| Action | When to use |
+|--------|-------------|
+| `PATCH_IMMEDIATELY` | Active exploitation, critical asset, no workaround |
+| `SCHEDULE_PATCH` | Important but not actively exploited, patch available |
+| `MITIGATE` | Patch unavailable or risky — apply compensating controls |
+| `ACCEPT_RISK` | Low impact, unreachable code path, network-isolated asset |
+| `INVESTIGATE` | Insufficient data to make a confident decision |
+| `DEFER` | Non-critical, low EPSS, no KEV listing, internal-only asset |
+
+## Quick Start
+
+### Ollama (Recommended)
+
+```bash
+# Create a Modelfile
+cat > Modelfile <<'EOF'
+FROM ./corvus-v2-q4km.gguf
+
+SYSTEM """You are a senior vulnerability triage analyst. Given vulnerability data including CVE details, CVSS scores, EPSS probability, KEV listing status, and asset context, produce a structured triage decision as JSON with the following fields:
+
+- severityOverride: string or null (override reason if priority differs from CVSS)
+- priority: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW"
+- recommendedAction: "PATCH_IMMEDIATELY" | "SCHEDULE_PATCH" | "MITIGATE" | "ACCEPT_RISK" | "INVESTIGATE" | "DEFER"
+- reasoning: string (detailed explanation referencing specific technical factors)
+- confidenceScore: number between 0.0 and 1.0
+
+Output ONLY valid JSON. No markdown, no explanation outside the JSON object."""
+
+PARAMETER temperature 0.1
+PARAMETER num_predict 512
+PARAMETER stop <|eot_id|>
+PARAMETER stop <|end_of_text|>
+EOF
+
+# Import and run
+ollama create corvus-triage -f Modelfile
+ollama run corvus-triage
+```
+
+### llama.cpp
+
+```bash
+./llama-cli -m corvus-v2-q4km.gguf \
+  --temp 0.1 \
+  -p "CVE: CVE-2024-3094\nTitle: XZ Utils Backdoor\nSeverity: CRITICAL\nCVSS: 10.0\nEPSS: 0.97\nKEV: Yes\nPackage: xz-utils@5.6.0\nDescription: Malicious backdoor in XZ Utils allowing unauthorized SSH access"
+```
+
+### Python (transformers)
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model = AutoModelForCausalLM.from_pretrained(
+    "CVRP/corvus-v2-8b",
+    device_map="auto",
+    torch_dtype="auto",
+)
+tokenizer = AutoTokenizer.from_pretrained("CVRP/corvus-v2-8b")
+
+messages = [
+    {"role": "system", "content": "You are a senior vulnerability triage analyst..."},
+    {"role": "user", "content": "CVE: CVE-2024-3094\nTitle: XZ Utils Backdoor\nSeverity: CRITICAL\nCVSS: 10.0\nEPSS: 0.97\nKEV: Yes"},
+]
+
+inputs = tokenizer.apply_chat_template(messages, return_tensors="pt").to(model.device)
+outputs = model.generate(inputs, max_new_tokens=512, temperature=0.1)
+print(tokenizer.decode(outputs[0][inputs.shape[-1]:], skip_special_tokens=True))
+```
+
+## Input Format
+
+The model expects vulnerability data as a newline-separated key-value string:
+
+```
+CVE: CVE-2024-3094
+Title: XZ Utils Backdoor
+Severity: CRITICAL
+CVSS: 10.0
+EPSS: 0.97
+KEV: Yes
+Package: xz-utils@5.6.0
+Description: Malicious backdoor in XZ Utils compression library allowing unauthorized access via modified liblzma in SSH authentication path
+```
+
+### Supported Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `Title` | Yes | Vulnerability title or summary |
+| `CVE` | No | CVE identifier(s), comma-separated |
+| `Severity` | No | CVSS severity label (CRITICAL/HIGH/MEDIUM/LOW) |
+| `CVSS` | No | CVSS base score (0.0-10.0) |
+| `EPSS` | No | EPSS exploitation probability (0.0-1.0) |
+| `KEV` | No | CISA Known Exploited Vulnerabilities listing (Yes/No) |
+| `Package` | No | Affected package name and version |
+| `Description` | No | Vulnerability description (truncated to 500 chars) |
+
+The model performs best with more context. Providing EPSS, KEV, and CVSS together produces the most accurate triage decisions.
+
+## Training Data
+
+The model was trained on 50,000+ labeled vulnerability triage examples generated through a synthetic data pipeline with 6-layer quality validation:
+
+1. **Real CVE data** from NVD, GHSA, OSV, and ExploitDB
+2. **Enrichment** with EPSS scores, KEV status, and CVSS vectors
+3. **Synthetic triage decisions** generated by Claude with domain-specific prompting
+4. **6-layer quality gate** — schema validation, field completeness, reasoning coherence, action-priority alignment, confidence calibration, cross-reference consistency
+5. **Class balancing** across all 6 action types and 4 priority levels
+6. **Human review** of edge cases and override patterns
+
+The training data is not included in this release.
+
+## Evaluation
+
+Evaluated on a held-out test set of 5,000 examples:
+
+| Metric | Score |
+|--------|-------|
+| Priority accuracy (4-class) | 94.8% |
+| Action accuracy (6-class) | 84.4% |
+| Full match (priority + action) | 82.7% |
+| Confidence calibration (ECE) | 0.08 |
+
+### Known Limitations
+
+- **Trained on public CVE data only.** The model has no knowledge of proprietary or internal vulnerability disclosures.
+- **No asset topology reasoning.** The model uses asset context fields provided in the input but cannot reason about network topology or dependency chains on its own.
+- **English only.** Training data is exclusively English-language CVE descriptions.
+- **Temporal cutoff.** Training data includes CVEs through early 2026. The model may be less accurate on novel vulnerability classes that emerge after this date.
+- **Not a scanner.** Corvus triages known vulnerabilities. It does not discover, detect, or exploit vulnerabilities.
+
+## Ethical Considerations
+
+This model is designed exclusively for defensive security operations. It helps security teams prioritize remediation work, not bypass security controls.
+
+We release it openly because we believe defensive AI capabilities should not be gated behind enterprise contracts while offensive AI capabilities continue to advance. Security teams at organizations of every size deserve access to intelligent triage.
+
+The model outputs recommendations, not autonomous actions. Every decision should be reviewed by a qualified professional before implementation.
+
+## Training Procedure
+
+- **Method:** QLoRA (4-bit quantization + Low-Rank Adaptation)
+- **Rank:** 16
+- **Alpha:** 32
+- **Dropout:** 0.05
+- **Learning rate:** 2e-4 with cosine schedule
+- **Epochs:** 3
+- **Batch size:** 4 per device, gradient accumulation 4 (effective batch 128 on 8 GPUs)
+- **Optimizer:** AdamW (8-bit)
+- **Max sequence length:** 2048
+- **Compute:** 8x NVIDIA A100 80GB (Vertex AI Custom Job)
+- **Training time:** 1.2 hours (4,432 seconds)
+- **Cost:** ~$30 (Vertex AI spot pricing)
+
+### Quantization
+
+GGUF quantization performed with `llama-cpp-python`:
+
+| Quantization | Size | Quality | Use case |
+|-------------|------|---------|----------|
+| f16 | 16 GB | Full precision | Research, benchmarking |
+| Q4_K_M | 4.6 GB | Minimal loss | Production, single GPU |
+
+### Framework Versions
+
+- PEFT 0.18.1
+- TRL 1.0.0
+- Transformers 5.5.0
+- PyTorch 2.7.1+cu128
+- Datasets 4.8.4
+- Tokenizers 0.22.2
+
+## Citation
+
+```bibtex
+@misc{corvus-v2-2026,
+  title={Corvus v2: A Fine-Tuned Language Model for Vulnerability Triage},
+  author={CVERiskPilot},
+  year={2026},
+  url={https://huggingface.co/CVRP/corvus-v2-8b},
+  note={QLoRA fine-tuned Llama 3.1 8B on 50K+ vulnerability triage examples}
+}
+```
+
+## License
+
+- **Model weights:** [Llama 3.1 Community License](https://github.com/meta-llama/llama-models/blob/main/models/llama3_1/LICENSE)
+- **Modelfile, documentation, and evaluation code:** Apache 2.0
+
+## Contact
+
+- **Website:** [cveriskpilot.com](https://cveriskpilot.com)
+- **GitHub:** [github.com/cveriskpilot](https://github.com/cveriskpilot)
+- **LinkedIn:** [CVERiskPilot](https://linkedin.com/company/cveriskpilot)
+
+CVERiskPilot LLC | 100% Veteran Owned | Texas, USA