FriendShield: I Built a Scam Shield for My Roommate Joy

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend.

What I Built

Last week, my roommate Joy handed me his phone and asked one question:

“Bhai, is this real?”

The message looked urgent:

“Your bKash account will be closed within 24 hours. Verify immediately: bkash-verify.xyz”

It used a trusted brand name. It was written in Bangla. It created an artificial deadline. And on a small smartphone screen, the link looked believable enough to make someone pause in panic.

But it was not from bKash.

It was a phishing message designed to exploit urgency, steal credentials, and drain mobile-wallet funds.

That moment made me realize the core problem: people do not need another abstract browser warning. They need a clear, definitive answer before they click.

• Is this message real or fake?
• Why is this specific link suspicious?
• What should I do right now?
• How can I explain the danger to a parent or friend who does not understand cybersecurity jargon?

So I built Friend Shield.

Friend Shield is an open-source, multilingual scam and phishing detection assistant for suspicious messages, URLs, QR codes, and screenshots. A user can paste a message, upload a screenshot (Ctrl + V), or a QR code. Friend Shield extracts links, safely unshortens redirects, analyzes threats through local ONNX machine learning, deterministic security rules, and Google Safe Browsing, then explains the risk in Bangla, English, or Banglish.

In Bangladesh, attackers frequently impersonate mobile financial services (MFS) like bKash and Nagad. While these local scams are a primary use case, the underlying issue is global: attackers leverage urgency, trusted brand names, and deceptive domains to exploit everyday people.

Friend Shield does not simply output a cryptic error code or a generic label. It turns concrete evidence into actionable advice:

“This link is pretending to be Nagad, but it is not the official domain. Do not enter your PIN or OTP.”

The language model explains the evidence in human terms, but it does not make the security decision.

Friend Shield is the calm second opinion I wanted Joy to have before urgency or fear makes the decision for him.

Friend Shield’s analysis

Friend Shield extracts the suspicious link, evaluates multi-layer evidence, and gives clear safety advice in the user’s preferred language.

Live demonstration of Friend Shield’s deterministic triage providing an immediate risk verdict, SEMI psychological score, and containment advice, followed by an asynchronous upgrade with open-weight Gemma’s empathetic reasoning.

Demo

• Live Web Application: Friend Shield on Render
• Source Code Repository: Friend Shield on GitHub

Try this sample scam message in the live app:

অভিনন্দন! আপনি নগদ ৫,০০০ টাকা জিতেছেন। এখনই ক্লেইম করুন:
http://nagad-cash-bonus.site/claim

Friend Shield flags the fake Nagad domain, identifies the unencrypted HTTP connection, detects financial bait and urgency, and explains the risk in plain Bangla.

Code

Pranto210102 / friend-shield

🛡️ Friend Shield

Defense-in-Depth Phishing & Scam Detection Engine with In-Process ONNX ML Inference, Anti-SSRF Redirect Expansion, Google Safe Browsing Reputation Checks, and Open-Weight AI Explanations.

---

🤝 The Friend Behind the Idea (Hacktoberfest: Build for a Friend)

Last week, my roommate Joy handed me his phone and asked one question:

“Bhai, is this real?”

The message looked urgent:

“Your bKash account will be closed within 24 hours. Verify immediately: bkash-verify.xyz”

It used a trusted brand name. It was written in Bangla. It created a deadline. And on a small phone screen, the link looked believable enough to make someone pause. But it was not from bKash—it was a phishing message designed to create panic, steal credentials, and compromise his wallet.

That moment made me realize the real problem: people do not need another technical warning. They need a clear, empathetic answer before they click.

• The Target Friend: Roommates, family…

View on GitHub

The complete open-source codebase is hosted on GitHub: Friend Shield on GitHub.

The system consists of three main components:

• Node.js & Express API Backend: URL extraction, Anti-SSRF redirect expansion, Safe Browsing lookup, in-process ONNX inference, deterministic brand rules, and Gemma explainer coordination.
• Modern Responsive Frontend: Lightweight web UI supporting text paste, clipboard screenshot OCR, in-browser QR scanning, and multilingual localization.
• Python Training Pipeline: 17-point feature extraction, Scikit-Learn Random Forest training on 149,900 balanced URLs, domain-disjoint validation, and ONNX export.

For the complete API contract, evaluation methodology, and latency benchmarks, check out the project README on GitHub.

How I Built It

Why one warning is not enough

A scam link can defeat a single detection layer in several ways:

Attack technique	Why one layer fails
Newly registered phishing domain	It does not yet appear in global reputation blocklists
URL shortener	The destination is masked behind a redirect
Fake brand domain	nagad-cash-bonus.site contains “Nagad,” but is not official
Emotional pressure	“Verify now” pushes users to act before thinking
Technical browser warnings	“Punycode spoofing” does not help an anxious user

Friend Shield uses defense in depth: multiple independent checks produce evidence before the system issues a final verdict.

flowchart TD
    A["Raw Message / Screenshot / QR"] --> B["Delimiter-Aware Link & OCR Extraction"]
    B --> C["Anti-SSRF Safe Redirect Unshortening"]
    C --> D["Parallel Threat Intelligence"]
    D --> D1["17-Point Feature Extraction + ONNX ML Inference"]
    D --> D2["Deterministic Rules Engine (MFS Brand & Raw IP)"]
    D --> D3["Google Safe Browsing v4 Reputation Lookup"]
    D --> D4["Social Engineering Manipulation Index (SEMI)"]
    D1 --> E["Uncertainty-Aware Decision & Abstention Policy"]
    D2 --> E
    D3 --> E
    D4 --> E
    E --> F["Open-Weight AI Safety Explainer (Google Gemma / Fallback)"]
    F --> G["Actionable Advice (Bangla, English, Banglish)"]

Local ML inference with ONNX

I trained a Random Forest classifier in Python using a balanced dataset of 149,900 URLs from the Kaggle Malicious URLs dataset. After domain-level deduplication and strict domain-disjoint splitting, the model was evaluated on 29,980 unseen test URLs:

Metric	Result
Accuracy	86.19%
Malicious Precision	87.59%
Malicious Recall	84.33%
Malicious F1-Score	85.93%
ONNX Model Size	12 MB

The model runs in-process inside Node.js via ONNX Runtime without requiring a secondary Python microservice.

Because statistical classifiers can be uncertain on novel domains, Friend Shield enforces an explicit abstention policy:

• 🔴 HIGH_RISK: Confirmed threat signals or critical structural hazards.
• 🟠 SUSPICIOUS: High statistical ML risk ($P \ge 0.85$).
• 🟡 NEEDS_REVIEW: Model abstention zone ($0.40 \le P < 0.85$) or cautionary signals.
• 🟢 NO_KNOWN_THREAT: No threat indicators detected.

NO_KNOWN_THREAT is an evidence-grounded assessment, not an absolute guarantee of safety.

Protecting users from hidden redirects

Scammers routinely hide destinations behind URL shorteners. Friend Shield expands redirects hop by hop, but with strict Anti-SSRF protection:

Before following each hop, the engine resolves DNS records and blocks private subnets (10.0.0.0/8, 192.168.0.0/16), loopback (127.0.0.1), and cloud-metadata endpoints (169.254.169.254). It cancels response body streams and limits chains to 5 hops to prevent denial-of-service loops.

Detecting scam psychology with SEMI

Scam messages rely on predictable emotional manipulation. Friend Shield computes a Social Engineering Manipulation Index (SEMI) measuring four psychological vectors:

1. Urgency & Panic (e.g., “account will be closed in 24 hours”)
2. Financial Bait & Greed (e.g., “you won 5,000 taka bonus”)
3. Authority Impersonation (e.g., “official verification team”)
4. Credential Coercion (e.g., “enter your PIN/OTP immediately”)

SEMI does not replace URL analysis; it helps the user understand why the message is trying to manipulate them.

Gemma: fast, evidence-grounded progressive explanations

This is where Gemma, Google’s open-weight model, becomes central to the user experience.

Friend Shield does not ask Gemma, “Is this link safe?” An LLM should never make an ungrounded security decision.

Instead, Friend Shield implements a Progressive Safety Architecture:

1. Instant Deterministic Triage (< 500 ms): The pipeline first returns an immediate risk verdict, SEMI psychological score, and containment advice using ONNX ML, deterministic rules, and Safe Browsing. The deterministic triage returns in under 500 ms so the user never waits on an AI queue to know whether a link is dangerous.
2. Asynchronous Gemma Deep Explanation: While the user reads the initial triage, Friend Shield requests a detailed Gemma explanation in the background. Gemma receives verified structured evidence (domain mismatch, HTTP protocol, SEMI vectors, ML score) and translates it into calm, empathetic guidance:

এই লিংকে ক্লিক করবেন না। এটি নগদের অফিসিয়াল ডোমেইন নয়।
আপনার PIN, OTP বা পাসওয়ার্ড কাউকে দেবেন না।

Friend Shield provides three parallel explanation modes:

• Bangla for native-language clarity
• English for broad accessibility
• Banglish (Bengali written in Latin alphabet) for how users naturally type on smartphones

All output is validated against a strict JSON schema. If the model is slow or unreachable, the user already has the instant deterministic explanation on screen.

Why cloud Gemma for mobile, local Gemma for privacy

Friend Shield supports both deployment modes:

• For the deployed web app, Friend Shield connects to Google AI Studio's hosted Gemma endpoint (gemma-4-26b-a4b-it). A person checking a suspicious SMS on a smartphone should not need to download a multi-gigabyte model or own high-end hardware before receiving help.
• For privacy-sensitive users, Friend Shield supports local inference through Ollama (ollama run gemma2:2b). In that mode, sensitive messages and Gemma explanations remain entirely on the user’s own machine without sending message content to an external service.

In both modes, Gemma receives only precomputed evidence. It never decides whether a link is safe.

Why Open Innovation Matters

Friend Shield is built for users who should not be forced to send private messages to a closed proprietary service. Open innovation matters here for four reasons:

1. Privacy & Data Sovereignty: In local Ollama mode, message analysis and Gemma explanation can run entirely on the user’s own machine without sending message content to an external service.
2. Auditability & Transparency: Verdicts are explainable. Users can inspect the extracted URL, redirect hops, ML score, rule triggers, and Safe Browsing results.
3. Cultural & Regional Localization: Commercial security tools often overlook non-English attacks. Friend Shield natively protects regional MFS brands (bKash, Nagad) and understands Bangla/Banglish scam syntax.
4. Resilience & No Vendor Lock-in: The core pipeline runs on open-weight models (ONNX Runtime and Google Gemma). Deterministic fallbacks keep the core safety workflow usable if a cloud endpoint is unavailable.

Prize Categories

Best Use of Render

Friend Shield is deployed in production on Render: Friend Shield on Render.

Render provides the live runtime environment for the Node.js/Express API: orchestrating delimiter parsing, executing in-process ONNX inference, validating SSRF-safe redirects, and managing asynchronous Gemma explanation streaming. Render’s Git-backed CI/CD pipeline enabled rapid, automated updates throughout development, while its environment variable manager securely stores API credentials.

Best Use of Gemma

Friend Shield showcases Google Gemma as an empathetic, culturally localized security explanation layer:

1. Evidence-Grounded Explanations: Gemma does not decide whether a link is malicious. It receives structured evidence from deterministic rules, local ONNX inference, Safe Browsing, and SEMI, then explains that evidence in user-friendly language. Output is schema-validated, with a deterministic fallback if validation fails.
2. Progressive Safety UX: Solves the latency dilemma of AI in security: deterministic triage delivers immediate protection in under 500 ms, while Gemma upgrades the UI with rich reasoning asynchronously in the background.
3. Dual Deployment Flexibility: Accommodates zero-install mobile web users via cloud Gemma while offering 100% air-gapped local execution via Ollama (AI_PROVIDER=ollama with gemma2:2b) for total data privacy.
4. Culturally Grounded Multilingual Synthesis: Generates nuanced, parallel advice across Bangla, English, and Banglish.

Limitations

Friend Shield is an educational decision-support tool, not an absolute guarantee of safety. A NO_KNOWN_THREAT verdict means no known threat indicators were found; newly registered phishing domains or phone-based social engineering can still bypass automated checks. That is why Friend Shield always reminds users never to disclose PINs, OTPs, or passwords.

How I Used AI

I used AI tools to accelerate development, including code assistance, debugging, documentation drafting, and refining this write-up. The multi-layer security architecture, deterministic evidence rules, abstention policy, ONNX model training and evaluation, Gemma integration, Render deployment, and final testing were designed, implemented, and reviewed by me.

What Joy Said

When I showed Joy the working build, he tested the suspicious message he had received.

Friend Shield immediately flagged the fake domain in red and explained in Banglish that bKash never asks for account verification via third-party .xyz links.

He looked up and said:

“Bhai, this would have saved me a lot of tension.”

That is why Friend Shield exists. It is the calm second opinion we all need before panic, urgency, or deception takes over.