leukquant 0.1.2

Fully Local, Decentralized Threat Defense

Leukquant — Fully Local, Decentralized Threat Defense

Zero cloud. Zero corporate telemetry. Zero single point of failure.

---

Overview

Leukquant is a fully offline, privacy-first endpoint threat-defense system. It combines on-device AI malware classification, a behavioral anomaly profiler, and post-quantum cryptography — all running locally with no cloud calls, no telemetry, and no account required.

The blockchain threat ledger is currently disabled. Detection relies on local ONNX AI models trained on datasets such as EMBER, VirusShare, and Kaggle malware corpora.

---

Features

Feature	Description
Local AI Scanning	On-device malware classification via ONNX RandomForest models. No telemetry.
Behavior Profiler	Learns a 14-day baseline of normal system activity and flags statistical deviations using Z-score analysis.
Post-Quantum Crypto Vault	Encrypts files with NIST PQC standards (ML-KEM-1024, ML-DSA-87, SLH-DSA). Falls back to X25519/Ed25519 when liboqs is unavailable.
Signature Database	Local SQLite database of SHA-256 / MD5 threat hashes. Supports bulk VirusShare imports.
Offline Sync	Export/import signed threat signatures as tamper-evident .lqsig bundles for air-gapped machines.
Quarantine Manager	Isolates suspicious files with forensic secure-delete on removal.
Auto-Start Service	Registers the monitor daemon as a systemd user unit (Linux) or Task Scheduler task (Windows).

---

Architecture

~/.leukquant/           ← all runtime data (override with LEUKQUANT_HOME)
  config/Leukquant.yml  ← YAML runtime config
  models/               ← ONNX model + .meta.json
  db/                   ← threats.db, behavior_baseline.db (SQLite)
  keys/                 ← kem.pub/priv, sig.pub/priv
  logs/                 ← monitor.pid, application logs
  quarantine/           ← isolated malicious files
  exports/              ← .lqsig signature bundles
  data/                 ← optional dataset downloads

Scan pipeline (two-stage):

1. Signature lookup — SHA-256 and MD5 checked against threats.db.
2. AI inference — 258-dim basic (file-size + Shannon entropy + byte histogram) or 2351-dim EMBER feature vector fed into an ONNX RandomForest.

---

Requirements

• Python 3.10 or newer
• Linux, macOS, or Windows

Optional — enable post-quantum cryptography:

# Install the liboqs C library first: https://github.com/open-quantum-safe/liboqs
pip install liboqs-python

Optional — enable the EMBER 2351-feature extractor:

pip install ember lief

---

Installation

git clone https://github.com/leukquant/leukquant
cd leukquant
pip install -r requirements.txt
pip install -e .

First-run initialization

Creates all required directories, SQLite databases, and a fresh PQ keypair:

leukquant init

---

Usage

1. Train the AI Model

# Synthetic data — no dataset needed (good for testing)
leukquant train

# EMBER 2018 PE dataset (~1 M samples, 2351 features)
leukquant train --source ember --ember-dir ~/data/ember2018

# VirusShare hash list → populates signature DB only (no ONNX model produced)
leukquant train --source virusshare --hash-list ~/VirusShare_00000.md5

# Kaggle CSV feature file
leukquant train --source kaggle --csv ~/malware_features.csv

# Raw binary sample directories
leukquant train --source files --malware-dir ~/samples/mal --benign-dir ~/samples/ok

2. Scan Files

# Scan a single file
leukquant scan --file /path/to/suspicious.exe

# Scan a directory recursively
leukquant scan --file /path/to/dir

# Auto-quarantine any file flagged as MALICIOUS
leukquant scan --file /path/to/dir --quarantine-on-detect

3. Behavior Monitor

# Foreground (Ctrl+C to stop)
leukquant monitor start

# Background daemon
leukquant monitor start --daemon

# Show live snapshot + recent anomalies
leukquant monitor status

# Stop the background daemon
leukquant monitor stop

4. Post-Quantum File Encryption

# Encrypt a file (produces secret.pdf.sqe)
leukquant encrypt --file secret.pdf

# Decrypt (produces secret.pdf.dec by default)
leukquant decrypt --file secret.pdf.sqe

# Decrypt to a specific output path
leukquant decrypt --file secret.pdf.sqe --key ~/.leukquant/keys/kem.priv --output secret.pdf

# Verify the digital signature of an encrypted bundle without decrypting it
leukquant verify --file secret.pdf.sqe

Key paths (defaults under ~/.leukquant/keys/):

• Private KEM key: kem.priv
• Public KEM key: kem.pub
• Signing key: sig.priv / sig.pub

5. Key Management

# Generate a named keypair
leukquant keygen --name alice

6. Signature Management

# Manually add a hash to the local threat DB
leukquant add-sig --hash <sha256>

# Export all signatures to a signed bundle (for air-gap transfer)
leukquant export-sigs --output /media/usb/sigs.lqsig

# Import and verify a signature bundle
leukquant import-sigs --input /media/usb/sigs.lqsig

7. Quarantine

# List quarantined files
leukquant quarantine list

# Restore a quarantined file to its original location
leukquant quarantine restore --id <uuid-prefix>

# Permanently and securely delete a quarantined file
leukquant quarantine delete --id <uuid-prefix>

8. Auto-Start Service

# Install the monitor as a persistent service (survives reboots)
#   Linux   → systemd user unit (~/.config/systemd/user/leukquant.service)
#   Windows → Task Scheduler task (Leukquant\Monitor)
leukquant service install

# Remove the service
leukquant service uninstall

9. System Status Dashboard

leukquant status

---

Configuration

The config file is written to ~/.leukquant/config/Leukquant.yml on first run. Override the entire data directory with the LEUKQUANT_HOME environment variable.

Key settings:

behavior:
  baseline_period_days: 14
  alert_threshold: 3.5       # Z-score alert level
  quarantine_threshold: 5.0  # Z-score critical level

scanner:
  malware_threshold: 0.85    # AI confidence threshold (0.0–1.0)

crypto:
  default_kem: ML-KEM-1024
  default_sig: ML-DSA-87

---

Datasets for Training

Dataset	Type	URL
EMBER 2018	~1 M labeled PE samples (2351 features)	elastic/ember
VirusShare	MD5 / SHA-256 hash lists	virusshare.com/hashfiles (free, no login)
Kaggle Malware	Various CSV feature datasets	kaggle.com

After training, the model is saved to ~/.leukquant/models/malware_detector.onnx.

---

Source Layout

src/
  cli/main.py           CLI entry point (Click)
  scanner/
    scan.py             Two-stage scanner (signature DB + AI model)
    train.py            Model training pipeline
    extract.py          Feature extraction (basic 258-dim / EMBER 2351-dim)
    dataset_loaders.py  EMBER / VirusShare / Kaggle / file-dir loaders
  behavior/
    profiler.py         Z-score anomaly detection loop
    monitors.py         psutil + watchdog system-metrics collector
  crypto/
    pq_encrypt.py       ML-KEM + AES-256-GCM + ML-DSA encryption vault
    key_manager.py      Keypair generation, persistence, sign/verify
  db/database.py        SQLite layer (threats, metrics, quarantine, anomalies)
  quarantine/manager.py Quarantine move / restore / secure-delete
  offline/sync.py       .lqsig export/import with HMAC integrity (V2 format)
  service.py            systemd user unit / Task Scheduler installer
  config.py             YAML config with deep-merge defaults
  paths.py              Platform-aware APP_DIR (~/.leukquant)