# 🛡️ The HALT Project
**H**ALT's **A** **L**ogin **T**rap — a web authentication framework leveraging honeypot and deception technology.
_Developed during an internship at Instruments Research and Development Establishment (IRDE), DRDO, Dehradun._
[](https://www.python.org/) [](https://fastapi.tiangolo.com/) [](https://www.sqlalchemy.org/) [](https://valkey.io/)
---
## Table of Contents
- [Why HALT](#why-halt)
- [How It Works](#how-it-works)
- [Architecture](#architecture)
- [Decision Pipeline](#decision-pipeline)
- [Monitoring & SOC Dashboard](#monitoring--soc-dashboard)
- [Tech Stack](#tech-stack)
- [Project Layout](#project-layout)
- [Getting Started](#getting-started)
- [Using the Application](#using-the-application)
- [Honeypot Document Repository](#honeypot-document-repository)
- [Testing](#testing)
- [Configuration](#configuration)
- [Detection Coverage](#detection-coverage)
- [Limitations & Roadmap](#limitations--roadmap)
- [Report & References](#report--references)
---
## Why HALT
Most authentication defenses — WAFs, IDS/IPS, CAPTCHA, rate limiting, MFA — are built to do one thing: **reject the request as fast as possible.** That's great for prevention, but it means the moment an attack is blocked, the trail goes cold. Security teams are left with a log line and nothing about what the attacker actually wanted.
HALT flips that model for the authentication endpoint. Suspicious login requests aren't rejected — they're **silently redirected into a realistic honeypot session** that looks and behaves exactly like the real application, but is completely isolated from production data. The attacker keeps clicking, uploading, and chatting, believing they're inside the real system, while every action is captured for forensic analysis and threat intelligence.
Traditional security terminates the connection at detection. HALT keeps the attacker engaged and builds a behavioural timeline instead.
## How It Works
1. A login request hits `/login` and is passed through the **Detection Pipeline**.
2. The pipeline extracts request/behavioural features and scores them against a configurable rule set.
3. Based on the resulting `risk_score`, the backend silently creates either a **real session** or a **honeypot session** — both use the _same_ frontend and endpoints, so the client can't tell the difference.
4. Real sessions read/write production data. Honeypot sessions run entirely on mock data and isolated storage.
5. Every action inside a honeypot session is captured by the **Monitoring System** and surfaced on a built-in **SOC dashboard** for live investigation.
## Architecture
Both session types are tracked through **Valkey** and share identical endpoints — routing is decided entirely on the backend via a `mode` attribute, so an attacker sees no observable difference between a real and a deceptive session.
## Decision Pipeline
The Detection Pipeline is HALT's core decision-making component. It builds a structured `feature_vector` from the incoming request (headers, body, network metadata, derived behavioural indicators), evaluates it against a configurable `RuleSet`, and produces a cumulative `risk_score`.
| Component | Responsibility |
| ---------------- | ------------------------------------------------------------------------ |
| `FeatureBuilder` | Extracts passive observations only; it does not make security decisions. |
| `RuleSet` | Combines observations into attack-specific signatures. |
| `Evaluator` | Builds attack, context, behaviour, and automation scores. |
| `DecisionEngine` | Maps risk bands to the real or honeypot destination. |
## Monitoring & SOC Dashboard
Every interaction inside a honeypot session — navigation, uploads, downloads, chat activity, login/logout — is intercepted and logged as a structured event tied to that session's ID. This lets analysts reconstruct a complete, chronological behavioural timeline for each attacker.
The **SOC dashboard** (`/monitor`) polls this data to provide:
- Live and historical session views with risk scores
- Full activity timelines per session
- Document activity tracking
- One-click session termination
## Tech Stack
| Layer | Technology |
| ---------------- | ----------------------------- |
| Language | Python 3.11+ |
| Web framework | FastAPI |
| ASGI server | Uvicorn |
| Database | SQLite |
| ORM | SQLAlchemy |
| Session store | Valkey |
| Auth hashing | bcrypt |
| Data validation | Pydantic |
| Detection config | YAML (feature & rule schemas) |
| Pattern matching | Regex |
| Frontend | HTML, CSS, Vanilla JS |
## Project Layout
```
api/
auth/ Session and IP-failure tracking
database/ SQLite models, queries, seed data, honeypot telemetry
decision_pipeline/ Features, rules, evaluator, and decision engine
monitor/ Event logging helpers
schemas/ Feature and rule configuration
services/ Valkey client and virtual honeypot document service
server.py FastAPI application and HTTP routes
storage/
documents/ Real-user uploads
honeypot/ Per-honeypot-session attacker uploads
mock/ Mock corporate files served in honeypot sessions
tests/ Detection-pipeline regression tests
web/ Login, portal, and SOC dashboard assets
```
## Getting Started
**1. Create and activate a virtual environment** from the repository root.
```bash
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
```
**2. Install backend dependencies.**
```bash
pip install fastapi "uvicorn[standard]" sqlalchemy pyyaml bcrypt valkey loguru rich python-multipart
```
**3. Start a Valkey server** on `localhost:6379`.
```bash
valkey-server
```
**4. Start the application.**
```bash
cd api
uvicorn server:app --reload
```
**5. Open the login page.**
```
http://127.0.0.1:8000/login
```
On startup, HALT auto-creates the SQLite schema and seeds document folders and chat channels. SQLite data lives in `api/database/halt.db`; Valkey stores active sessions and IP failure counters.
## Using the Application
| Endpoint | Description |
| ---------------------------- | -------------------------------------------------------- |
| `GET / POST /login` | Authentication entry point and detection pipeline |
| `POST /register` | Creates a real portal account for local testing |
| `GET /portal` | Real or honeypot portal, depending on session mode |
| `GET /api/documents` | Combined honeypot document repo, or real user documents |
| `POST /api/documents/upload` | Uploads to the current user's real or virtual repository |
| `GET /monitor` | SOC dashboard |
The SOC dashboard polls:
```
GET /monitor/overview
GET /monitor/sessions
GET /monitor/session/{session_id}
GET /monitor/events
GET /monitor/documents
POST /monitor/session/{session_id}/terminate
```
Terminating a session marks its SQLite record as `Terminated` and deletes the matching Valkey session — the next request with that cookie is redirected back to `/login`.
## Honeypot Document Repository
Each honeypot session sees a single, dynamically assembled document list:
```
Mock files in storage/mock/
+ uploads in storage/honeypot/session_/
= visible virtual repository
```
Preview and download resolve an uploaded file first, then fall back to the mock repository — so mock files stay functional while attacker uploads appear immediately. Session upload directories are **deliberately retained after logout** so investigators can inspect collected artifacts.
## Testing
Run the regression suite from the repository root:
```bash
python -m unittest discover -s tests -v
```
Tests cover feature extraction, rule completeness, false-positive regressions, exploit routing, and IP-based escalation.
## Configuration
| Setting | Location | Default |
| ---------------------------- | ---------------------------------- | ---------- |
| Session TTL | `api/constants.py` (`SESSION_TTL`) | 1 hour |
| Failed-login TTL | `FAILED_LOGIN_TTL` | 24 hours |
| Failed-login escalation | `FAILED_LOGIN_LIMIT` | 6 attempts |
| Detection features | `api/schemas/feature_schema.yaml` | — |
| Detection rules & confidence | `api/schemas/rules.yaml` | — |
| Valkey connection | `api/services/valkey_client.py` | — |
> **Production note:** put Valkey behind proper access controls, configure trusted proxy handling before relying on client IPs, use secure cookies/TLS, restrict dashboard access, and move database/storage paths to managed infrastructure before deploying beyond a lab environment.
## Detection Coverage
| Attack Type | Detection Mechanism | Supported |
| -------------------------- | ----------------------------------- | :--------: |
| SQL Injection | Regex + Rule Engine | ✅ |
| Cross-Site Scripting (XSS) | Regex + Rule Engine | ✅ |
| LDAP Injection | Regex + Rule Engine | ✅ |
| NoSQL Injection | Regex + Rule Engine | ✅ |
| Command Injection | Regex + Rule Engine | ✅ |
| Directory Traversal | Rule Engine | ✅ |
| Automated Bot Requests | Header & Behaviour Analysis | ✅ |
| Brute Force Attack | IP Tracking | ✅ |
| Credential Stuffing | IP Tracking | ✅ |
| Remote File Inclusion | Document Upload Endpoint Monitoring | ✅ |
| Phishing (via chat) | Chat Endpoint Monitoring | 🔜 Planned |
## Limitations & Roadmap
**Current limitations**
- Detection relies on rule-based analysis, which can miss novel or highly sophisticated attack patterns.
- The document module is demo-oriented and needs further hardening.
- SOC dashboard covers visualization/monitoring but not yet attack correlation, filtering, or automated investigation workflows.
- Chat monitoring is logged but not yet analyzed for phishing/social-engineering indicators.
**Planned enhancements**
- User and Entity Behaviour Analytics (UEBA) and ML-based scoring alongside the rule engine.
- Replace dashboard polling with WebSockets for true real-time updates.
- MITRE ATT&CK mapping for captured attacker activity.
- Sandboxed execution of uploaded files for safe payload analysis.
- NLP-based phishing/social-engineering detection in the chat module.
---
Built by Sankalp Bansal.