0
# Safety CLI
1

2
Safety CLI is a comprehensive vulnerability scanning tool for Python dependencies that helps developers identify and fix security vulnerabilities in their projects. It scans Python packages for known security vulnerabilities, licenses issues, and provides automated fixes.
3

4
## Installation
5

6
```bash
7
pip install safety
8
```
9

10
## Package Information
11

12
- **Package Name**: `safety`
13
- **Version**: `3.6.1`
14
- **Entry Point**: `safety.cli:cli`
15
- **Python Support**: 3.8+
16
- **Homepage**: [https://safetycli.com](https://safetycli.com)
17
- **Documentation**: [https://docs.safetycli.com/safety-docs](https://docs.safetycli.com/safety-docs)
18

19
## Basic Usage
20

21
### CLI Interface
22

23
```bash
24
# Scan current project for vulnerabilities
25
safety scan
26

27
# Legacy check command (deprecated but still available)
28
safety check
29

30
# Check for license issues
31
safety license
32

33
# Authenticate with Safety platform
34
safety auth login
35

36
# Get help
37
safety --help
38
```
39

40
### Programmatic Access
41

42
```python
43
# Import the main CLI function
44
from safety.cli import cli
45

46
# Import core models and utilities
47
from safety.models import (
48
    Vulnerability, CVE, Severity, Fix, 
49
    SafetyRequirement, Package, RequirementFile
50
)
51

52
# Import scanning functionality
53
from safety.scan.main import process_files
54
from safety.scan.finder import FileFinder
55

56
# Import formatters
57
from safety.formatters.json import JsonReport
58
from safety.formatters.text import TextReport
59
```
60

61
## Core Capabilities
62

63
### Vulnerability Scanning { .api }
64

65
Safety provides comprehensive vulnerability scanning capabilities for Python projects:
66

67
- **Project Scanning**: Scan entire Python projects for vulnerabilities
68
- **System Scanning**: Scan system-wide Python packages
69
- **Dependency Analysis**: Deep analysis of direct and transitive dependencies
70
- **License Checking**: Identify license compliance issues
71
- **Policy Enforcement**: Apply organizational security policies
72

73
**Primary Scanning Commands:**
74

75
```bash
76
safety scan [OPTIONS] [TARGET]      # Scan project dependencies
77
safety system-scan [OPTIONS]       # Scan system packages  
78
safety check [OPTIONS] [FILES]     # Legacy vulnerability check
79
safety license [OPTIONS] [FILES]   # License compliance check
80
```
81

82
### Authentication and Configuration { .api }
83

84
Safety integrates with the Safety platform for enhanced vulnerability data and organizational features:
85

86
- **Authentication**: OAuth-based authentication with Safety platform
87
- **Organization Management**: Multi-organization support
88
- **Policy Management**: Centralized security policies
89
- **API Access**: Programmatic access to Safety services
90

91
**Authentication Commands:**
92

93
```bash
94
safety auth login              # Authenticate with Safety platform
95
safety auth logout             # Sign out
96
safety auth status             # Check authentication status
97
safety auth register          # Register new account
98
```
99

100
### Output and Reporting { .api }
101

102
Multiple output formats and reporting options:
103

104
- **Interactive Console**: Rich terminal output with colors and formatting
105
- **JSON Output**: Machine-readable structured data
106
- **Text Reports**: Plain text vulnerability reports
107
- **HTML Reports**: Web-viewable vulnerability reports
108
- **Custom Formatting**: Extensible formatter system
109

110
**Output Format Options:**
111

112
```bash
113
--output json                  # JSON format
114
--output text                  # Plain text
115
--output html                  # HTML report
116
--save-as FILE                # Save report to file
117
```
118

119
### Advanced Features { .api }
120

121
- **Auto-remediation**: Automatic vulnerability fixes
122
- **Policy as Code**: YAML-based security policies
123
- **CI/CD Integration**: GitHub Actions and GitLab CI support
124
- **Proxy Support**: Corporate proxy configuration
125
- **Telemetry**: Optional usage analytics
126
- **Tool Integration**: Extensible tool ecosystem
127

128
## Sub-Documentation
129

130
- [CLI Commands Reference](./cli-commands.md) - Complete command-line interface documentation
131
- [Scanning and Analysis](./scanning.md) - Vulnerability scanning and analysis features  
132
- [Authentication System](./authentication.md) - Authentication and platform integration
133
- [Output and Formatters](./formatters.md) - Report generation and output formatting
134
- [Data Models](./models.md) - Core data structures and types
135
- [Configuration and Policies](./configuration.md) - Policy management and configuration
136
- [Error Handling](./errors.md) - Exception classes and error management
137
- [Programmatic API](./programmatic.md) - Python API for automation
138

139
## Key Types and Models
140

141
### Vulnerability Data { .api }
142

143
```python
144
from safety.models import Vulnerability, CVE, Severity
145

146
# Core vulnerability information
147
class Vulnerability:
148
    vulnerability_id: str
149
    package_name: str
150
    vulnerable_spec: str
151
    advisory: str
152
    published_date: datetime
153
    fixed_versions: List[str]
154
    CVE: CVE
155
    severity: Severity
156

157
# CVE information  
158
class CVE:
159
    name: str
160
    cvssv2: Optional[float]
161
    cvssv3: Optional[float]
162

163
# Severity assessment
164
class Severity:
165
    source: str
166
    cvssv2: Optional[float] 
167
    cvssv3: Optional[float]
168
```
169

170
### Package Information { .api }
171

172
```python
173
from safety.models import Package, SafetyRequirement
174

175
# Package metadata
176
class Package:
177
    name: str
178
    version: str
179
    requirements: List[SafetyRequirement]
180

181
# Enhanced requirement with safety features
182
class SafetyRequirement(Requirement):
183
    raw: str                    # Original requirement line
184
    found: Optional[str]        # Where requirement was found
185
    
186
    def to_dict(self) -> Dict   # Convert to dictionary
187
```
188

189
### Configuration Models { .api }
190

191
```python
192
from safety_schemas.models import ConfigModel, Ecosystem, Stage
193

194
# Main configuration
195
class ConfigModel:
196
    telemetry_enabled: bool
197
    
198
# Supported ecosystems
199
class Ecosystem(Enum):
200
    PYTHON = "python"
201
    
202
# Development stages  
203
class Stage(Enum):
204
    DEVELOPMENT = "development"
205
    PRODUCTION = "production"
206
```
207

208
## Quick Examples
209

210
### Basic Vulnerability Scan
211

212
```bash
213
# Scan current directory
214
safety scan
215

216
# Scan specific path
217
safety scan /path/to/project
218

219
# Scan with JSON output
220
safety scan --output json
221
```
222

223
### Authentication Workflow
224

225
```bash
226
# Login to Safety platform
227
safety auth login
228

229
# Check authentication status
230
safety auth status
231

232
# Scan with authenticated access
233
safety scan
234
```
235

236
### Policy Enforcement
237

238
```bash
239
# Generate policy template
240
safety generate policy
241

242
# Scan with policy file
243
safety scan --policy-file .safety-policy.yml
244

245
# Generate installation policy
246
safety generate installation_policy
247
```
248

249
### License Compliance
250

251
```bash
252
# Check licenses in requirements file
253
safety license --files requirements.txt
254

255
# Check with custom database
256
safety license --db /path/to/license_db
257
```
258

259
This documentation provides comprehensive coverage of Safety CLI's public API for developers who need to integrate vulnerability scanning into their workflows, whether through command-line usage or programmatic access.