Medusa Documentation
Complete guide to deploying, configuring, and operating the Medusa in-browser AI-DLP extension and its dashboard control plane.
How It Works
Medusa is an endpoint DLP (Data Loss Prevention) browser extension for AI sites. It runs a small classification model directly in the browser and scans what people type or paste into AI providers (ChatGPT, Claude, Gemini, Copilot, Perplexity, Grok) in real-time, before anything is sent.
You type or paste
(ChatGPT, Claude, Gemini)
Medusa Extension
(scans in-browser)
Warn / block per policy
(optional approval)
Medusa Platform
The extension runs a lightweight ONNX token-classification model (Medusa Model) directly in the browser. It scans the text you type or paste into AI sites for sensitive data across 7 categories — all inference is local, so nothing leaves the device for scanning.
Self-Host Walkthrough
The whole stack — Supabase (Postgres, Auth, Edge Functions behind Kong) andthe dashboard — comes up on one box with a single command. Nothing phones home; detection runs in each browser. Here's the path from first command to first catch.
One command brings it up
Point it at your hostnames and run it. It stages Supabase, applies migrations + the 5 edge functions, generates every secret, waits until healthy, builds your per-org extension, and smoke-tests itself.
$ DASHBOARD_URL=https://dlp.your-firm.com \ SUPABASE_PUBLIC_URL=https://supabase.your-firm.com \ node scripts/selfhost-up.mjs [1/5] Preparing the stack (Supabase + migrations + edge fns + secrets) [2/5] Starting services (docker compose up -d) [3/5] Waiting for the stack to be healthy … ✓ [4/5] Building the per-org browser extension [5/5] Smoke-testing the deployment … ✓ all checks passed
Create the admin account
Open the dashboard and sign up. On a fresh self-host the first account is auto-confirmed — no email round-trip needed to get started.
Create your account
Free for your first 3 browsers. No card required.
Land in the dashboard
You're in. The control plane is where policy, findings, approvals, and fleet coverage live — endpoints are managed here, not on each device.
Endpoints
1 protected
Catches (7d)
0
Policy
Warn-all
Welcome to Medusa — in-browser AI data loss prevention
Scans what people type or paste into AI sites, on-device, before anything is sent.
Generate your organization key
On Install, generate the org key. It's what browsers enroll with — pushed silently via MDM, or pasted once per browser. Your endpoint cap is enforced against it server-side.
Org-wide rollout
Extension ID
Organization key
Set your policy
Decide what's flagged and how it's enforced — per category, for the whole fleet or a single browser. For a firm: block client identifiers, warn on the rest.
The first catch
Load the extension (or push it via MDM), enroll with the org key, then paste a client SSN into ChatGPT. Medusa blocks it in the browser — before it's ever sent — and the event lands under Findings.
Medusa
Blocked — cannot be sent
Your message contains data classified as sensitive:
PII123-45-6789Screens above are faithful UI recreations. For the exact command set and MDM rollout, see the Deployment Guide.
Using the Dashboard
The dashboard is the control plane — endpoints are managed here, not on each device. Here's how to navigate it, set a policy, and act on what the extension catches.
Know the map
Eight sections down the left rail. You'll live in Policy, Findings, and Approvals; Browsers is your coverage + audit story.
Set the default policy
Policy → set an action per category. Off ignores it, Warn lets the user send anyway, Block stops it (they can request approval), Hard block removes even that. This baseline applies to every enrolled browser.
Tune a single browser (optional)
Most stay on the default. When one needs its own rules — a stricter partner laptop, a looser test box — open Browsers → Edit policy. A custom endpoint shows a badge; “Reset to default” drops it back.
Review what got caught
Findings is the record of every flagged send — category, site, and what the user did (blocked, sent anyway, approved). Only category + context is logged by default; the sensitive text never leaves the device.
Approve an exception
When a user requests approval on a blocked send, it lands here with the evidence — including the actual file for uploads. Grant a time-boxed, content-scoped allowance so only that exact item can go through.
“Client approved sharing for the summary.”
Confirm coverage
Browsers doubles as your audit story: a heartbeat-driven status per endpoint — Protected now, Idle, or Silent >24h — plus an “outdated” flag on any browser behind the fleet's version. Proof of who's actually protected.
Getting Started
Roll out the Medusa extension to any Chromium- or Firefox-based browser in under a minute.
📘 Full Deployment Guide →
Granular, step-by-step instructions for org-wide MDM rollout (Google Admin / Intune / Jamf / Edge) and self-hosting on your own infrastructure.
1. Generate an Org Key
Go to Settings in the dashboard and create a new org enrollment key.
2. Install the Extension
Install Medusa from your browser's web store (or load the packaged extension for managed deployments). Once installed, Medusa adds a small icon to the toolbar and is ready to enroll.
3. Enroll the Browser
Enroll the browser one of two ways: click Enrollon the Deploy page in the dashboard, or open the extension's options and paste your org key:
Org key: org_YOUR_KEY_HERE
As soon as the browser is enrolled, the extension fetches your org policy and starts scanning AI sites in-browser. Check the Browsers page to confirm it appears online.
Extension Settings
Most settings are pushed from your org policy, but a few local options are stored in the extension's own settings and surfaced in its options page.
Key Fields
| Field | Description | Default |
|---|---|---|
| org_key | Enrollment key for the dashboard | (required) |
| supabase_url | Dashboard backend URL | (set during enrollment) |
| telemetry_interval_seconds | Finding upload frequency | 60 |
| policy_sync_interval_seconds | Policy fetch frequency | 300 |
| dlp_confidence_threshold | Min confidence for DLP detections | 0.5 |
| dlp_model_enabled | Enable in-browser DLP scanning | true |
| auto_update_enabled | Auto-update the extension | true |
Supported AI Sites
The extension activates automatically on the major AI provider sites:
- ChatGPT —
chatgpt.com - Claude —
claude.ai - Gemini —
gemini.google.com - Copilot, Perplexity, and Grok
On each supported site, the extension watches the prompt input and scans text in-browser before a submission is sent — no changes to the site and no proxying required.
DLP Detection
The DLP engine uses a fine-tuned ONNX token-classification model (Medusa Model) that runs entirely in the browser. No data is sent to external APIs for scanning.
Detection Categories
Secrets
API keys, tokens, passwords, connection strings
PII
Names, emails, phone numbers, SSNs, addresses
Financial
Credit cards, bank accounts, transactions
Health / PHI
Medical records, diagnoses, prescriptions
Injection
Prompt injection, jailbreak attempts
Source Code
Code snippets, function definitions
Insurance
Policy details, claims, underwriting
How Scanning Works
As you type or paste into an AI site, the extension captures the pending submission and runs it through the DLP scanner in-browser. The Medusa Model classifies each token with BIO labels (B-SECRET, I-SECRET, B-PII, I-PII, etc.) and merges contiguous tokens into detected spans with confidence scores — all before the text is sent.
Custom regex patterns can be added via the Policy Manager for organization-specific formats (internal IDs, proprietary tokens).
Policy Engine
Policies are configured in the dashboard and synced to enrolled browsers every 5 minutes. They control, per category, whether a flagged submission is warned, blocked, blocked-with-justification, or hard-blocked.
Policy Scopes
- Global — applies to all enrolled browsers
- Endpoint — applies to a specific enrolled browser
- Group — applies to browsers with a specific tag
Policy Controls
| Control | Description |
|---|---|
| Site Blocklist | Block submissions on specific AI sites |
| Site Allowlist | Only scan listed AI sites (allowlist mode) |
| Category Actions | Set warn / block / justify / hard-block per category |
| Pattern Rules | Flag custom formats with regex patterns |
| DLP Toggles | Enable/disable detection per category |
| Warn vs Block | Show a warning or stop the submission |
| Justification Mode | Require a logged reason to proceed |
| Approvals | Let admins approve blocked submissions |
| Injection Protection | Detect and block prompt-injection attempts |
Policy Actions
WARN
Warn, then proceed
BLOCK
Stop the submission
JUSTIFY
Block unless justified
HARD-BLOCK
Stop, no override
Dashboard
The dashboard provides real-time visibility into every flagged submission across all of your enrolled browsers.
Dashboard
KPI cards, activity chart, recent findings, DLP engine status
Policies
Configure DLP categories, per-category actions, site rules, custom patterns
Findings
Browse detections by category, AI site, and action
Browsers
Enrolled browser endpoints, per-endpoint policy, activity
Settings
Org keys, cloud integration, alerting channels, auto-update config
Profile
Account info, security credentials, endpoint access, danger zone actions
API Reference
The extension communicates with the dashboard via Supabase Edge Functions. All endpoints require a Bearer token (org key).
/functions/v1/gateway-eventsUpload findings from the extension. Returns update directives (target_version, auto_update_enabled).
/functions/v1/gateway-policyFetch the resolved policy for this browser. Supports ETag caching (If-None-Match → 304). Returns HMAC-signed policy.
/functions/v1/extension-registerEnroll a new browser as an endpoint. Resolves the org from the org key and mints a per-endpoint key.
/functions/v1/dlp-approval-requestRequest admin approval for a hard-blocked submission. Only sha256(content) is sent — never the text.
/functions/v1/dlp-approval-statusPoll the approval status for a content hash. Returns pending / approved (with expiry) / denied.
Authentication
Authorization: Bearer org_YOUR_ORG_KEY
Org keys are generated in the Settings page. Keys are hashed with SHA-256 — the full key is only shown once at creation time.
Security
Medusa is built security-first. The extension runs with minimal permissions and all sensitive data is protected.
Local-Only Inference
All scanning runs in-browser. Scanned text never leaves the device, and org keys are never stored in plaintext logs.
Model Integrity
The Medusa Model is verified via SHA-256 checksum against the manifest on every load. Tampered models are rejected.
Inference Safety
A 10-second timeout on model inference prevents adversarial inputs from hanging the extension. Submissions over 10MB are skipped.
Policy Signing
Policies are signed with Ed25519 by the edge function; the extension verifies the signature with an embedded public key before applying, and rejects a tampered policy (keeping the last-known-good). The private key never ships in client code.
Minimal Permissions
The extension only requests host access for supported AI sites and stores settings in the browser's own extension storage.
ReDoS Protection
Custom regex patterns are tested with a 1-second timeout before activation. Vulnerable patterns are rejected.
Endpoint Identity Validation
The gateway-events edge function verifies that the agent_id belongs to the authenticated customer before accepting findings.