README.md

---
title: ShadowSage AI
emoji: 👁️
colorFrom: purple
colorTo: indigo
sdk: gradio
sdk_version: "6.26.0"
app_file: app.py
pinned: false
license: mit
---

# ShadowSage AI — the all-seeing guardian of your digital world

An AI-powered cybersecurity oracle that defends **proactively**, not reactively.
ShadowSage detects hidden threats before they land, analyzes suspicious messages,
identifies phishing, uncovers your exposed digital footprint, and watches login
behavior for signs of account takeover — then distills everything into one
**Sage Score** with plain-English guidance.

Built for CPU-only live demos: small models, no API keys required, everything
degrades gracefully to a labeled fallback instead of crashing.

## The four scrying stones

| Tab | What it does | How |
| --- | --- | --- |
| **Sage Verdict** | One combined Sage Score + 2-3 personalized recommendations | Weighted average of the three module scores (formula in `utils/scoring.py`) |
| **Phishing Analyzer** | Risk score, verdict and highlighted evidence for any email / SMS / URL | DistilBERT fine-tuned on a bundled 284-example dataset **plus** transparent rule + URL heuristics (typosquats, raw-IP hosts, abuse TLDs, entropy, urgency patterns) |
| **Footprint Scanner** | Breach history + exposure score for an email or domain | HaveIBeenPwned API v3 when `HIBP_API_KEY` is set; otherwise a **clearly-labeled** deterministic demo dataset |
| **Behavior Monitor** | Login timeline with anomalies highlighted + behavioral risk score | Isolation Forest over `data/login_activity.csv` (90 days of synthetic history with 7 planted intrusions), features include circular hour encoding, rare country/device flags and impossible-travel velocity |

## Project structure

```
app.py                      # Gradio Blocks UI — the whole mystical dashboard
model/phishing_classifier.py # DistilBERT training + rule/URL fallback engine
model/behavior_monitor.py    # Isolation Forest behavioral monitor
utils/footprint_scanner.py   # HaveIBeenPwned v3 wrapper + demo fallback
utils/scoring.py             # Sage Score formula + recommendation engine
data/phishing_dataset.csv    # 284 labeled examples (1 = phishing)
data/login_activity.csv      # 130 login events, 7 planted anomalies
data/generate_login_data.py  # deterministic generator for the login history
```

## Run locally

```bash
python -m venv .venv
# Windows: .venv\Scripts\activate   |   macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
python app.py                # -> http://127.0.0.1:7860
```

On the very first launch there is no trained model yet, so the app starts in
**rule-engine mode** (fully functional) and fine-tunes DistilBERT in a
background thread — the Phishing tab shows the training status
("the Sage is awakening"). Analysis is never blocked.

## Deploy to Hugging Face Spaces

1. Create a new Space → SDK: **Gradio**.
2. Push this repo as-is (`app.py` stays at the root; the YAML block at the top
   of this README is the Spaces config).
3. Done. `requirements.txt` installs everything; on first boot the Space trains
   the phishing model in the background and shows rule-based results meanwhile.

Optional: add a Space secret `HIBP_API_KEY` to switch the Footprint Scanner from
demo data to live HaveIBeenPwned lookups. Nothing else changes.

## Retraining the phishing model on your own dataset

Replace `data/phishing_dataset.csv` (two columns: `text,label`, label 1 =
phishing), then either:

```bash
# CLI: train and save to model_artifacts/phishing_distilbert/
python -m model.phishing_classifier            # full 2-epoch run
python -m model.phishing_classifier --limit 60 # quick smoke-train
```

…or simply delete the `model_artifacts/` folder and start the app: it retrains
itself in the background. The entry points to look at first are
`train()` in `model/phishing_classifier.py` (hyperparameters are the constants
at the top of that file) and the retraining notes in its module docstring.

## How the scores work (viva crib sheet)

- **Phishing risk** — ML mode blends `0.65 × P(phishing from DistilBERT)` with
  `0.35 × URL-heuristic score` when a link is present; rule mode blends
  keyword and URL scores 60/40. In ML mode the rule score is a guardrail: if
  the transparent heuristics are more alarmed than the model (a blind spot
  from the tiny dataset), the higher score wins. Every added point is listed
  in the UI.
- **Footprint exposure** — +16 per breach containing password data, +8 per
  data-only breach, +6 extra for breaches newer than ~3 years, capped at 100.
- **Behavioral risk** — `0.5 × peak anomaly severity + 0.25 × anomaly density +
  0.25 × recency`; the detector is fully unsupervised but the CSV carries a
  `known_anomaly` column so the UI can show precision/recall against the
  planted truth (currently 6 of 7 caught).
- **Sage Score** — `0.40 × phishing + 0.35 × footprint + 0.25 × behavior`,
  renormalized over whichever modules have run.

## Regenerating the demo data

```bash
python data/generate_login_data.py   # deterministic (seed 42)
```

## Deployment note

The primary target is Hugging Face Spaces (Gradio SDK), where this repo runs
with zero changes. A Vercel deployment would need a serverless-friendly
rewrite (Gradio on Node/Vercel is not supported; you would front the same
Python modules with a FastAPI + static UI) — out of scope for the hackathon,
but the `model/` and `utils/` packages are UI-agnostic and would carry over
unchanged.