---
language:
  - bs
  - en
  - de
library_name: transformers
license: mit 
base_model: xlm-roberta-base 
tags: 
- email-security
- phishing-detection
- cybersecurity
- nlp
- transformers
- xlm-roberta
- generated_from_trainer
metrics: 
- accuracy
- precision
- recall
- f1 
---
<p align="center">
  <img src="https://huggingface.co/MujMej/phishguard-ai/resolve/main/banner.png" alt="PhishGuard AI Banner" width="100%">
</p>


# PhishGuard AI — Model za detekciju prijetnji u elektronskoj pošti / Email Threat Detection Model (Risk Edition)


**PhishGuard AI** je inteligentni model mašinskog učenja koji koristi **prirodnojezičnu obradu (NLP)** za klasifikaciju elektronskih poruka kao **phishing**, **spam** ili **legitimnih**.
Model je razvijen i fino podešen na osnovu *XLM-RoBERTa* arhitekture i kombinovan sa **heurističkom analizom** (prepoznavanje ključnih riječi, gustoće URL-ova i strukture mejla).
Cilj modela je pružiti **brzu i automatsku analizu rizika** e-mail poruka u kontekstu sajber bezbjednosti i edukacije.

---

##  Opis i arhitektura modela / Model Overview

Model koristi **XLM-RoBERTa-Base** (multijezična varijanta RoBERTa) i treniran je na datasetima koji sadrže stvarne i simulirane primjere phishing i spam poruka.
Klasifikacija se zasniva na tekstualnim obrascima, kontekstu, emocionalnom tonu i ključnim riječima koje ukazuju na socijalni inženjering.

**Output labele:**

* `PHISH` – lažne poruke koje imitiraju legitimne organizacije s ciljem krađe podataka
* `SPAM` – neželjene marketinške ili promotivne poruke
* `LEGIT` – legitimne, neškodljive poruke

---

##  Skup podataka i obuka / Dataset & Training Data

Model je treniran na kombinovanom datasetu koji uključuje:

* **Kaggle Phishing Email Dataset (2023)**
* Prošireni skup na **bosanskom, engleskom i njemačkom jeziku**, prikupljen i označen ručno
* Filtrirane primjere neželjenih marketinških mejlova

Podaci su očišćeni, normalizovani, tokenizovani i podijeljeni u omjeru **80 % trening / 20 % validacija**.
Trening je obavljen pomoću **PyTorch** biblioteke i **Transformers (Hugging Face)** okvira.

---

##  Parametri obuke / Training Hyperparameters

| Parametar      | Vrijednost / Value           |
| -------------- | ---------------------------- |
| Broj epoha     | 3                            |
| Batch veličina | 16                           |
| Learning rate  | 2e-5                         |
| Optimizator    | AdamW (weight decay 0.01)    |
| Scheduler      | Linear                       |
| GPU            | NVIDIA T4 (Google Colab Pro) |

---

##  Rezultati evaluacije / Evaluation Metrics

| Metrika   | Vrijednost / Value |
| --------- | -----------------: |
| Loss      |             0.0812 |
| Accuracy  |             0.9677 |
| Precision |             0.9649 |
| Recall    |             0.9701 |
| F1 Score  |             0.9674 |

Model pokazuje visoku preciznost i odziv kod identifikacije phishing poruka (preko 96 %), uz minimalnu stopu lažnih pozitivnih rezultata (ispod 2 %).
Najveći broj grešaka dešava se kod poruka koje su po strukturi vrlo slične legitimnim obavještenjima.

---

##  Integracija s PhishGuard AI aplikacijom / Integration with App

Model je implementiran unutar web aplikacije **PhishGuard AI – Risk Edition**, koja omogućava:

* učitavanje `.eml` fajlova
* automatsko izvlačenje sadržaja, URL-ova i pošiljaoca
* NLP analizu putem modela
* heurističko bodovanje i vizualizaciju doprinosa (AI vs Heuristika)

> 🔗 [Online demo on Hugging Face Space](https://huggingface.co/spaces/MujMej/phishguard-ai)

---

##  Integracija s heuristikom / Heuristic Integration

Aplikacija kombinuje rezultate modela i heurističke funkcije:

* AI analiza (semantička detekcija phishing sadržaja)
* Heuristika (broj URL-ova, ključne riječi, obrasci sumnjivog ponašanja)
* Kombinovani rizik = 60 % NLP + 40 % heuristika

Rezultat je vizualizovan kroz grafikon koji prikazuje doprinos oba pristupa.

---

##  Prednosti / Model Strengths

 Multijezična podrška (B/H/S, engleski, njemački)
 Visoka preciznost i brzina obrade
 Može se koristiti lokalno bez interneta
 Kombinacija AI i heuristike povećava tačnost
 Edukativna i istraživačka primjena

---

##  Ograničenja / Limitations

* Ne analizira zaglavlja (SPF, DKIM, DMARC) ni priloge
* Oslanja se na tekstualni sadržaj mejla
* Neki mejlovi s minimalnim sadržajem mogu proizvesti neodređene rezultate
* Hugging Face Spaces sandbox ne dozvoljava vanjske API pozive (VirusTotal, AbuseIPDB)

---

##  Projekat i upotreba / Project Context

PhishGuard AI je kreiran kao u sklopu diplomskog rada na temu ML u Pythonu i je dio većeg istraživačkog projekta **S.AF.E — Security Awareness for Families & Education**,
usmjerenog na edukaciju i prevenciju digitalnih prijetnji u BiH kroz praktične alate i podizanje svijesti o sajber bezbjednosti.
Model se koristi i u verziji za lokalnu analizu (offline), koja uključuje reputacione servise VirusTotal i AbuseIPDB.

---

##  Citat / Citation

> Mujanović, M. (2025). *PhishGuard AI – Risk Edition: Multijezični NLP model za detekciju prijetnji u elektronskoj pošti.*
> Hugging Face Model Repository. [https://huggingface.co/MujMej/phishguard-ai](https://huggingface.co/MujMej/phishguard-ai)

---

##  Etički aspekt / Ethical Use

Model je razvijen isključivo za **edukativne i defanzivne** svrhe u oblasti sajber bezbjednosti.
Zabranjeno je korištenje u svrhe napada, masovnog skeniranja ili distribucije phishing sadržaja.
Svi podaci korišteni u treningu su javno dostupni i ne sadrže lične informacije.

---

## 📬 Kontakt / Contact

**Autor / Author:** Mejra Mujanović
**Projekat / Project:** S.AF.E — Security Awareness for Families & Education
**Email:** mejrajob@gmail.com
**Model:** [https://huggingface.co/MujMej/phishguard-ai](https://huggingface.co/MujMej/phishguard-ai)