convez.ai
MCP ServerSegurançaAvançado
mychaelconnolly

PhishFort MCP Server

mychaelconnolly/phishfort-mcp

Integração segura com PhishFort para gestão de incidentes de phishing via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP security-first que integra a API unificada do PhishFort ao ecossistema Claude, permitindo revisão de incidentes, gerenciamento de webhooks e operações com dados de segurança. Implementa controles de aprovação gated, proteção de secrets e validações rigorosas para evitar vazamento de dados sensíveis.

Instalação

$npx convez-ai mychaelconnolly/phishfort-mcp

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
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 3 meses
Versão
v0.1.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Revisão e análise de incidentes de phishing em tempo real
  • Gerenciamento de webhooks e automação de respostas de segurança
  • Integração com workflows de resposta a incidentes via Claude Agent

Veredito

Implementação robusta e security-first com aprovações gated para operações destrutivas, proteção de secrets e validações contra TOCTOU. Ideal para times de segurança que precisam integrar PhishFort em agents Claude com garantias de controle e auditoria.

README

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

██████╗ ██╗  ██╗██╗███████╗██╗  ██╗███████╗ ██████╗ ██████╗ ████████╗
██╔══██╗██║  ██║██║██╔════╝██║  ██║██╔════╝██╔═══██╗██╔══██╗╚══██╔══╝
██████╔╝███████║██║███████╗███████║█████╗  ██║   ██║██████╔╝   ██║
██╔═══╝ ██╔══██║██║╚════██║██╔══██║██╔══╝  ██║   ██║██╔══██╗   ██║
██║     ██║  ██║██║███████║██║  ██║██║     ╚██████╔╝██║  ██║   ██║
╚═╝     ╚═╝  ╚═╝╚═╝╚══════╝╚═╝  ╚═╝╚═╝      ╚═════╝ ╚═╝  ╚═╝   ╚═╝

                         ███╗   ███╗ ██████╗██████╗
                         ████╗ ████║██╔════╝██╔══██╗
                         ██╔████╔██║██║     ██████╔╝
                         ██║╚██╔╝██║██║     ██╔═══╝
                         ██║ ╚═╝ ██║╚██████╗██║
                         ╚═╝     ╚═╝ ╚═════╝╚═╝

        MCP server + paired agent skill for PhishFort workflows
        approval-gated writes | secret-safe defaults | no URL fetching

phishfort-mcp

security: reviewed & hardened tests: 36 passing python: 3.11+ license: MIT

A security-first MCP server and paired agent skill for the PhishFort Unified Client API.

Security-reviewed and hardened — 2026-06-10. Approval-gated writes · secret-safe by default · no incident-URL fetching · every security claim verified against the code.

Bring PhishFort incident review, reporting, attachments, comments, and webhook management into your MCP client, then give your agent the workflow playbook for using those tools safely.

Paired skill | Official PhishFort API docs | Security review | Local reference

Unofficial project. Not affiliated with, endorsed by, or maintained by PhishFort.

Security, reviewed in the open

This is a security tool, so the security work is the headline — not a disclaimer at the bottom. Every control is implemented in code, covered by tests, and was put through a review-and-harden pass whose results are public.

  • 2026-06-02 — v0.1.0. Local stdio MCP server and paired agent skill, security-first by default: approval-gated writes, API host pinning, redirects disabled, and no fetching of incident URLs.

  • 2026-06-05 — Posture mapped to evidence. Every security feature documented against MCP, OpenAI, and Anthropic guidance, each row tied to the exact code and test behind it.

  • 2026-06-10 — v0.1.1 Review and hardening pass. A security review conducted by Claude Fable 5 Ultracode (initial pass), Opus 4.8 xhigh, rubber-ducked with Codex 5.5 xhigh via plugin drove a hardening pass:

    • destructive confirmation is now enforced on incident-action requests — the annotation and the approval gate agree,
    • secret-named fields are scrubbed recursively, and one-time webhook secrets are written through O_NOFOLLOW 0600 files,
    • retries now cover transport errors, and secret-named fields are redacted from errors,
    • the approval salt is random and process-stable, and the retry count is bounded,
    • the webhook URL preflight rejects legacy numeric-IP encodings,
    • the attachment validate→upload race (TOCTOU) is closed.

    The same pass reworded every security claim to match what the code enforces — the approval gate is described as in-process integrity and confirmation, not independent authorization, and the webhook URL check as a pre-submit sanity check. Tests went from 26 to 36.

The table below is the evidence: each control maps to the code and the test that backs it.

Standards-Backed Security Posture

This server was designed against the Official Model Context Protocol security guidance, Anthropic connector guidance, OpenAI MCP guidance, OpenAI agent safety guidance, and PhishFort's official API docs. The table below lists only security features that are implemented in code, with local evidence.

Local evidence:

Security featureWhat it preventsConfirmed implementation
Local stdio transport onlyAvoids exposing a public HTTP MCP surface in v1server.main() rejects non-stdio transport
Two-step approval gate for writesForces an explicit plan→confirm step with a tamper-evident digest before any mutation. This is in-process integrity/confirmation, not independent human authorization — the host UI provides the human prompt via the destructive hints belowWrite tools require approval_id, approval_phrase, expires_at, request_digest; _validate_approval() recomputes the digest from the actual params
Tamper-resistant approval digestBlocks changing params after approval planningapproval.py canonicalizes params and verifies request_digest; covered by test_approval_rejects_tampered_params
Destructive confirmationAdds explicit friction for delete/rotate operationsDestructive specs require destructive_confirmed=true; covered by test_destructive_operation_requires_confirmed
Read/write MCP annotationsGives MCP hosts correct safety hints_read_annotations() and _write_annotations() set read-only/destructive/idempotent hints
API keys never passed as tool argsReduces credential leakage through prompts/tool logsSettings reads PHISHFORT_API_KEY or PHISHFORT_API_KEY_FILE; tool signatures do not accept API keys
Default API host pinningAvoids accidental credential use against arbitrary hostsSettings.validate_base_url() requires https://capi.phishfort.com/v1 unless explicit override is enabled
Redirects disabledAvoids following API responses to unexpected locationshttpx.AsyncClient(..., follow_redirects=False)
Error redactionPrevents API keys and secret-named fields from leaking through raised API errorsPhishFortClient._error() applies redact() (key value plus recursive secret/token/apiKey key masking); covered by test_error_redacts_api_key and test_error_redacts_secret_keys
Untrusted data warningsReminds agents not to treat incident content as instructionsresponse_envelope() adds untrusted_data_warning to PhishFort data outputs
No generic URL fetchingAvoids browsing hostile URLs returned in incident dataServer exposes PhishFort API tools only; no tool fetches incident URLs
Attachment file restrictionsReduces local file exfiltration riskvalidate_attachment_paths() enforces roots, extensions, max 12 files, and 10 MiB cap; open_attachments() holds O_NOFOLLOW fds to close the validate→open race; covered by attachment tests
Webhook URL preflight (defense-in-depth)Rejects localhost/private/reserved targets — including legacy decimal/octal/hex IP forms — before a webhook is registered. The server never fetches the URL itself (PhishFort delivers webhooks), so backend egress controls remain the real boundaryvalidate_webhook_url() and is_private_host(); covered by webhook URL tests
Webhook secret containmentKeeps one-time secrets out of tool output_handle_secret_response() recursively strips secret/token/apiKey keys at any depth; write_secret_file() writes 0600 with O_NOFOLLOW; covered by secret tests
Webhook signature verificationEnables receiver-side HMAC verificationverify_signature() uses HMAC-SHA256 and hmac.compare_digest(); covered by test_verify_signature
Limit-aware behaviorAvoids known API limit failures where possiblephishfort_get_limits, reference_limits, incident limit clamp, webhook 5-subscription preflight; covered by tests/test_limits.py
Bounded retry behaviorAvoids unsafe retry storms or unbounded sleepsRetries only 429/5xx and transport errors, caps the retry count at 5, treats terminal statuses as terminal, caps Retry-After; covered by retry tests

About

phishfort-mcp is a public, unofficial MCP integration for teams and operators who want PhishFort incident workflows available inside agentic tools without giving up basic operational control. The MCP server provides live API access; the paired skill gives compatible agents the workflow memory needed to use that access consistently.

It is built for local-first use, explicit approvals, and careful handling of phishing data. The goal is not to make incident response fully autonomous. The goal is to make the repetitive parts faster while keeping sensitive actions, secrets, and untrusted content under control.

Why This Exists

PhishFort has a focused REST API for phishing incident workflows. MCP makes that API usable from agentic tools, and the paired skill teaches those agents the operating procedure: what to read first, how to plan writes, what data is untrusted, and when to stop for explicit approval.

That pairing matters because security workflows are not just API calls. Incident data can contain hostile text, URLs should not be fetched casually, and takedown or webhook operations should not happen from a loose prompt.

phishfort-mcp ships two pieces that work together:

  • a local stdio MCP server for live PhishFort API access
  • an agent-agnostic skill that turns raw tool access into repeatable, safer workflows
  • approval-gated writes for reporting, actions, evidence, comments, and webhooks
  • secret-safe handling for API keys and one-time webhook secrets
  • untrusted-data guardrails for incident text, URLs, and webhook payloads

What You Can Do

WorkflowTools
Give agents the PhishFort operating playbookskills/phishfort-mcp/SKILL.md
Check documented API limitsphishfort_get_limits
Check identity and client scopephishfort_whoami
Search and inspect incidentsphishfort_list_incidents, phishfort_get_incident, phishfort_find_incident_by_subject
Report URLs, domains, emails, phones, and IPv4 subjectsphishfort_report_incident
Request takedown, monitoring, or safe reviewphishfort_request_incident_action
Add evidence and analyst contextphishfort_add_attachments, phishfort_add_comment
Manage webhook subscriptionsphishfort_list_webhooks, phishfort_create_webhook, phishfort_update_webhook, phishfort_delete_webhook, phishfort_test_webhook, phishfort_rotate_webhook_secret
Verify incoming webhook deliveriesphishfort_verify_webhook_signature

The server also exposes MCP resources for the distilled API reference, source manifest, and security review:

  • phishfort://reference/summary
  • phishfort://reference/limits
  • phishfort://reference/source-manifest
  • phishfort://reference/security-review

Paired Skill

This repo ships an agent-agnostic skill in skills/phishfort-mcp/SKILL.md. Use it with any skill-capable MCP host to teach the agent the safe operating pattern for this server: read before write, treat incident data as untrusted, never fetch returned URLs by default, and use phishfort_plan_change before mutating calls.

The skill keeps detailed workflows in references/workflows.md, exact tool parameters in references/tool-map.md, and points agents to phishfort_get_limits before workflows where limits change the right next step.

Safety Built In

The standards-backed table above is the detailed proof. Operationally, the server stays local-first, keeps credentials out of tool arguments, treats PhishFort data as untrusted, gates writes through phishfort_plan_change, stores webhook secrets outside tool output, and constrains attachments, webhook URLs, limits, and retries.

See MCP security review for the reasoning behind these choices.

Quick Start

git clone https://github.com/mychaelconnolly/phishfort-mcp.git
cd phishfort-mcp
uv sync --extra dev

Create a local key file:

mkdir -p ~/.config/phishfort-mcp
chmod 700 ~/.config/phishfort-mcp
$EDITOR ~/.config/phishfort-mcp/phishfort-api-key.txt
chmod 600 ~/.config/phishfort-mcp/phishfort-api-key.txt

Run a local CLI smoke:

uv run phishfort-mcp --help

Codex MCP Registration

codex mcp add phishfort \
  --env PHISHFORT_API_KEY_FILE=$HOME/.config/phishfort-mcp/phishfort-api-key.txt \
  -- uv --directory <path-to-phishfort-mcp> run phishfort-mcp

Then verify:

codex mcp list

A fresh Codex session may be required before new MCP tools are discoverable.

Configuration

VariableDefaultNotes
PHISHFORT_API_BASE_URLhttps://capi.phishfort.com/v1Pinned to official API host unless override is enabled.
PHISHFORT_API_KEYunsetUseful for short-lived local shells.
PHISHFORT_API_KEY_FILEunsetPreferred for MCP registration.
PHISHFORT_SECRET_DIR~/.config/phishfort-mcp/secretsWebhook secrets are written here with 0600 permissions.
PHISHFORT_ATTACHMENT_ROOTS.Comma-separated roots allowed for attachment uploads.
PHISHFORT_TIMEOUT_SECONDS30HTTP request timeout.
PHISHFORT_MAX_RETRIES3Retries apply to 429, 5xx, and transport errors; capped at 5; Retry-After on 429 is capped locally.
PHISHFORT_ALLOW_CUSTOM_BASE_URLfalseTest-only escape hatch for non-production API hosts.
PHISHFORT_ALLOW_UNSAFE_WEBHOOK_URLfalseTest-only escape hatch for localhost/private webhook targets.

Approval-Gated Writes

Read tools can be called directly. Writes are two-step on purpose:

  1. Call phishfort_plan_change with operation and exact params.
  2. Review warnings, risk, request_digest, and approval_phrase.
  3. Call the intended mutating tool with the same params plus approval_id, approval_phrase, expires_at, and request_digest.

If anything changes, rerun phishfort_plan_change.

This gate is in-process integrity and confirmation: it proves the executed params match the planned params (tamper-evident digest), enforces expiry, and requires destructive_confirmed=true for destructive operations. It is not an independent authorization boundary — the same agent can plan and confirm. The human-in-the-loop checkpoint is the MCP host's own tool-confirmation UI, driven by the destructive annotations the server sets.

Verification

uv run ruff check .
uv run pytest

Optional live smoke when a valid key exists:

  • phishfort_whoami
  • phishfort_list_incidents(limit=1)

Do not run live mutating smoke unless you intend to change PhishFort state.

API Reference

Official PhishFort docs:

This repo includes a distilled reference in docs/reference/phishfort-unified-client-api.md and a source URL manifest in docs/reference/source-manifest.json. Fetched raw PhishFort docs are intentionally not tracked.

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados