or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

core-auditing.mddata-models.mddependency-sources.mdfix-resolution.mdindex.mdoutput-formats.mdvulnerability-services.md
tile.json

tessl/pypi-pip-audit

A tool for scanning Python environments for known vulnerabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pip-audit@2.9.x

To install, run

npx @tessl/cli install tessl/pypi-pip-audit@2.9.0

index.mddocs/

pip-audit

A comprehensive Python security tool for scanning Python environments and identifying packages with known vulnerabilities. pip-audit leverages the Python Packaging Advisory Database and PyPI JSON API to provide real-time vulnerability detection across local environments, requirements files, and installed packages.

Package Information

  • Package Name: pip-audit
  • Language: Python
  • Installation: pip install pip-audit

Core Imports

import pip_audit

For programmatic API usage:

from pip_audit._audit import Auditor, AuditOptions
from pip_audit._dependency_source import PipSource, RequirementSource, PyProjectSource
from pip_audit._service import PyPIService, OsvService
from pip_audit._format import JsonFormat, ColumnsFormat, MarkdownFormat

Basic Usage

Command Line Interface

# Audit current environment
pip-audit

# Audit a requirements file
pip-audit -r requirements.txt

# Fix vulnerable packages automatically
pip-audit --fix

# Output in JSON format
pip-audit --format=json

# Use specific vulnerability service
pip-audit --vulnerability-service=osv

Programmatic API

from pip_audit._audit import Auditor, AuditOptions
from pip_audit._dependency_source import PipSource
from pip_audit._service import PyPIService

# Create a vulnerability service
service = PyPIService()

# Create an auditor
auditor = Auditor(service=service)

# Create a dependency source
source = PipSource()

# Perform the audit
for dependency, vulnerabilities in auditor.audit(source):
    if vulnerabilities:
        print(f"{dependency.name}: {len(vulnerabilities)} vulnerabilities found")

Architecture

pip-audit follows a plugin-based architecture with abstract interfaces and concrete implementations:

  • Auditor: Core orchestrator that coordinates dependency collection and vulnerability checking
  • Dependency Sources: Various sources of Python dependencies (pip environment, requirements files, pyproject.toml)
  • Vulnerability Services: Services that provide vulnerability information (PyPI, OSV)
  • Output Formats: Different ways to display audit results (columns, JSON, markdown, CycloneDX SBOM)
  • State Management: Progress tracking and user feedback mechanisms

This design allows pip-audit to be extended with new dependency sources, vulnerability services, and output formats while maintaining a consistent API.

Capabilities

Core Auditing API

The main auditing functionality that coordinates dependency collection and vulnerability scanning. Provides the primary entry point for programmatic usage.

class Auditor:
    def __init__(self, service: VulnerabilityService, options: AuditOptions = AuditOptions()): ...
    def audit(self, source: DependencySource) -> Iterator[tuple[Dependency, list[VulnerabilityResult]]]: ...

@dataclass(frozen=True)
class AuditOptions:
    dry_run: bool = False

Core Auditing

Dependency Sources

Various sources of Python dependencies including pip environments, requirements files, pyproject.toml files, and lock files.

class DependencySource(ABC):
    def collect(self) -> Iterator[Dependency]: ...
    def fix(self, fix_version: ResolvedFixVersion) -> None: ...

class PipSource(DependencySource): ...
class RequirementSource(DependencySource): ...
class PyProjectSource(DependencySource): ...
class PyLockSource(DependencySource): ...

Dependency Sources

Vulnerability Services

Services that provide vulnerability information for Python packages, supporting multiple backends.

class VulnerabilityService(ABC):
    def query(self, spec: Dependency) -> tuple[Dependency, list[VulnerabilityResult]]: ...

class PyPIService(VulnerabilityService): ...
class OsvService(VulnerabilityService): ...

Vulnerability Services

Output Formats

Different ways to format and display audit results, from human-readable to machine-parseable formats.

class VulnerabilityFormat(ABC):
    def format(self, iterator) -> str: ...

class ColumnsFormat(VulnerabilityFormat): ...
class JsonFormat(VulnerabilityFormat): ...
class MarkdownFormat(VulnerabilityFormat): ...
class CycloneDxFormat(VulnerabilityFormat): ...

Output Formats

Data Models

Core data structures representing dependencies, vulnerabilities, and fix information.

@dataclass(frozen=True)
class Dependency:
    name: str
    @property
    def canonical_name(self) -> str: ...
    def is_skipped(self) -> bool: ...

@dataclass(frozen=True)
class VulnerabilityResult:
    id: VulnerabilityID
    description: str
    fix_versions: list[Version]
    aliases: set[str]

Data Models

Fix Resolution

Functionality for resolving and applying fixes to vulnerable dependencies.

@dataclass(frozen=True)
class FixVersion:
    dep: ResolvedDependency
    def is_skipped(self) -> bool: ...

def resolve_fix_versions(...) -> Iterator[FixVersion]: ...

Fix Resolution