Add security hardening and testing documentation

Implement multiple security improvements and expand testing documentation.

Author: motionbug

.gitignore

@@ -26,3 +26,6 @@ Thumbs.db
 # Logs
 *.log
 npm-debug.log*
+
+# Claude
+CLAUDE.md

README.md

@@ -252,6 +252,34 @@ Authorization: Bearer <your-secret>
 
 The Worker validates this header on `/webhook` requests if the `WEBHOOK_SECRET` environment variable is set. If it's not set, the webhook accepts all valid payloads (the default behavior).
 
+### Optional: Rate Limiting the Webhook Endpoint
+
+The `/webhook` endpoint is open to the internet so devices can POST enrollment events. To prevent abuse (flooding with fake events, exhausting KV storage), you can add a Cloudflare WAF rate limiting rule. This is configured entirely in the Cloudflare dashboard — no code changes required.
+
+#### Setup
+
+1. In the [Cloudflare dashboard](https://dash.cloudflare.com), select your account and domain (or Workers route)
+2. Go to **Security → WAF → Rate limiting rules**
+3. Click **Create rule** and configure:
+   - **Rule name:** `Rate limit webhook`
+   - **If incoming requests match:** Field `URI Path` — Operator `equals` — Value `/webhook`
+   - **Rate:** `30 requests` per `1 minute` (adjust based on your fleet size)
+   - **With the same:** `IP Address`
+   - **Then:** `Block` for `1 minute`
+4. Deploy the rule
+
+#### Choosing the Right Rate
+
+The rate depends on how many devices enroll simultaneously from the same IP. Each device sends exactly two webhook requests per enrollment (one `started`, one `finished`), so:
+
+| Fleet scenario | Concurrent enrollments from one IP | Suggested rate |
+|---|---|---|
+| Small office (1–10 devices) | 1–10 | 30 req/min |
+| Medium site (10–50 devices) | 10–50 | 120 req/min |
+| Large deployment (50+ from one NAT IP) | 50+ | 300 req/min |
+
+If your devices enroll behind a shared NAT or VPN gateway, choose a higher limit to avoid blocking legitimate traffic. You can always start with a permissive limit and tighten it after observing real traffic patterns in **Security → Analytics**.
+
 ### Access Configuration Summary
 
 | Route | Authentication | Who |
@@ -277,6 +305,43 @@ For local Worker development, create a `.dev.vars` file (see `.dev.vars.example`
 
 > **Note:** Cloudflare Access is not active during local development. The dashboard is unprotected when running locally - this is expected and convenient for development.
 
+## Testing the Dashboard
+
+After deploying, you can populate the dashboard with dummy data to verify everything is working.
+
+### Send Dummy Events
+
+The included test script generates 140 realistic webhook events (70 started + 70 finished) across 10 simulated devices, spread over the past 3 days. This gives the dashboard enough data to display KPIs, charts, and event details.
+
+```bash
+# Replace with your actual Worker URL
+WORKER_URL=https://setup-manager-hud.<your-subdomain>.workers.dev \
+  node scripts/send-dummy-events.js
+```
+
+If you have a `WEBHOOK_SECRET` configured on your Worker, pass it along:
+
+```bash
+WORKER_URL=https://setup-manager-hud.<your-subdomain>.workers.dev \
+  WEBHOOK_SECRET=your-secret-here \
+  node scripts/send-dummy-events.js
+```
+
+Once the script finishes, open the dashboard in your browser. You should see events appearing with device details, enrollment actions, and charts populated with data.
+
+### Cleaning Up Test Data from KV
+
+After testing, you'll likely want to remove the dummy events. Cloudflare KV entries have a 90-day TTL so they will expire on their own, but you can remove them immediately through the Cloudflare dashboard:
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com)
+2. Go to **Workers & Pages → KV** in the left sidebar
+3. Click on your **WEBHOOKS** namespace
+4. You'll see a list of stored keys — dummy events use serial numbers starting with `DUMMY` (e.g. `com.jamf.setupmanager.started:DUMMY000001:...`)
+5. To delete individual entries: click the **three-dot menu** next to an entry and select **Delete**
+6. To bulk delete all test data: select entries using the checkboxes, then click **Delete selected**
+
+> **Tip:** You can use the search/filter field at the top of the KV viewer to filter keys containing `DUMMY` to quickly find and select all test entries.
+
 ## Architecture
 
 ```

public/jamf-icon-dark.svg

@@ -1,5 +1,34 @@
-const WORKER_URL = process.env.WORKER_URL || 'https://setup-manager-hud.motionbug-site.workers.dev';
+/**
+ * send-dummy-events.js
+ *
+ * Generates dummy Setup Manager webhook events and POSTs them to your
+ * Setup Manager HUD instance. Useful for verifying the dashboard works
+ * after a fresh deploy or for demo purposes.
+ *
+ * Usage:
+ *   WORKER_URL=https://your-worker.your-subdomain.workers.dev node scripts/send-dummy-events.js
+ *
+ * If WEBHOOK_SECRET is set on your Worker, pass it as an env variable:
+ *   WORKER_URL=https://your-worker.your-subdomain.workers.dev \
+ *   WEBHOOK_SECRET=your-secret-here \
+ *   node scripts/send-dummy-events.js
+ *
+ * What it does:
+ *   - Creates 10 dummy devices with random Mac models and macOS versions
+ *   - Sends 70 started events and 70 matching finished events (7 per device)
+ *   - Events are spread over the last 3 days so charts have data to display
+ *   - ~5% of enrollment actions are randomly marked as "failed"
+ */
+
+const WORKER_URL = process.env.WORKER_URL;
+if (!WORKER_URL) {
+  console.error('Error: WORKER_URL environment variable is required.\n');
+  console.error('Usage:');
+  console.error('  WORKER_URL=https://your-worker.your-subdomain.workers.dev node scripts/send-dummy-events.js\n');
+  process.exit(1);
+}
 const WEBHOOK_URL = `${WORKER_URL}/webhook`;
+const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET || '';
 
 const MODELS = [
   { name: 'MacBook Air', identifier: 'Mac14,2' },
@@ -85,9 +114,14 @@ function buildFinishedPayload(device, startedTime, durationSeconds) {
 }
 
 async function sendPayload(payload) {
+  const headers = { 'Content-Type': 'application/json' };
+  if (WEBHOOK_SECRET) {
+    headers['Authorization'] = `Bearer ${WEBHOOK_SECRET}`;
+  }
+
   const response = await fetch(WEBHOOK_URL, {
     method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
+    headers,
     body: JSON.stringify(payload)
   });
 

public/jamf-icon-white.svg

@@ -72,8 +72,19 @@ export class DashboardRoom implements DurableObject {
     return new Response("Not Found", { status: 404 });
   }
 
+  /** Maximum accepted WebSocket message size (bytes) */
+  private static readonly MAX_WS_MESSAGE_SIZE = 4096;
+
   async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
     try {
+      const messageLength =
+        typeof message === "string" ? message.length : message.byteLength;
+
+      if (messageLength > DashboardRoom.MAX_WS_MESSAGE_SIZE) {
+        ws.send(JSON.stringify({ type: "error", message: "Message too large" }));
+        return;
+      }
+
       if (typeof message === "string") {
         const data = JSON.parse(message);
 
@@ -82,7 +93,11 @@ export class DashboardRoom implements DurableObject {
         }
 
         if (data.type === "request-history") {
-          const limit = typeof data.limit === "number" ? data.limit : 200;
+          const MAX_HISTORY = 200;
+          const limit =
+            typeof data.limit === "number"
+              ? Math.min(Math.max(data.limit, 1), MAX_HISTORY)
+              : MAX_HISTORY;
           await this.sendHistory(ws, limit);
         }
       }

scripts/send-dummy-events.js

@@ -216,12 +216,12 @@ function PoweredByJamf() {
       <span className="inline-flex items-center gap-2">
         Powered by Jamf
         <img
-          src="https://setup-manager-hud.motionbug-site.workers.dev/jamf-icon-white.svg"
+          src="/jamf-icon-white.svg"
           alt="Jamf"
           className="hidden h-[1.05em] w-auto dark:block"
         />
         <img
-          src="https://setup-manager-hud.motionbug-site.workers.dev/jamf-icon-dark.svg"
+          src="/jamf-icon-dark.svg"
           alt="Jamf"
           className="block h-[1.05em] w-auto dark:hidden"
         />

src/DashboardRoom.ts

@@ -65,6 +65,23 @@ export function Filters({ filters, onFiltersChange, events }: FiltersProps) {
     URL.revokeObjectURL(url);
   };
 
+  /**
+   * Sanitize a string for safe CSV output.
+   * Prefixes cells that start with formula-triggering characters with a
+   * single quote so spreadsheet apps (Excel, Sheets) treat them as text
+   * rather than executable formulas.
+   */
+  const sanitizeCsvValue = (str: string): string => {
+    const FORMULA_CHARS = ["=", "+", "-", "@", "\t", "\r", "\n"];
+    if (FORMULA_CHARS.some((c) => str.startsWith(c))) {
+      str = "'" + str;
+    }
+    if (str.includes(",") || str.includes('"') || str.includes("\n")) {
+      return `"${str.replace(/"/g, '""')}"`;
+    }
+    return str;
+  };
+
   const toCsv = (rows: WebhookPayload[]) => {
     const headers = [
       "event", "timestamp", "started", "finished", "duration",
@@ -75,10 +92,7 @@ export function Filters({ filters, onFiltersChange, events }: FiltersProps) {
       const values = headers.map((h) => {
         const v = (payload as unknown as Record<string, unknown>)[h];
         if (v === undefined || v === null) return "";
-        const str = String(v);
-        return str.includes(",") || str.includes('"')
-          ? `"${str.replace(/"/g, '""')}"`
-          : str;
+        return sanitizeCsvValue(String(v));
       });
       lines.push(values.join(","));
     });