# Professional Defensive Process Monitoring Baseline

This project is a defensive Windows monitoring baseline for authorized lab and internal use. It is meant to observe process creation and background runtime activity without hiding anything from the operating system or security tooling.

## Executive summary

The design is intentionally transparent and audit-friendly:

- kernel-mode callbacks log process and thread activity
- a user-mode relay polls Windows process state and emits JSONL telemetry
- policy rules classify processes as allowlisted, watchlisted, or high-risk
- the output is suitable for a local dashboard, a SIEM, or a security operations workflow

This is not a stealth tool and not a bypass mechanism. It is a visibility baseline for defensive monitoring.

## Quick start

Python 3.10 or newer is required. The desktop interface uses the standard-library `tkinter`/`ttk` toolkit and requires no third-party GUI framework.

### Launch the Windows desktop console

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

The GUI reads status on launch but does not automatically install or start the driver, start the relay, change Windows security settings, or run remediation. Use **Driver & Relay > Start Relay** and **Stop Relay** for explicit relay control.

### 1. Validate the project

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

### 2. Check deployment readiness

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

### 3. Run the relay service wrapper

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

### 4. Export a monitoring snapshot

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

## Architecture

### 1. Kernel monitoring layer

The C driver is a minimal process/thread observer. It uses the standard Windows kernel notification APIs to log new processes and threads through `DbgPrintEx`.

### 2. Policy layer

The configuration file defines:

- allowed applications
- watchlisted processes
- alert keywords and severity thresholds
- telemetry retention settings
- operational relay settings

### 3. User-mode telemetry relay

The Python relay polls `tasklist` and emits structured JSONL records for:

- process started
- process exited
- heartbeat
- relay status
- alert classification

### 4. Remediation and recovery model

The project also includes a reversible, audit-friendly response workflow that is designed for controlled defensive remediation:

- startup entry backup and restore
- scheduled task disable/restore
- service disable/restore
- registry value rollback
- browser configuration restore
- DNS, proxy, and hosts rollback
- firewall rule state tracking
- Defender posture snapshot and restore
- cleanup playbooks for temporary and suspicious artifacts
- recovery center summary for pending restore actions

This keeps the platform aligned with a transparent “monitor, verify, remediate, and restore” posture rather than silent removal or bypass.

### 5. Operational model

The design supports a realistic security workflow:

- monitor local AI and background processes
- determine whether a process is expected or unusual
- produce audit records for review
- trigger reversible remediation where appropriate
- restore known-good state after a confirmed security action

## Example event

```json
{"timestamp":"2026-08-13T12:00:00+00:00","source":"user_mode_relay","event":"process_started","pid":4321,"image":"ollama.exe","allowlisted":false,"watchlisted":true,"severity":"medium","triggered_rule":true}
```

## Project layout

- `src/process_monitor_driver.c` — kernel driver callbacks
- `src/process_monitor_driver.h` — driver declarations
- `core/event_model.py` — canonical event schema
- `core/database.py` — SQLite storage and retention logic
- `core/collector.py` — tasklist snapshot parsing
- `core/rules.py` — alert evaluation
- `core/reporting.py` — summary and JSON snapshot export
- `core/dashboard.py` — lightweight local dashboard wrapper
- `core/service_runtime.py` — telemetry service runtime loop
- `core/service_wrapper.py` — start/stop life cycle wrapper
- `core/deployment_validation.py` — package validation checks
- `config/process_monitor_config.json` — monitoring policy and runtime settings
- `scripts/install_driver.ps1` — installation workflow for an authorized environment
- `scripts/uninstall_driver.ps1` — removal workflow
- `docs/LAB_RUNBOOK.md` — controlled VM deployment workflow
- `docs/FINAL_PROJECT_SUMMARY.md` — project snapshot and status summary

## Safe operational guidance

Use this only in:

- a VM or sandbox you control
- a lab or internal environment with explicit authorization
- a defensive security exercise with logging and governance

Kernel driver work is high-risk: a bad build can destabilize or crash Windows. Always test in a disposable environment.

## Release checklist

- tests pass
- deployment validation passes
- INF uses demand-start semantics
- install and uninstall scripts are present
- telemetry JSONL output is enabled
- retention and health logging are configured
- service wrapper starts and stops cleanly
- logs are reviewed in a controlled lab environment

## Legal and ethical use

This project is for lawful monitoring, defensive engineering, and research in authorized environments. It is not intended to conceal, remove, or bypass the OS or security controls.

## Desktop GUI architecture and features

The kernel driver provides the kernel observation layer. The persistent user-mode relay polls Windows process state, writes JSONL telemetry, and updates `data/processmonitor.db`. The GUI consumes the relay status and stored telemetry without creating another collector or lifecycle implementation.

The dark, resizable desktop console includes:

- **Overview** — health cards, counts, uptime, and recent events
- **Live Processes** — active-process projection, search, filters, and sortable columns
- **Events** — SQLite event browsing, filtering, sorting, and CSV export
- **Alerts** — stored alerts and high-risk telemetry with severity coloring
- **Driver & Relay** — read-only kernel service inspection and persistent relay controls
- **Remediation** — read-only transaction, recovery, and audit visibility
- **Configuration** — validation, timestamped backup, and atomic save
- **Logs** — view-only JSONL search/filter, copy, and jump-to-newest
- **About** — architecture and safety boundaries

The GUI never silently elevates. Driver installation, service control, signing, WDK builds, and test-signing policy remain Administrator-only lab workflows. If driver status is unavailable, confirm Windows, the `ProcessMonitor` service name, and signed package installation. If telemetry is missing, start the relay and verify the configured JSONL directory is writable. Malformed configuration is reported and is not overwritten.
