Update README.md

README.md

@@ -1,27 +1,190 @@
-
 ---
+language: en
 library_name: transformers
+pipeline_tag: token-classification
 tags:
-- autotrain
+- ner
 - token-classification
-base_model: answerdotai/ModernBERT-large
-widget:
-- text: "I love AutoTrain"
+- cybersecurity
+- threat-intelligence
 datasets:
-- juanmcristobal/ner-ioc-dataset3
+- juanmcristobal/secureModernBert2
 ---
 
-# Model Trained Using AutoTrain
+# SecureModernBERT-NER
+
+SecureModernBERT-NER is a ModernBERT-base model fine-tuned to recognise named entities that appear in cyber-threat intelligence (CTI) narratives. It predicts BIO-formatted tags for 22 security-specific entity types (e.g., `MALWARE`, `THREAT-ACTOR`, `CVE`, `IPV4`, `URL`). The model is suitable for extracting indicators of compromise and contextual metadata from English-language threat reports, product advisories, and incident write-ups.
+
+## Quick Start
+
+```python
+from transformers import pipeline
+
+model_id = "juanmcristobal/autotrain-sec4"
+
+pipe = pipeline(
+    task="token-classification",
+    model=model_id,
+    tokenizer=model_id,
+    aggregation_strategy="first",
+)
+
+text = "TrickBot connects to hxxp://185.222.202.55 to exfiltrate data from Windows hosts."
+predictions = pipe(text)
+for pred in predictions:
+    print(pred)
+```
+
+Sample output:
+
+```
+{'entity_group': 'MALWARE', 'score': np.float32(0.9615546), 'word': 'TrickBot', 'start': 0, 'end': 8}
+{'entity_group': 'URL', 'score': np.float32(0.9905957), 'word': ' hxxp://185.222.202.55', 'start': 20, 'end': 42}
+{'entity_group': 'PLATFORM', 'score': np.float32(0.92317337), 'word': ' Windows', 'start': 66, 'end': 74}
+```
+
+## Intended Use & Limitations
+
+- **Use cases:** automated tagging of CTI reports, IOC extraction pipelines, knowledge-base enrichment, security-focused RAG systems.
+- **Languages:** English (model was trained and evaluated on English sources only).
+- **Input format:** free-form prose or long-form CTI articles; maximum sequence length 128 tokens during training.
+- **Limitations:** noisy or ambiguous extractions may occur, especially with rare entity types (`IPV6`, `EMAIL`) and obfuscated strings. The model does not normalise entities (e.g., deobfuscating `hxxp`) nor validate indicator authenticity. Always pair with downstream validation and human review.
+
+## Training Data
+
+- **Source:** curated CTI corpus derived from the `dataset_20251024_1.jsonl` snapshot and published on the Hub as [`juanmcristobal/ner-ioc-dataset3`](https://huggingface.co/datasets/juanmcristobal/ner-ioc-dataset3) (earlier iterations remain available under `secureModernBert2`).
+- **Size:** 502,726 labelled text spans before filtering; 22 distinct entity classes in BIO format.
+- **Label distribution (spans):** `ORG` (~198k), `PRODUCT` (~79k), `MALWARE` (~67k), `PLATFORM` (~57k), `THREAT-ACTOR` (~49k), `SERVICE` (~46k), `CVE` (~41k), `LOC` (~38k), `SECTOR` (~34k), `TOOL` (~29k), plus indicator types such as `URL`, `IPV4`, `SHA256`, `MD5`, and `REGISTRY-KEYS`.
+- **Pre-processing:** JSONL articles were tokenised and converted to BIO tags; spans in conflict were resolved manually and via automated heuristics before upload.
+
+## Label Mapping
+
+```
+ 0 -> B-URL
+ 1 -> I-URL
+ 2 -> O
+ 3 -> B-ORG
+ 4 -> B-SERVICE
+ 5 -> I-ORG
+ 6 -> B-SECTOR
+ 7 -> I-SECTOR
+ 8 -> B-FILEPATH
+ 9 -> I-FILEPATH
+10 -> I-DOMAIN
+11 -> B-PLATFORM
+12 -> I-SERVICE
+13 -> I-PLATFORM
+14 -> B-THREAT-ACTOR
+15 -> I-THREAT-ACTOR
+16 -> B-PRODUCT
+17 -> B-MALWARE
+18 -> I-MALWARE
+19 -> B-LOC
+20 -> B-CVE
+21 -> I-CVE
+22 -> B-TOOL
+23 -> I-PRODUCT
+24 -> B-IPV4
+25 -> I-IPV4
+26 -> B-MITRE-TACTIC
+27 -> I-MITRE-TACTIC
+28 -> B-DOMAIN
+29 -> I-TOOL
+30 -> B-MD5
+31 -> I-LOC
+32 -> B-CAMPAIGN
+33 -> I-CAMPAIGN
+34 -> B-SHA1
+35 -> B-SHA256
+36 -> B-EMAIL
+37 -> I-EMAIL
+38 -> B-IPV6
+39 -> I-IPV6
+40 -> B-REGISTRY-KEYS
+41 -> I-REGISTRY-KEYS
+```
+
+The `B-` prefix marks the first token of an entity span, while `I-` marks subsequent tokens within the same span. The base labels are described below.
+
+| Label | Description | Example mention |
+|-------|-------------|-----------------|
+| URL | Web address or obfuscated link used in campaigns. | `hxxp://185.222.202.55` |
+| ORG | Organisations such as companies, CERTs, or research groups. | `Microsoft Threat Intelligence` |
+| SERVICE | Online or cloud services referenced in attacks. | `Google Ads` |
+| SECTOR | Industry sectors or verticals targeted. | `critical infrastructure` |
+| FILEPATH | File system paths observed in malware samples. | `C:\Windows\System32\svchost.exe` |
+| DOMAIN | Fully qualified domains or subdomains. | `malicious-domain[.]com` |
+| PLATFORM | Operating systems or computing platforms. | `Windows Server` |
+| THREAT-ACTOR | Named adversary groups or aliases. | `LockBit` |
+| PRODUCT | Commercial or open-source software products. | `VMware ESXi` |
+| MALWARE | Malware families, strains, or toolkits. | `TrickBot` |
+| LOC | Countries, cities, or regions. | `United States` |
+| CVE | CVE identifiers for vulnerabilities. | `CVE-2023-23397` |
+| TOOL | Legitimate or dual-use tools leveraged in incidents. | `Cobalt Strike` |
+| IPV4 | IPv4 addresses. | `185.222.202.55` |
+| MITRE-TACTIC | MITRE ATT&CK tactic categories. | `Credential Access` |
+| MD5 | MD5 cryptographic hashes. | `d41d8cd98f00b204e9800998ecf8427e` |
+| CAMPAIGN | Named operations or campaigns. | `Operation Cronos` |
+| SHA1 | SHA-1 hashes. | `da39a3ee5e6b4b0d3255bfef95601890afd80709` |
+| SHA256 | SHA-256 hashes. | `9e107d9d372bb6826bd81d3542a419d6...` |
+| EMAIL | Email addresses. | `alerts@example.com` |
+| IPV6 | IPv6 addresses. | `2001:0db8:85a3:0000:0000:8a2e:0370:7334` |
+| REGISTRY-KEYS | Windows registry keys or paths. | `HKLM\Software\Microsoft\Windows\CurrentVersion\Run` |
+
+## Training Procedure
+
+- **Project:** `autotrain-sec4` running inside a Hugging Face AutoTrain Space (local hardware mode).
+- **Base model:** [`answerdotai/ModernBERT-large`](https://huggingface.co/answerdotai/ModernBERT-large).
+- **Dataset configuration:** training and validation splits pulled from `juanmcristobal/ner-ioc-dataset3` with column mapping `tokens` → tokens, `tags` → labels.
+- **Optimisation setup:** mixed precision `fp16`, optimiser `adamw_torch`, cosine learning-rate scheduler, gradient accumulation `1`.
+- **Key hyperparameters:** learning rate `5e-5`, batch size `128`, epochs `5`, maximum sequence length `128`.
+- **Checkpoint:** best-performing checkpoint automatically pushed to the Hub as `juanmcristobal/autotrain-sec4`.
+
+| Parameter | Value |
+|-----------|-------|
+| Mixed precision | `fp16` |
+| Batch size | `128` |
+| Learning rate | `5e-5` |
+| Optimiser | `adamw_torch` |
+| Scheduler | `cosine` |
+| Epochs | `5` |
+| Gradient accumulation | `1` |
+| Max sequence length | `128` |
+
+## Evaluation
+
+Validation metrics reported by AutoTrain on the held-out split:
+
+| Metric     | Score  |
+|------------|--------|
+| Precision  | 0.8468 |
+| Recall     | 0.8484 |
+| F1         | 0.8476 |
+| Accuracy   | 0.9589 |
+
+These metrics were computed with the `seqeval` micro-average at the entity level.
+
+## Responsible Use
 
-- Problem type: Token Classification
+- Confirm entity detections before acting on indicators (e.g., automated blocking).
+- Combine with enrichment and scoring systems to filter false positives.
+- Monitor for drift if applying to new domains (e.g., non-English sources, informal channels).
+- Respect licensing and confidentiality of any proprietary CTI sources used for inference.
 
-## Validation Metrics
-loss: 0.080692358314991
+## Citation
 
-precision: 0.8956920811279763
+If you find this model useful, please cite the repository and the base model:
 
-recall: 0.9126250733540829
+```
+@software{securemodernbert_ner_2025,
+  author = {Juan M. Cristobal},
+  title = {SecureModernBERT-NER: Cyber Threat Intelligence Named Entity Recogniser},
+  year = {2025},
+  publisher = {Hugging Face},
+  url = {https://huggingface.co/juanmcristobal/autotrain-sec4}
+}
+```
 
-f1: 0.9040792973909716
+## Contact
 
-accuracy: 0.9731636716504077
+Questions or feedback? Open an issue on the Hugging Face model repository or reach out at [`@juanmcristobal`](https://huggingface.co/juanmcristobal).