Skip to content

rahul07890-dev/LURKHOUND

BranchesTags

Repository files navigation

LURKHOUND

Active Directory Attack-Path Discovery Mapper

A Windows-hosted, web-based security analysis dashboard for post-compromise AD reconnaissance. LURKHOUND performs LDAP-based enumeration, builds a permission graph, discovers privilege escalation attack paths, detects misconfigurations, and generates PowerShell remediation guidance, all tagged with MITRE ATT&CK techniques.

Key Features

  • LDAP Enumeration - Users, groups, computers, OUs, and ACLs via LDAPS (port 636)
  • Attack Path Discovery - BFS/DFS engine finds privilege escalation chains to Domain Admin
  • Misconfiguration Detection - ACL abuse, DA sprawl, Kerberoastable accounts, nested group abuse
  • Interactive Dashboard - Dark glassmorphism UI with risk gauges, graphs, and real-time search
  • Graph Visualization - Cytoscape.js-powered permission graph with severity-colored nodes
  • Remediation Engine - Copy-ready PowerShell commands for every finding
  • MITRE ATT&CK Mapping - 30 unique technique IDs covering every finding and attack path
  • Scan History - Track and compare enumeration results over time
  • BloodHound Import/Export - Ingest BloodHound/SharpHound JSON exports for analysis
  • Shortest Path Calculator - Find shortest privilege escalation path between any two AD objects
  • Finding Status Tracking - Track remediation status (open/acknowledged/in_progress/fixed/accepted_risk)

Project Structure

LURKHOUND/
├── backend/
│   ├── main.py                # FastAPI application & REST API
│   ├── config.py              # Environment config loader (.env)
│   ├── auth.py                # LDAPS authentication (port 636, NTLM)
│   ├── ldap_enum.py           # LDAP enumeration (users, groups, computers, ACLs)
│   ├── normalizer.py          # Data normalization & deduplication
│   ├── graph_builder.py       # NetworkX permission graph construction
│   ├── attack_paths.py        # BFS/DFS attack path discovery engine
│   ├── misconfig_detector.py  # Misconfiguration detection module
│   ├── risk.py                # Risk score calculation engine
│   ├── remediation.py         # PowerShell remediation generator
│   ├── mitre_mapping.py       # MITRE ATT&CK technique mapping
│   ├── bloodhound_io.py       # BloodHound JSON import/export
│   ├── report_generator.py    # PDF/HTML report generation
│   ├── scan_history.py        # Scan history tracking (SQLite)
│   └── models.py              # Pydantic request/response models
│
├── frontend-next/             # Primary UI (Next.js 16 + TypeScript)
│   ├── src/
│   │   ├── app/
│   │   │   ├── page.tsx              # Landing / login page
│   │   │   ├── layout.tsx            # Root layout
│   │   │   ├── globals.css           # Global styles
│   │   │   └── dashboard/
│   │   │       ├── layout.tsx        # Dashboard shell with sidebar
│   │   │       ├── overview/         # Domain overview & risk score
│   │   │       ├── objects/          # Object explorer (users/groups/computers)
│   │   │       ├── paths/            # Attack path viewer
│   │   │       ├── graph/            # Permission graph visualization
│   │   │       ├── findings/         # Findings & remediation panel
│   │   │       ├── ou-tree/          # OU tree view
│   │   │       └── history/          # Scan history & comparisons
│   │   ├── components/
│   │   │   ├── Sidebar.tsx           # Navigation sidebar
│   │   │   ├── SearchModal.tsx       # Global search (Ctrl+K)
│   │   │   ├── ObjectDrawer.tsx      # Object detail slide-out drawer
│   │   │   ├── NotificationBell.tsx  # Real-time notifications
│   │   │   ├── OnboardingTour.tsx    # First-run guided tour
│   │   │   ├── AboutModal.tsx        # About / credits modal
│   │   │   ├── PantherIcon.tsx       # LURKHOUND branding icon
│   │   │   ├── ErrorBoundary.tsx     # Error handling wrapper
│   │   │   ├── SkeletonLoader.tsx    # Loading state skeletons
│   │   │   └── Toast.tsx             # Toast notifications
│   │   ├── context/
│   │   │   └── SessionContext.tsx    # Session state management
│   │   ├── lib/
│   │   │   └── api.ts               # API client layer
│   │   └── types/
│   │       └── index.ts             # TypeScript type definitions
│   ├── tailwind.config.js
│   ├── next.config.ts
│   ├── tsconfig.json
│   └── package.json
│
├── frontend/                  # ⚠️ DEPRECATED — Legacy UI (HTML/CSS/JS)
│                              #   Use frontend-next/ instead.
│
├── sample_data/
│   └── marvel_sample.json     # Sample MARVEL.local test dataset
│
├── tests/                     # Pytest test suite
│   ├── conftest.py
│   ├── test_attack_paths.py
│   ├── test_remediation.py
│   └── test_risk.py
│
├── data/                      # Runtime data (gitignored)
│   └── scan_history.db        # SQLite scan history database
│
├── .env                       # Environment config (gitignored)
├── .gitignore
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Container deployment
├── docker-compose.yml         # Multi-service deployment
├── start.bat                  # Windows launcher (CMD)
├── start.ps1                  # Windows launcher (PowerShell)
├── start.sh                   # Linux/macOS launcher
└── README.md

Prerequisites

Requirement Version
Python 3.10+
Node.js 18+ (for Next.js frontend)
pip Latest
Network access To your Domain Controller
LDAPS (port 636) Must be enabled on DC
Valid domain account Read access to AD is sufficient

Setup & Run

Option A: Docker (Recommended)

docker-compose up --build

This starts both the backend API (port 8000) and the Next.js frontend (port 3000).

Option B: Quick Start (Windows)

Use the included launcher script:

# PowerShell
.\start.ps1
:: CMD
start.bat

Option C: Quick Start (Linux/macOS)

chmod +x start.sh
./start.sh

Option D: Manual Setup

1. Install Python Dependencies

cd LURKHOUND
pip install -r requirements.txt

2. Install Frontend Dependencies

cd frontend-next
npm install

3. Configure Environment

Create a .env file in the project root (see .env.example):

API_PORT=8000
LOG_LEVEL=info
SESSION_TTL_MINUTES=30
CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000,http://localhost:8000,http://127.0.0.1:8000
LDAP_TLS_VERIFY=false

4. Start the Backend

cd backend
python main.py

Server starts at http://localhost:8000

5. Start the Frontend

cd frontend-next
npm run dev

Dashboard opens at http://localhost:3000

6. Connect to Your Domain

Fill in the login form:

  • DC IP: Your domain controller IP
  • Domain: Your AD domain (e.g., MARVEL.local)
  • Username: Domain account with read access
  • Password: Domain account password
  • LDAPS: Enabled (port 636)

Click Connect & Enumerate — the system will authenticate, enumerate all AD objects, build the permission graph, and display results.

Security Design

Principle Implementation
Zero credential storage Passwords cleared immediately after authentication
In-memory only No database writes of credentials
LDAPS encryption All AD communication over TLS (port 636)
Input validation All API inputs sanitized; SSRF protection on DC IP
Session-based Session tokens via Authorization header, never in URL paths
Rate limiting Authentication endpoint rate-limited to prevent brute-force

Dashboard Pages

1. Domain Overview

  • Total Users / Groups / Computers / Privileged Accounts
  • Risk Score gauge (0–100)
  • Domain Admins list
  • Risk trend chart over time
  • Top 5 critical findings preview
  • Quick search across all objects

2. Object Explorer

  • Browse Users, Groups, Computers
  • Filter and search objects
  • Detailed view: memberships, permissions, SPNs
  • Slide-out drawer with cross-references to findings and attack paths

3. Attack Path Viewer

  • Visual graph rendering via Cytoscape.js
  • Step-by-step chain: User → [MemberOf] → Group → [AdminTo] → DC
  • Severity classification (Critical / High / Medium / Low)
  • Filter by severity and path type
  • MITRE ATT&CK technique tags per path

4. Permission Graph

  • Full interactive permission graph
  • Severity-colored nodes and edges
  • Zoom, pan, and node selection
  • Orphan node filtering

5. Findings & Remediation

  • Expandable finding cards with severity badges
  • Impact and description per finding
  • Step-by-step remediation guidance
  • Copy-ready PowerShell remediation commands
  • MITRE ATT&CK tagging
  • Finding status tracking (open/acknowledged/in_progress/fixed/accepted_risk)

6. OU Tree View

  • Hierarchical Organizational Unit browser
  • Collapse/expand OU branches
  • Object counts per OU

7. Scan History

  • Historical scan results comparison
  • Track changes in risk score over time
  • Side-by-side diff between scans

Detection Coverage

Category Detections
ACL Abuse GenericAll, WriteDACL, WriteOwner, GenericWrite
Privilege Escalation User → Group → Domain Admin paths
Lateral Movement AdminTo relationships, local admin rights
Domain Admin Sprawl Excessive DA group membership
Nested Group Abuse Over-privileged nested group chains
Credential Risk Kerberoastable admin accounts, passwords never expire
Delegation Unconstrained, constrained, and RBCD delegation abuse
GPO Abuse Write access to GPOs linked to privileged OUs
Trust Risk SID filtering disabled on trust relationships

MITRE ATT&CK Coverage

30 unique technique IDs mapped across all detections:

Technique Name
T1003 OS Credential Dumping
T1003.006 DCSync
T1021.002 Remote Services: SMB/Windows Admin Shares
T1069.002 Permission Groups Discovery: Domain Groups
T1078.002 Valid Accounts: Domain Accounts
T1087.002 Account Discovery: Domain Account
T1098 Account Manipulation
T1110 Brute Force
T1187 Forced Authentication
T1207 Rogue Domain Controller
T1222 File and Directory Permissions Modification
T1484 Domain Policy Modification
T1484.001 Group Policy Modification
T1550.002 Use Alternate Authentication Material: Pass the Hash
T1550.003 Use Alternate Authentication Material: Pass the Ticket
T1558 Steal or Forge Kerberos Tickets
T1558.003 Kerberoasting

Testing with Sample Data

A mock MARVEL.local dataset is provided in sample_data/marvel_sample.json with:

  • 7 users (including Tony Stark, Natasha Romanoff, Peter Parker)
  • 10 groups (Domain Admins, AVENGERS-IT, HelpDesk, etc.)
  • 3 computers (DC, WORKSTATION01, WORKSTATION02)
  • 4 ACL entries (WriteDACL, GenericAll, GenericWrite, WriteOwner)
  • Intentional misconfigurations for demo purposes

You can also import BloodHound JSON exports via the /api/import/bloodhound endpoint.

REST API Reference

Endpoint Method Description
/api/authenticate POST Authenticate & enumerate AD
/api/summary/{sid} GET Domain overview summary
/api/users/{sid} GET All user objects
/api/groups/{sid} GET All group objects
/api/computers/{sid} GET All computer objects
/api/acls/{sid} GET All ACL relationships
/api/attack-paths/{sid} GET Attack paths with MITRE tags
/api/findings/{sid} GET Misconfigurations + remediation
/api/graph/{sid} GET Permission graph (nodes/edges)
/api/data/{sid} GET All session data in one response
/api/path/{sid}?source=X&target=Y GET Shortest path between objects
/api/finding-status/{sid} GET/POST Finding remediation status
/api/object/{sid}/{name} GET Single object detail
/api/report/{sid}?format=html GET Generate security report
/api/scans GET List all scan records
/api/scans/{id} GET Get specific scan
/api/scans/diff/{id1}/{id2} GET Compare two scans
/api/export/bloodhound/{sid} GET Export BloodHound JSON
/api/import/bloodhound POST Import BloodHound JSON
/api/mitre-techniques GET MITRE technique lookup
/api/logout/{sid} POST Clear session
/ws/enumerate WebSocket Real-time enumeration progress

Note: Session IDs should be provided via the Authorization: Bearer <session_id> header for security. URL path parameters are supported for backward compatibility.

Architecture

┌──────────────────────────────────────────────────────────┐
│                     Browser (Client)                     │
│  ┌─────────────────────────────────────────────────────┐ │
│  │  Next.js 16 Frontend  (TypeScript + Tailwind CSS)   │ │
│  │  ── Landing Page ── Dashboard ── Graph Viewer ──    │ │
│  └────────────────────────┬────────────────────────────┘ │
└───────────────────────────┼──────────────────────────────┘
                            │ REST API (JSON) + WebSocket
┌───────────────────────────┼──────────────────────────────┐
│                    FastAPI Backend                       │
│  ┌────────────┐  ┌────────────────┐  ┌───────────────┐   │
│  │  auth.py   │  │  ldap_enum.py  │  │ normalizer.py │   │
│  └─────┬──────┘  └───────┬────────┘  └──────┬────────┘   │
│        │                 │                   │           │
│  ┌─────▼─────────────────▼───────────────────▼────────┐  │
│  │              graph_builder.py (NetworkX)           │  │
│  └─────────────────────┬──────────────────────────────┘  │
│                        │                                 │
│  ┌─────────────────────▼──────────────────────────────┐  │
│  │  attack_paths.py │ misconfig_detector.py │ risk.py │  │
│  └─────────────────────┬──────────────────────────────┘  │
│                        │                                 │
│  ┌─────────────────────▼──────────────────────────────┐  │
│  │  remediation.py │ mitre_mapping.py │ report_gen.py │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘
                            │ LDAPS (636)
                ┌───────────▼───────────┐
                │   Domain Controller   │
                │   Active Directory    │
                └───────────────────────┘

Known Limitations

  • Single-threaded pipeline: Enumeration runs synchronously. Only one enumeration can execute at a time per server instance. For large ADs (1,000+ users), enumeration may take 30–60 seconds.
  • In-memory sessions: Each session stores complete enumeration results in memory. Large ADs with extensive ACLs may consume significant RAM.
  • Lab-scale validation: Performance metrics are validated against the 7-user MARVEL.local environment. Enterprise-scale validation (10,000+ objects) has not been performed.
  • No multi-domain/forest support: Currently supports single-domain enumeration.
  • Platform dependencies: PDF export via weasyprint may have GTK dependency issues on Windows (xhtml2pdf fallback is available).

Important Notes

  • This tool does NOT perform: LLMNR poisoning, SMB relay, NTLM relay, or hash cracking
  • Starting assumption: Valid domain credentials are already available
  • LDAPS certificate: The tool accepts self-signed certificates in lab environments (set LDAP_TLS_VERIFY=true for production)
  • Scope: Designed for small-to-medium AD environments (up to ~500 objects)
  • Platform: Runs on Windows and Linux; tested with Python 3.11

Tech Stack

Layer Technology
Backend Python 3.11, FastAPI, Uvicorn
AD Communication ldap3 (LDAPS / NTLM)
Graph Engine NetworkX
Frontend Next.js 16, TypeScript, Tailwind CSS
Visualization Cytoscape.js
Data Models Pydantic v2
Database SQLite (scan history only)
Testing pytest
Containerization Docker

License

This project is licensed under the MIT License.

LURKHOUND — Sniff out every attack path in your Active Directory.

About

Active Directory Attack Path Discovery Mapper — LDAP enumeration, privilege escalation analysis, and MITRE ATT&CK mapped remediation

Topics

python ldap nextjs active-directory bloodhound cybersecurity privilege-escalation security-tools attack-path

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

LURKHOUND v1.0.0 — Initial Stable Release Latest
Apr 11, 2026

Packages

 
 
 

Contributors

Languages