Branik Engine

Multimodal AI phishing detection for the Western Balkans

Branik analyzes text content, screenshots, URLs, and metadata using Google Gemini to detect phishing attacks. It specializes in Serbian, Croatian, Bosnian, Montenegrin, Macedonian, Albanian, and Slovenian language content.

Built as a REST API — plug it into a browser extension, mobile app, email gateway, or any client that can make HTTP requests.

How It Works

Your app sends a POST /api/v1/analyze request with an X-API-Key header and a body containing text, screenshot, url, etc. The engine returns a structured JSON response.

Your App (browser plugin, mobile, etc.)
  │
  │  POST /api/v1/analyze
  │  Headers: { X-API-Key: "your-key" }
  │  Body:    { text, screenshot, url, ... }
  │
  ▼
┌── Branik Engine ──────────────────────────────────────┐
│                                                        │
│  1. Preprocessing (deterministic, <10ms)               │
│     URL heuristics, brand impersonation detection,     │
│     homoglyph checks, sensitive data patterns,         │
│     urgency signal detection, entropy analysis         │
│                                                        │
│  2. Gemini Analysis (multimodal, ~5-15s)               │
│     Text + image in single call, structured output     │
│     via Adaptive Linguistic Prompting (ALP) with       │
│     few-shot examples for the region                   │
│                                                        │
│  3. Structured Response                                │
│     Risk score, verdict, reasons, safety tips —        │
│     all in the user's native language                  │
│                                                        │
└────────────────────────────────────────────────────────┘
  │
  ▼
JSON Response → Your app renders it

What it detects

Attack Type	Examples
Postal service scams	Fake Pošta Srbije, Hrvatska Pošta, BH Pošta
Bank credential phishing	Fake Raiffeisen, Intesa, NLB, PBZ logins
Government impersonation	Fake eUprava, tax refund scams
Telecom billing scams	Fake BH Telecom, MTS, Yettel payment pages
SMS phishing (smishing)	Prize scams, delivery scams, verification scams
QR code phishing	Malicious QR codes in screenshots
AI-generated visuals	Fake logos, manipulated branding

Preprocessing checks (instant, no AI cost)

Suspicious TLD detection (.xyz, .top, .icu, .click, etc.)
Brand impersonation matching against 30+ Balkan institutions
Homoglyph/IDN attack detection (Cyrillic characters disguised as Latin)
IP-based URL flagging
URL shortener detection (bit.ly, tinyurl, etc.)
Subdomain trick detection
Domain entropy analysis (randomly generated domains)
Sensitive data request patterns (JMBG, OIB, EMBG, CVV, PIN, etc.)
Social engineering signal detection (urgency, fear, reward lures)

Setup

Prerequisites: Python 3.11+, and a Gemini API key from Google AI Studio (free tier available).

1. Install dependencies

cd branik-model-alpha
python -m venv .venv
source .venv/bin/activate   # Linux / macOS
pip install -r requirements.txt

2. Configure environment

Copy .env.example to .env and set:

GEMINI_API_KEY (required)
BRANIK_API_KEYS (optional, comma-separated)
BRANIK_LOG_LEVEL (optional, e.g. INFO)

Running the Engine

Development (with auto-reload)

uvicorn app.main:app --reload --port 8000

Production

uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Docker

docker compose up --build

Once running: /docs (Swagger), /redoc, /api/v1/health.

API Reference

All analysis requests require X-API-Key in the header.

POST /api/v1/analyze

Request body: page_url, text_content, screenshot_base64, urls_found, source_type, metadata. At least one of text_content or screenshot_base64 required.

Response: risk_score (1–10), verdict (safe | suspicious | dangerous), summary, reasons, safety_tips, modules (url_analysis, visual_analysis, language_analysis).

GET /api/v1/health

No auth. Returns status, model, version.

Error responses

401 — Missing X-API-Key
403 — Invalid API key
422 — Invalid request (e.g. no text or screenshot)
500 — Engine error

Connecting Your Client

Browser extension: call POST /api/v1/analyze with page_url, text_content, urls_found, and optionally screenshot_base64. Use result.verdict to show warnings.

Python: use requests.post() with JSON payload and API key header. cURL: same headers and JSON body.

Testing

Run the full test suite (8 scenarios covering postal scams, bank phishing, government impersonation, prize scams, IP URLs, and legitimate pages):

python tests/test_scenarios.py

Single scenario: --scenario 1. Remote: --base-url and --api-key. Or use Swagger UI at /docs.

Deployment

Docker: docker compose up --build -d. For Railway / Render / Fly.io: connect repo, set environment variables, deploy.

Required: GEMINI_API_KEY. Optional: BRANIK_API_KEYS, BRANIK_LOG_LEVEL (DEBUG | INFO | WARNING | ERROR).

Research Background

Adaptive Linguistic Prompting (ALP) — Structured semantic reasoning for LLM-based phishing detection (F1=0.93).
Temperature=0 for classification maximizes accuracy and avoids stochastic false negatives.
Screenshots — Commercial LLMs achieve 93–95% accuracy on brand identification from screenshots.
Western Balkans threat intelligence — Group-IB documented postal and banking phishing campaigns with SMS as primary vector.
Smishing — Hundreds of thousands of smishing messages daily; mobile browsers make URL verification difficult.

Interested in Branik or our other products?

Get in touch to discuss integration, licensing, or custom AI solutions.

Contact CoraLabs

BRANIK ENGINE