The self-hosted KQL query management platform for SOC teams

Passphrase authentication · AES-256-GCM encryption · MITRE ATT&CK mapping · Investigation tracking

SOC analysts accumulate hundreds of KQL queries across Microsoft Defender and Azure Sentinel. They live in Notepad, Notion, shared drives — undocumented, unsearchable, scattered across teams.

KQLab centralizes them in a self-hosted, encrypted platform: team-based sharing, MITRE ATT&CK mapping, investigation tracking, and passphrase authentication — with zero cloud dependency and zero vendor lock-in.

Deploy it on your infrastructure. Own your data.

• Node.js LTS ≥ 18
• npm (bundled with Node.js)

node --version   # v18.x or higher
npm --version

git clone https://github.com/vinsk0h/kqlab.git
cd kqlab

npm install

Windows — build error on better-sqlite3? Install Visual Studio Build Tools then retry npm install.

cp .env.example .env

Generate secret keys (run twice — you need two different keys):

npm run keygen   # → paste as DB_ENCRYPTION_KEY
npm run keygen   # → paste as SESSION_SECRET

Minimal .env for local development:

PORT=3000
DB_ENCRYPTION_KEY=<64-char hex key>
SESSION_SECRET=<64-char hex key>

RP_ID, RP_NAME, and ORIGIN are legacy fields kept for compatibility — they are not required for passphrase-based auth.

npm start

Open http://localhost:3000 — the demo account john.doe is pre-seeded (read-only access). Create your own account via the registration form.

Docker is the recommended deployment method for production — no Node.js install required on the host.

• Docker ≥ 24
• Docker Compose v2 (docker compose, not docker-compose)

cp .env.example .env

Edit .env with your values. At minimum, set the three required fields:

DB_ENCRYPTION_KEY=<64-char hex>
SESSION_SECRET=<64-char hex>

No Node.js locally? Generate keys with Docker:

docker run --rm node:20-alpine node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Run twice — one value per key.

docker compose up -d --build

Open http://localhost:3000 — demo account john.doe is pre-seeded.

docker compose logs -f kqlab            # stream logs
docker compose ps                       # check health status
docker compose restart kqlab           # restart container
docker compose down                     # stop (data preserved in volume)
docker compose down -v                  # stop + delete database volume
docker exec -it kqlab sh               # open shell inside container
docker exec kqlab npm run sync-repos   # trigger GitHub repo sync

The database lives in a named Docker volume (kqlab-db). Back it up with:

# Backup
docker run --rm \
  -v kqlab-db:/data \
  -v "$(pwd)":/backup \
  alpine tar czf /backup/kqlab-$(date +%Y%m%d).tar.gz -C /data .

# Restore (container must be stopped first)
docker compose down
docker run --rm \
  -v kqlab-db:/data \
  -v "$(pwd)":/backup \
  alpine tar xzf /backup/kqlab-<date>.tar.gz -C /data
docker compose up -d

KQLab is designed for self-hosted enterprise deployments behind a reverse proxy (nginx, Caddy, Traefik).

NODE_ENV=production

NODE_ENV=production enables secure (HTTPS-only) session cookies and stricter CSP. HTTPS is strongly recommended in production to protect credentials in transit.

Internet → HTTPS reverse proxy → KQLab (127.0.0.1:3000)

Docker (recommended): set the env vars above in .env, then docker compose up -d --build. Place a TLS-terminating reverse proxy in front. Example Caddy config:

kqlab.yourdomain.com {
    reverse_proxy kqlab:3000
}

Bare metal: bind KQLab to 127.0.0.1 only and let the reverse proxy handle TLS. The SQLite database is at backend/db/kqlab.db — back it up regularly.

# GitHub token — raises repo sync rate limit from 60 to 5000 req/h
GITHUB_TOKEN=<personal access token, scope: public_repo>

# VirusTotal — IoC enrichment (free: 4 req/min, 500 req/day)
VT_API_KEY=<your VT api key>

To report a vulnerability, open a GitHub Security Advisory — do not use public issues.

Users belong to exactly one team. Queries, folders, and investigations are scoped to teams.

npm start              # Production server (port 3000)
npm run dev            # Dev server with file watch (auto-restart)
npm run keygen         # Generate a 64-char hex secret key
npm run sync-repos     # Sync queries from configured GitHub repositories
npm run release:patch  # Bump patch version + git tag (2.1.1 → 2.1.2)
npm run release:minor  # Bump minor version + git tag (2.1.1 → 2.2.0)
npm run release:major  # Bump major version + git tag (2.1.1 → 3.0.0)

KQLab exposes a full REST API. All endpoints require authentication (/api/auth/* excepted) and return JSON.

See docs/API.md for the full endpoint reference.

kqlab/
├── frontend/
│   ├── index.html              # Main SPA
│   ├── admin.html              # Admin portal
│   ├── investigations.html     # Investigations view
│   └── js/
│       ├── app.js              # UI state + render loop
│       ├── admin.js            # Admin portal UI
│       ├── admin-templates.js  # Report template editor UI
│       ├── api.js              # REST fetch wrapper (GET/POST/PUT/DELETE)
│       ├── auth.js             # Auth client helpers
│       ├── data.js             # MITRE/SANS IR Cycle constants, query variable templates, enums
│       ├── i18n.js             # Internationalisation (FR/EN)
│       ├── investigations.js   # Investigation UI
│       ├── kql-monaco.js       # Monaco editor integration
│       ├── rich-editor.js      # Rich text editor (findings)
│       └── chart.umd.min.js    # Chart.js (bundled, admin dashboard)
├── backend/
│   ├── server.js               # Express entry point + rate limiting
│   ├── db/database.js          # SQLite init · AES-256-GCM · seed data
│   ├── lib/
│   │   ├── sanitize.js         # Input sanitization helpers
│   │   ├── reportGenerator.js  # PDF / DOCX / HTML report generation
│   │   ├── repo-parser.js      # GitHub repo sync engine
│   │   └── watch-engine.js     # Threat feed fetcher
│   ├── middleware/
│   │   ├── auth.js             # requireAuth()
│   │   ├── roles.js            # requireWriter(), requireAdmin()
│   │   └── utils.js            # Re-exports from lib/sanitize + roles
│   └── routes/
│       ├── auth.js             # Register · login · session · lockout
│       ├── queries.js          # KQL CRUD · star · import · export
│       ├── folders.js          # Folder CRUD
│       ├── comments.js         # Per-query comments
│       ├── investigations.js   # Investigations · IoCs · findings · reports
│       ├── templates.js        # Report templates (admin)
│       ├── settings.js         # System + report settings (admin)
│       ├── fingerprint.js      # Environment profiles + compatibility
│       ├── repos.js            # GitHub repo sources + sync
│       ├── watch.js            # Threat feeds + articles
│       └── admin.js            # User/team/audit management
├── scripts/
│   └── sync-repos.js           # Standalone repo sync runner
├── docs/
│   └── API.md                  # Full REST API reference
├── .env.example
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── .dockerignore
├── CHANGELOG.md
├── LICENSE
└── package.json

better-sqlite3 fails to compile (Windows) Install Visual Studio Build Tools then npm install.

Port 3000 already in use

netstat -ano | findstr :3000
taskkill /PID <pid> /F

Or set a different PORT= in .env.

Login fails in production (cookie not sent) Session cookies use the Secure flag when NODE_ENV=production. Ensure you're serving over HTTPS — cookies won't be sent over plain HTTP in production mode.

Reset the database

rm backend/db/kqlab.db
npm start   # re-seeds with demo data automatically

Docker: container exits immediately Check logs: docker compose logs kqlab. Most common cause: DB_ENCRYPTION_KEY missing or too short (min 32 chars).

Docker: port already in use Set PORT=8080 in .env, then docker compose up -d.

Docker: healthcheck stuck in "starting" Normal for the first 15 seconds while Node initializes. Check with docker compose ps after startup.

Docker: volume permission error

docker compose down -v && docker compose up -d --build

Contributions are welcome. Please:

1. Fork the repo and create a branch from main
2. Follow the commit convention: feat: fix: docs: security: chore:
3. Open a pull request with a clear description of the change

For significant changes, open an issue first to discuss the approach.

See CHANGELOG.md for the full version history.

MIT — see LICENSE for details.