Update readme

README.md

@@ -6,154 +6,226 @@ tags:
 - base_model:adapter:fdtn-ai/Foundation-Sec-8B-Instruct
 - lora
 - transformers
+- cybersecurity
+- vulnerability-remediation
+- cve
 ---
 
 # Model Card for Model ID
 
-<!-- Provide a quick summary of what the model is/does. -->
-
+LoRA adapter for `fdtn-ai/Foundation-Sec-8B-Instruct` tuned for structured CVE remediation output. The model is designed to take CVE evidence and return a fixed seven-field JSON object containing severity, affected component, root cause, and remediation guidance.
 
 
 ## Model Details
 
 ### Model Description
 
-<!-- Provide a longer summary of what this model is. -->
+This model is a parameter-efficient fine-tuning adapter built on top of `fdtn-ai/Foundation-Sec-8B-Instruct`. It is intended for structured vulnerability remediation assistance rather than open-ended chat. Given CVE evidence such as CVE ID, description, CVSS score, CWE, and affected component context, it generates a JSON response with a fixed schema:
 
+- `cve_id`
+- `severity`
+- `affected_component`
+- `technical_root_cause`
+- `recommended_fix`
+- `developer_remediation_steps`
+- `verification_steps`
 
+The adapter was evaluated in a Colab-based external benchmark on 100 CVE examples and showed strong schema adherence and high exact-match performance on most structured fields.
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+- **Developed by:** Ramitha Iddamalgoda
+- **Funded by [optional]:** Self-directed
+- **Shared by [optional]:** Ramitha Iddamalgoda
+- **Model type:** LoRA adapter for causal language modeling
+- **Language(s) (NLP):** English
+- **License:** Apache 2.0
+- **Finetuned from model [optional]:** `fdtn-ai/Foundation-Sec-8B-Instruct`
 
-### Model Sources [optional]
 
-<!-- Provide the basic links for the model. -->
+### Model Sources [optional]
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+- **Paper [optional]:** Not applicable
+- **Demo [optional]:** Not available
 
 ## Uses
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
 ### Direct Use
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+This adapter is intended for structured CVE remediation tasks where the input contains vulnerability evidence and the desired output is a constrained JSON object. Likely uses include:
 
-[More Information Needed]
+- vulnerability triage experiments
+- structured remediation drafting
+- evaluation workflows for CVE understanding
+- prototype security assistant pipelines
 
-### Downstream Use [optional]
+### Downstream Use
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+This adapter can be used inside larger systems that:
 
-[More Information Needed]
+- collect CVE descriptions from vulnerability feeds
+- normalize vulnerability information into a fixed schema
+- generate remediation suggestions for analyst review
+- compare structured output quality across model variants
 
 ### Out-of-Scope Use
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+This model should not be used as:
 
-[More Information Needed]
+- a fully autonomous security remediation engine
+- a guaranteed-safe patch recommendation system
+- a replacement for expert review in production security operations
+- a general-purpose cybersecurity assistant outside its structured CVE task
 
 ## Bias, Risks, and Limitations
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
+This model inherits limitations from the base model and from its fine-tuning data. It may produce incomplete, incorrect, outdated, or oversimplified remediation guidance. Although it performs well on the reported benchmark, the benchmark is small and not a definitive production evaluation.
 
 ### Recommendations
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+Use this model as an assistive tool, not an authoritative source. All outputs should be reviewed by a human with security context before operational use. When reporting results, describe them as an initial external benchmark rather than a final research-grade evaluation.
 
 ## How to Get Started with the Model
 
 Use the code below to get started with the model.
 
-[More Information Needed]
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+
+base_model = "fdtn-ai/Foundation-Sec-8B-Instruct"
+adapter_repo = "your-username/secfix-cve-remediation-lora"
+
+tokenizer = AutoTokenizer.from_pretrained(adapter_repo)
+model = AutoModelForCausalLM.from_pretrained(base_model, device_map="auto")
+model = PeftModel.from_pretrained(model, adapter_repo)
+model.eval()
+```
+
+Example input format:
+
+```
+CVE ID: CVE-2024-11773
+Description: SQL injection in the admin web console of Ivanti CSA before version 5.0.3 allows a remote authenticated attacker with admin privileges to run arbitrary SQL statements.
+CVSS Score: 9.8
+CWE: CWE-89
+Affected Component: Ivanti - Cloud Services Application
+```
+
+Expected output schema:
+
+```
+{
+  "cve_id": "",
+  "severity": "",
+  "affected_component": "",
+  "technical_root_cause": "",
+  "recommended_fix": "",
+  "developer_remediation_steps": "",
+  "verification_steps": ""
+}
+```
 
 ## Training Details
 
 ### Training Data
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+The adapter was trained for structured CVE remediation tasks using public CVE-oriented datasets prepared into JSONL chat-style training rows. The broader project used public CVE records with descriptions, CVSS-derived severity information, CWE information where available, and remediation-oriented text derived from source evidence.
 
-[More Information Needed]
+Datasets considered in the project included:
 
-### Training Procedure
+- AlicanKiraz0/All-CVE-Records-Training-Dataset
+- iamthierno/cvedataset.jsonl
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
+The final task format used a system prompt plus a user message containing CVE evidence, with the assistant target being a structured JSON object.
 
-#### Preprocessing [optional]
-
-[More Information Needed]
+### Training Procedure
 
+The model was fine-tuned as a LoRA adapter over fdtn-ai/Foundation-Sec-8B-Instruct for causal language modeling.
 
 #### Training Hyperparameters
 
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
+- **Training regime:** bf16 when supported, otherwise fp32
+- **LoRA rank:** 16
+- **LoRA alpha:** 32
+- **LoRA dropout:** 0.1
+- **Target modules:** `q_proj`, `k_proj`, `v_proj`, `o_proj`
+- **Epochs:** 2
+- **Max sequence length:** 2048
+- **Learning rate:** 2e-5
+- **Weight decay:** 0.05
+- **Gradient accumulation steps:** 4
+- **Effective batch size:** 16
+- **Gradient checkpointing:** enabled
 
-#### Speeds, Sizes, Times [optional]
+#### Speeds, Sizes, Times
 
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
+The adapter artifact is much smaller than the full base model because only LoRA parameters are stored. Evaluation and inference in Colab were performed using 4-bit loading for practical memory usage.
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
-
 ### Testing Data, Factors & Metrics
 
 #### Testing Data
 
-<!-- This should link to a Dataset Card if possible. -->
+The published benchmark was run on 200 examples sampled from:
 
-[More Information Needed]
+- `AlicanKiraz0/All-CVE-Records-Training-Dataset`
+
+The reported sample used a balanced severity mix:
+
+- 25 Critical
+- 25 High
+- 25 Medium
+- 25 Low
 
 #### Factors
 
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
+The evaluation focuses on:
 
-[More Information Needed]
+- structured JSON validity
+- exact-match correctness on normalized fields
+- token overlap on short text spans
+- overlap-based quality on longer remediation text
 
 #### Metrics
 
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
+The evaluation used:
 
-[More Information Needed]
+- JSON validity rate
+- required key set match rate
+- field completeness
+- exact match for `cve_id`
+- exact match and Macro-F1 for `severity`
+- exact match and Token-F1 for `affected_component`
+- exact match, Token-F1, and CWE Macro-F1 for `technical_root_cause`
+- ROUGE-L for:
+  - `recommended_fix`
+  - `developer_remediation_steps`
+  - `verification_steps`
+
+BERTScore was not computed in the published run.
 
 ### Results
 
-[More Information Needed]
+Published benchmark results:
+
+- JSON validity: `0.9400`
+- Required key match: `0.9400`
+- Field completeness: `0.9400`
+- CVE ID exact match: `0.9400`
+- Severity exact match: `0.9400`
+- Severity Macro-F1: `0.7748`
+- Affected component exact match: `0.9400`
+- Affected component Token-F1: `0.9400`
+- Technical root cause exact match: `0.9400`
+- Technical root cause Token-F1: `0.9400`
+- Technical root cause CWE Macro-F1: `0.9062`
+- Recommended fix ROUGE-L: `0.9367`
+- Developer remediation ROUGE-L: `0.9228`
+- Verification steps ROUGE-L: `0.9400`
 
 #### Summary
 
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
+On the published 100-example Colab benchmark, the adapter showed strong schema adherence and high exact-match performance across most structured fields. The weakest reported metric is severity Macro-F1, which suggests that the remaining errors are concentrated in a subset of severity classes rather than evenly distributed.
 
 ## Technical Specifications [optional]
 
@@ -163,45 +235,48 @@ Carbon emissions can be estimated using the [Machine Learning Impact calculator]
 
 ### Compute Infrastructure
 
-[More Information Needed]
+Training used NVIDIA MI300X VRAM and Google Colab for testing.
 
 #### Hardware
 
-[More Information Needed]
+- NVIDIA MI300X VRAM for training
+- Google Colab T4 GPU for evaluation
 
 #### Software
 
-[More Information Needed]
+- Transformers
+- PEFT
+- PyTorch
+- Hugging Face Hub
+- rouge-score
+- scikit-learn
 
 ## Citation [optional]
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
-
 **BibTeX:**
 
-[More Information Needed]
+```bibtex
+@misc{secfix_lora_adapter,
+  title={SecFix CVE Remediation LoRA Adapter},
+  author={Ramitha},
+  year={2026},
+  howpublished={Hugging Face model repository}
+}
+```
 
 **APA:**
 
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
+Iddamalgoda, I. H. R. P. (2026). *SecFix CVE Remediation LoRA Adapter* [LoRA adapter]. Hugging Face.
 
-## Model Card Authors [optional]
 
-[More Information Needed]
+## Glossary
 
-## Model Card Contact
+- **CVE:** Common Vulnerabilities and Exposures identifier
+- **CWE:** Common Weakness Enumeration label
+- **LoRA:** Low-Rank Adaptation, a parameter-efficient fine-tuning method
+- **ROUGE-L:** Longest-common-subsequence overlap metric for generated text
+- **Macro-F1:** Class-balanced F1 score across labels
 
-[More Information Needed]
 ### Framework versions
 
 - PEFT 0.19.1