winhelm-mcp 1.1.0

package/docs/PROFILES.md

@@ -0,0 +1,423 @@
+# WinHelm MCP — Tool Profiles & Context Optimization
+
+Modern AI coding assistants consume **thousands of tokens before the first message** just to load tool schemas. Every tool definition (name, description, parameter types, enums, defaults) is sent on every request — even when the tool is never called.
+
+WinHelm solves this with **Dynamic Profile Loading**: you decide which subset of the 38 tools your agent actually sees.
+
+---
+
+## Table of Contents
+
+- [Why Profiles Matter](#why-profiles-matter)
+- [The Token Math](#the-token-math)
+- [Built-in Profiles](#built-in-profiles)
+  - [`minimal` — 6 tools](#minimal--6-tools-small-models--token-constrained-workflows)
+  - [`core` — 15 tools](#core--15-tools-general-purpose-baseline)
+  - [`dev` — 28 tools](#dev--28-tools-software-development)
+  - [`sysadmin` — 37 tools](#sysadmin--37-tools-system-administration)
+  - [`full` — 38 tools](#full--38-tools-everything)
+- [Comparison Matrix](#comparison-matrix)
+- [Custom Profiles (`--tools`)](#custom-profiles---tools)
+- [Use Case Recipes](#use-case-recipes)
+- [FAQ](#faq)
+
+---
+
+## Why Profiles Matter
+
+Every MCP tool schema averages **200–300 tokens** when serialized. Loading all 38 tools means:
+
+- **~10,000 tokens** consumed before the conversation even starts
+- **Slower tool selection** — the model scans 38 candidates to pick the right one
+- **Higher hallucination rate** — overlapping tool names increase wrong-tool calls
+- **Higher cost** — every turn re-sends the full tool list
+
+For small models (Claude Haiku, Llama 3 8B, Phi-3), the entire context window is only 8k–32k tokens. Loading 38 tools can consume **50–100% of the window** before any user message.
+
+**Loading only what you need is the single highest-leverage optimization.**
+
+---
+
+## The Token Math
+
+Estimated based on schema serialization + description length:
+
+| Profile | Tools | Approx. Tokens | Context Saved | Best For |
+| :--- | :---: | :---: | :---: | :--- |
+| `full` | 38 | ~10,000 | baseline | Power users, visual previews & complete suite |
+| `sysadmin` | 37 | ~9,200 | **−8%** | IT ops, server diagnostics, Windows services |
+| `dev` | 28 | ~6,800 | **−32%** | Coding agents (default for software engineering) |
+| `core` | 15 | ~4,000 | **−60%** | Everyday coding & file operations |
+| `minimal` | 6 | ~1,500 | **−85%** | Claude Haiku, Llama 8B, local models |
+
+> **Real-world impact:** Running Claude Haiku 3.5 (200k context) with `full` wastes ~5% of the window on tools. Running Llama 3.1 8B (8k context) with `full` is **impossible** — the tool list alone overflows the context.
+
+---
+
+## Built-in Profiles
+
+### `minimal` — 6 tools (Small Models / Token-Constrained Workflows)
+
+```powershell
+winhelm --profile minimal
+```
+
+**Tools included:**
+
+| Tool | Purpose |
+| :--- | :--- |
+| `terminal_run` | Run PowerShell commands |
+| `file_read` | Read file contents |
+| `file_write` | Create / overwrite files |
+| `file_list` | List directories |
+| `file_search` | Substring search across files |
+| `system_info` | CPU / RAM / OS / drives telemetry |
+
+**Use when:**
+- Running Claude Haiku, Llama 3 8B, Phi-3, or any model with ≤ 32k context
+- You need a fast, focused agent that only reads/writes code
+- You want to minimize cost per request
+
+**Trade-offs:**
+- No file editing (use `file_write` instead)
+- No background tasks
+- No process/service management
+
+---
+
+### `core` — 15 tools (General-Purpose Baseline)
+
+```powershell
+winhelm --profile core
+```
+
+**Tools included:**
+
+| Category | Tools |
+| :--- | :--- |
+| Terminal | `terminal_run` |
+| Filesystem | `file_read`, `file_write`, `file_edit`, `file_list`, `file_search`, `file_copy`, `file_move`, `file_delete_safe`, `file_tail`, `file_hash` |
+| System | `system_info`, `gpu_info`, `process_list`, `port_check` |
+
+**Use when:**
+- General-purpose assistant that edits code but doesn't build/run long tasks
+- You want safe file operations (Recycle Bin delete) without archive/PDF bloat
+- Balanced default for most users
+
+**Trade-offs:**
+- No background daemons (can't run `npm run dev` async)
+- No ripgrep (slower search on large codebases)
+- No PDF / preview / clipboard / notification
+
+---
+
+### `dev` — 28 tools (Software Development)
+
+```powershell
+winhelm --profile dev
+```
+
+**Tools included:** All `core` (15 tools) + the following 13 tools:
+
+| Category | Added Tools |
+| :--- | :--- |
+| Terminal | `terminal_task_start`, `terminal_task_list`, `terminal_task_logs`, `terminal_task_send`, `terminal_task_kill` |
+| Filesystem | `archive_zip`, `archive_unzip` |
+| Codebase & Docs | `file_search_ripgrep`, `pdf_generate`, `file_preview` |
+| Network | `http_ping`, `http_request` |
+| Desktop | `system_open` |
+
+**Use when:**
+- Autonomous coding agents (Claude 3.7 Sonnet, Cursor, Cline, Windsurf, ChatGPT)
+- Running dev servers, test watchers, or builds in the background
+- Searching large codebases with streaming ripgrep
+- Testing REST API endpoints (`http_request`) and health checks (`http_ping`)
+- Zipping build artifacts and exporting Markdown documentation to styled PDFs
+- Opening generated files or URLs in default applications (`system_open`)
+
+**Trade-offs:**
+- No process kill (guards against accidental termination of system processes)
+- No Windows service control
+- No Windows event log inspection
+- No desktop surveillance (clipboard and screen capture omitted)
+
+> **This is the recommended default for software engineering agents.**
+
+---
+
+### `sysadmin` — 37 tools (System Administration & Ops)
+
+```powershell
+winhelm --profile sysadmin
+```
+
+**Tools included:** All tools in WinHelm **except `pdf_generate`** (All `core` + 22 advanced tools):
+
+| Category | Added Tools |
+| :--- | :--- |
+| Terminal | `terminal_task_start`, `terminal_task_list`, `terminal_task_logs`, `terminal_task_send`, `terminal_task_kill` |
+| Filesystem | `archive_zip`, `archive_unzip` |
+| Codebase & Preview | `file_search_ripgrep`, `file_preview` |
+| System | `process_kill`, `eventlog_query` |
+| Services | `service_list`, `service_status`, `service_control` |
+| Network | `network_info`, `http_ping`, `http_request` |
+| Desktop | `clipboard_get`, `clipboard_set`, `screen_capture`, `system_open`, `notification_send` |
+
+**Use when:**
+- IT operations, Windows DevOps, and server management
+- Troubleshooting crashes via Windows Event Log and killing runaway PIDs
+- Starting, stopping, and inspecting Windows Services
+- Searching massive server logs with ripgrep and archiving bundles to `.zip`
+- Inspecting network adapters, DNS, open ports, and Tailscale IPs
+- Desktop automation with native Toast notifications and screenshot capture
+
+**Trade-offs:**
+- No headless Chromium PDF generation (`pdf_generate` omitted to preserve a clean, lightweight footprint in headless/server environments without Edge or Chrome)
+
+---
+
+### `full` — 38 tools (Everything)
+
+```powershell
+winhelm --profile full
+```
+
+**Default when `--profile` is omitted.**
+
+Includes **all 38 tools** plus the `preview://file` MCP Resource.
+
+**Use when:**
+- You're building a power-user agent
+- You need every capability in one session
+- You don't care about token cost
+
+**Trade-offs:**
+- Highest token cost
+- Slower tool selection
+- Overkill for 90% of tasks
+
+---
+
+## Comparison Matrix
+
+| Tool | `minimal` (6) | `core` (15) | `dev` (28) | `sysadmin` (37) | `full` (38) |
+| :--- | :---: | :---: | :---: | :---: | :---: |
+| `terminal_run` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `terminal_task_start` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `terminal_task_list` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `terminal_task_logs` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `terminal_task_send` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `terminal_task_kill` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `file_read` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `file_write` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `file_edit` | ❌ | ✅ | ✅ | ✅ | ✅ |
+| `file_list` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `file_search` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `file_delete_safe` | ❌ | ✅ | ✅ | ✅ | ✅ |
+| `file_move` | ❌ | ✅ | ✅ | ✅ | ✅ |
+| `file_copy` | ❌ | ✅ | ✅ | ✅ | ✅ |
+| `archive_zip` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `archive_unzip` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `file_tail` | ❌ | ✅ | ✅ | ✅ | ✅ |
+| `file_hash` | ❌ | ✅ | ✅ | ✅ | ✅ |
+| `file_search_ripgrep` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `pdf_generate` | ❌ | ❌ | ✅ | ❌ | ✅ |
+| `file_preview` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `clipboard_get` | ❌ | ❌ | ❌ | ✅ | ✅ |
+| `clipboard_set` | ❌ | ❌ | ❌ | ✅ | ✅ |
+| `screen_capture` | ❌ | ❌ | ❌ | ✅ | ✅ |
+| `system_open` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `notification_send` | ❌ | ❌ | ❌ | ✅ | ✅ |
+| `system_info` | ✅ | ✅ | ✅ | ✅ | ✅ |
+| `gpu_info` | ❌ | ✅ | ✅ | ✅ | ✅ |
+| `process_list` | ❌ | ✅ | ✅ | ✅ | ✅ |
+| `process_kill` | ❌ | ❌ | ❌ | ✅ | ✅ |
+| `port_check` | ❌ | ✅ | ✅ | ✅ | ✅ |
+| `eventlog_query` | ❌ | ❌ | ❌ | ✅ | ✅ |
+| `service_list` | ❌ | ❌ | ❌ | ✅ | ✅ |
+| `service_status` | ❌ | ❌ | ❌ | ✅ | ✅ |
+| `service_control` | ❌ | ❌ | ❌ | ✅ | ✅ |
+| `http_ping` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `http_request` | ❌ | ❌ | ✅ | ✅ | ✅ |
+| `network_info` | ❌ | ❌ | ❌ | ✅ | ✅ |
+| `preview://file` *(resource)* | ❌ | ❌ | ✅ | ✅ | ✅ |
+| **Total** | **6** | **15** | **28** | **37** | **38** |
+
+---
+
+## Custom Profiles (`--tools`)
+
+For advanced users who need a specific subset, WinHelm supports explicit tool selection:
+
+### Whitelist Mode
+
+Load only the tools you list:
+
+```powershell
+winhelm --profile custom --tools "terminal_run,file_read,file_write,file_list"
+```
+
+### Extend a Preset
+
+Start from a preset and add specific tools:
+
+```powershell
+winhelm --profile dev --tools "+pdf_generate,process_kill"
+```
+
+### Exclude from a Preset
+
+Start from a preset and remove specific tools:
+
+```powershell
+winhelm --profile full --tools "-screen_capture,-clipboard_set"
+```
+
+### Via Config File
+
+```json
+{
+  "profile": "custom",
+  "customTools": [
+    "terminal_run",
+    "file_read",
+    "file_write",
+    "file_list",
+    "system_info"
+  ]
+}
+```
+
+**Validation:**
+- Unknown tool names → startup error with suggestion
+- Conflicting `+` and `-` in the same list → error
+- Empty result → warning + fallback to `core`
+
+---
+
+## Multi-Project Isolation (`--config <path>` & Session Non-Persistence)
+
+When running multiple AI agents or projects concurrently with different security scopes or profiles:
+
+1. **Dedicated Config File per Project (`--config`)**:
+   Point WinHelm to an explicit project configuration file:
+   ```powershell
+   winhelm --config "D:\mcp\configs\project-a.json"
+   ```
+   Or in Claude Desktop configuration:
+   ```json
+   {
+     "mcpServers": {
+       "project-a": {
+         "command": "winhelm",
+         "args": ["--stdio", "--config", "D:\\mcp\\configs\\project-a.json"]
+       }
+     }
+   }
+   ```
+
+2. **Session-Only CLI Overrides (`--no-persist`)**:
+   By default, CLI flags (`--allowed-dirs`, `--auth`, `--profile`, `--tools`, `--read-only`) apply **only to that running instance** without overwriting the config file on disk (`persist = false`). This ensures that multiple instances running in parallel will not clobber each other's settings. To permanently save CLI flags back to disk, explicitly pass `--persist`.
+
+---
+
+## Use Case Recipes
+
+### Recipe 1: Claude Haiku on a Budget
+
+```powershell
+winhelm --profile minimal --port 8788
+```
+
+Result: **~1,500 tokens** for tools → leaves 198k+ for the conversation.
+
+---
+
+### Recipe 2: Cursor AI Coding Agent
+
+```powershell
+winhelm --profile dev --port 8788
+```
+
+Result: **~6,800 tokens** for tools → covers 98% of software development tasks with background tasks, ripgrep, and archives.
+
+---
+
+### Recipe 3: Remote Windows Server Monitoring
+
+```powershell
+winhelm --profile sysadmin --auth <strong-token> --host 0.0.0.0
+```
+
+Result: **~9,200 tokens** → full ops capability without headless Chromium PDF bloat.
+
+---
+
+### Recipe 4: Read-Only Audit Agent
+
+```powershell
+winhelm --profile custom --read-only --tools "file_read,file_list,file_search,file_tail,file_hash,system_info,eventlog_query"
+```
+
+Result: **~2,000 tokens** → no mutation possible, perfect for auditors.
+
+---
+
+### Recipe 5: PDF Report Generator
+
+```powershell
+winhelm --profile custom --tools "file_read,file_write,pdf_generate,file_list,system_info"
+```
+
+Result: **~1,300 tokens** → minimum viable report workflow.
+
+---
+
+## FAQ
+
+**Q: What's the default profile?**  
+A: `full` when `--profile` is omitted. For most users, `dev` is a better default — see recommendations below.
+
+**Q: Can I switch profiles at runtime?**  
+A: No. Profiles are resolved at startup. Restart the server to change.
+
+**Q: Does the profile affect the Web Dashboard?**  
+A: No. The dashboard always shows all metrics regardless of profile.
+
+**Q: Which profile should I start with?**  
+A: 
+- **Coding agents** → `dev`
+- **General assistants** → `core`
+- **Small models** → `minimal`
+- **Ops / IT** → `sysadmin`
+- **Undecided** → `dev`
+
+**Q: How do you calculate token counts?**  
+A: We serialize each tool's JSON schema (name + description + parameters + enums) and count tokens with `tiktoken` (cl100k_base). Actual counts vary ±10% across models.
+
+**Q: Why not just use `full` always?**  
+A: Because every token sent costs money, adds latency, and increases the chance of wrong-tool selection. The difference between `full` and `dev` is ~3,500 tokens **per request**.
+
+**Q: Will you add more profiles?**  
+A: Unlikely. Five profiles cover 99% of use cases. For anything else, use `--tools`.
+
+**Q: Can I define my own named profile?**  
+A: Yes, via `winhelm.config.json`:
+
+```json
+{
+  "profiles": {
+    "mytools": ["terminal_run", "file_read", "system_info"]
+  }
+}
+```
+
+Then: `winhelm --profile mytools`
+
+---
+
+## See Also
+
+- [Tools Reference](./TOOLS.md) — full parameter documentation for every tool
+- [Security Model](./SECURITY.md) — read-only mode, path confinement, blacklist
+- [Real-World Examples](./EXAMPLES.md) — end-to-end agent workflows

package/docs/SECURITY.md

@@ -0,0 +1,190 @@
+# WinHelm MCP — Security Model & Architecture
+
+Security is a foundational design pillar of WinHelm. Giving an AI agent access to terminal execution, filesystem writes, and system processes requires robust, multi-layered safeguards.
+
+---
+
+## 1. Multi-Layer Security Architecture
+
+```
+[ MCP Client / AI Agent ]
+           │
+           ▼
+┌──────────────────────────────────────────────┐
+│  Layer 1: Network & Authentication Gate      │
+│  - Token Authentication (Bearer Header)     │
+│  - Rate Limiting (120 req/min Sliding Window)│
+└──────────────────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────┐
+│  Layer 2: Operation & Read-Only Guard        │
+│  - Enforce Read-Only Mode (--read-only)      │
+│  - Mutating Tools Blocked at Dispatcher      │
+└──────────────────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────┐
+│  Layer 3: Filesystem Confinement             │
+│  - Allowed Directories Whitelist             │
+│  - Drive Letter Isolation (e.g. D:\ only)    │
+│  - Path Traversal (..\) Sanitization         │
+└──────────────────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────┐
+│  Layer 4: Command Filter & Execution Shield  │
+│  - Blacklist Pattern Regex Filtering         │
+│  - Destructive Command Interception          │
+│  - NonInteractive / NoProfile PowerShell     │
+└──────────────────────────────────────────────┘
+           │
+           ▼
+┌──────────────────────────────────────────────┐
+│  Layer 5: Secret Masking & Audit Logging     │
+│  - Auto Redaction of API Keys & Passwords    │
+│  - Daily Rotating Log Files with Hashing     │
+└──────────────────────────────────────────────┘
+```
+
+---
+
+## 2. Authentication & Access Control
+
+By default, WinHelm binds strictly to **`127.0.0.1` (localhost loopback)**, preventing external machines on your local network (LAN) or public internet from reaching the server.
+
+If you bind WinHelm to an external interface (`--host 0.0.0.0`) without an authentication token, a prominent startup warning is emitted to alert you of open exposure. In any shared, multi-user, LAN, or remote setup, you should enforce Bearer Token authentication:
+
+### CLI Flag
+```powershell
+winhelm --auth "my-secure-random-token-here"
+```
+
+### Environment Variable
+```powershell
+$env:MCP_AUTH_TOKEN = "my-secure-random-token-here"
+winhelm
+```
+
+When enabled:
+- All protocol endpoints (`/mcp`, `/sse`, `/message`), file previews (`/preview`), and administrative telemetry APIs (`/api/monitor/*`) require an `Authorization: Bearer <token>` header.
+- For clients without custom header support (such as Claude.ai Custom Connectors) or convenient browser access to the Web Monitor Dashboard and Previewer, the token can also be supplied via URL query parameter (`?token=<token>` or `?auth=<token>`) or browser cookie.
+- Unauthenticated access is strictly confined to public health checks (`/health`) and the basic dashboard HTML shell (`/`, `/dashboard`).
+
+### Disabling Authentication (`"authToken": null`)
+
+If `"authToken"` is explicitly set to `null` in `winhelm.config.json` (or `--auth` / `MCP_AUTH_TOKEN` is omitted):
+- The server operates in **No-Auth Mode** (`Public network mode active (No auth token set)`).
+- Incoming MCP requests and tools are executed without verifying any Bearer token or query token.
+- **Safety Restriction:** This mode should be strictly confined to local loopback development (`127.0.0.1`). Exposing an unauthenticated server with unrestricted drive access to public networks is dangerous and guarded by safety gates in `start-funnel.ps1`.
+
+---
+
+## 3. Read-Only Enforcement Mode
+
+If you wish to allow an AI agent to read code, query event logs, and inspect system telemetry without modifying anything, start WinHelm in **Read-Only Mode**:
+
+```powershell
+winhelm --read-only
+```
+
+When active, any call to mutating tools (e.g. `file_write`, `file_edit`, `file_delete_safe`, `terminal_run`, `process_kill`, `service_control`) is rejected before reaching the execution engine.
+
+---
+
+## 4. Path Confinement (`allowedDirectories`) & Fail-Closed Design
+
+WinHelm follows a **fail-closed by default** security principle:
+- **Default (`allowedDirectories: []` or empty)**: If no allowed directories are configured, **all filesystem operations are strictly blocked**. This prevents accidental full-machine exposure when running an unconfigured instance.
+- **Specific Directory Whitelist**: Specify target directories or drives to restrict access:
+  ```json
+  {
+    "allowedDirectories": [
+      "D:\\mcp",
+      "C:\\Projects"
+    ],
+    "allowSystemExecution": true
+  }
+  ```
+- **Whole-Volume Whitelist**: You can whitelist an entire volume by specifying `"D:\\"`, `"D:"`, or `"D"`.
+- **Wildcard Full-Drive Access (`["*"]` or `["all"]`)**: You can explicitly opt-in to unrestricted machine access by configuring `["*"]` or `["all"]`.
+  > ⚠️ **Warning:** Wildcard access (`["*"]`) should only be used for trusted, local single-user development with authentication enabled. Never expose an unauthenticated server with wildcard access to a public network or reverse proxy.
+- Any attempt to access paths outside the whitelist is rejected with a descriptive security error.
+- Path traversal tricks (`..\..\Windows\System32`) and NTFS directory junctions/symlinks are resolved to canonical real paths via `fs.realpathSync` before boundary checks.
+
+---
+
+---
+
+## 5. Security Model & Trust Boundaries (Important Clarification)
+
+To configure WinHelm safely, understand the distinction between hard security boundaries and defense-in-depth safeguards:
+
+### 🛡️ Hard Security Boundaries
+1. **Authentication Token (`authToken` / `--auth`)**:
+   - The primary security perimeter. When enabled, all MCP protocol interactions, tool dispatches, file previews, and monitoring APIs require token verification via timing-safe comparison (`crypto.timingSafeEqual`).
+2. **Tool Profiles (`--profile minimal` or `--profile core`)**:
+   - The most effective containment strategy. Profiles strictly exclude tools at registration time. Using `core` provides 15 file inspection and reading tools while completely excluding `terminal_run`, `terminal_task_start`, and system mutation tools.
+3. **Read-Only Mode (`--read-only`)**:
+   - Enforces an immutable environment. Blocks all filesystem modifications, archive creations, service controls, process terminations, mutating HTTP methods (POST/PUT/DELETE), and shell executions (`terminal_run` / `terminal_task_start`).
+
+### ⚠️ Defense-in-Depth Safeguards (Not Hard Security Boundaries)
+1. **Command Blocklist Patterns**:
+   - Regex-based command filtering is designed to prevent accidental destructive operations (e.g. `format-volume`, `rmdir /s /q C:\`). It is **not** an impregnable security sandbox against intentional evasion, as PowerShell syntax supports aliases, string concatenation, and encoded commands (`-EncodedCommand`, `iex`).
+2. **Filesystem Confinement (`allowedDirectories`)**:
+   - Strictly confines native **File Tools** (`file_read`, `file_write`, `file_edit`, `file_delete_safe`, `copy_file`, `create_zip`, `extract_zip`). It also sets the working directory for terminal execution. However, if `terminal_run` is enabled (under `dev`, `sysadmin`, or `full` profiles) with `allowSystemExecution: true`, processes run with the full operating system permissions of the Windows user account running WinHelm.
+
+---
+
+## 6. Network Hardening & Web Protections
+
+1. **Host Header Validation (DNS Rebinding Defense)**:
+   - WinHelm validates incoming `Host` headers against an allowlist (`localhost`, `127.0.0.1`, `[::1]`, and configured `allowedHosts` such as `*.ts.net`). Requests with unauthorized host headers are rejected with **HTTP 403 Forbidden**, preventing malicious websites from exploiting browser same-origin policies via DNS rebinding.
+2. **Unauthenticated Remote Proxy / Tunnel Guard**:
+   - If WinHelm is started without an authentication token (`authToken: null`), any request detected arriving through a reverse proxy or tunnel (containing `X-Forwarded-For` or `Forwarded` headers) is immediately blocked with **HTTP 403 Forbidden** (Fail-Closed). This prevents accidental exposure of a local shell to the internet.
+3. **Content Security Policy & Security Headers**:
+   - File previews (`/preview`) enforce a strict Content Security Policy (`default-src 'none'; connect-src 'none'; form-action 'none'; frame-ancestors 'none'`) preventing previewed Markdown files from executing network requests against the local API.
+   - Global HTTP responses include `X-Content-Type-Options: nosniff` and `X-Frame-Options: DENY`.
+4. **Token Security Notice**:
+   - While `?token=...` query parameters are supported for browser dashboards and Claude.ai custom connectors, automated tools and production integrations should prefer `Authorization: Bearer <token>` headers to avoid token retention in intermediate proxy logs or browser history.
+
+---
+
+## 7. Dangerous Command Blacklist
+
+WinHelm inspects command lines executed via `terminal_run` or `terminal_task_start` against regex patterns targeting destructive or risky actions:
+
+| Category | Blocked Patterns |
+| :--- | :--- |
+| **Disk & Partition Formatting** | `format\s+`, `format-volume`, `diskpart`, `clear-disk`, `initialize-disk` |
+| **Recursive Root Deletion** | `rmdir\s+/[sS]`, `del\s+/[fF]/[sS]/[qQ]\s+[cC]:\\`, `remove-item\s+.*-recurse\s+.*[cC]:\\` |
+| **Registry & Boot Tampering** | `reg\s+delete\s+hklm`, `bcdedit`, `bootrec` |
+| **Account & Privilege Escalation** | `net\s+user\s+.*\/add`, `takeown\s+/[fF]`, `icacls\s+.*\/grant` |
+| **Credential Dumping** | `mimikatz`, `procdump\s+.*lsass`, `comsvcs\.dll` |
+
+---
+
+## 8. Secret Redaction & Log Sanitization
+
+Before log entries are displayed on the Web Monitor Dashboard or written to disk, all text is piped through [sanitizer.ts](../src/utils/sanitizer.ts):
+
+- **Bearer Tokens**: `Bearer ************`
+- **OpenAI & Claude API Keys**: `sk-ant-************`, `sk-************`
+- **GitHub Tokens**: `ghp_************`, `gho_************`
+- **AWS Access Keys**: `AKIA************`
+- **JSON Fields & Credentials**: `"authToken": "************"`, `"password": "************"`, `"x-api-key": "************"`
+- **Password Objects**: `{ "password": "************" }`
+
+---
+
+## 9. Audit Logging & Export
+
+All executed commands, exit codes, durations, and tool errors are sequentially logged to daily audit logs in `logs/winhelm-YYYY-MM-DD.log`.
+
+You can export audit logs at any time via the Web Monitor Dashboard buttons ("📥 Export JSON" / "📥 Export CSV") or programmatically via the HTTP endpoint:
+```
+GET /api/monitor/export?format=json
+GET /api/monitor/export?format=csv
+```
+
+Logs older than 7 days are automatically pruned to prevent disk consumption.