Sentinel

Account takeover detection and behavioural risk intelligence. Sentinel builds a behavioural profile for each account, scores new activity against that account's own history, explains what moved the score, and presents the result through an investigation console.

Every account, login and payment in this system is synthetic. It is a learning project built against a public research dataset and a scenario simulator. It is not connected to any real financial system and holds no real credentials.

The finding the project is built around

The RBA login dataset contains 31,269,264 rows and 141 account-takeover logins — a positive rate of 4.51e-06. Two measured facts shaped everything else:

• Only 77 of those 141 takeovers came from a known-attack IP. A blocklist misses roughly 45% of them. That is the argument for behavioural detection, and it means Is Attack IP is a genuinely different task whose metrics must never be presented as takeover performance.
• 141 labels cannot train and test a classifier. So the supervised work is split into two tracks that are never mixed: one trained on real, abundant attack-IP labels, and one trained on simulator-generated takeovers whose headline metric is recall on the real takeovers it never saw.

The gap between those two is reported rather than hidden. The simulator-trained model scores 89.3% on synthetic test data and 50.0% against real takeovers. Both numbers are on the Models screen, labelled by what they were measured against.

How it scores an event

login event
     |
behavioural profile   <- built ONLY from events strictly before this one
     |
feature engineering   <- deviation from that account's own pattern
     |
     +-- XGBoost (attack-IP probability)
     +-- Isolation Forest (anomaly score)
     |
risk fusion -> score + band, with deterministic floors
     |
SHAP -> ranked, plain-English factors
     |
alert + timeline -> Postgres -> FastAPI -> React console

One feature-engineering package is imported by the training scripts, the seeder and the API. If a feature were computed differently offline than online, the demo would be a lie.

What is honest about it, deliberately

• The score is not a probability. The fitted thresholds put MEDIUM at 0.9189 and HIGH at 0.9860, so a score of 0.7253 is LOW. The UI never renders it as a percentage, and the band meter prints the thresholds in force.
• Explanation is not causation. A ranked SHAP factor describes what moved the model's output, not what happened to the account.
• Cold start says so. An account below the maturity threshold shows "insufficient history", never a comfortable low score.
• Deterministic floors are labelled. When a rule sets the band, the UI says the rule did it rather than implying the models agreed.
• The score does not always climb through an attack. It often falls, for a measured reason. See reports/burst_response.md.

Running it locally

Requires Python 3.12, Node 22, and Docker.

docker compose up -d db
python -m venv .venv && .venv/Scripts/pip install -e ".[dev]"
cp .env.example .env
.venv/Scripts/python -m alembic upgrade head
.venv/Scripts/python scripts/seed_demo.py
.venv/Scripts/python -m uvicorn backend.app.main:app --reload

cd frontend && npm install && npm run dev

The console is at http://localhost:5173, the API at http://localhost:8000, and its docs at /docs.

Deploying it is covered in DEPLOYMENT.md.

Layout

Path	What lives there
ml/	features, profiles, models, risk fusion, explanations, simulator
backend/	FastAPI app, SQLAlchemy models, Alembic migrations
frontend/	React + TypeScript console — see its README
reports/	committed EDA and evaluation write-ups
tests/	leakage guards, feature fixtures, API integration tests
scripts/	dataset download, demo seeding

Tests

.venv/Scripts/python -m pytest -q

The highest-value ones are the leakage guards: a profile built with as_of=t is byte-identical whether or not events after t exist in the input, and the chronological split asserts max(train) < min(test).

A few API tests read the seeded database live and reuse each account's most recent device and city. Running a Security Lab scenario writes real rows and can therefore break them until scripts/seed_demo.py is run again.

Data

The login data is the RBA dataset (Wiefling et al., CC BY 4.0). Its IP addresses, user agents and timestamps were synthesised by its authors, so they are never geolocated here — the provided city and country columns are used instead. No public dataset links logins to transactions for the same account with takeover labels, so all transaction behaviour is simulator-generated and labelled as such in the database, the API and the UI.