security-first MCP server for pfSense

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. Um caminho de alteração protegida totalmente construído e verificado duas vezes ao vivo existe, 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 tocar em 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 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. A configuração oferece criar uma conta pfSense dedicada somente leitura para você (recomendado), então mesmo uma solicitação que ignore esta ferramenta é recusada pelo próprio pfSense — ou você pode usar sua própria chave de API existente.	Quase todos. Esta é a opção mais segura e cobre a grande maioria do trabalho útil de pfSense assistido por IA.
Alterações protegidas	Adiciona exatamente uma capacidade (editar a descrição de um alias de firewall) atrás de autorização explícita e assinada criptograficamente 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 no nível de 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).

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

Um caminho totalmente construído e verificado duas vezes ao vivo existe 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á-lo, e uma autoridade de confirmação separada deve confirmá-lo. 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/configuração do WireGuard, CARP
Firewall	15	regras, aliases, estados, NAT, agendamentos, IPs virtuais, modeladores de tráfego
DNS	7	configurações do resolvedor, sobreposições, 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 escrever qualquer coisa — nunca sobrescreve silenciosamente uma configuração existente. Todos os outros clientes suportados — Claude Code, Cursor, VS Code, Continue e qualquer outro cliente compatível com MCP — têm seu próprio guia pronto para copiar e 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 versus meramente 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 Tier 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

v1.1.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. Uma versão de defesa em profundidade e integração: provisionamento de credenciais gerenciado somente leitura — uma conta de serviço pfSense pfsense-mcp-readonly dedicada e provisionada pelo projeto, mantendo exatamente 94 privilégios READ, verificada ao vivo em LAB para ser rejeitada pelo próprio pfSense quando usada diretamente contra o endpoint WRITE revisado deste projeto — agora é o caminho recomendado do assistente de configuração para novas instalações read_only; traga sua própria chave permanece totalmente suportado, inalterado por padrão, para instalações existentes. Não é uma expansão de capacidade — veja docs/STABILITY.md para a promessa de estabilidade independente de versão feita nas superfícies MCP/CLI/config/estado persistido. 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 [1.1.0] de CHANGELOG.md e docs/ACCEPTANCE_v1.1.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 e construída pela comunidade. Não é afiliado, endossado ou patrocinado pela Electric Sheep Fencing, LLC ou Netgate.