Metadata-Version: 2.4
Name: leukquant
Version: 0.1.1
Summary: Fully Local, Decentralized Threat Defense
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: onnxruntime>=1.16.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: click>=8.1.7
Requires-Dist: rich>=13.7.0
Requires-Dist: watchdog>=3.0.0
Requires-Dist: scikit-learn>=1.3.2
Requires-Dist: skl2onnx>=1.16.0
Provides-Extra: pqc
Requires-Dist: liboqs-python>=0.8.0; extra == "pqc"
Provides-Extra: ember
Requires-Dist: ember; extra == "ember"
Requires-Dist: lief; extra == "ember"
Provides-Extra: kaggle
Requires-Dist: kaggle; extra == "kaggle"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"

# Leukquant — Fully Local, Decentralized Threat Defense

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

[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

---

## 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:
```bash
# Install the liboqs C library first: https://github.com/open-quantum-safe/liboqs
pip install liboqs-python
```

Optional — enable the EMBER 2351-feature extractor:
```bash
pip install ember lief
```

---

## Installation

```bash
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:

```bash
leukquant init
```

---

## Usage

### 1. Train the AI Model

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Generate a named keypair
leukquant keygen --name alice
```

### 6. Signature Management

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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:

```yaml
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](https://github.com/elastic/ember) |
| **VirusShare** | MD5 / SHA-256 hash lists | [virusshare.com/hashfiles](https://virusshare.com/hashfiles) (free, no login) |
| **Kaggle Malware** | Various CSV feature datasets | [kaggle.com](https://www.kaggle.com/datasets/rtatman/malware-classification) |

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)
```
