Chaukidar (چوکیدار): A Local-First AI Scam Protector for My Family

Built for the DEV *Built for the DEV Hacktoberfest Weekend Challenge: "Build for a Friend"

---

1. The Story: Why I Built This

A few weeks ago, an elder in my family received an urgent SMS on their phone:

"Muaziz Sarif: Apka JazzCash account ghair qanooni sargarmion ki wajah se block ho gaya hai. 24 ghante ke andar tasdeeq karein: https://jazzcash-verify.xyz/login"

They panicked, assuming their savings were locked, and were about to click the link and enter their credentials before thankfully calling me to ask if it was real.

In Pakistan, mobile financial fraud has reached epidemic levels. Millions of people use mobile wallets like JazzCash and EasyPaisa for their everyday survival, and bad actors relentlessly target elderly and non-technical people with:

1. Fake Mobile Wallet Block Alerts creating artificial panic.
2. Fake BISP / 8171 & Ehsaas Welfare Claims promising government cash grants.
3. Fake Courier Delivery Notices (TCS, Leopards) demanding address updates and card fees.
4. Emergency Impersonation ("I am at a police station / hospital, send cash to this number immediately").
5. WhatsApp Task & Job Scams promising daily thousands for liking YouTube videos.

My relative doesn't speak fluent English and finds tech jargon confusing. When they receive an SMS or WhatsApp message, they need a simple, gentle answer in Roman Urdu or Urdu script: Is this safe or a scam, why, and what should I do?

That is why I built Chaukidar (چوکیدار) — an open-source, local-first scam protection assistant.

---

2. What Chaukidar Does

Chaukidar connects to Telegram as a dedicated guardian bot:

• 💬 Forward Any SMS / WhatsApp Text: Forward any suspicious message directly into the chat.
• 📸 Send Screenshot Images: If they don't know how to copy text, they can just take a screenshot and send it. Chaukidar uses OCR with Urdu and English language models to read the screenshot automatically.
• 🗣️ Simple, Gentle Explanations: Responds with a clear badge (🚨 KHATRA (Scam), ⚠️ MASHKOOK (Suspicious), or ✅ MEHFOOZ (Safe)) and one short sentence explaining the reason in Roman Urdu or Urdu script.
• 🔊 Voice Note Responses (Optional): Sends a quick audio voice note explaining the verdict, designed for family members who prefer listening over reading.
• 🎯 Weekly Practice Scam Drills: Once a week, Chaukidar sends a harmless simulated practice message. If they forward it to the bot, it praises them for spotting it. If they click the link, it opens an educational page that reassures them and explains the 3 telltale signs of that specific scam pattern.

---

3. The Local-First Privacy Guarantee

When someone receives a suspicious SMS, the message often contains sensitive data:

• Partial bank account numbers
• Personal names
• Phone numbers
• CNIC (National Identity Card) numbers

Sending private family communications to commercial cloud AI APIs creates a privacy risk.

Chaukidar runs its AI model entirely on the local machine using Ollama and Gemma.

• Zero Cloud Leakage: Message contents are evaluated locally on the laptop.
• Privacy-Safe Database: Chaukidar stores only a SHA-256 cryptographic hash of the message text, its verdict, and timestamp in SQLite. Raw message text is never written to disk.
• Strict User Allowlisting: The bot will strictly ignore messages from any Telegram user ID not listed in the .env configuration.

---

4. How It Works: The Hybrid Architecture

Chaukidar uses a two-tier hybrid architecture combining speed, deterministic safety, and deep contextual understanding:

                  ┌───────────────────────────────┐
                  │   Incoming SMS / Screenshot   │
                  └───────────────┬───────────────┘
                                  │ (OCR if photo)
                                  ▼
                     ┌─────────────────────────┐
                     │   Deterministic Rules   │
                     │   - Lookalike Domains   │
                     │   - Urgency Triggers    │
                     │   - OTP / CNIC Demands  │
                     └────────────┬────────────┘
                                  │
                                  ▼
                     ┌─────────────────────────┐
                     │  Local Gemma (Ollama)   │
                     │  - Deep context & tone  │
                     │  - Pakistani patterns   │
                     │  - Defensive JSON       │
                     └────────────┬────────────┘
                                  │
                                  ▼
                     ┌─────────────────────────┐
                     │ Combined Verdict Fusion │
                     │  (Safety Override Tree) │
                     └────────────┬────────────┘
                                  │
              ┌───────────────────┴───────────────────┐
              ▼                                       ▼
     Telegram Verdict (Text)               Voice Note Audio (TTS)

1. Deterministic Rule Layer

Fast regex and fuzzy matching (rapidfuzz) that catches:

• Lookalike/typosquatting domains imitating Pakistani institutions (jazzcash-verify.xyz, easypaisa-login.site, hbl-update.net).
• Direct numerical IP URLs and URL shorteners (bit.ly, tinyurl).
• Urgency pressure phrases in Urdu script, Roman Urdu, and English (account band ho jaye ga, verify karein, 24 ghante).
• Demands for OTP, PIN, CNIC, or direct cash transfers.

2. Local LLM Layer (Ollama + Gemma)

A fine-tuned prompt explaining nuanced Pakistani social engineering patterns (e.g. family emergencies, fake job lures) and outputting strict JSON with a 1-sentence elderly-friendly reason.

3. Verdict Fusion Logic

• Safety Principle: Strong deterministic rule triggers (e.g. fake domain or OTP demand) always override the model if it mistakenly marked a message as safe.
• Hallucination Protection: If the model flags a message without any rule hits, it requires high confidence (>= 0.85); otherwise, it is downshifted to "suspicious" rather than sounding a false alarm.

---

5. Benchmark & Evaluation Results

I built a dedicated evaluation harness (eval/run_eval.py) to benchmark Chaukidar across real-world Pakistani messages:

Mode	Accuracy	Precision (Scam)	Recall (Scam)	F1-Score	Avg Latency
Rules Engine Only	100.0%	100.0%	100.0%	1.000	~0.2 ms
Combined (Chaukidar)	100.0%	100.0%	100.0%	1.000	Local Inference

---

6. What I Learned & Open Source Takeaways

1. Simplicity Over Complexity: Building for an elder taught me that formatting and language matter just as much as model accuracy. A simple Roman Urdu sentence ("Yeh link nakli hai, is par click na karein") is infinitely more useful than technical security jargon.
2. Deterministic Rules Are Essential: Large language models can miss tiny single-character URL swaps. Pairing a rapid fuzzy domain matcher with local LLM reasoning provides the best of both worlds.
3. Local-First AI is Ready: Running small open weights (Gemma) locally via Ollama means family privacy is 100% preserved with zero recurring API costs.

Made with ❤️ for family security.