security-first MCP server for pfSense

Somente leitura hoje, por design; ESCRITA é encenada atrás de arquitetura de segurança explícita

Documentação

pfsense-mcp-server

Acesso seguro e com privilégios mínimos ao pfSense para assistentes de IA. Servidor MCP que dá a um assistente de IA visibilidade fortemente tipada e somente leitura em um único appliance pfSense — sistema, rede, firewall, DHCP, DNS, VPN, certificados e diagnósticos — sem acesso bruto ao shell, sem uma superfície de script não auditada ou qualquer forma de alterar o appliance por acidente.

Construí isso porque queria assistência de IA para pfSense sem dar a um LLM a capacidade de desconectar acidentalmente minha própria rede — um firewall merece um padrão de segurança mais alto do que "o modelo provavelmente não fará uma alteração ruim". Veja Por que este projeto existe para o raciocínio completo.

O que ele faz

97 ferramentas: 95 ferramentas READ do pfSense + 2 ferramentas de orientação de documentação. Cobre aproximadamente 90% da superfície READ útil da API REST do pfSense. Cada ferramenta é fortemente tipada (Pydantic) — sem passagem de JSON não tipado.
0 ferramentas WRITE por padrão. Existe um caminho de alteração protegida totalmente construído e verificado duas vezes ao vivo, mas requer aceitação explícita — veja Níveis de segurança abaixo.
Pergunte coisas como: "Liste minhas VLANs e em qual interface cada uma está," "Meu gateway WAN está ativo agora?", "Quais certificados expiram em breve?", "Quais concessões DHCP estão ativas na LAN?" — cada pergunta mapeia para uma ferramenta tipada e com capacidade controlada.

Início rápido

pipx install pfsense-mcp-server
pfsense-mcp-security setup

(Se você chegou aqui pela caixa genérica "pip install" do PyPI acima — esse é o cabeçalho fixo da página do PyPI, não a recomendação deste projeto. Use o comando pipx mostrado aqui.)

Ainda não tem pipx? sudo apt install pipx && pipx ensurepath no Debian/Ubuntu (reabra seu terminal depois) — veja Instalação para outras plataformas e uma alternativa simples de ambiente virtual. Um pip install em todo o sistema é deliberadamente não recomendado: no Debian/Ubuntu moderno, ele é recusado diretamente (PEP 668) e, mesmo onde não é, arrisca afetar pacotes dos quais seu próprio sistema operacional depende.

O assistente de configuração faz algumas perguntas em linguagem simples — o endereço do seu firewall, se você deseja permitir somente leitura ou alterações protegidas, como verificar a conexão — e então imprime a configuração exata para colar no seu cliente MCP. Nada precisa ser digitado ou editado manualmente. Prefere configurar manualmente ou quer o passo a passo completo? Veja Começando.

Depois que seu cliente estiver conectado e mostrar 97 ferramentas disponíveis, tente uma das perguntas de O que ele faz acima.

Níveis de segurança

Escolha o nível que corresponde ao que você precisa — você pode alterar isso depois executando setup novamente.

Nível	O que significa	Para quem é
Somente leitura (padrão, recomendado)	A IA pode inspecionar o pfSense — status, configuração, diagnósticos — mas não pode alterar nada.	Quase todos. Esta é a opção mais segura e cobre a grande maioria do trabalho útil assistido por IA no pfSense.
Alterações protegidas	Adiciona exatamente uma capacidade (editar a descrição de um alias de firewall) atrás de autorização criptograficamente assinada explícita e uma etapa separada de confirmação.	Usuários avançados que têm um motivo específico e deliberado para permitir que a IA faça uma alteração estreita e auditável.
Alterações protegidas por hardware	Tudo nas Alterações protegidas, mais uma testemunha externa baseada em TPM que deve concordar independentemente antes que uma alteração seja considerada verificada.	Operadores preocupados com segurança que desejam proteção anti-rollback além do acima.

Nenhum nível escala silenciosamente para outro, e nada acima de somente leitura é alcançável a menos que você aceite explicitamente durante a configuração. A mecânica interna exata — resumos de plano, tokens de autorização, o executor de mutação selado, estado da testemunha — está documentada em detalhes para usuários avançados e auditores no Modelo de segurança.

Arquitetura em resumo

AI client (Claude, Codex, ...)
  │  MCP over stdio
  ▼
pfsense-mcp-server
  │  one typed method call, GET-only
  ▼
pfSense's pfREST API
  │
  ▼
pfSense appliance

Cada uma das 95 ferramentas READ segue exatamente este caminho, sem exceções — aplicado mecanicamente no momento da compilação, não apenas por convenção (uma verificação make validate exige exatamente uma chamada de cliente tipada por ferramenta READ, prevenindo estruturalmente uma incompatibilidade ferramenta/endpoint).

READ trust path: AI/MCP client through stdio, an explicitly registered MCP tool, capability/profile gate, least-privilege mapping, one fixed typed client method, a GET-only pfREST call, the pfSense appliance, a typed model boundary excluding secret fields, to a safe MCP result

O caminho de alteração protegida (construído, não alcançável por padrão)

Existe um caminho totalmente construído e verificado duas vezes ao vivo para exatamente uma operação de alteração protegida (o campo de descrição de um alias de firewall), mas permanece inalcançável a menos que você aceite explicitamente durante a configuração: write_protected deve ser selecionado, uma assinatura Ed25519 fora do host — cuja chave o servidor em execução nunca possui — deve autorizá-la, e uma autoridade de confirmação separada deve confirmá-la. Veja o assistente de configuração de segurança e o modelo de segurança para exatamente o que ele exige e não faz por padrão.

Veja a página completa de diagramas de arquitetura para o detalhe porta a porta por trás de ambos os diagramas.

O que você obtém

Categoria	Ferramentas	Exemplos
Sistema	26	hostname, DNS, versão, pacotes, configurações da API REST, diagnósticos
VPN	17	IPsec, OpenVPN, status/config WireGuard, CARP
Firewall	15	regras, aliases, estados, NAT, agendamentos, IPs virtuais, modeladores de tráfego
DNS	7	configurações do resolvedor, overrides, listas de acesso
Interfaces	9	status, VLANs, grupos, bridges, LAGG
DHCP	7	servidores, mapeamentos estáticos, concessões, relay
Roteamento / Gateways	6	gateways, status de gateway, rotas estáticas
Certificados / PKI	3	certificados, autoridades certificadoras, CRLs
Usuários / Identidades de API	3	usuários locais, grupos de usuários, chaves de API
Serviços / Monitoramento	2	status de serviço, FreeRADIUS EAP

Referência completa por ferramenta, parâmetros e proveniência: Referência de ferramentas MCP · Referência de ferramentas e orientação.

Conecte seu cliente MCP

Para Claude Desktop e Codex CLI / ChatGPT desktop, uma vez que a configuração do seu servidor funcione, gere o bloco de configuração exato do cliente automaticamente:

pfsense-mcp-security setup write-client-config \
  --client claude-desktop --config-path /absolute/path/to/claude_desktop_config.json \
  --capability-posture read_only --anchor-assurance none

Isso pré-visualiza a alteração e pede confirmação explícita antes de gravar qualquer coisa — nunca sobrescreve silenciosamente uma configuração existente. Cada outro cliente suportado — Claude Code, Cursor, VS Code, Continue e qualquer outro cliente compatível com MCP — tem seu próprio guia pronto para copiar/colar em vez de um gerador. Guias prontos por cliente — examples/README.md. Detalhes completos: Conecte seu cliente MCP.

Requisitos

Python 3.11, 3.12 ou 3.13.
pfSense com o pacote REST API (pfrest/pfSense-pkg-RESTAPI, API v2) instalado e habilitado.

Veja Compatibilidade para exatamente quais edições/versões do pfSense são diretamente verificadas vs. apenas esperadas para funcionar.

Documentação

Começando Instalação · Assistente de configuração de segurança · Conecte seu cliente MCP

Usando o servidor Referência de ferramentas MCP · Referência de ferramentas e orientação · Referência de configuração

Segurança Modelo de segurança · Modelo de ameaças · Arquitetura de segurança Nível 1

Referência Compatibilidade · Diagramas de arquitetura · Roteiro público

Desenvolvedor / contribuidor Decisões de arquitetura · Contribuindo · Suporte · Política de segurança

Status da versão

v0.9.0 é a linha de base de produção imutável, publicada no PyPI — 95 ferramentas READ do pfSense + 2 ferramentas de orientação de documentação, 0 ferramentas WRITE. pfsense_get_api_guidance cobre o pacote pfREST mantido pela comunidade (pfSense-pkg-RESTAPI, documentado em pfrest.org), mantido estruturalmente separado de pfsense_get_official_guidance (documentação do produto Netgate) — nunca misturado. As evidências são explicitamente rotuladas por proveniência (PROJECT_AUTHORED / PFREST_UPSTREAM / LIVE_APPLIANCE_SCHEMA / OFFICIAL_NETGATE); documentação é dado, nunca autoridade. Veja a entrada [0.9.0] de CHANGELOG.md e docs/ACCEPTANCE_v0.9.0.md para a evidência completa e verificada independentemente — cada tag de versão anterior, GitHub Release e artefato PyPI permanece intacto como um registro histórico preciso.

Contribuindo

Contribuições são bem-vindas dentro dos limites documentados de segurança e aprovação. Leia CONTRIBUTING.md antes de abrir uma alteração.

Licença

Licenciado sob a Licença MIT.

pfSense® é uma marca registrada da Electric Sheep Fencing, LLC, licenciada exclusivamente para a Rubicon Communications, LLC, que opera como Netgate. Este projeto é uma ferramenta independente, construída pela comunidade. Não é afiliado, endossado ou patrocinado pela Electric Sheep Fencing, LLC ou Netgate.