> For the complete documentation index, see [llms.txt](https://2dam-7.gitbook.io/defensive-lab/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://2dam-7.gitbook.io/defensive-lab/readme.md). # Defensive Identity Lab VM ## Defensive Identity Lab #### A safe, local training environment for identity detection and SOC analysis [![Validate hub](https://github.com/rubenasuasoto/defensive-identity-lab-vm/actions/workflows/validate.yml/badge.svg)](https://github.com/rubenasuasoto/defensive-identity-lab-vm/actions/workflows/validate.yml) [![Python](https://img.shields.io/badge/Python-3.12-3776AB?logo=python\&logoColor=white)](https://www.python.org/) [![Security](https://img.shields.io/badge/data-synthetic-B8FF5A?labelColor=111512)](https://github.com/rubenasuasoto/defensive-identity-lab-vm/tree/main/SECURITY.md) [Public hub](https://rubenasuasoto.github.io/defensive-identity-lab-vm/) · [Documentation](https://2dam-7.gitbook.io/defensive-lab/) · [Case study](https://rubenasua.vercel.app/projects/defensive-identity-lab) · [Español](https://github.com/rubenasuasoto/defensive-identity-lab-vm/tree/main/README.es.md) ![Defensive Identity Lab analyst workbench](https://295479062-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F33LwATSRdSnh4agnYNQD%2Fuploads%2Fgit-blob-288c6914c2b958658f877fa734f7e6b07113fdbe%2Fproject-cover.png?alt=media) Defensive Identity Lab is a lightweight coordination hub and local workbench for learning defensive identity detection. It connects three public detection labs and adds a synthetic live environment with event ingestion, rule evaluation, incidents, analyst notes and guided exercises. > Synthetic lab only. No production logs, credentials, tenants, tokens, malware, offensive simulation or host-changing action is required. ### What it demonstrates | Area | Implementation | | ---------------- | ------------------------------------------------------------------------ | | Detection | Local rules evaluate synthetic Windows, Entra and Sentinel-style signals | | Investigation | Incident queue, entities, timeline, evidence desk and rule evaluation | | Analyst workflow | Triage statuses, persistent notes, decisions and case closure | | Training | Guided activities, separate knowledge checks and contextual feedback | | Evidence | Reproducible JSON and Markdown exports | | Portability | Python CLI, SQLite, static hub and Windows helper scripts | ### Architecture ```mermaid flowchart LR EVENTS[Synthetic events] --> ENGINE[Local detection engine] ENGINE --> ALERTS[Alerts] ALERTS --> CASES[Incidents and cases] CASES --> WORKBENCH[Analyst Workbench] WORKBENCH --> SQLITE[(Local SQLite)] WORKBENCH --> EVIDENCE[JSON / Markdown evidence] HUB[Static public hub] --> LABS[Three connected labs] ``` All live data stays in `live_lab.sqlite` on the local machine. Alerts are generated as events arrive rather than being pre-rendered from a scenario. ### Public hub and connected labs The hub brings together public demos, documentation, repositories and suggested walkthroughs without duplicating the original projects. | Lab | Detection layer | Demo | Documentation | | ------------------------------------ | ----------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------- | | Windows Authentication Detection Lab | Endpoint authentication | [Open](https://rubenasuasoto.github.io/windows-authentication-detection-lab/reports/latest/demo.html) | [Read](https://2dam-7.gitbook.io/window-auth/) | | Microsoft Entra Detection Lab | Cloud identity | [Open](https://rubenasuasoto.github.io/microsoft-entra-detection-lab/reports/latest/demo.html) | [Read](https://2dam-7.gitbook.io/window-entra/) | | Microsoft Sentinel KQL Detection Lab | SIEM correlation | [Open](https://rubenasuasoto.github.io/microsoft-sentinel-kql-detection-lab/reports/latest/demo.html) | [Read](https://2dam-7.gitbook.io/window-sentinel/) | Recommended path: 1. `AUTH-003-POS`: repeated authentication failures followed by success. 2. `ENTRA-003-POS`: repeated MFA denials followed by a successful sign-in. 3. `SENT-006-POS`: correlation between cloud identity and endpoint signals. ### Quick start Requirements: Python 3.12 and [`uv`](https://docs.astral.sh/uv/). ```powershell uv sync --extra dev --locked uv run identitylab build-site uv run identitylab verify uv run identitylab all uv run identitylab vm-check uv run identitylab live ``` Open the static hub at `site/index.html` or the Live Lab at: ``` http://127.0.0.1:8090/ ``` ### Live Lab The workbench provides an incident queue, incident detail, entities, rule evaluation, analyst states and persistent notes. * `CASE-001` is a complete SOC-style case with benign noise, a cross-source identity incident, analyst tasks, closure and evidence export. * `TRAIN-001` guides learners through briefing, evidence-led decisions, correlation, triage and feedback. * `TRAIN-002` covers repeated Entra MFA denials followed by a successful sign-in from the same account and source IP. * Evidence is available during the activity and deliberately separated from the knowledge check. Start the environment with: ```powershell .\scripts\start-live-lab.ps1 ``` On a dedicated Windows lab machine, optional user-level startup and safe update helpers are available: ```powershell .\scripts\install-live-lab-task.ps1 .\scripts\update-live-lab.ps1 .\scripts\uninstall-live-lab-task.ps1 ``` The installer attempts a least-privilege Scheduled Task and falls back to the current user's Startup folder when task registration is unavailable. ### Validation ```powershell uv run ruff check . uv run pytest uv run identitylab build-site uv run identitylab verify uv run identitylab all uv run identitylab vm-check ``` Secret scanning and dependency checks are included in the validation workflow. ### Documentation * [Live Lab guide](https://github.com/rubenasuasoto/defensive-identity-lab-vm/tree/main/docs/LIVE_LAB.md) * [Portable setup](https://github.com/rubenasuasoto/defensive-identity-lab-vm/tree/main/docs/PORTABLE_SETUP.md) * [VM plan and evidence checklist](/defensive-lab/docs/vm_plan.md) * [Release checklist](/defensive-lab/docs/release_checklist.md) * [Security policy](https://github.com/rubenasuasoto/defensive-identity-lab-vm/tree/main/SECURITY.md) ### Scope This is a defensive learning project, not a production SIEM, an identity provider or an offensive security toolkit. The current VM direction is intentionally phased and documented rather than presented as complete. ### Licence See the repository licence and the connected labs' individual terms before reuse. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://2dam-7.gitbook.io/defensive-lab/readme.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.