Deployment guide

Deploying PhishGuard

Two clients, one backend. The Chrome extension covers Gmail and Outlook on the web and scans automatically; the Outlook add-in covers the desktop and mobile Outlook apps. Both read only the open message, mask personal details in the client, and send the remainder to hodan.ai over HTTPS.

Outlook add-in — Microsoft 365 tenant

1admin.microsoft.com → Settings → Integrated apps → Upload custom apps
2App type: Office Add-in → Provide link to manifest file → paste the URL above
3Validate → assign to Entire organization (or a pilot group) → Next
4Review the single permission — Read item — and Finish deployment
5Propagation takes up to 24 hours, usually much less. Users open a message → ⋯ → PhishGuard. The pane's bottom line should read "build 1.25.0 · ready".

The same manifest works in the Exchange admin center (Settings → Add-ins → Add from URL). Users should pin the pane (📌) — Office add-ins cannot scan a message until the pane is open, and an unpinned pane closes on every message change. Removal: Integrated apps → PhishGuard → Remove; nothing is left on any machine.

Chrome extension — Google Workspace / managed Chrome

Once the Chrome Web Store listing is live (Unlisted — link-only, auto-updating), force-install it from Admin console → Devices → Chrome → Apps & extensions by extension ID, then set the managed policy below so every install is pre-configured with your organization key. Nothing for employees to type.

For a small pilot without managed Chrome, employees can install from theinstall pageand paste the organization key under the popup's Advanced section.

Vendor registry — the payment-change cross-check

"Our banking details have changed" is caught by wording. Whether the account is actually new is something only your own records can say. Finance enters each supplier once: the domain they email from, the account number on file (hashed on entry, never stored), and a verification phone number from your records. From then on:

A registered vendor asking for payment to an account that is not on file → CRITICAL, with the phone number to call.
A registered vendor's name and invoice from any other domain, including a personal mailbox → CRITICAL.
A sender domain one character away from a registered vendor → HIGH, even with no payment wording.
A payment change whose account matches the registry → noted, not alarmed.

Manage the list at /phishguard/vendors with your organization's admin key (issued with your API key; it manages only your organization). Both clients extract account numbers from the message locally and send only a hash; the number itself never leaves the mailbox.

PhishGuard for Claude Code — run it inside Claude

An AI assistant is a delivery channel: it returns a link, you paste the install command, and if the domain is a lookalike registered last week the payload runs on contact. The PhishGuard plugin sits on every surface of a Claude Code session — commands it runs, pages it fetches, files it writes into its own context, links in its replies, and every email you paste or it reads — and checks before anything takes effect. Emails are scanned in quiet mode: nothing when clean, a verdict when something is off.

1
Requirements
Claude Code (the desktop app's Code tab, or the claude CLI) with Node 18+. On Windows, Git Bash must be installed — the standard Claude Code setup.
2
Install (two commands, in a terminal or inside Claude with a leading slash)
3
Start a new Claude Code session
Hooks load at session start. You'll see nothing yet — that's the point.
4
Pin your context files once
Review your own CLAUDE.md and skills, then type /phishguard and choose pin. From then on any change to those files is reported at session start; if you make the change, re-pin.
5
Verify it's working
Type /phishguard and choose audit — you'll get a severity-ranked report of your setup. Or ask Claude to run a lookalike install command; the gate blocks it and explains why.
6
Day to day
Blocked command → Claude shows the reason and the one-line approve command for a domain you've verified. Suspicious email pasted → a panel with the verdict, what to do, and why, before Claude answers. Clean email → silence.
7
Update / remove

The plugin is published at github.com/hodanmillion/phishguard-plugin with a SHA-256 for every release. Everything runs locally from one file; only email-shaped text and links leave the machine, PII-masked, to the PhishGuard API. If Node is missing, every hook fails open — the plugin can never break Claude Code. Plugin decisions are logged to ~/.phishguard/gate.log.

How AI is used — off by default

The rules engine always runs and needs no key: sender and domain checks, SPF/DMARC, domain age, link analysis, payment-instruction changes, Reply-To divergence, look-alike domains, and per-user sender history. AI is a tie-breaker for genuinely ambiguous email only, and never runs unless enabled.

Off — rules onlyDefault

No email content reaches any AI provider. Nothing to configure or pay for.

User's own Anthropic keyUser pays

Held in browser session memory only; sent per request, never stored on our servers.

Organization keyOrg pays

A pg_live_… key from us. Attributes scans to your organization, enables your trusted-sender allowlist, and uses your AI budget.

What your security team will ask

What does it access?: The message currently open — sender, subject, body, links. Permission: Read item (add-in) / the mail page only (extension). No mailbox-wide access, no send, no calendar, no contacts.
What leaves the device?: The sender's domain (never the address), the subject and first part of the body with personal details masked, the links with tracking stripped, and a random install id. On the add-in, the Reply-To domain. From the extension, one yes/no flag when a familiar sender name arrives from a new domain — computed from a hashed ledger that never leaves the browser.
What is stored?: Not the email. A 24-hour verdict cache keyed by a one-way hash; a scan record (timestamp, sender domain, score, organization) only for organization-key scans; feedback only when a user presses the button. Retention job runs weekly.
Sub-processors: Vercel (hosting, US), Supabase (database, US), Upstash (verdict cache, US), Cloudflare (DNS lookups — domain names only), Anthropic (only if AI is enabled). Data crosses the border; the privacy page states this.
Can users be tracked?: No. Verdicts are not attributed to individuals. Organization admins see counts, verdicts and flagged sender domains — not who received what.
How do we remove it?: Add-in: Integrated apps → Remove. Extension: unpublish from the admin console or uninstall. Nothing persists on endpoints.

Every claim above is enforced by an automated test that fails the build if behaviour drifts. Full text: privacy policy.

Known limits, stated plainly

The Outlook add-in cannot scan a message until its pane is open — pinning makes it rescan as users move through mail; the Chrome extension scans automatically.
Recall on a hard test set is roughly 88%: about one in eight phishing emails will not be flagged. It is a second opinion, not a filter. A green "verified" label appears only on affirmative evidence: a sender this mailbox has corresponded with before, a clean domain with published authentication, and no signals. A first contact, however polite, never earns it.
Reply-To divergence is only detectable where headers are readable — the add-in, not the browser extension.

Install page · Privacy