Impedindo Agentes de IA de Adivinharem Portas do Localhost com portmap

Um agente de codificação de IA pode escrever uma solicitação perfeitamente razoável para http://localhost:3000 e ainda assim estar completamente errado. O Next.js frequentemente usa essa porta, mas o Vite comumente usa 5173, uma API pode usar 8080, e o Docker pode expor uma porta do host que difere da porta do contêiner.

A falha resultante é enganosamente cara. Você investiga CORS, autenticação ou um endpoint quebrado quando o problema real é que nenhum processo está ouvindo na URL que o agente inventou.

Este tutorial usa portmap para tornar essa topologia local explícita. Você irá construir a ferramenta a partir de sua tag estável v0.1.0, executar uma verificação estática contra um fixture reproduzível, inspecionar o contrato legível por máquina .portmap.json e, em seguida, ver onde os modos de execução e MCP se encaixam.

TL;DR

portmap é um CLI determinístico e um servidor MCP somente leitura para desenvolvimento local. Ele compara portas declaradas em arquivos de projeto com ouvintes do sistema operacional e URLs localhost encontradas em arquivos de ambiente. O resultado é um relatório .portmap.json mais descobertas como PRT-01 para uma porta declarada que está inativa e PRT-04 para uma URL de ambiente sem ouvinte.

Ele não inicia processos, gerencia contêineres, monitora produção ou pede a um LLM para inferir a resposta.

Pré-requisitos

Você precisa:

• Node.js 20 ou mais recente. O pacote declara node >=20.
• npm e Git.
• Um projeto local ou os fixtures do repositório usados abaixo.
• Um terminal que possa ler os arquivos do projeto e a tabela de soquetes local.

O projeto é licenciado sob a MIT. Os comandos abaixo visam a fonte marcada v0.1.0 em vez de uma alteração de branch padrão não lançada. Verifique os metadados do pacote e a licença se você estiver empacotando para uma equipe.

Instale a fonte estável

O README atualmente documenta um checkout de fonte. Fixar a tag torna este tutorial reproduzível:

git clone --branch v0.1.0 https://github.com/paladini/portmap.git
cd portmap
npm ci
npm run build

O pacote expõe um binário portmap após a publicação, mas o fluxo de trabalho do repositório pode executar o CLI compilado diretamente:

node dist/cli.js --help

Os principais comandos são:

scan [path]       Configuração estática mais ouvintes do SO
declare [path]    Somente configuração estática
listen            Listar ouvintes do SO
workspace [dir]   Reconciliar projetos irmãos
mcp               Iniciar o servidor MCP somente leitura

Use declare quando você quiser uma verificação de configuração segura antes de iniciar serviços. Use scan quando você também quiser comparar a declaração com processos que estão atualmente ouvindo na máquina.

Execute uma verificação de incompatibilidade reproduzível

O repositório inclui um fixture onde um frontend Vite declara a porta 5173, enquanto as variáveis de ambiente apontam para 3000 e 8080. Nenhum processo em execução é necessário para esta primeira verificação:

node dist/cli.js declare fixtures/mismatch --json

O relatório tem o esquema portmap-v1. Suas partes importantes se parecem com isto:

{
  "services": [
    {
      "id": "vite",
      "declared": { "port": 5173 },
      "actual": null,
      "status": "down"
    }
  ],
  "references": [
    {
      "envKey": "VITE_API_URL",
      "value": "http://localhost:8080",
      "targetPort": 8080,
      "status": "unresolved"
    }
  ]
}

O fixture relata três erros:

• PRT-01: a porta Vite declarada não está ouvindo.
• PRT-04: NEXT_PUBLIC_API_URL aponta para localhost:3000 sem ouvinte.
• PRT-04: VITE_API_URL aponta para localhost:8080 sem ouvinte.

Essa é uma resposta mais útil do que pedir a um agente para tentar portas até que uma responda. O fixture de incompatibilidade e o guia de exemplos contêm a configuração de origem por trás deste resultado.

Escreva um artefato para a próxima sessão do agente

Uma vez que o relatório seja útil, escreva-o na raiz do projeto:

node dist/cli.js scan . --write

Isso cria .portmap.json. Um agente de codificação ou um humano pode ler references[].value em vez de assumir que a API frontend vive em localhost:3000.

Para uma verificação que deve falhar no CI quando erros existem, use as flags de limite:

node dist/cli.js declare . --min-findings 1 --min-severity error --quiet

O comando sai com status 1 quando pelo menos uma descoberta de erro atende ao critério.