0
# Core Auditing
1

2
The main auditing functionality that coordinates dependency collection and vulnerability scanning. This provides the primary entry point for programmatic usage of pip-audit.
3

4
## Capabilities
5

6
### Auditor Class
7

8
The central coordinator that orchestrates the audit process by combining a dependency source with a vulnerability service.
9

10
```python { .api }
11
class Auditor:
12
    """
13
    The core class of the pip-audit API.
14
    
15
    For a given dependency source and vulnerability service, supply a mapping of dependencies to
16
    known vulnerabilities.
17
    """
18
    
19
    def __init__(
20
        self,
21
        service: VulnerabilityService,
22
        options: AuditOptions = AuditOptions(),
23
    ):
24
        """
25
        Create a new auditor.
26
        
27
        Parameters:
28
        - service: VulnerabilityService, the service to query for vulnerabilities
29
        - options: AuditOptions, configuration options for the audit
30
        """
31

32
    def audit(
33
        self, source: DependencySource
34
    ) -> Iterator[tuple[Dependency, list[VulnerabilityResult]]]:
35
        """
36
        Perform an audit of the given dependency source.
37
        
38
        Parameters:
39
        - source: DependencySource, the source of dependencies to audit
40
        
41
        Returns:
42
        Iterator yielding (dependency, vulnerabilities) tuples
43
        """
44
```
45

46
### Audit Options
47

48
Configuration options that control the behavior of an Auditor instance.
49

50
```python { .api }
51
@dataclass(frozen=True)
52
class AuditOptions:
53
    """
54
    Settings that control the behavior of an Auditor instance.
55
    """
56
    
57
    dry_run: bool = False
58
    """
59
    Whether to perform a dry run (no actual fixes applied).
60
    """
61
```
62

63
## Usage Examples
64

65
### Basic Audit
66

67
```python
68
from pip_audit._audit import Auditor, AuditOptions
69
from pip_audit._dependency_source import PipSource
70
from pip_audit._service import PyPIService
71

72
# Create components
73
service = PyPIService()
74
source = PipSource()
75
auditor = Auditor(service=service)
76

77
# Perform audit
78
results = list(auditor.audit(source))
79
for dependency, vulnerabilities in results:
80
    if vulnerabilities:
81
        print(f"{dependency.name} v{dependency.version}: {len(vulnerabilities)} vulnerabilities")
82
        for vuln in vulnerabilities:
83
            print(f"  - {vuln.id}: {vuln.description}")
84
```
85

86
### Audit with Options
87

88
```python
89
from pip_audit._audit import Auditor, AuditOptions
90
from pip_audit._dependency_source import RequirementSource
91
from pip_audit._service import OsvService
92

93
# Create with options
94
options = AuditOptions(dry_run=True)
95
service = OsvService()
96
source = RequirementSource("requirements.txt")
97
auditor = Auditor(service=service, options=options)
98

99
# Perform dry run audit
100
for dependency, vulnerabilities in auditor.audit(source):
101
    if vulnerabilities:
102
        print(f"Would fix {dependency.name}: {len(vulnerabilities)} issues")
103
```