Flare Guardian — Real-Time Phishing Protection Powered by Flare

Flare Guardian is a Web3-native cybersecurity layer that protects users from malicious and high-risk links.

Built for the Flare blockchain ecosystem, it combines:

Tech	Purpose
FDC — Flare Data Connector	Live web intelligence → URL risk scoring
FTSO — Time Series Oracle	Risk-weighting using decentralized threat feeds
Flare Smart Accounts	On-chain, auditable security alerts
Local AI (Groq / Qwen)	Phishing intent classification + Safety guidance

It runs automatically as a browser extension, scanning every redirect link and blocking attacks in real time.

Project Overview

A professional, developer-ready web app + browser extension that scans suspicious URLs for Web3-related threats and (optionally) reports them on-chain.

Built as a hackathon-ready template so devs and security-minded users can run it locally (or in Docker) and extend it safely.

What it is / Who it’s for

• What: A threat-scanning website (frontend + backend) + optional browser extension called Phis-Guard. It analyzes URLs for phishing/drainer indicators, runs an LLM oracle for readable guidance, and can (optionally) emit an on-chain alert to a smart contract.

• Who: Web3 builders, security researchers, and non-technical users who want a simple check/report workflow or browser protection against scam sites.

Quick elevator pitch (one sentence)

A Web3-focused URL threat scanner that combines heuristics, third-party reputation checks, and an LLM oracle — with an optional on-chain alerting path and a browser extension that protects non-technical users in real time.

Key Features

• Real-time phishing + malware detection
• Web2 + Web3 signals fused (SSL, domain age, GSB reports, drainer patterns)
• User intent verification via wallet signature
• Blockchain-anchored alerts → fully auditable
• Clean warning UI with phishing education
• Manual URL scan mode for testing
• Runs both as a website + extension

Key Frontend Features (what users see)

• URL Scanner UI

  • Paste a domain/URL and click Scan.
  • Connect wallet (MetaMask) to sign scans if desired (FDC verification).

• Pipeline visualization

  • Three staged pipeline shown in real-time:
    1. FDC — Data verification (wallet signature check)
    2. FTSO — Oracle/LLM analysis (AI classification)
    3. Smart Account — On-chain alert (optional)

• Evaluation panel

  • Severity (0–10 mapped to Safe / Low / Medium / High)
  • Score (numeric)
  • Attack Type (phishing, drainer, malware, unknown)
  • SSL status (valid / invalid / unknown)
  • Safe Browsing flag (Google Safe Browsing)
  • On-chain Tx link (if DEMO_MODE=false and tx succeeded)
  • LLM Guidance: list of short, actionable tips from the LLM
  • Insight: a one-line professional explanation of the threat and Web3 mitigations

• UX extras

  • Wallet chip (shows abbreviated address)
  • Empty-state, loading states, and clear error messages
  • Demo mode banner (when running without a private key)

How It Works (Security Pipeline)

1. URL Extraction — From browsing navigation events
2. FDC Risk Verification
   • Domain age
   • SSL certificate check
   • Google Safe Browsing
   • Web exploit heuristics
3. FTSO Oracle Threat Signal Injection
   • Oracle-driven extra weighting
   • Detects drainer + fake brand networks
4. Flare Smart Account Alert
   • Signed scan request proves user intent
   • Trigger on-chain security event
   • Alert is tamper-resistant + traceable
5. AI Safety Scoring (Groq)
   • Attack type classification
   • Human-readable safe tips
6. Decision Engine
   • Score ≥ 6 → Block + Warning page
   • Score ≤ 5 → Safe but monitored

AI-Driven Response

We run an LLM prompt that returns:

{
  "score": 0-10,
  "attackType": "...",
  "tips": ["..."]
}

Examples:

• Credential Phishing
• Crypto Drainer
• Fake Giveaway
• Malware Download
• Tech Support Scam

Architecture

flowchart LR
A[User Clicks Link] --> B[Extension Intercept]
B --> C{LLM Risk Scan Backend}
C -->|FDC| D[FDC Web Intel]
C -->|FTSO| E[FTSO Threat Feed]
C -->|Smart Account| F[On-Chain Alert]
C --> G[Risk Score Output]
G -->|>=6| H[Warning/Block UI]
G -->|<=5| I[Broswer Continues Safely]

Loading

Modular — FDC & FTSO can be directly replaced with real Flare feeds

Supported Components

Component	Location
Backend	NodeJS + Express
Frontend	React + Vite UI
Browser Extension	Manifest V3 interception
Smart Contract	Flare Coston2 testnet
AI	Groq LLM API

Backend Features & Tech

What it does

• Accepts /scan POSTs from frontend (signed optionally with a wallet signature).
• Runs a 3-stage pipeline:
  1. FDC: verify signer via ethers.verifyMessage(url, signature) if provided.
  2. FTSO: call LLM (Groq client in current code) with a strict JSON prompt, parse the JSON { score, attackType, tips, insight }.
  3. Smart Account: optionally call a smart contract (triggerAlert) to emit an immutable on-chain alert (skipped when DEMO_MODE=true or private key missing).

Integrations / Data sources

• Groq LLM (or a configurable LLM) for human-readable analysis and suggestions.
• Google Safe Browsing (optional — API key) for known phishing/malware flags.
• WHOIS / Domain age via an external API to detect brand-new domains.
• SSL check (simple HEAD request to site).
• On-chain via ethers and a provided RPC URL to optionally call a smart contract.

Tech stack (backend)

• Node.js (ESM), Express
• ethers for signature verification and on-chain interactions
• groq-sdk (LLM client used in code) — pluggable for other LLMs
• node-fetch for external HTTP checks
• Runs in Docker (Node/alpine image) and reads secrets from .env

Important runtime behaviors

• DEMO_MODE=true disables wallet & contract initialization and skips on-chain TXs — ideal for templates and public repos.
• Backend returns consistent JSON describing pipeline status + metrics + tips.

Phis-Guard (Browser Extension) — extra feature

Purpose: protect non-technical users by intercepting and blocking malicious websites and wallet-connect attempts in real time.

Core capabilities:

• Realtime blocking: intercept navigation to URLs flagged by the scanner, show a blocking interstitial.
• Script fingerprinting: detect known drainer JS patterns and fake wallet dialogs (pre-load detection).
• Wallet connect firewall: detect attempts to auto-connect or prompt for seed phrases / approvals and block or warn.
• Safe overlay: optionally present a safe UI overlay with clear guidance and an “Open Scanner” button that sends the current URL to the backend for a full scan.
• User reporting: quick button to report suspicious sites to the Flare Guardian network (backend /scan + optional on-chain alert via user's signed message).
• Low friction: designed for non-technical users (one click to “Block & Report”).

Why This Matters

Users get scammed every day from malicious redirect links that:

• mimic exchanges
• drain wallets
• steal seed phrases
• drop malware payloads

Flare Guardian protects before the damage happens.

This is a preventative security layer, not just forensics.

Flare becomes the trust backbone for Web3 browsing security.

Installing the Browser Extension

To install the extension:

1. Open your browser and navigate to the extensions page (e.g., chrome://extensions/ for Chrome).
2. Enable developer mode.
3. Click "Load unpacked" and select the extension folder from the root folder of the project.

Testnet Details

Network	Coston2
Contract Address	0x2426e6A2f1c10c19E8F3233F60C7854877b26eAB
Explorer	Coston2 Flare Explorer
Faucet	faucet.flare.network

Deployment & Docker

• Dockerized frontend (multi-stage build): build React/Vite app → serve static via nginx.
• Dockerized backend: Node Alpine container exposing port 3000.
• docker-compose.yml ties them together:
  • frontend (nginx) serves static files on host port 5173.
  • frontend proxies /scan → http://backend:3000/scan.
  • backend exposes port 3000.

Demo flow: .env.example includes DEMO_MODE=true by default so template users can run the app without private keys.

Commands (dev)

# from repo root
cp .env.example .env   # edit .env if you want real keys, or leave blank and DEMO_MODE=true
docker compose up --build
# frontend: http://localhost:5173
# backend api: http://localhost:3000/scan

Project Structure (recommended / used)

/flare-demo
├─ backend/
│  ├─ server.js
│  ├─ package.json
│  └─ Dockerfile
├─ frontend/
│  ├─ src/
│  │  ├─ App.jsx
│  │  └─ index.css
│  ├─ package.json
│  └─ Dockerfile
├─ nginx/
│  └─ default.conf
├─ extension/                 # (optional) Phis-Guard extension source
│  └─ manifest.json
├─ .env.example
├─ .dockerignore
├─ docker-compose.yml
└─ README.md

Environment variables (.env keys)

• GROQ_KEY — LLM API key (optional)
• PRIVATE_KEY — blockchain wallet to sign on-chain txs (do NOT commit)
• API_KEY_GOOGLE — Google Safe Browsing API key (optional)
• CONTRACT_ADDRESS — smart contract address for alerts (optional)
• RPC_URL — JSON-RPC endpoint for the target chain
• DEMO_MODE — true to disable on-chain TXs and wallet init (recommended for public templates)

Always add .env to .gitignore. Use .env.example as the public template.

API (quick ref)

POST /scan

Request:

{
  "url": "https://sus.example",
  "wallet": "0xabc...def",      // optional
  "signature": "0x..."          // optional, signature of the URL
}

Response:

{
  "url": "...",
  "score": 7,
  "attackType": "phishing",
  "tips": ["Don't connect your wallet", "..."],
  "insight": "...",
  "whois": {...},
  "ssl": { "valid": true, "issuer": "..." },
  "gsb": { "flagged": false, "reasons": [] },
  "tx": null,
  "explorer": null,
  "fdc": { "verified": true },
  "ftso": { "verified": true, "model": "..." },
  "smartAccount": { "verified": false }
}

Security, privacy & best practices (things you must do)

• Never commit secrets (private keys, API keys) to Git. Use .env + .gitignore.
• DEMO_MODE default protects templates — keep it true for public repos.
• Add secret scanning (GitHub secret scanning) to CI.
• Rate limit / auth backend in production to prevent abuse.
• CSP headers for the frontend when deploying (Nginx) — tighten script-src, connect-src.
• Logging/monitoring: add structured logging and Sentry/Prometheus for production.
• Consent & privacy: do not store PII or scan results longer than necessary; document retention policy.
• CI tests & pre-commit hooks: add git-secrets / pre-commit to prevent future leaks.

Future Enhancements

• Browser-level drainer signature DB
• ML fingerprinting for scam networks
• Automatic revocation of unsafe permissions
• Wallet provider integrations
• Native mobile security agent
• Active smart contract scanner (scan contracts on connected sites)
• Screenshot / visual analysis (Puppeteer + vision model)
• Honeypots that safely interact with malicious sites to capture behavior
• Reputation DB & attacker graph (Neo4j or a graph DB)
• User accounts + rate-limits + API keys for production
• Webhooks & alerts (Slack / Telegram) for high-severity scans
• CI/CD (GitHub Actions) to build and publish images automatically
• Unit & integration tests (Jest / Supertest)
• Browser extension auto-update + store packaging

Final notes (short & practical)

• The architecture makes this safe for public sharing: LLM + heuristic checks run without blockchain writes by default.
• Demo mode + .env.example let users get started instantly and safely.
• Phis-Guard closes the loop: website for checking/reporting + extension for active protection.

Built by

Jordan — Cybersecurity student & Flare enjoyer

Bangalore, India