Skip to main content
Glama
hebrew-scam-shield-mcp

hebrew-scam-shield-mcp

by benziRaz
README.md
# Hebrew Scam Shield 🛡️

**Explainable scam and phishing detection for Hebrew messages (SMS, WhatsApp, e-mail).**
Zero dependencies, a command-line tool, a Python library, and an [MCP](https://modelcontextprotocol.io) server so AI assistants can check messages for you.

[עברית ↓](#עברית)

Fake "your parcel is held" texts, fake government and bank alerts, fake emergency-app links: these messages reach everyone, but they hurt most the people who are least likely to have help at hand: elderly people, new internet users, and communities that are under-served by mainstream security tools. Most scam filters are built for English. Hebrew Scam Shield is built for Hebrew, and every verdict comes with a plain-language reason, so the person (or the assistant) can understand *why* a message looks dangerous.

## Quick start

```bash
pip install "hebrew-scam-shield[mcp] @ git+https://github.com/benziRaz/hebrew-scam-shield"

hebrew-scam-shield "דואר ישראל: החבילה שלך לא ניתנת למסירה. אשר כתובת תוך 12 שעות http://israelpost-il.top/x"
```

```
HIGH RISK  (score 90/100)
  +25  Claims a parcel/delivery problem (address, payment, customs) - a very common lure.
  +15  Creates artificial urgency or threatens a deadline.
  +15  Link uses a top-level domain that is rarely used by genuine services.  [http://israelpost-il.top/x]
  +5  Link is not encrypted (http).  [http://israelpost-il.top/x]
  +30  Domain contains a known brand/institution name but is not that organisation's domain.  [http://israelpost-il.top/x]
```

Use `--lang he` for Hebrew explanations and `--json` for machine-readable output. Exit codes: `0` low, `1` suspicious, `2` high.

### As a library

```python
from hebrew_scam_shield import analyze

result = analyze(message_text)
result.level      # "low" | "suspicious" | "high"
result.score      # 0-100
result.reasons    # list of Reason(id, weight, en, he, detail)
```

### As an MCP server (for Claude and other assistants)

```json
{
  "mcpServers": {
    "hebrew-scam-shield": { "command": "hebrew-scam-shield-mcp" }
  }
}
```

The server exposes one tool, `check_message(text)`. Ask your assistant: *"Is this message a scam?"* and paste the text.

## What it looks for

| Signal | Example |
|---|---|
| Parcel / customs / address problem | "החבילה לא ניתנת למסירה, אשר כתובת" |
| Artificial urgency | "תוך 12 שעות", "אחרת החשבון ייחסם" |
| Government / bank impersonation with an account problem | "פעילות חריגה בחשבון" + link |
| Requests for verification codes, passwords, card data | "הזן את קוד האימות" |
| Fake emergency or "security update" app installs | "הורד את האפליקציה" |
| Prize and voucher lures | "זכית בשובר" |
| Wallet-linking tricks | "לקשר Apple Pay לשחרור החבילה" |
| "Reply Y to activate the link" | "השב Y" |
| Suspicious links | shorteners, look-alike brand domains, odd TLDs, raw IPs, `@` tricks, `.apk` files, punycode |
| Evasion | zero-width characters, niqqud |

Rules live in [`rules.py`](src/hebrew_scam_shield/rules.py) as readable data (weight + English/Hebrew explanation + regex groups). Sources are listed in [docs/PATTERNS.md](docs/PATTERNS.md).

## Honest limitations

- It is a **heuristic**, not a guarantee. A low score does not prove a message is safe; a high score does not prove it is malicious.
- Rules are public, so determined scammers can study them. Use this as one layer of defence, not the only one.
- The list of official domains is short and non-exhaustive. Pull requests that add verified domains are very welcome.
- It was built from public warnings, not from a private corpus of real messages, so expect false positives and gaps.
- Not affiliated with the Israel National Cyber Directorate. If you receive a suspicious message in Israel, you can report it to the national **119** hotline.

## Contributing

New scam patterns, official domains and false-positive reports are the most valuable contributions. See [CONTRIBUTING.md](CONTRIBUTING.md). **Never paste real personal data into issues**: redact names, phone numbers and ID numbers first.

```bash
pip install -e ".[mcp,dev]"
pytest
```

License: [MIT](LICENSE)

---

<a name="עברית"></a>
<div dir="rtl">

## עברית

**זיהוי הונאות והודעות פישינג בעברית, עם הסבר לכל החלטה.**
הכלי עובד על SMS, וואטסאפ ומייל, בלי תלויות חיצוניות, ומגיע כשורת פקודה, כספרייה בפייתון וכשרת MCP שמאפשר לעוזרי AI לבדוק הודעות עבורך.

הודעות על "חבילה שנתקעה", התראות מזויפות מהבנק או מהמדינה וקישורים לאפליקציות חירום מזויפות מגיעות לכולם, אבל הנזק גדול במיוחד אצל מי שאין לידו מי שיעזור: קשישים, גולשים חדשים וקהילות שכלי האבטחה הרגילים לא בנויים בשבילן. רוב המסננים נכתבו לאנגלית. הכלי הזה נבנה לעברית, וכל תוצאה מלווה בהסבר ברור למה ההודעה נראית מסוכנת.

### התקנה ושימוש

```bash
pip install "hebrew-scam-shield[mcp] @ git+https://github.com/benziRaz/hebrew-scam-shield"
hebrew-scam-shield --lang he "דואר ישראל: החבילה שלך לא ניתנת למסירה. אשר כתובת תוך 12 שעות http://israelpost-il.top/x"
```

קוד יציאה: `0` סיכון נמוך, `1` חשוד, `2` סיכון גבוה.

### מגבלות

- זו הערכה לפי כללים ולא ודאות. ציון נמוך לא מוכיח שההודעה בטוחה, וציון גבוה לא מוכיח שהיא זדונית.
- הכללים פומביים, ולכן נוכלים נחושים יכולים ללמוד אותם. כדאי להשתמש בכלי כאחת משכבות ההגנה ולא כשכבה יחידה.
- רשימת הדומיינים הרשמיים קצרה וחלקית. תוספות מאומתות יתקבלו בברכה.
- הכלי לא קשור למערך הסייבר הלאומי. מי שקיבל הודעה חשודה בישראל יכול לדווח לקו 119.

### תרומה לפרויקט

דפוסי הונאה חדשים, דומיינים רשמיים מאומתים ודיווחים על התראות שווא הם התרומה הכי חשובה. פרטים ב-[CONTRIBUTING.md](CONTRIBUTING.md). **אל תדביקו מידע אישי אמיתי ב-issues**: מחקו שמות, טלפונים ומספרי זהות.

</div>