Improve model card: add Intended Use, Training, Limitations, Citation sections

README.md

@@ -34,22 +34,57 @@ model-index:
 
 # Malware Detection LightGBM
 
-LightGBM-based static malware detector for PE files.
+LightGBM-based static malware detector for PE (Portable Executable) files. Classifies Windows executables as benign or malicious using structural PE header features.
+
+## Intended Use
+
+- **Primary**: Static analysis of PE files for malware classification
+- **Secondary**: Educational demonstration of ML-based malware detection
+- **Not suitable for**: Dynamic analysis, packed/obfuscated samples, or production-grade antivirus replacement
+
+## Training Data
+
+- **Dataset**: [fabriciojoc/brazilian-malware-dataset](https://huggingface.co/datasets/fabriciojoc/brazilian-malware-dataset)
+- **Features**: Structural PE header fields (imports, sections, resources, etc.)
+- **Split**: 80/20 train/test with stratification
+
+## Training Procedure
+
+- **Model**: LightGBM (gradient boosting)
+- **Preprocessing**: Custom pipeline in `preprocessing_pipeline.joblib`
+- **Hyperparameters**: See `model_metrics.json` for full configuration
 
 ## Performance (hold-out test set)
 
-- AUC: `0.9978`
-- Accuracy: `0.9895`
-- Confusion matrix: `[[4158, 66], [39, 5774]]`
+| Metric | Value |
+|--------|-------|
+| AUC | 0.9978 |
+| Accuracy | 0.9895 |
+| Confusion Matrix | [[4158, 66], [39, 5774]] |
 
 ## Artifacts
 
-- `production_model.joblib`
-- `preprocessing_pipeline.joblib`
-- `feature_names.json`
+- `production_model.joblib` - trained LightGBM model
+- `preprocessing_pipeline.joblib` - feature extraction pipeline
+- `feature_names.json` - feature name mapping
+- `model_metrics.json` - training metrics and configuration
+
+## Limitations
+
+- Trained on PE header features only; does not analyze code behavior
+- Performance may degrade on obfuscated or packed samples
+- Tested on Brazilian malware dataset; generalization to other regions unverified
+
+## Citation
 
-## Notes
+If you use this model, please cite the original dataset:
 
-- This repository contains model artifacts only.
-- For large CSV batch inference, use the Render app:
-  `https://malware-detection-ml-mihai.onrender.com/upload`
+```bibtex
+@dataset{fabriciojoc2024brazilian-malware,
+  author = {Fabricio, Joc},
+  title = {Brazilian Malware Dataset},
+  year = {2024},
+  publisher = {Hugging Face},
+  url = {https://huggingface.co/datasets/fabriciojoc/brazilian-malware-dataset}
+}
+```