• Funcionalidades
• Instalação
  • Pacotes de terceiros
  • GitHub Actions
  • Suporte ao pre-commit
• Uso
  • Variáveis de ambiente
  • Códigos de saída
  • Execuções de teste
• Exemplos
• Solução de problemas
• Dicas e truques
• Modelo de segurança
• Licenciamento
• Contribuição
• Código de Conduta

Funcionalidades

• Suporte para auditoria de ambientes locais e arquivos no estilo requirements
• Suporte para múltiplos serviços de vulnerabilidade (PyPI, OSV)
• Suporte para emissão de SBOMs em CycloneDX XML ou JSON
• Suporte para correção automática de dependências vulneráveis (--fix)
• Formatos de saída legíveis por humanos e máquinas (colunar, Markdown, JSON)
• Reutiliza perfeitamente seus caches locais existentes do pip

Instalação

pip-audit requer Python 3.10 ou superior, e pode ser instalado diretamente via pip:```bash python -m pip install pip-audit

Pacotes de terceiros não são diretamente suportados por este projeto. Consulte a documentação do seu gerenciador de pacotes para obter instruções de instalação mais detalhadas.

GitHub Actions

O pip-audit possui uma GitHub Action oficial!

Você pode instalá-la pelo GitHub Marketplace, ou adicioná-la manualmente ao seu CI:```yaml jobs: pip-audit: steps: - uses: pypa/[email protected] with: inputs: requirements.txt

Quaisquer argumentos do pip-audit documentados abaixo podem ser passados.

Uso

Você pode executar o pip-audit como um programa independente, ou via python -m:```bash pip-audit --help python -m pip_audit --help

Variáveis de ambiente

pip-audit permite que os utilizadores configurem algumas flags através de variáveis de ambiente em vez disso:

Códigos de saída

Ao finalizar, o pip-audit sairá com um código indicando o seu estado.

Os códigos atuais são:

• 0: Nenhuma vulnerabilidade conhecida foi detetada.
• 1: Uma ou mais vulnerabilidades conhecidas foram encontradas.

O código de saída do pip-audit não pode ser suprimido. Consulte Suprimindo códigos de saída do pip-audit para alternativas suportadas.

Testes simulados

O pip-audit suporta a flag --dry-run, que pode ser usada para controlar se uma etapa de auditoria (ou correção) é realmente executada.

• Sozinha, pip-audit --dry-run salta a etapa de auditoria e imprime o número de dependências que teriam sido auditadas.
• No modo de correção, pip-audit --fix --dry-run realiza a etapa de auditoria e imprime o comportamento de correção (ou seja, quais dependências seriam atualizadas ou ignoradas) que teria sido executado.

Exemplos

Auditar dependências para o ambiente Python atual:```console $ pip-audit No known vulnerabilities found

Auditar dependências de um arquivo de requisitos, excluindo pacotes do sistema:```console $ pip-audit -r ./requirements.txt -l No known vulnerabilities found

Auditar lockfiles para um projeto Python local:```console $ pip-audit --locked . No known vulnerabilities found

Auditar dependências incluindo aliases:```console $ pip-audit --aliases Found 2 known vulnerabilities in 1 package Name Version ID Fix Versions Aliases

Flask 0.5 PYSEC-2019-179 1.0 CVE-2019-1010083, GHSA-5wv5-4vpf-pj6m Flask 0.5 PYSEC-2018-66 0.12.3 CVE-2018-1000656, GHSA-562c-5r94-xh97

Auditar dependências em formato JSON:```console $ pip-audit -f json | python -m json.tool Found 2 known vulnerabilities in 1 package [ { "name": "flask", "version": "0.5", "vulns": [ { "id": "PYSEC-2019-179", "fix_versions": [ "1.0" ], "aliases": [ "CVE-2019-1010083", "GHSA-5wv5-4vpf-pj6m" ], "description": "The Pallets Project Flask before 1.0 is affected by: unexpected memory usage. The impact is: denial of service. The attack vector is: crafted encoded JSON data. The fixed version is: 1. NOTE: this may overlap CVE-2018-1000656." }, { "id": "PYSEC-2018-66", "fix_versions": [ "0.12.3" ], "aliases": [ "CVE-2018-1000656", "GHSA-562c-5r94-xh97" ], "description": "The Pallets Project flask version Before 0.12.3 contains a CWE-20: Improper Input Validation vulnerability in flask that can result in Large amount of memory usage possibly leading to denial of service. This attack appear to be exploitable via Attacker provides JSON data in incorrect encoding. This vulnerability appears to have been fixed in 0.12.3. NOTE: this may overlap CVE-2019-1010083." } ] }, { "name": "jinja2", "version": "3.0.2", "vulns": [] }, { "name": "pip", "version": "21.3.1", "vulns": [] }, { "name": "setuptools", "version": "57.4.0", "vulns": [] }, { "name": "werkzeug", "version": "2.0.2", "vulns": [] }, { "name": "markupsafe", "version": "2.0.1", "vulns": [] } ]

Solução de problemas

Você resolveu um problema com pip-audit? Ajude-nos contribuindo para esta seção!

pip-audit mostra relatórios de vulnerabilidade irrelevantes!

Em um mundo perfeito, os feeds de vulnerabilidade teriam uma relação sinal-ruído infinita: cada relatório de vulnerabilidade seria (1) correto e (2) aplicável a todos os usos de cada dependência.

Infelizmente, nenhuma dessas condições é garantida: os feeds de vulnerabilidade não estão imunes a relatórios estranhos ou de spam, e nem todos os usos de uma dependência específica abrangem todas as classes potenciais de vulnerabilidades.

Se suas execuções do pip-audit produzem relatórios de vulnerabilidade que não são acionáveis para seu aplicativo ou caso de uso específico, você pode usar a opção --ignore-vuln ID para ignorar relatórios de vulnerabilidade específicos. O --ignore-vuln suporta aliases, então você pode usar um ID GHSA-xxx ou CVE-xxx em vez de um ID PYSEC-xxx se o relatório em questão não tiver um ID PYSEC.

Por exemplo, veja como você pode ignorar GHSA-w596-4wvx-j9j6, que é uma fonte comum de relatórios de vulnerabilidade ruidosos e falsos positivos para usuários do pytest:```console

Run the audit as normal, but exclude any reports that match GHSA-w596-4wvx-j9j6

$ pip-audit --ignore-vuln GHSA-w596-4wvx-j9j6

pip-audit demora mais do que eu esperava!

Dependendo de como você está usando, o pip-audit pode ter que realizar sua própria resolução de dependências, o que pode levar aproximadamente o mesmo tempo que o pip install leva para um projeto. Veja o modelo de segurança para uma explicação.

Você tem duas opções para evitar a resolução de dependências: auditar um ambiente pré-instalado ou garantir que suas dependências já estejam totalmente resolvidas.

Se você sabe que já configurou completamente um ambiente equivalente àquele que pip-audit -r requirements.txt auditaria, você pode simplesmente reutilizá-lo:```console

Note the absence of any "input" arguments, indicating that the environment is used.

$ pip-audit

Optionally filter out non-local packages, for virtual environments:

$ pip-audit --local

pip-audit não consegue autenticar no meu índice de terceiros!

Índices autenticados ou privados

O pip-audit suporta --index-url e --extra-index-url para configurar um índice de pacotes alternativo ou suplementar, assim como o pip.

Quando não autenticado, esses índices devem funcionar conforme o esperado. No entanto, quando um índice de terceiros requer autenticação, o pip-audit possui algumas restrições adicionais em relação ao pip normal:

• A autenticação interativa não é suportada. Em outras palavras: o pip-audit não solicitará nome de usuário/senha para o índice.
• A autenticação via keyring do pip é suportada, mas de forma limitada: o pip-audit usa o provedor de keyring subprocess, já que as auditorias ocorrem em ambientes virtuais isolados. O provedor subprocess, por sua vez, está sujeito a restrições adicionais (como a exigência de um nome de usuário); a documentação do pip explica isso em detalhes.

Além do acima, alguns índices de terceiros possuem nomes de usuário fixos requeridos. Por exemplo, para o Google Artifact Registry, o nome de usuário fixo é oauth2accesstoken. Veja #742 e pip#11971 para mais contexto.

Dicas e Truques

Executando contra um projeto pipenv

O pipenv usa tanto um arquivo Pipfile quanto Pipfile.lock para rastrear e congelar dependências, em vez de um arquivo requirements.txt. O pip-audit não consegue processar os arquivos Pipfile[.lock] diretamente; no entanto, eles podem ser convertidos para um arquivo requirements.txt suportado, contra o qual o pip-audit pode executar. O pipenv possui um comando embutido para converter dependências em um arquivo requirements.txt (a partir da v2022.4.8):```console $ pipenv run pip-audit -r <(pipenv requirements)

ou, para sair completamente:```bash pip-audit || exit 0

Consulte Códigos de saída para uma lista de códigos potenciais que precisam de tratamento.

Relatando apenas vulnerabilidades corrigíveis

Em fluxos de trabalho de desenvolvimento, você pode querer ignorar as vulnerabilidades que ainda não foram corrigidas e investigá-las apenas no seu processo de release. O pip-audit não suporta ignorar vulnerabilidades não corrigidas. No entanto, você pode exportar sua saída no formato JSON e processá-la externamente. Por exemplo, se você deseja sair com um código não-zero apenas quando as vulnerabilidades detectadas possuem versões de correção conhecidas, você pode processar a saída usando jq da seguinte forma:

pip-audit ... | jq ...```shell test -z "$(pip-audit -r requirements.txt --format=json 2>/dev/null | jq '.dependencies[].vulns[].fix_versions[]')"

which runs pip-audit as usual and exits with a non-zero code only if there are fixed versions for the known vulnerabilities.

que executa pip-audit como de costume e sai com um código diferente de zero apenas se há versões corrigidas para as vulnerabilidades conhecidas.

Security Model

Modelo de Segurança

This section exists to describe the security assumptions you can and must not make when using pip-audit.

Esta secção existe para descrever as suposições de segurança que pode e não deve fazer ao utilizar o pip-audit.

TL;DR: If you wouldn't pip install it, you should not pip audit it.

TL;DR: Se não faria pip install de algo, não deve fazer pip audit disso.

pip-audit is a tool for auditing Python environments for packages with known vulnerabilities. A "known vulnerability" is a publicly reported flaw in a package that, if uncorrected, might allow a malicious actor to perform unintended actions.

pip-audit é uma ferramenta para auditar ambientes Python em busca de pacotes com vulnerabilidades conhecidas. Uma "vulnerabilidade conhecida" é uma falha publicamente reportada num pacote que, se não corrigida, pode permitir que um ator malicioso realize ações indesejadas.

pip-audit can protect you against known vulnerabilities by telling you when you have them, and how you should upgrade them. For example, if you have somepackage==1.2.3 in your environment, pip-audit can tell you that it needs to be upgraded to 1.2.4.

pip-audit pode protegê-lo contra vulnerabilidades conhecidas ao informá-lo quando as tem e como deve atualizá-las. Por exemplo, se tiver somepackage==1.2.3 no seu ambiente, pip-audit pode dizer-lhe que precisa de ser atualizado para 1.2.4.

You can assume that pip-audit will make a best effort to fully resolve all of your Python dependencies and either fully audit each or explicitly state which ones it has skipped, as well as why it has skipped them.

Pode assumir que o pip-audit fará o melhor esforço para resolver completamente todas as suas dependências Python e ou auditar cada uma completamente ou indicar explicitamente quais as que foram ignoradas, bem como o motivo pelo qual foram ignoradas.

pip-audit is not a static code analyzer. It analyzes dependency trees, not code, and it cannot guarantee that arbitrary dependency resolutions occur statically. To understand why this is, refer to Dustin Ingram's excellent post on dependency resolution in Python.

pip-audit não é um analisador de código estático. Analisa árvores de dependências, não código, e não pode garantir que resoluções arbitrárias de dependências ocorram estaticamente. Para entender porquê, consulte o excelente post de Dustin Ingram sobre resolução de dependências em Python.

As such: you must not assume that pip-audit will defend you against malicious packages. In particular, it is incorrect to treat pip-audit -r INPUT as a "more secure" variant of pip-audit. For all intents and purposes, pip-audit -r INPUT is functionally equivalent to pip install -r INPUT, with a small amount of non-security isolation to avoid conflicts with any of your local environments.

Portanto: não deve assumir que o pip-audit o defenderá contra pacotes maliciosos. Em particular, é incorreto tratar pip-audit -r INPUT como uma variante "mais segura" do pip-audit. Para todos os efeitos, pip-audit -r INPUT é funcionalmente equivalente a pip install -r INPUT, com uma pequena quantidade de isolamento não relacionado à segurança para evitar conflitos com qualquer um dos seus ambientes locais.

pip-audit is first and foremost an auditing tool for Python packages. You must not assume that pip-audit will detect or flag "transitive" vulnerabilities that might be exposed through Python packages, but are not actually part of the package itself. For example, pip-audit's vulnerability information sources are unlikely to include an advisory for a vulnerable shared library that a popular Python package might use, since the Python package's version is not strongly connected to the shared library's version.

O pip-audit é, antes de mais, uma ferramenta de auditoria para pacotes Python. Não deve assumir que o pip-audit irá detetar ou sinalizar vulnerabilidades "transitivas" que possam ser expostas através de pacotes Python, mas que não fazem parte do pacote em si. Por exemplo, as fontes de informação de vulnerabilidades do pip-audit provavelmente não incluirão um aviso para uma biblioteca partilhada vulnerável que um pacote Python popular possa usar, uma vez que a versão do pacote Python não está fortemente ligada à versão da biblioteca partilhada.

Licensing

Licenciamento

pip-audit is licensed under the Apache 2.0 License.

pip-audit está licenciado sob a Licença Apache 2.0.

pip-audit reuses and modifies examples from resolvelib, which is licensed under the ISC license.

O pip-audit reutiliza e modifica exemplos do resolvelib, que está licenciado sob a licença ISC.

Contributing

Contribuição

See the contributing docs for details.

Consulte a documentação de contribuição para mais detalhes.

Code of Conduct

Código de Conduta

Everyone interacting with this project is expected to follow the PSF Code of Conduct.

Espera-se que todos que interagem com este projeto sigam o Código de Conduta da PSF.