pip-audit compara o ambiente, arquivo de requisitos ou lockfile com fontes de vulnerabilidades conhecidas. Ele ajuda a identificar versões afetadas e possíveis correções, mas não analisa a lógica do seu código nem comprova que um pacote seja seguro.

Auditar o projeto

Instale a ferramenta em ambiente isolado, por exemplo com pipx:

pipx install pip-audit
pip-audit .
pip-audit --locked .

O comando retorna status diferente de zero quando encontra vulnerabilidades, o que permite bloquear a CI. Use saída JSON quando outra ferramenta precisar consumir o resultado.

Não execute --fix sem revisar o diff. Uma atualização pode corrigir a falha e, ao mesmo tempo, introduzir incompatibilidades. Reproduza a instalação, rode testes e confirme que a versão corrigida chega à produção. O guia de uv e lockfiles ajuda a manter a resolução previsível.

Investigar e documentar exceções

Leia o advisory, avalie se o caminho vulnerável é alcançável e priorize pelo impacto real. Quando uma correção ainda não existir, registre responsável, mitigação e prazo. Se precisar ignorar um identificador, faça isso de forma específica e revisável, nunca com uma exclusão ampla.

Auditorias dependem de bases públicas e não cobrem falhas desconhecidas, bibliotecas do sistema ou comportamento malicioso sem advisory. Combine-as com revisão de origem, versões fixadas, testes e análise de código.

O repositório oficial do pip-audit, consultado em 22 de julho de 2026, documenta fontes de vulnerabilidades, lockfiles, formatos e modelo de segurança. Use a ferramenta como um controle contínuo, não como selo de segurança.

O que realmente é auditado

O resultado depende das versões resolvidas. Uma faixa aberta como requests>=2 não identifica a versão instalada em produção. Audite um ambiente implantável ou um lockfile atual e reproduzível. Dependências transitivas também importam: outro pacote pode trazer uma biblioteca vulnerável mesmo que sua aplicação não a importe diretamente.

O pip-audit relaciona nomes e versões a advisories publicados. Um alerta costuma informar o identificador e versões corrigidas conhecidas. Isso responde se a versão consta da base, não se a execução alcança o trecho vulnerável. A ferramenta também não examina código próprio, imagens completas de contêiner, bibliotecas do sistema ou serviços externos.

Selecionar a entrada correta

Para um ambiente virtual preparado, execute pip-audit e registre como ele foi construído. Para requirements, escolha o arquivo usado pela implantação. Quando houver metadados e lockfile compatíveis, audite o projeto bloqueado para não resolver um grafo diferente do que foi testado.

pip-audit
pip-audit -r requirements.txt
pip-audit --locked .

Não junte resultados de ambientes distintos como se descrevessem uma release. Versão do Python, plataforma e marcadores podem alterar o grafo. Na CI, use a mesma versão principal e grupos de dependência relevantes para produção. Ferramentas de desenvolvimento também merecem análise porque executam com acesso ao código e a credenciais.

Analisar um achado

Comece pelo advisory original e pela correção do mantenedor. Confirme pacote, versão, comportamento afetado e pré-condições. Identifique qual dependência direta o introduziu e se seu uso alcança a funcionalidade vulnerável. Exposição externa, impacto sobre confidencialidade, execução de código e facilidade de exploração influenciam prioridade.

Um caminho aparentemente inalcançável não permite ignorar o alerta indefinidamente. Registre análise, evidência, responsável e data de revisão. Mudanças futuras podem torná-lo alcançável. Quando existe correção compatível, atualizar costuma ser mais sustentável que manter uma exceção longa.

Corrigir sem adivinhar

Descubra por que o pacote está presente. Se for dependência direta, atualize a restrição e regenere o lockfile. Se for transitiva, procure versão atualizada do pacote pai. Forçar uma versão filha pode violar restrições ou criar combinação sem suporte.

Reconstrua o ambiente do zero, execute testes unitários e de integração e valide os fluxos relacionados. Audite novamente o artefato resolvido. O alerta desaparecer do arquivo editado não prova que a versão corrigida chegou à produção.

--fix acelera a edição, mas não entende compatibilidade funcional. Use-o em branch revisável, examine o diff e regenere arquivos derivados. O artigo sobre uv e gerenciamento de projetos explica a função do lockfile.

Integrar à CI

Instale a ferramenta de forma controlada e fixe sua versão conforme a política interna. Execute após resolver dependências, preserve saída legível e use o código de saída para impedir que um alerta novo passe despercebido.

- name: Auditar dependências Python
  run: |
    python -m pip install pip-audit
    pip-audit -r requirements.txt

O formato JSON facilita histórico e painéis, mas relatórios não devem expor nomes privados ou arquitetura sensível. Programe auditorias mesmo sem commits, pois advisories novos surgem para versões que não mudaram.

Exceções precisam expirar

Uma vulnerabilidade sem correção pode exigir mitigação temporária. Desabilite a função afetada, restrinja entradas ou isole o componente quando houver evidência. Registre identificador exato, justificativa, controle compensatório, responsável e prazo. Uma supressão ampla pode esconder alertas futuros.

Se o alerta não se aplicar, preserve a análise técnica. Revise a exceção após atualização, mudança arquitetural ou nova informação. Sem prazo, uma decisão temporária vira dívida invisível.

Controles complementares

Auditoria por versão não detecta pacote malicioso sem advisory, typo-squatting, credencial exposta nem código inseguro da aplicação. Restrinja fontes, revise dependências e mantenedores novos, use hashes ou lockfiles quando adequado e proteja credenciais. Análise estática, testes e revisão de código cobrem outras classes.

Mantenha inventário do que chega à produção e remova dependências sem uso. Uma superfície menor reduz atualizações e investigações. O objetivo não é um relatório vazio a qualquer custo, mas decisões verificáveis e versões corrigidas no ambiente real.

Checklist para cada release

Confirme que o lockfile foi gerado com a ferramenta e versão previstas, que não há arquivos derivados esquecidos e que o ambiente foi reconstruído sem aproveitar pacotes antigos. Compare o relatório com a release anterior e destaque achados novos, removidos e ainda excepcionados.

Para cada correção, associe a alteração a testes relevantes e registre qual artefato será implantado. Depois do deploy, verifique a versão efetiva em produção quando o processo permitir. Um pipeline verde que auditou outro ambiente oferece uma garantia enganosa.

Defina responsável por acompanhar advisories fora do ciclo de releases. Meça tempo até triagem e correção, não apenas quantidade de alertas. Evite metas que incentivem supressões. Uma prática madura mostra por que um risco foi aceito, quando será revisto e como se comprovou que a atualização chegou ao destino.

Guarde o comando exato usado na auditoria junto ao resultado. Assim, outra pessoa consegue reproduzir a análise e distinguir uma mudança na base de dados de uma mudança real nas dependências.