scamgate

scamgate

A self-hosted scam check for AI agents: verify links and payments before the agent acts.

Website and docs: https://odaiameera.github.io/scamgate/

AI agents now click links and make payments for people, and scammers follow the money. Text planted in pages, listings or messages can steer an agent to a fake shop, a credential prompt or a "pay by bank transfer" request. Agent payment rails secure *the payment* (tokens, limits, authentication). They don't judge whether the payee or the site is a scam. scamgate does that check, runs locally as an MCP server, and makes no network calls while checking.

How it decides

• Deterministic rules, no LLM judging. The same input always gets the same verdict.
• Each rule that fires adds points and a plain-English reason. The total (capped at 100) decides:
• allow: under 25
• ask (stop and check with the human): 25 to 69
• deny: 70 or more
• The agent gets the decision, the score, every reason, and any warnings (for example a stale feed cache).

Link rules: known-bad-link feeds, your own blocklist, brand look-alikes (typosquats, homoglyphs, brand names on unofficial domains, real domains used as a prefix like paypal.com.secure-login.xyz), addresses hidden before an @ (paypal.com@evil.example), raw IP hosts, punycode, cheap abused TLDs, and pages asking for a seed phrase or a login the task doesn't need. A link it can't read (an invalid site name, a javascript: or data: link, an oversized address) asks: it never gets an allow.

Payment rules: new payee plus urgency, changed bank details, irreversible methods (crypto, gift cards, transfer to a new payee), sellers insisting on a method, over budget, pressure or secrecy phrases, and Verification of Payee results.

Quickstart

Requires Python 3.11+.

# with uv

git clone https://github.com/odaiameera/scamgate.git cd scamgate uv sync uv run scamgate update-feeds # download the known-bad-link feeds into ~/.cache/scamgate

or from PyPI, pinned to a release

uv tool install scamgate==0.3.3 # or: pip install scamgate==0.3.3 scamgate update-feeds

Using Claude Code? Install the Claude Code plugin instead: it brings the hook, the MCP tools and the feed refresh in one step.

Check a link (real output):

$ uv run scamgate check-url "https://paypa1.com/login" --intent "buy a ticket"

{ "decision": "deny", "risk_score": 100, "reasons": [ { "rule_id": "url.lookalike_brand", "explanation": "'paypa1.com' disguises 'paypal' with look-alike characters ('paypa1'). The real site is paypal.com.", "weight": 60 }, { "rule_id": "url.intent_mismatch", "explanation": "The task is 'buy a ticket', but the link goes to a 'login' page. A credential prompt the task doesn't need is a classic phishing step.", "weight": 45 } ], "summary": "Do not proceed with this link. Main concern: 'paypa1.com' disguises 'paypal' with look-alike characters ('paypa1'). The real site is paypal.com.", "checked_host": "paypa1.com", "warnings": [], "advisory": "scamgate is advisory. It can miss scams and flag legitimate actions; a human should make the final call on anything flagged." }

(warnings is empty once feeds are cached. Before update-feeds it says no feed is cached.)

A link listed in a feed comes back with the feed named in the reason:

{

"rule_id": "url.known_bad_feed", "explanation": "This exact link is listed as phishing/malware by OpenPhish community feed.", "weight": 100 }

Other commands: scamgate feeds-status, scamgate bench, scamgate serve (MCP over stdio), plus hook, review, promote and record-payment (see Enforce it with a hook).

Add it to your agent

Claude Code plugin

The easiest way for Claude Code. One install adds the enforcing hook, the check_url, check_payment and update_feeds tools, and a refresh of the phishing lists every 6 hours. It runs scamgate from PyPI with uvx scamgate==0.3.3, so it needs uv, and Claude Code v2.1.295 or later so that a hook that can't start blocks instead of letting calls through.

/plugin install scamgate --marketplace odaiameera/scamgate

On Claude Code before 2.1.275, run /plugin marketplace add odaiameera/scamgate, then /plugin install scamgate@scamgate. What the plugin runs, downloads and stores: claude-plugin/README.md.

MCP server only

Replace /path/to/scamgate with your checkout, or run the PyPI release with uvx scamgate==0.3.3 serve.

Claude Desktop (claude_desktop_config.json):

{

"mcpServers": { "scamgate": { "command": "uv", "args": ["--directory", "/path/to/scamgate", "run", "scamgate", "serve"] } } }

Claude Code:

claude mcp add scamgate -- uv --directory /path/to/scamgate run scamgate serve

Hermes (~/.hermes/config.yaml):

mcp_servers:

scamgate: command: "uv" args: ["--directory", "/path/to/scamgate", "run", "scamgate", "serve"]

Then tell the agent: *"Call check_url before opening any link and check_payment before any payment. On ask, stop and show me the reasons. On deny, don't proceed."*

MCP tools

check_url(url: str, intent: str | None = None) -> Verdict

update_feeds() -> {updated, failed, not_configured, skipped, summary}

check_payment(payee_name: str, payee_account: str, amount: float, currency: str, method: "card" | "bank_transfer" | "crypto" | "gift_card" | "other", context_text: str | None = None, is_new_payee: bool | None = None, bank_details_changed: bool | None = None, budget: float | None = None, vop_result: "match" | "close_match" | "no_match" | "unavailable" | None = None) -> Verdict

Verdict = decision, risk_score, reasons[] (rule_id, explanation, weight), summary, checked_host (for links: the host a browser would open), warnings[], advisory. Both check tools are marked read-only and publish this as their output schema, so MCP clients get it as structured content. update_feeds takes no arguments: it downloads the default lists from their fixed sources, at most once an hour, so an agent can ask for a refresh but can't choose what lands in the cache.

Enforce it with a hook

The MCP tools only work when the agent chooses to call them, and a prompt injection can tell it not to. The hook moves the check into the harness: the agent can't skip it.

scamgate-hook (or scamgate hook) reads one hook event as JSON on stdin and writes a decision. It speaks Hermes shell hooks and Claude Code PreToolUse hooks.

• Links: every URL in a web, browser, media, terminal, code or unknown MCP tool call is checked, including disguised forms (evilsh%6fp.com, http://3405803781). deny blocks the call, ask sends it to you for approval. One bad link in a batch blocks the whole batch.
• Payments: money-moving tool calls (wallet, banking or payments MCP tools, or any tool whose arguments carry an amount and an IBAN, wallet or account) get the same check as check_payment, with your payee history, whatever the agent claims. deny blocks, ask sends it to you. A payment whose payee or amount can't be read, crypto CLIs (cast send, bitcoin-cli sendtoaddress, solana transfer…) and write calls to payment APIs (Stripe, PayPal, Wise, Revolut Business…) go to you. Each approval covers one account and amount.
• Hidden code: code that's decoded or downloaded and then run (… | base64 -d | bash, exec(b64decode(…)), curl … | sh, powershell -enc) goes to you, network keyword or not.
• Hidden destinations: a network step scamgate can't read goes to you, judged per command (curl https://example.org; curl "$URL" still asks): variables, $(…), string-built, base64/hex-decoded or reversed links, requests.get(open(…).read()), installs of named packages, git clone, new git remotes. In code, only a literal URL counts as readable.
• Routine dev work stays quiet: installs from a lockfile, manifest or local path (pip install -r requirements.txt, uv sync, npm ci), git push/pull/fetch to remotes you already have, and commands that only read text (grep requests.get src/). Any URL in them is still checked.
• Running blind: with no feeds cached, links go to you for approval (SCAMGATE_NO_FEEDS=warn turns that into a warning). Stale feeds are mentioned in every ask and block.
• Tampering: blocks agent writes (including editors like vim/ed/nano and find -exec, rsync, patch) to scamgate's own code, state and feed cache and to the hook config, plus commands or code that revoke the hook, remove the server, promote rules, record payees or call scamgate's state APIs directly.
• The agent's stated reason can only add risk. It's scored with and without the reason, and the higher score wins.
• Approvals stay narrow. Hermes remembers "always" per rule_key; scamgate's keys include the host and the rules that fired (or a hash of the hidden command), so one "always" can't pre-approve other destinations. Still, pick "once" for asks you don't expect to repeat.
• Fails closed: bad input, input over 2 MB, deep nesting or an internal error blocks the call (exit 2).
• Stays fast on long commands. The hook reads a command's words in one linear pass (no shlex), so a padded command can't tie it up: a 2,000,000-character quoted command takes about 5 s on one Windows machine, down from over 200 s. Decisions are unchanged.
• Never says "allow". Silence means "no objection", so it can only tighten your agent's permissions, never loosen them.

Pipeline

hook.handle() is the only enforcement function. The shell hook and the Hermes plugin both call it. MCP does not.

1. Integrity check on a wheel install. A mismatch blocks every gated call. Editable and unpackaged installs pass as dev.
2. scamgate's own check_url / check_payment tools return silence, so asking the gate is not itself blocked.
3. Tamper: writes to the package, state, feed cache, hook config, and other Hermes profiles, plus commands that uninstall the gate or call promote / record-payment.
4. Extra checks: reading the signing key; Hermes safety switches (approvals.mode off, --yolo, plugins uninstall, --safe-mode, --dangerously-skip-permissions); writes to files other tools run; cron scripts under $HERMES_HOME/scripts; script files named by bash / `py