# afsh4ck/hacklabs architecture

> Architecture diagram of the GitHub repository afsh4ck/hacklabs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/afsh4ck/hacklabs
- Repository: https://github.com/afsh4ck/hacklabs

## Overview

#### Purpose and Entry Points
HackLabs is an intentionally vulnerable ethical-hacking training platform. The primary Flask application is `app.py`; local initialization runs through `init_db.py`. Container startup is defined by `Dockerfile`, `entrypoint.sh`, and `docker-compose.yml`; `deploy.sh` orchestrates LAN-facing deployment and optional Active Directory infrastructure.

#### Web Application and Lab Engine
`app.py` is the central control plane: it serves the lab routes, applies session-selected difficulty behavior, exposes intentionally insecure endpoints, validates flags, and manages account state. HTML rendering is organized around shared layout and individual lab views:
- `templates/base.html`
- `templates/index.html`
- `templates/labs/`

The application is deliberately not a secure service; vulnerable request handling is the product behavior and must remain isolated from public networks.

#### Accounts, Persistence, and Gamified Progress
SQLite persists both lab-facing seed data and registered-user progress. Schema/bootstrap boundaries are:
- `database/schema.sql`
- `init_db.py`
- `hacklabs.db`

Account pages under `templates/account/` support registration, login, profile, and reset flows. Progress, XP, achievements, completion toggling, and certificate eligibility are user-account features, distinct from intentionally vulnerable lab users.

#### Lab Content and Evidence Delivery
Most web labs pair route logic in `app.py` with a dedicated instructional UI in `templates/labs/`, covering OWASP, API, authentication, AI, and exploitation scenarios. Static content provides client behavior and intentionally exposed/downloadable artifacts:
- `static/js/main.js`
- `static/files/`
- `secret/`

Digital-forensics labs are data-driven: templates present questions and evidence links, while artifact files are shipped in `evidence/forensic/`. Evidence generation utilities live in `ad_hoc/forensics/`.

#### Active Directory Lab Environment
AD labs are a separate, real Samba AD Domain Controller environment rather than Flask-only simulations. Its compose topology and container build are:
- `docker-compose.active-directory.yml`
- `ad_hoc/active_directory/Dockerfile`
- `ad_hoc/active_directory/provision.sh`

The AD container provisions domain identities, services, ACLs, flags, and attack paths; the web app’s AD templates provide target details and guided instructions. `deploy.sh` assigns separate network identity/IPs and updates local name resolution needed for Kerberos.

#### Host/Container Exploitation Scenarios
The primary container intentionally exposes services and host-like artifacts for labs such as SSH, FTP, SMB, LFI, upload, and privilege escalation. Build/runtime definitions are:
- `Dockerfile`
- `docker-compose.yml`
- `etc/passwd`

Container-escape training is deliberately separated into its own dangerous compose scenario:
- `docker-compose.docker-escape.yml`
- `ad_hoc/docker_escape/victim/Dockerfile`
- `ad_hoc/docker_escape/dind/Dockerfile`

#### Deployment Boundaries and External Tooling
Python/Flask is the main runtime, with SQLite embedded locally. Docker Compose provides isolated lab infrastructure; macvlan-style LAN deployment is handled by `deploy.sh`. No external cloud service is required. Learners interact using browser and Kali-compatible offensive/forensic tools; the AD environment additionally exposes DNS, Kerberos, LDAP/LDAPS, and SMB.

Main entry points: [`app.py`](https://github.com/afsh4ck/hacklabs/blob/main/app.py) (Flask lab engine), [`deploy.sh`](https://github.com/afsh4ck/hacklabs/blob/main/deploy.sh) (LAN deployment), [`docker-compose.yml`](https://github.com/afsh4ck/hacklabs/blob/main/docker-compose.yml) (Primary lab container), [`docker-compose.active-directory.yml`](https://github.com/afsh4ck/hacklabs/blob/main/docker-compose.active-directory.yml) (Active Directory topology)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web Lab Platform"]
  node_flask{{"Flask lab engine<br/>Python/Flask<br/>[app.py]"}}
  node_layout["Shared web UI<br/>templates<br/>[base.html]"]
  node_home["Lab catalogue<br/>template<br/>[index.html]"]
  node_lab_views["Lab instructional views<br/>templates"]
  node_account_views["Account views<br/>templates"]
end

subgraph group_data["Data &amp; Lab Content"]
  node_schema["SQLite schema<br/>SQL schema<br/>[schema.sql]"]
  node_initializer["Database bootstrap<br/>Python initializer<br/>[init_db.py]"]
  node_database[("Lab and progress store<br/>SQLite<br/>[hacklabs.db]")]
  node_client_js["Client behavior<br/>JavaScript<br/>[main.js]"]
  node_downloadables["Exposed artifacts<br/>static files"]
  node_secrets["Challenge secrets<br/>lab artifacts"]
  node_forensic_evidence["Forensic evidence<br/>evidence artifacts"]
  node_evidence_tools["Evidence generators<br/>forensics utilities"]
end

subgraph group_infra["Isolated Infrastructure"]
  node_main_compose["Primary lab container<br/>Docker Compose<br/>[docker-compose.yml]"]
  node_main_image["Primary lab image<br/>Docker image build"]
  node_host_accounts["Host-like accounts<br/>passwd artifact"]
  node_deployment["LAN deployment<br/>deployment script<br/>[deploy.sh]"]
  node_ad_compose["Active Directory topology<br/>Docker Compose"]
  node_ad_image["AD controller image<br/>Docker image build"]
  node_ad_provision["AD provisioning<br/>provisioning script<br/>[provision.sh]"]
  node_escape_compose["Container escape scenario<br/>Docker Compose"]
  node_escape_victim["Escape victim image<br/>Docker image build"]
  node_dind_image["DinD image<br/>Docker image build"]
end

node_flask -->|"renders"| node_layout
node_flask -->|"renders"| node_home
node_flask -->|"serves labs through"| node_lab_views
node_flask -->|"serves accounts through"| node_account_views
node_flask -->|"stores users and progress"| node_database
node_flask -->|"delivers"| node_client_js
node_flask -->|"exposes"| node_downloadables
node_flask -->|"uses for challenges"| node_secrets
node_lab_views -->|"links evidence"| node_forensic_evidence
node_evidence_tools -->|"generates"| node_forensic_evidence
node_schema -->|"applied by"| node_initializer
node_initializer -->|"creates and seeds"| node_database
node_main_image -->|"built by"| node_main_compose
node_host_accounts -->|"included in"| node_main_image
node_main_compose -->|"runs"| node_flask
node_deployment -->|"deploys"| node_main_compose
node_ad_image -->|"built by"| node_ad_compose
node_ad_provision -->|"provisions"| node_ad_image
node_deployment -->|"deploys with network identity"| node_ad_compose
node_lab_views -.->|"guides learners to"| node_ad_compose
node_escape_victim -->|"built by"| node_escape_compose
node_dind_image -->|"built by"| node_escape_compose
node_deployment -.->|"kept separate from"| node_escape_compose

click node_flask "https://github.com/afsh4ck/hacklabs/blob/main/app.py"
click node_layout "https://github.com/afsh4ck/hacklabs/blob/main/templates/base.html"
click node_home "https://github.com/afsh4ck/hacklabs/blob/main/templates/index.html"
click node_schema "https://github.com/afsh4ck/hacklabs/blob/main/database/schema.sql"
click node_initializer "https://github.com/afsh4ck/hacklabs/blob/main/init_db.py"
click node_database "https://github.com/afsh4ck/hacklabs/blob/main/hacklabs.db"
click node_client_js "https://github.com/afsh4ck/hacklabs/blob/main/static/js/main.js"
click node_main_compose "https://github.com/afsh4ck/hacklabs/blob/main/docker-compose.yml"
click node_main_image "https://github.com/afsh4ck/hacklabs/blob/main/Dockerfile"
click node_host_accounts "https://github.com/afsh4ck/hacklabs/blob/main/etc/passwd"
click node_deployment "https://github.com/afsh4ck/hacklabs/blob/main/deploy.sh"
click node_ad_compose "https://github.com/afsh4ck/hacklabs/blob/main/docker-compose.active-directory.yml"
click node_ad_image "https://github.com/afsh4ck/hacklabs/blob/main/ad_hoc/active_directory/Dockerfile"
click node_ad_provision "https://github.com/afsh4ck/hacklabs/blob/main/ad_hoc/active_directory/provision.sh"
click node_escape_compose "https://github.com/afsh4ck/hacklabs/blob/main/docker-compose.docker-escape.yml"
click node_escape_victim "https://github.com/afsh4ck/hacklabs/blob/main/ad_hoc/docker_escape/victim/Dockerfile"
click node_dind_image "https://github.com/afsh4ck/hacklabs/blob/main/ad_hoc/docker_escape/dind/Dockerfile"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flask,node_layout,node_home,node_lab_views,node_account_views toneBlue
class node_schema,node_initializer,node_database,node_client_js,node_downloadables,node_secrets,node_forensic_evidence,node_evidence_tools toneAmber
class node_main_compose,node_main_image,node_host_accounts,node_deployment,node_ad_compose,node_ad_image,node_ad_provision,node_escape_compose,node_escape_victim,node_dind_image toneMint
```

## Components

### Web Lab Platform

- [Flask lab engine](https://github.com/afsh4ck/hacklabs/blob/main/app.py): Python/Flask · Central routes, vulnerabilities, flags, sessions, and accounts. · `app.py`
- [Shared web UI](https://github.com/afsh4ck/hacklabs/blob/main/templates/base.html): templates · `templates/base.html`
- [Lab catalogue](https://github.com/afsh4ck/hacklabs/blob/main/templates/index.html): template · `templates/index.html`
- **Lab instructional views**: templates · OWASP, API, authentication, AI, and exploitation lab interfaces.
- **Account views**: templates · Registration, login, profile, and reset interfaces.

### Data & Lab Content

- [SQLite schema](https://github.com/afsh4ck/hacklabs/blob/main/database/schema.sql): SQL schema · `database/schema.sql`
- [Database bootstrap](https://github.com/afsh4ck/hacklabs/blob/main/init_db.py): Python initializer · `init_db.py`
- [Lab and progress store](https://github.com/afsh4ck/hacklabs/blob/main/hacklabs.db): SQLite · Seed lab data and registered-user progress. · `hacklabs.db`
- [Client behavior](https://github.com/afsh4ck/hacklabs/blob/main/static/js/main.js): JavaScript · `static/js/main.js`
- **Exposed artifacts**: static files · Intentionally downloadable lab artifacts.
- **Challenge secrets**: lab artifacts
- **Forensic evidence**: evidence artifacts
- **Evidence generators**: forensics utilities

### Isolated Infrastructure

Dangerous lab environments must remain off public networks.

- [Primary lab container](https://github.com/afsh4ck/hacklabs/blob/main/docker-compose.yml): Docker Compose · Exposes intentionally vulnerable web and host-like services. · `docker-compose.yml`
- [Primary lab image](https://github.com/afsh4ck/hacklabs/blob/main/Dockerfile): Docker image build · `Dockerfile`
- [Host-like accounts](https://github.com/afsh4ck/hacklabs/blob/main/etc/passwd): passwd artifact · `etc/passwd`
- [LAN deployment](https://github.com/afsh4ck/hacklabs/blob/main/deploy.sh): deployment script · Orchestrates LAN addressing and optional AD infrastructure. · `deploy.sh`
- [Active Directory topology](https://github.com/afsh4ck/hacklabs/blob/main/docker-compose.active-directory.yml): Docker Compose · Separate Samba AD Domain Controller environment. · `docker-compose.active-directory.yml`
- [AD controller image](https://github.com/afsh4ck/hacklabs/blob/main/ad_hoc/active_directory/Dockerfile): Docker image build · `ad_hoc/active_directory/Dockerfile`
- [AD provisioning](https://github.com/afsh4ck/hacklabs/blob/main/ad_hoc/active_directory/provision.sh): provisioning script · Creates domain identities, services, ACLs, flags, and attack paths. · `ad_hoc/active_directory/provision.sh`
- [Container escape scenario](https://github.com/afsh4ck/hacklabs/blob/main/docker-compose.docker-escape.yml): Docker Compose · Separately isolated dangerous Docker escape lab. · `docker-compose.docker-escape.yml`
- [Escape victim image](https://github.com/afsh4ck/hacklabs/blob/main/ad_hoc/docker_escape/victim/Dockerfile): Docker image build · `ad_hoc/docker_escape/victim/Dockerfile`
- [DinD image](https://github.com/afsh4ck/hacklabs/blob/main/ad_hoc/docker_escape/dind/Dockerfile): Docker image build · `ad_hoc/docker_escape/dind/Dockerfile`

## Connections

- Flask lab engine → Shared web UI: renders
- Flask lab engine → Lab catalogue: renders
- Flask lab engine → Lab instructional views: serves labs through
- Flask lab engine → Account views: serves accounts through
- Flask lab engine → Lab and progress store: stores users and progress
- Flask lab engine → Client behavior: delivers
- Flask lab engine → Exposed artifacts: exposes
- Flask lab engine → Challenge secrets: uses for challenges
- Lab instructional views → Forensic evidence: links evidence
- Evidence generators → Forensic evidence: generates
- SQLite schema → Database bootstrap: applied by
- Database bootstrap → Lab and progress store: creates and seeds
- Primary lab image → Primary lab container: built by
- Host-like accounts → Primary lab image: included in
- Primary lab container → Flask lab engine: runs
- LAN deployment → Primary lab container: deploys
- AD controller image → Active Directory topology: built by
- AD provisioning → AD controller image: provisions
- LAN deployment → Active Directory topology: deploys with network identity
- Lab instructional views → Active Directory topology: guides learners to
- Escape victim image → Container escape scenario: built by
- DinD image → Container escape scenario: built by
- LAN deployment → Container escape scenario: kept separate from