Assistente de IA Nativo para pfSense, Endpoint MCP e Correções na REST API: Como transformei um firewall em um agente autônomo e auditável.

Pedi ao assistente que instalei no meu firewall: “faça um ping para o Google.”
Ele respondeu: “não consigo executar comandos no firewall.”

Minha primeira hipótese foi de que faltava alguma integração, conector ou MCP. Estava errado. Fui ler o código que eu mesmo tinha escrito e descobri duas coisas:

1. Não havia uma única chamada de execução no projeto inteiro. O assistente não tinha mãos.
2. O prompt do sistema afirmava: "Você é SOMENTE LEITURA, não consegue aplicar nenhuma mudança."

O modelo não estava falhando. Ele estava obedecendo. A grande lição de engenharia de software aplicada à IA: instrução desatualizada dentro de um prompt é defeito de produto, não erro de configuração. E não aparece em testes sintéticos convencionais, pois o código estava tecnicamente correto — o erro era semântico.

🛡️ O Desenho de Segurança em 5 Pilares

• 1. Sem Execução Crua de Shell: O modelo nunca escreve uma linha de comando livre. Ele seleciona uma função dentro de um catálogo fechado de 21 ferramentas com argumentos estritamente tipados e validados antes de qualquer chamada.
• 2. Duas Vias de Execução:
  • Via REST API Local (127.0.0.1/api/v2): Para estado de serviços, interfaces, gateways, ARP e concessões DHCP (onde o pfSense já aplica autenticação e validação).
  • Via Binários Nativos: Para diagnósticos que a REST API não possui (traceroute, drill para DNS, netstat -rW para rotas, sockstat para sockets e pfctl para contadores e estados do firewall).
• 3. Ações com Confirmação Humana (Human-in-the-Loop): Comandos que alteram o sistema (reiniciar serviços, flush de tabela de estados, remoção de leases) são apenas propostos na interface, exigindo clique de confirmação do operador com aviso explícito do impacto.
• 4. Documentação Viva & Histórico: Gera documentação técnica completa do firewall sob demanda e arquiva snapshots automáticos apenas quando há mudança de configuração real.
• 5. Servidor MCP Completo: Expõe um endpoint MCP nativo (/suporte_ia/mcp.php) com as 21 ferramentas de rede e as 690 operações da REST API para agentes de IA externos (Claude Code, Gemini CLI, Cursor).

📦 Downloads dos Pacotes e Código-Fonte

Todos os pacotes foram higienizados e estão disponíveis para download direto abaixo:

📦 Código-fonte completo do projeto: Download Suporte IA Source (.tar.gz)

🔒 Repositórios Privados no Painel Git

O código-fonte integral e o histórico de commits estão versionados em nossa infraestrutura própria de Git:

git clone https://git.programandosolucoes.com.br/git/repos/pfsense-suporte-ia.git
git clone https://git.programandosolucoes.com.br/git/repos/pfsense-restapi-fix-publico.git

Nota: Repositórios privados. Caso deseje acesso para avaliação técnica ou parceria, entre em contato diretamente.

Pedi ao assistente que instalei no meu firewall: "faça um ping para o Google."

Ele respondeu: "não consigo executar comandos no firewall."

Minha primeira hipótese foi de que faltava integração ou conector. Fui ler o código que eu mesmo escrevi e descobri:
1. Não havia uma única chamada de execução no projeto. O assistente não tinha mãos.
2. O prompt dizia categoricamente: "Você é SOMENTE LEITURA, não consegue aplicar nenhuma mudança."

O modelo não estava falhando. Estava obedecendo.

A grande lição: instrução desatualizada dentro de um prompt é defeito de produto, não erro de configuração.

Reescrevi a arquitetura do zero. Hoje o addon roda dentro do pfSense e o operador interage em português com execução real.

Confira os 3 pilares dessa engenharia:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
⚡ PILAR 1: Catálogo Fechado de 21 Ferramentas
▸ O modelo NUNCA gera linhas de comando de shell abertas.
▸ Escolhe funções de um catálogo fechado de 21 ferramentas, com argumentos tipados e validados antes de qualquer chamada.
▸ Duas vias: REST API local (127.0.0.1/api/v2) para estado/configuração e binários nativos (drill, netstat, sockstat, pfctl, nc) para diagnósticos profundos que a API não expõe.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🛡️ PILAR 2: Segurança & Human-in-the-Loop
▸ Ações que alteram o firewall (reiniciar serviços, flush de estados, remover leases DHCP) são apenas propostas na conversa.
▸ Execução condicionada ao clique explícito do operador, com alerta do impacto.
▸ Documentação viva gerada sob demanda e arquivamento automático apenas quando há mudança real de configuração.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔌 PILAR 3: Endpoint MCP Nativo & REST API Patches
▸ Servidor MCP embutido (/suporte_ia/mcp.php) expondo diagnósticos e 690 operações da REST API para agentes de IA externos (Claude Code, Gemini CLI, Cursor).
▸ Correções submetidas na REST API oficial do pfSense para garantir estabilidade.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 Downloads & Artigo Técnico Completo:
🔗 https://carloslopes.programandosolucoes.com.br/index.php/assistente-ia-pfsense-mcp-restapi/