# Lab Runbook

## Scope

Use this runbook only in an authorized Windows lab or isolated VM environment. This project is a defensive monitoring baseline and should not be used in production or on systems you do not own or manage.

## Prerequisites

- Windows VM or isolated test host
- Administrator access in the test environment
- WDK or compatible driver build tooling if compiling the kernel driver
- Test authorization and a controlled rollback plan
- Python 3.10 or newer with tkinter/Tk support

## Step 1: Validate project state

From the repo root, verify the project baseline:

```powershell
python -c "import sys, unittest; sys.path.insert(0, r'.'); suite = unittest.defaultTestLoader.discover('tests'); result = unittest.TextTestRunner(verbosity=2).run(suite); raise SystemExit(0 if result.wasSuccessful() else 1)"
```

Expected result: all tests pass.

## Step 2: Confirm package readiness

Review the deployment validation output:

```powershell
python -c "from core.deployment_validation import DeploymentValidator; import json; print(json.dumps(DeploymentValidator().validate(), indent=2, sort_keys=True))"
```

Confirm the package files and demand-start configuration are present.

## Step 3: Install the driver package

Run the installation script from an elevated PowerShell prompt:

```powershell
Set-ExecutionPolicy -Scope Process Bypass
./scripts/install_driver.ps1
```

The project is configured for demand-start installation semantics rather than boot-start.

## Step 4: Start the relay service wrapper

```powershell
python .\core\service_wrapper.py --start
```

Check status:

```powershell
python .\core\service_wrapper.py --status
```

## Step 5: Capture telemetry

The relay writes JSONL telemetry to the configured location. Review the generated output under the configured log directory and check for process_started and process_exited events.

## Step 6: Export a monitoring report

```powershell
python -c "from core.reporting import ReportBuilder; import json; report = ReportBuilder([], [], []); print(report.build_status_snapshot())"
```

For a file export:

```powershell
python -c "from core.reporting import ReportBuilder; report = ReportBuilder([], [], []); print(report.write_status_snapshot('C:/Logs/monitor_snapshot.json'))"
```

## Step 7: Stop and clean up

```powershell
python .\core\service_wrapper.py --stop
```

Uninstall the driver package when finished:

```powershell
./scripts/uninstall_driver.ps1
```

## Safety note

This project is intentionally transparent and log-oriented. It is intended for defensive monitoring in controlled environments only.

## Windows desktop GUI

Launch from the repository root:

```powershell
python -m gui.app
```

The GUI pages are Overview, Live Processes, Events, Alerts, Driver & Relay, Remediation, Configuration, Logs, and About. It reads current state without automatically starting or installing anything.

The operational data flow is:

1. `ProcessMonitor.sys` provides kernel observation.
2. The persistent relay polls process state and writes JSONL.
3. `data/processmonitor.db` stores normalized events and alerts.
4. The GUI presents these sources and calls the existing relay lifecycle API.

Use **Driver & Relay > Start Relay** and **Stop Relay** for behavior equivalent to:

```powershell
python -m core.service_wrapper --start
python -m core.service_wrapper --status
python -m core.service_wrapper --stop
```

The GUI does not silently elevate. Driver installation/removal, signing, WDK builds, test-signing policy, and kernel service controls remain Administrator-only lab workflows. The Remediation page is visibility-only until a complete preview, confirmation, and recovery contract is available.

Troubleshooting:

- If the driver is not installed or stopped, verify it from an elevated shell with `sc.exe query ProcessMonitor`.
- If the relay is stopped, start it from the GUI or CLI.
- If JSONL is missing, verify relay status, `Telemetry.Path`, and directory permissions.
- If configuration is malformed, restore a `process_monitor_config.json.backup-*` file or correct the JSON manually.
- If the database is unavailable, verify `data/processmonitor.db` is writable and not held by an external SQLite editor.
