convez.ai
MCP ServerSegurançaAvançado
ginkida

Sallyport

ginkida/sallyport

Ponte segura entre Claude Code e Chrome com HMAC, allowlist e opt-in por domínio

Ver no GitHub
BomPluginScore · de 0 a 100

Um servidor MCP que conecta Claude Code ao Chrome com segurança em primeiro lugar, implementando HMAC-SHA256, lista de domínios permitidos e controle granular sobre execução de código. Oferece automação segura de navegador com visibilidade operacional completa e auditoria de todas as ações.

Instalação

$npx convez-ai ginkida/sallyport

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
10
Forks
1
Acompanhando
0
Saúde
57%
Último commit
há 1 semana
Versão
v0.27.0
Issues abertas
7
Contribuidores
1

Casos de uso

  • Automação segura de navegador via Claude Code com proteção contra acessos não autorizados
  • Execução controlada de JavaScript em abas específicas com auditoria completa
  • Interação com páginas web (clique, preenchimento, leitura) com validação de segurança em camadas

Veredito

Sallyport é uma solução robusta e bem arquitetada para automação segura de navegador via MCP, com modelo de segurança explícito e auditoria completa. Ideal para quem precisa de automação confiável sem comprometer a segurança do sistema.

README

A tradução para o português deste README ainda está na fila.

Sallyport

CI CodeQL License: MIT Release

A secure browser-automation bridge between Claude Code (or any MCP client) and your Chrome. An alternative to Kimi WebBridge with explicit security boundaries instead of implicit ones.

Claude Code ── MCP/stdio ──▶ daemon ── WS+HMAC ──▶ extension ── CDP ──▶ Chrome
StatusNumber
Daemon tests (pytest)268
Extension tests (vitest)293
Lint / typecheck (ruff, mypy, eslint, prettier, tsc)all green

What's in the box

PathWhat it is
extension/MV3 Chrome extension (TypeScript, esbuild, vitest). Loads as an unpacked extension.
daemon/Python MCP server. Speaks MCP on stdio to Claude Code, hosts a WS server on 127.0.0.1:10086 for the extension.
fixtures/Cross-language canonical-JSON / HMAC vectors shared by both test suites.
.pre-commit-config.yamlFast lint/format checks before commit.
.github/workflows/ci.ymlSame checks plus full tests on push/PR.

Security model

A deeper threat model + known limitations lives in SECURITY.md. The short version: the original Kimi extension trusts any process that can reach 127.0.0.1:10086, which on a shared/compromised machine means everything. Sallyport changes the default in five places:

  1. HMAC-SHA256 on every frame. A 32-byte random secret lives in ~/.config/sallyport/secret (chmod 600) and is generated on first run. Both sides sign every WS frame and verify timestamp drift (≤ 30 s) and nonce freshness (rolling cache of 4096 nonces — replay-protected). A cross-language test pin in pytest + vitest guarantees the canonical-JSON and MAC bytes stay byte-for-byte compatible.
  2. Domain allowlist enforced in the extension. Tools refuse to run on any URL whose host isn't in chrome.storage.local.sallyport_allowlist. Patterns are example.com, *.example.com, or https://x.com/path/*. Bare * is rejected by the validator.
  3. evaluate is opt-in per domain. Even on an allow-listed domain, arbitrary JS is refused unless that entry has allowEvaluate: true. Other tools (click, fill, read_text, …) use structured CDP calls only.
  4. Defense-in-depth on inputs. fill refuses <input type=password> unless allowPassword=true. The daemon refuses to bind to anything that isn't a loopback address. WS frames over 16 MiB are dropped (1009).
  5. Operational visibility. Every tool call (and its outcome — ok or error) is appended to chrome.storage.local.sallyport_audit (last 500 entries), browsable and JSON-exportable from the popup. One-click Pause in the popup stops the WS connection and rejects all tool calls.

Other deliberate choices:

  • No content-script injection, no <all_urls> content scripts. Permissions are only what the debugger API needs (tabs, activeTab, debugger, storage, alarms).
  • Per-tab accessibility refs (@e1, @e2). Snapshotting tab A cannot invalidate refs for tab B, and a ref scoped to A cannot resolve to a node in B.
  • MCP-side tool calls are serialised by a daemon-side lock so Claude can't accidentally race state on the extension.
  • The daemon shuts down cleanly on stdin EOF (Claude Code closing) or SIGINT/SIGTERM: pending calls fail with ExtensionNotConnected, the client gets a 1001 close, no orphan tasks.

What the extension still trusts: anyone with read access to ~/.config/sallyport/secret. The browser debugger is, ultimately, the browser debugger — this bridge limits which domains it operates on and who can drive it.

Setup

1. Build the extension

cd extension
npm install
npm run build

The output lands in extension/dist/. Load it as an unpacked extension:

  1. chrome://extensions
  2. Enable Developer mode
  3. Load unpacked → pick extension/dist

Pin the toolbar icon.

2. Install the daemon

Sallyport needs Python ≥ 3.10 (it uses match statements and X | Y type syntax). Check with python --version first.

pip install --user sallyport

Or from source (for development): cd daemon && pip install --user -e .

This installs the sallyport-daemon command on your PATH. Verify it landed there:

which sallyport-daemon   # should print a path; if not, add your Python
                      # user-scripts dir (e.g. ~/.local/bin) to PATH

The first time something runs it, the daemon will:

  • Generate a 32-byte secret in ~/.config/sallyport/secret (chmod 600).
  • Print the base64 secret to stderr — paste it into the extension popup.
  • Start listening on 127.0.0.1:10086 and speak MCP on stdio.

Then run the built-in setup check, which validates the install and prints the exact block to paste into the popup:

sallyport-daemon doctor

It checks your Python version, the secret file and its permissions, and that the port is free — then prints the pairing secret and the remaining steps. Run it any time a connection won't come up. To just re-print the secret:

sallyport-daemon --show-secret

3. Register with Claude Code

Add an MCP server entry — either edit ~/.claude/mcp.json directly, or:

claude mcp add sallyport sallyport-daemon

Producing:

{
  "mcpServers": {
    "sallyport": {
      "command": "sallyport-daemon",
      "args": []
    }
  }
}

Restart Claude Code. The tools appear as mcp__sallyport__navigate, mcp__sallyport__click, etc.

4. Pair the extension

  1. Open the popup. It will show a one-card Pair onboarding view.
  2. Get the secret. Run sallyport-daemon doctor (or --show-secret) in a terminal and copy the printed block. Note: when Claude Code spawns the daemon for you (step 3), the first-run banner goes to the daemon's stderr, which Claude Code does not display — so doctor/--show-secret is the reliable way to see it.
  3. Paste into the popup textarea — you can paste the whole banner; the popup auto-extracts the base64 secret and shows "✓ secret detected (32 bytes)".
  4. Click Pair. Status flips to connected with a pulsing green indicator and an at-a-glance summary of allowed sites / recent calls.

5. Add the first domain to the allowlist

The allowlist starts empty — every tool rejects every URL by default. In the popup's Allowlist tab, add an entry like example.com or *.github.com. Tick allow evaluate() only if you actually need arbitrary JS on that host.

Tools

NameNotes
list_tabsNo allowlist check — listing is free.
navigateChecks the destination URL against allowlist.
reloadHard reload via bypassCache=true. Allowlist-gated; refs invalidate.
close_tabtabId required — no implicit fallback (closing the wrong tab loses work).
snapshotAccessibility tree with stable @eN refs (per-tab).
read_textWhole-page or by ref. No raw JS.
clickDOM .click(). CSS selector or @eN ref.
mouse_clickReal Input.dispatchMouseEvent at element center. Use when click doesn't trip pointer listeners (canvas, drag-and-drop). button left/middle/right, clickCount 1–3.
fillBlocks password fields without allowPassword=true.
key_typeRaw text input via CDP. Blocks when focus is on a password field without allowPassword=true.
send_keysMod+A, Shift+Tab, etc. Mod = Cmd on macOS, Ctrl elsewhere. Same password-field gate as key_type.
screenshotPNG/JPEG, base64.
evaluatePer-domain opt-in. Returns {type, value}.
fetch_in_pagefetch() with page cookies/auth. Returns {status, contentType, headers, mode, data}. Allowlist-gated.
uploadAttach local files to <input type=file> via DOM.setFileInputFiles. Paths must be absolute, ..-free, and resolve under ~/Downloads/sallyport/ (override via SALLYPORT_DOWNLOAD_DIR) — same sandbox as save_to_file, with symlink escapes blocked by Path.resolve(). Target must really be a file input. Allowlist-gated.
save_to_fileDaemon-local — writes base64 to ~/Downloads/sallyport/<filename> (override via SALLYPORT_DOWNLOAD_DIR). Sandboxed: no path separators or ...

All tools accept tabId to target a specific tab; otherwise they use the active tab in the current window. There is no implicit "last touched tab" memo — explicit IDs win, the active tab is the only fallback.

Compared to Kimi WebBridge

Sallyport implements the everyday Kimi tools (navigate, click, fill, snapshot, screenshot, evaluate, mouse_click, upload, …) and adds a few of its own (fetch_in_page, save_to_file, reload). Three Kimi features are deliberately not here:

Kimi featureWhy Sallyport omits itIf you need the behaviour
network (start/stop/list/detail HTTP capture via Network.enable)Captures auth headers, cookies, and response bodies on every request, with no per-domain gate that makes any sense. Adding it would defeat the whole "explicit boundaries" framing.Use fetch_in_page against the specific URL, or Chrome's own DevTools.
save_as_pdf (Page.printToPDF)Niche — screenshot (full-page PNG/JPEG) already covers "preserve what's on screen" for the agent tasks we've seen.Speak up if you hit a case where selectable PDF text matters; trivial to add.
_session (per-agent Chrome tab groups, coloured)Cosmetic flair that complicates tab handling without solving a real problem at current scale.Use list_tabs to find what you opened.

find_tab is also intentionally absent: Sallyport's list_tabs returns the full set and the agent filters client-side — one round trip instead of two.

Testing it locally

Three layers, from fastest to most realistic:

A. Wire only — no MCP, no Claude Code

Confirms HMAC pairing, allowlist, audit log without any tools firing.

# terminal: run the daemon in WS-only mode. Stays up until Ctrl-C —
# no stdin / no MCP client needed.
sallyport-daemon serve

Default sallyport-daemon (no subcommand) expects an MCP client on stdin and exits immediately on EOF — fine for Claude Code, awkward for local testing. Use serve whenever you want a stable long-running daemon.

Open the popup → Pair → paste secret → status flips to connected. That alone proves: WS reach, HMAC handshake, perms.

B. Fire individual tools from the shell — no Claude Code

sallyport-daemon exec <tool> key=value... spins up the daemon, waits for the extension, calls one tool, prints JSON, exits. Values are JSON when parseable, otherwise strings.

# Catalogue of tools (works offline, no extension needed):
sallyport-daemon list-tools

# Open a tab (the host must already be in the popup's allowlist):
sallyport-daemon exec navigate url=https://example.com newTab=true

# Read the page:
sallyport-daemon exec read_text

# Get the accessibility tree + refs:
sallyport-daemon exec snapshot

# Click something from snapshot (use a ref):
sallyport-daemon exec click selector=@e3

# Targeted screenshot:
sallyport-daemon exec screenshot format=jpeg quality=70

Notes:

  • exec mode is mutually exclusive with the Claude Code MCP session (single-client invariant in the WS server). Stop Claude Code first, or pass a different --port here and update the popup's daemon URL.
  • The first exec waits up to 10s (--wait 30 to bump it) for the popup to connect. Once paired, the extension reconnects on its own.
  • Screenshot blobs are truncated in the printout — they're still passed in full to a real MCP client.

C. End-to-end with Claude Code

Once A and B work, register the MCP server (see Setup → step 3), restart Claude Code, and ask it to do anything web-shaped. Watch the popup's Audit tab — every call lands there with ok/error and target URL.

Troubleshooting

SymptomFix
Anything in setup feels offRun sallyport-daemon doctor — it checks Python version, secret + perms, and port, and reprints the pairing block.
Popup stuck on "Connecting to daemon…"The daemon isn't reachable at the popup's URL. Confirm it's running (sallyport-daemon serve in another shell), that the Advanced → daemon URL matches (default ws://127.0.0.1:10086/ws), and that the port is free (sallyport-daemon doctor). The single-client rule means a live Claude Code session already holds the port — that's expected; the extension connects to it.
Popup says "extension is not connected"Daemon isn't running, or the popup says paused — open and hit Resume/Reconnect.
domain_not_allowedAdd the host to the Allowlist tab.
evaluate_not_allowedEdit the allowlist entry and re-add with allow evaluate() checked.
password_field (from fill)fill refuses <input type=password> by default. Pass allowPassword=true if you really mean it.
wrong_element (from upload)Selector resolved to something other than <input type=file>. Re-snapshot and pick a real file-input ref.
unsafe_path (from upload)Path contains .., isn't absolute, or resolves outside the sandbox (default ~/Downloads/sallyport/). Stage the file via save_to_file first (writes to the sandbox), then upload. Widen the sandbox via SALLYPORT_DOWNLOAD_DIR if you really need to upload from elsewhere.
not_visible (from mouse_click)Element has zero size — likely display:none or detached. Snapshot again; if it's hidden by design, drive the toggle that reveals it.
bad_refAn @eN ref is stale (snapshot expired) or addressed at the wrong tab. Re-snapshot the right tab. Refs are per-tab and per-snapshot.
mac mismatch (in popup)Secret in ~/.config/sallyport/secret no longer matches the one paired in the popup. Run sallyport-daemon --show-secret, copy, Unpair → paste → Pair.
timestamp skewClocks are >30 s apart. Check NTP.
Daemon warns about loose permissions on startupchmod 600 ~/.config/sallyport/secret.
WS frame >16 MiBThe extension is silently dropped with a 1009 close. Lower screenshot quality or take a region screenshot.

Rotating the secret

  1. rm ~/.config/sallyport/secret
  2. Restart whatever runs sallyport-daemon (Claude Code will respawn it on next call). A new secret prints to stderr.
  3. In the popup: Unpair → paste new secret → Pair.

Development

# Extension
cd extension
npm install
npm run watch         # esbuild rebuild on save — reload extension in chrome://extensions to pick up
npm run typecheck     # tsc --noEmit
npm test              # vitest run
npm run lint          # eslint
npm run format        # prettier --write
npm run format:check  # prettier --check (CI gate)

# Daemon
cd daemon
pip install -e '.[dev]'
ruff check .
mypy
pytest -q
sallyport-daemon --verbose < <(sleep 99999)   # smoke-test a long-running daemon

Pre-commit

pip install --user pre-commit
pre-commit install

This runs trailing-whitespace/json/yaml/merge-conflict checks plus ruff, mypy, prettier, eslint, and tsc on each commit. Heavy test suites stay in CI because they're too slow for a commit gate.

CI

.github/workflows/ci.yml matrices over Python 3.10/3.11/3.12 (daemon) and Node 20/22 (extension), runs lint + typecheck + tests + build for both, and uploads extension/dist as an artefact on main.

Adding a new tool

Five files, same order both for an extension-side tool and a daemon-local one — keep tool names byte-identical on both sides since routing is a dict lookup.

  1. Implement. Extension-side: a new extension/src/tools/<name>.ts exporting a Tool. Pure validators (path / arg shape) belong in a chrome-free sibling module like upload-path.ts so vitest can cover them without a chrome harness. Daemon-only: a coroutine in daemon/src/sallyport_daemon/local_tools.py registered in LOCAL_TOOLS.
  2. Register on the extension side. Add an import + entry to the tools map in extension/src/tools.ts.
  3. Declare the MCP schema. Append a Tool(name=..., description=..., inputSchema=...) to TOOLS in daemon/src/sallyport_daemon/mcp_server.py. Mark fields required whenever the implementation throws without them — schema and behaviour should agree (see the close_tab regression captured by test_close_tab_requires_tab_id).
  4. Pin the catalogue. Add the new name to the expected set in daemon/tests/test_mcp_server.py::test_tools_catalogue_covers_extension. Mismatches between the daemon and extension registries fail the build immediately rather than at the wire.
  5. Document. A row in the Tools table in README.md, and an entry in CHANGELOG.md under [Unreleased] / Added describing the user-visible shape (args, gates, error codes worth knowing).

Then cd extension && npm test && npm run lint && npm run typecheck and cd daemon && ruff check . && mypy && pytest -q — all green before calling it done.

Versioning & releases

CHANGELOG.md tracks every notable change; the project uses Semantic Versioning. The wire protocol version is 1 — bump only on incompatible changes and update the cross-language vector tests in the same commit.

License

MIT — see LICENSE.

Wire protocol

Documented in extension/src/protocol.ts and daemon/src/sallyport_daemon/protocol.py. Envelope shape:

{ v, ts, nonce, type, id?, body, mac }

mac = HMAC-SHA256(secret, canonical_json({v, ts, nonce, type, id?, body})), base64. Canonical JSON: keys sorted by Unicode code point, no whitespace, unicode passthrough, cross-language number formatting.

The exact bytes are pinned to 49 cross-language vectors in fixtures/canonical-vectors.json — both daemon/tests/test_vectors.py and extension/test/vectors.test.ts read that file and assert byte-by-byte agreement. If you change the canonicalisation rules, regenerate via python3 fixtures/generate.py and update both implementations in the same commit.

There is no version negotiation — both sides expect v: 1. Bump it on breaking changes and update both vector tests in the same commit.

Ver o original no GitHub

Bom para

Relacionados