Programação e automação

agent-framework no PyPI: como um arquivo .pth roda código sem que ninguém o importe

O pacote oficial agent-framework teve duas versões maliciosas no PyPI. Entenda os arquivos .pth, como verificar seu ambiente e como se proteger.

Eddwan HallenInstrutor & Co-fundador · 9 min de leitura

Em 17 de novembro de 2026, o pacote oficial agent-framework, o Microsoft Agent Framework para Python, recebeu duas versões maliciosas no PyPI. Elas ficaram disponíveis por menos de uma hora. Foi o suficiente: segundo a JFrog, bots de atualização de dependências como o Renovate já abriam pull requests sugerindo a nova versão seis minutos depois da publicação.

O detalhe que interessa a quem programa em Python é o mecanismo. O código malicioso rodava mesmo em projetos que nunca executaram import agent_framework. Bastava o pacote estar instalado no ambiente e qualquer processo Python ser iniciado. Como isso é possível? A resposta está num recurso antigo e pouco conhecido do interpretador: os arquivos .pth.

O que é um arquivo .pth

Quando o Python inicia, ele importa automaticamente o módulo site, a menos que você use a opção -S. O site monta a lista de diretórios onde os pacotes estão instalados (os site-packages) e acrescenta esses caminhos ao sys.path.

Durante esse processo, o site procura arquivos com a extensão .pth na raiz de cada site-packages. Cada linha desses arquivos é tratada de um de dois jeitos:

  • Uma linha comum é interpretada como um caminho. Se o diretório existir, ele é adicionado ao sys.path.

  • Uma linha que começa com import (seguido de espaço ou tabulação) é executada como código Python.

O recurso existe por bons motivos. Pacotes instalados em modo editável (pip install -e .) usam .pth para apontar o sys.path para o diretório do código-fonte. Ferramentas como o setuptools usam linhas import para ajustar o ambiente antes de qualquer código seu rodar. Num ambiente virtual recém-criado é comum encontrar um distutils-precedence.pth com uma linha desse tipo.

Fluxo de inicialização do Python: o módulo site lê os arquivos .pth e executa as linhas que começam com import

Veja o efeito com um exemplo inofensivo

Faça este teste num ambiente virtual descartável, nunca no Python do sistema:

python3 -m venv /tmp/lab-pth
SP=$(/tmp/lab-pth/bin/python -c "import site; print(site.getsitepackages()[0])")
echo 'import sys; print("[demo.pth] rodei na inicialização", file=sys.stderr)' > "$SP/demo.pth"
/tmp/lab-pth/bin/python -c "print('meu script')"

A mensagem do demo.pth aparece antes de meu script. Nenhum código importou nada: o próprio interpretador executou a linha ao iniciar. Agora rode com -S, que desliga o módulo site:

/tmp/lab-pth/bin/python -S -c "print('meu script')"

A mensagem some. Guarde esse detalhe, ele volta na seção de verificação. Para limpar, apague a pasta /tmp/lab-pth.

Por que isso é pior do que um import malicioso

Num ataque comum de cadeia de suprimentos, o código malicioso fica dentro do pacote e só roda quando o pacote é importado. Se o seu projeto declara a dependência mas não usa aquele módulo num determinado processo, o código não roda ali.

Com um .pth, isso deixa de valer. O código roda em todo processo Python iniciado naquele ambiente:

  • no script que usa o pacote e no que não usa;

  • na suíte de testes (pytest);

  • em ferramentas de linha de comando escritas em Python, como linters e formatadores;

  • em cada etapa de um job de CI que chame python, inclusive o próprio pip em execuções seguintes.

Em resumo, instalar já é executar. E como o pacote continuava funcionando normalmente (as versões maliciosas mantinham a dependência do agent-framework-core 1.26.0 legítimo), nada parecia quebrado.

O caso, passo a passo

A linha do tempo abaixo segue a Wiz, que publicou a análise mais detalhada. Os horários estão em UTC, no dia 17/11/2026:

Horário (UTC)

O que aconteceu

20h35

Versão maliciosa 1.26.1 publicada no PyPI

cerca de 21h08

Versão maliciosa 1.26.2 publicada

cerca de 21h30

As duas versões já não estavam disponíveis no PyPI

A JFrog registra horários um pouco diferentes para a remoção: a 1.26.1 em quarentena às 21h06 e as duas fora do ar às 21h16. Em qualquer das contagens, foi menos de uma hora. A última versão segura é a 1.26.0. A remoção não desfaz nada: quem instalou uma das versões maliciosas nesse intervalo continua exposto.

O que muda entre as duas versões é onde o gatilho fica:

  • 1.26.1: grava agent_framework_meta.pth em site-packages. Ele importa um módulo que chama um componente disfarçado de _telemetry, com nomes que imitam telemetria legítima do SDK.

  • 1.26.2: restaura o __init__.py limpo e move o gatilho para af_runtime_diag.pth e af_runtime_diag.py. Quem procurasse só os nomes da primeira versão não encontraria a segunda.

O que era coletado

  • variáveis de ambiente com nomes que sugerem segredos, e também segredos lidos do ambiente de outros processos;

  • arquivos de credenciais de Azure CLI, npm, pip, git, Docker, Hugging Face e de agentes do Azure DevOps, além de arquivos .env;

  • tokens OIDC do Azure DevOps, tokens de identidade gerenciada para 12 recursos do Azure e metadados da instância;

  • na 1.26.2, também tokens OIDC do GitHub Actions.

Tudo era reunido num JSON, compactado, codificado em base64 e enviado numa única requisição HTTPS para uma URL fixa do webhook.site, um serviço público de inspeção de requisições.

Como o atacante conseguiu publicar

Segundo a Wiz, o atacante parece ter obtido um certificado de cliente e a chave privada do ESRP, o pipeline interno que a Microsoft usa para assinar e publicar esse pacote. Uma primeira tentativa, feita a partir da AWS, foi barrada por filtro de IP. A segunda, a partir de um endereço da própria Microsoft, funcionou. Não se sabe como essas credenciais foram obtidas. A JFrog acrescenta que o pacote foi montado por um script local, e não pelo processo normal de build. Até a publicação deste artigo, não encontramos um comunicado oficial da Microsoft sobre o caso; a SecurityWeek relata que um mantenedor do projeto confirmou no GitHub a remoção das versões e uma investigação em andamento.

Por que o CI é o alvo preferido

Um notebook de desenvolvedor tem segredos. Um runner de CI costuma ter mais, e mais valiosos: tokens de publicação de pacotes, credenciais de registro de contêiner e acesso à nuvem para fazer deploy.

Muitos pipelines modernos não guardam mais uma senha da nuvem. Eles usam OIDC: a cada execução, o provedor de CI (GitHub Actions, Azure DevOps) emite um token assinado que diz "sou o workflow X do repositório Y". A nuvem confia nesse emissor e troca o token por uma credencial temporária. É uma prática melhor do que guardar segredo fixo, mas tem uma consequência: qualquer código que roda dentro do job pode pedir esse token. Um .pth malicioso roda dentro do job.

Caminho do token OIDC: o job de CI pede o token, o código malicioso intercepta e troca por acesso à nuvem

No GitHub Actions, isso depende da permissão id-token: write no workflow. Onde existe uma credencial federada do Entra ID confiando naquele repositório, o token roubado pode ser trocado por acesso ao Azure, sem nenhum segredo armazenado.

Como verificar se o seu ambiente foi afetado

Uma regra antes dos comandos: não rode python nem pip num ambiente que você suspeita estar comprometido. Cada inicialização do interpretador executa o .pth de novo. Use ferramentas do shell. Se precisar do Python, python -S não processa os .pth.

1. Procure as versões em lockfiles e requisitos

grep -rnE 'agent[-_]framework[^-]{0,4}1\.26\.[12]\b' \
  --include='requirements*.txt' --include='*.lock' --include='*.toml' .

No uv.lock e no poetry.lock, nome e versão ficam em linhas separadas:

grep -n -A1 '^name = "agent-framework"$' uv.lock poetry.lock 2>/dev/null

2. Procure nos logs de CI

O pip registra o que instalou. Exporte os logs dos jobs entre 17/11 e a data em que você fixou a versão e procure:

grep -rnE 'agent[-_]framework-1\.26\.[12]' ./logs-ci/

3. Procure os arquivos no disco e em imagens

Em ambientes virtuais, servidores e runners próprios:

find / \( -name 'agent_framework_meta.pth' -o -name 'af_runtime_diag.pth' \
  -o -name 'af_runtime_diag.py' -o -name 'agent_framework-1.26.[12].dist-info' \) 2>/dev/null

Em imagens de contêiner, rode o mesmo find trocando o entrypoint por sh, para não iniciar o Python da imagem:

docker run --rm --entrypoint sh SUA_IMAGEM -c \
  "find / -name 'agent_framework_meta.pth' -o -name 'af_runtime_diag.pth' 2>/dev/null"

Aproveite para revisar todos os .pth que executam código. A maioria será legítima, mas vale saber quais existem:

find / -path '*site-packages/*.pth' -exec grep -l '^import' {} + 2>/dev/null

4. Procure a saída de dados na rede

Nos logs de proxy, DNS e firewall, procure acessos ao domínio webhook.site a partir de máquinas de desenvolvimento e runners. A Wiz publicou a URL completa nos indicadores de comprometimento. Um acesso a esse domínio vindo de um runner, no período, é motivo para tratar o host como comprometido.

O que fazer se foi afetado

  • Isole e reconstrua. Prefira recriar o ambiente virtual, a imagem ou o runner a partir de uma base limpa, com a versão fixada em 1.26.0.

  • Troque todo segredo que estava no ambiente. Variáveis de ambiente, sessões do Azure CLI, PATs e service connections do Azure DevOps, tokens de npm, PyPI, Docker e Hugging Face, credenciais de git e chaves de provedores de IA.

  • Audite identidades do Azure. Revise logs de login e atividade das identidades gerenciadas e das credenciais federadas acessíveis a partir das máquinas e pipelines afetados. Tokens de identidade gerenciada e tokens obtidos por troca OIDC podem valer até 24 horas.

  • GitHub Actions com a 1.26.2. Para workflows que instalaram essa versão com id-token: write, trate os tokens OIDC como expostos: revise as credenciais federadas que confiam naqueles repositórios e troque os segredos do repositório e da organização usados pelo job.

Como se proteger daqui para frente

  • Fixe versões com hash. Um lockfile com hashes impede que uma versão nova entre sem você decidir. Com pip, gere o arquivo com pip-compile --generate-hashes (pip-tools) e instale com pip install --require-hashes -r requirements.txt. uv e poetry gravam hashes no lockfile por padrão.

  • Dê um tempo antes de aceitar versões novas. As duas versões ficaram no ar por menos de uma hora. Uma regra de espera de alguns dias no Renovate ou no Dependabot teria evitado a instalação. No uv, a opção --exclude-newer faz o mesmo papel.

  • Use um proxy ou mirror interno de pacotes. Ele centraliza o que entra, permite bloquear versões e registra quem baixou o quê.

  • Reduza o que o CI pode fazer. Dê id-token: write só aos jobs que fazem deploy, separe o job que instala dependências do job que publica e prefira credenciais de vida curta.

  • Verifique proveniência quando houver. O PyPI aceita atestados de publicação. Quando o pacote oferecer, confira se o artefato veio do repositório e do workflow esperados.

Fechamento

Este caso não envolveu um pacote falso com nome parecido. Era o pacote oficial, publicado pelo canal oficial. Confiar no publicador continua necessário, mas não basta: o controle sobre o que entra no seu ambiente, quando entra e com quais permissões tem que ser seu. E agora você sabe que, no Python, instalar um pacote já pode ser o mesmo que executá-lo.

Newsletter da EDCA

Receba os próximos artigos por e-mail.

Um resumo por semana, só quando sai coisa nova: artigos, ferramentas e cursos de VoIP, redes e programação.

Ao se inscrever, você concorda em receber a newsletter da EDCA por e-mail e com a política de privacidade. Você pode cancelar quando quiser.