0
# pip-audit
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: pip-audit
7
- **Language**: Python
8
- **Installation**: `pip install pip-audit`
9

10
## Core Imports
11

12
```python
13
import pip_audit
14
```
15

16
For programmatic API usage:
17

18
```python
19
from pip_audit._audit import Auditor, AuditOptions
20
from pip_audit._dependency_source import PipSource, RequirementSource, PyProjectSource
21
from pip_audit._service import PyPIService, OsvService
22
from pip_audit._format import JsonFormat, ColumnsFormat, MarkdownFormat
23
```
24

25
## Basic Usage
26

27
### Command Line Interface
28

29
```bash
30
# Audit current environment
31
pip-audit
32

33
# Audit a requirements file
34
pip-audit -r requirements.txt
35

36
# Fix vulnerable packages automatically
37
pip-audit --fix
38

39
# Output in JSON format
40
pip-audit --format=json
41

42
# Use specific vulnerability service
43
pip-audit --vulnerability-service=osv
44
```
45

46
### Programmatic API
47

48
```python
49
from pip_audit._audit import Auditor, AuditOptions
50
from pip_audit._dependency_source import PipSource
51
from pip_audit._service import PyPIService
52

53
# Create a vulnerability service
54
service = PyPIService()
55

56
# Create an auditor
57
auditor = Auditor(service=service)
58

59
# Create a dependency source
60
source = PipSource()
61

62
# Perform the audit
63
for dependency, vulnerabilities in auditor.audit(source):
64
    if vulnerabilities:
65
        print(f"{dependency.name}: {len(vulnerabilities)} vulnerabilities found")
66
```
67

68
## Architecture
69

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

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

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

80
## Capabilities
81

82
### Core Auditing API
83

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

86
```python { .api }
87
class Auditor:
88
    def __init__(self, service: VulnerabilityService, options: AuditOptions = AuditOptions()): ...
89
    def audit(self, source: DependencySource) -> Iterator[tuple[Dependency, list[VulnerabilityResult]]]: ...
90

91
@dataclass(frozen=True)
92
class AuditOptions:
93
    dry_run: bool = False
94
```
95

96
[Core Auditing](./core-auditing.md)
97

98
### Dependency Sources
99

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

102
```python { .api }
103
class DependencySource(ABC):
104
    def collect(self) -> Iterator[Dependency]: ...
105
    def fix(self, fix_version: ResolvedFixVersion) -> None: ...
106

107
class PipSource(DependencySource): ...
108
class RequirementSource(DependencySource): ...
109
class PyProjectSource(DependencySource): ...
110
class PyLockSource(DependencySource): ...
111
```
112

113
[Dependency Sources](./dependency-sources.md)
114

115
### Vulnerability Services
116

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

119
```python { .api }
120
class VulnerabilityService(ABC):
121
    def query(self, spec: Dependency) -> tuple[Dependency, list[VulnerabilityResult]]: ...
122

123
class PyPIService(VulnerabilityService): ...
124
class OsvService(VulnerabilityService): ...
125
```
126

127
[Vulnerability Services](./vulnerability-services.md)
128

129
### Output Formats
130

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

133
```python { .api }
134
class VulnerabilityFormat(ABC):
135
    def format(self, iterator) -> str: ...
136

137
class ColumnsFormat(VulnerabilityFormat): ...
138
class JsonFormat(VulnerabilityFormat): ...
139
class MarkdownFormat(VulnerabilityFormat): ...
140
class CycloneDxFormat(VulnerabilityFormat): ...
141
```
142

143
[Output Formats](./output-formats.md)
144

145
### Data Models
146

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

149
```python { .api }
150
@dataclass(frozen=True)
151
class Dependency:
152
    name: str
153
    @property
154
    def canonical_name(self) -> str: ...
155
    def is_skipped(self) -> bool: ...
156

157
@dataclass(frozen=True)
158
class VulnerabilityResult:
159
    id: VulnerabilityID
160
    description: str
161
    fix_versions: list[Version]
162
    aliases: set[str]
163
```
164

165
[Data Models](./data-models.md)
166

167
### Fix Resolution
168

169
Functionality for resolving and applying fixes to vulnerable dependencies.
170

171
```python { .api }
172
@dataclass(frozen=True)
173
class FixVersion:
174
    dep: ResolvedDependency
175
    def is_skipped(self) -> bool: ...
176

177
def resolve_fix_versions(...) -> Iterator[FixVersion]: ...
178
```
179

180
[Fix Resolution](./fix-resolution.md)