xyz-vulnerability-scanner 1.0.1
Professional vulnerability scanner CLI tool
Requires Python: >=3.8
Keywords: vulnerability scanner, security, CVE, GHSA, OSV

# XYZ CLI - API-based Vulnerability Scanner

A modern, API-based command-line interface for the XYZ Vulnerability Database. This tool provides the same functionality as the original direct-database CLI but connects to the XYZ API Backend for secure, rate-limited access.

## Features

- 🔍 **Vulnerability Search**: Search by CVE, GHSA, OSV, and other vulnerability IDs
- 📦 **Package Scanning**: Find vulnerabilities affecting specific packages
- 🖥️ **System Scanning**: Scan installed Python and npm packages
- 🛡️ **Exploit Information**: Access detailed exploit data with `-x` flag
- 🎨 **Rich Output**: Beautiful, color-coded terminal output
- 📊 **Statistics**: Database and ecosystem statistics
- 🌐 **API-based**: Secure remote access to vulnerability data

## 🚀 **Quick Installation**

### **Option 1: Install from PyPI (Recommended)**
```bash
# Install globally
pip install xyz-vulnerability-scanner

# Start scanning immediately
xyz scan --python
xyz vuln CVE-2021-44228
```

### **Option 2: Using uv (Modern Package Manager)**
```bash
# Install with uv
uv add xyz-vulnerability-scanner

# Run with uv
uv run xyz scan --python
```

### **Option 3: Development Install**
```bash
git clone https://github.com/xyz-security/xyz-platform.git
cd xyz-platform/clients/xyz-cli
pip install -e .
```

## 🔑 **Getting Started**

### **1. Get Your API Key**
- **Free Tier**: Register at [xyz-security.com](https://xyz-security.com)
- **Pro/Enterprise**: Contact [sales@xyz-security.com](mailto:sales@xyz-security.com)

### **2. Configure Authentication**
```bash
# Set environment variables (recommended)
export XYZ_API_KEY="sk_xyz_your_key_here"
export XYZ_API_URL="https://api.xyz-security.com"

# Or use command-line options
xyz --api-key sk_xyz_your_key_here vuln CVE-2021-44228
```

### **3. Verify Installation**
```bash
# Check API connectivity
xyz info

# View your usage stats
xyz stats
```

## 💻 **Usage Examples**

### **🔍 Vulnerability Search**
```bash
# Search by CVE ID
xyz vuln CVE-2021-44228

# Search by GHSA ID
xyz vuln GHSA-jfh8-c2jp-5v3q

# Search by OSV ID  
xyz vuln OSV-2021-1234

# Include exploit information
xyz vuln CVE-2021-44228 --exploits
```

### **📦 Package Vulnerability Search**
```bash
# Search for package vulnerabilities
xyz package log4j
xyz package express --ecosystem npm
xyz package django --ecosystem pypi

# Get affected versions
xyz package log4j --affected
```

### **🛡️ System Scanning**
```bash
# Scan Python packages
xyz scan --python

# Scan npm packages
xyz scan --npm

# Scan all package types
xyz scan --all

# Include exploit information
xyz scan --python --exploits
```

### **📊 JSON Output for Automation**
```bash
# Machine-readable output
xyz vuln CVE-2021-44228 --json
xyz scan --python --json | jq '.vulnerabilities'
```

## 🎯 **Features**

| Feature | Free Tier | Pro Tier | Enterprise |
|---------|-----------|----------|-----------|
| **Vulnerability Search** | ✅ | ✅ | ✅ |
| **Package Scanning** | ✅ | ✅ | ✅ |
| **System Scanning** | ✅ | ✅ | ✅ |
| **Exploit Information** | ❌ | ✅ | ✅ |
| **API Rate Limit** | 100/hour | 1,000/hour | 10,000/hour |
| **Export Formats** | JSON | JSON, CSV | JSON, CSV, SARIF |
| **Priority Support** | ❌ | ✅ | ✅ |

## 🔧 **Advanced Configuration**

### **Environment Variables**
```bash
# API Configuration
XYZ_API_KEY=sk_xyz_your_key_here
XYZ_API_URL=https://api.xyz-security.com

# Output Preferences
XYZ_OUTPUT_FORMAT=json          # json, table
XYZ_COLOR_OUTPUT=true           # true, false
XYZ_DEBUG=false                 # true, false
Show API capabilities, supported formats, and rate limits.

```bash
./xyz.py info
```

### `vuln` - Vulnerability Search

Search for a specific vulnerability by ID.

```bash
./xyz.py vuln <VULNERABILITY_ID> [OPTIONS]

Options:
  -x, --exploits    Include exploit information
  --json           Output as JSON
```

Examples:
```bash
./xyz.py vuln CVE-2021-44228
./xyz.py vuln GHSA-jfh8-c2jp-5v3q -x
./xyz.py vuln PYSEC-2021-385 --json
```

### `package` - Package Vulnerability Search

Search for vulnerabilities affecting a specific package.

```bash
./xyz.py package <PACKAGE_NAME> [OPTIONS]

Options:
  -e, --ecosystem TEXT  Filter by ecosystem (npm, pypi, maven, etc.)
  -s, --severity TEXT   Filter by severity (critical, high, medium, low)
  -x, --exploits        Include exploit information
  --limit INTEGER       Maximum results to return (default: 50)
  --json               Output as JSON
```

Examples:
```bash
./xyz.py package log4j
./xyz.py package axios -e npm
./xyz.py package django -s critical -x
./xyz.py package react --limit 20 --json
```

### `scan` - System Package Scanning

Scan installed packages for vulnerabilities.

```bash
./xyz.py scan [OPTIONS]

Options:
  --python         Scan Python packages only
  --npm           Scan npm packages only
  -x, --exploits  Include exploit information
  --json          Output as JSON
```

Examples:
```bash
./xyz.py scan                    # Scan both Python and npm
./xyz.py scan --python          # Python packages only
./xyz.py scan --npm -x          # npm packages with exploits
./xyz.py scan --json            # JSON output
```

### `recent` - Recent Vulnerabilities

Show recently published vulnerabilities.

```bash
./xyz.py recent [OPTIONS]

Options:
  --days INTEGER    Number of days to look back (default: 7)
  --limit INTEGER   Maximum results to return (default: 20)
  -x, --exploits    Include exploit information
  --json           Output as JSON
```

Examples:
```bash
./xyz.py recent                  # Last 7 days
./xyz.py recent --days 30       # Last 30 days
./xyz.py recent --limit 5 -x    # Top 5 with exploits
```

### `stats` - Database Statistics

Show database and ecosystem statistics.

```bash
./xyz.py stats
```

## Feature Comparison

| Feature | Legacy CLI | API CLI | Notes |
|---------|------------|---------|-------|
| Vulnerability search by ID | ✅ | ✅ | Full compatibility |
| Package vulnerability search | ✅ | ✅ | Full compatibility |
| System package scanning | ✅ | ✅ | Python and npm supported |
| Exploit information | ✅ | ✅ | With `-x` flag |
| Malicious package detection | ✅ | ✅ | Automatic detection |
| Multiple output formats | ✅ | ✅ | Table and JSON |
| Ecosystem filtering | ✅ | ✅ | All ecosystems supported |
| Severity filtering | ✅ | ✅ | All severity levels |
| Statistics | ✅ | ✅ | Enhanced with API data |
| Rate limiting | ❌ | ✅ | API-based limits |
| Authentication | ❌ | ✅ | API key required |
| Remote access | ❌ | ✅ | API-based |
| Audit logging | ❌ | ✅ | Full request logging |

## Output Examples

### Vulnerability Search

```bash
$ ./xyz.py vuln CVE-2021-44228 -x

                                  Vulnerability Results
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID              ┃ Package          ┃ Ecosystem  ┃ Severity   ┃ CVSS    ┃ Status                   ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ CVE-2021-44228  │ log4j-core       │ maven      │ CRITICAL   │ 10.0    │ HAS EXPLOIT              │
└─────────────────┴──────────────────┴────────────┴────────────┴─────────┴──────────────────────────┘

Vulnerability Details: CVE-2021-44228
┏━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Field       ┃ Value                                                                                    ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Package     │ log4j-core                                                                               │
│ Ecosystem   │ maven                                                                                    │
│ Severity    │ CRITICAL                                                                                 │
│ CVSS Score  │ 10.0                                                                                     │
│ Description │ Apache Log4j2 2.0-beta9 through 2.15.0 (excluding security releases 2.12.2, 2.12.3, │
│             │ and 2.3.1) JNDI features used in configuration, log messages, and parameters do not... │
└─────────────┴──────────────────────────────────────────────────────────────────────────────────────┘

🔓 EXPLOIT INFORMATION
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Author                  ┃ Type             ┃ Platform                 ┃ Verified     ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ multiple                │ remote           │ linux                    │ ✅           │
│ exploit-db              │ poc              │ multiple                 │ ✅           │
└─────────────────────────┴──────────────────┴──────────────────────────┴──────────────┘
```

### Package Scanning

```bash
$ ./xyz.py package log4j

Scan Results for 'log4j'
Packages found: 3
Total vulnerabilities: 28

📦 apache:log4j (maven)
Vulnerabilities: 15
Severity breakdown:
  • critical: 8
  • high: 4
  • medium: 3

                                  Vulnerability Results
┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ ID              ┃ Package          ┃ Ecosystem  ┃ Severity   ┃ CVSS    ┃ Status                   ┃
┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ CVE-2021-44228  │ apache:log4j     │ maven      │ CRITICAL   │ 10.0    │ HAS EXPLOIT              │
│ CVE-2021-45046  │ apache:log4j     │ maven      │ CRITICAL   │ 9.0     │ HAS EXPLOIT              │
│ CVE-2021-45105  │ apache:log4j     │ maven      │ HIGH       │ 7.5     │ Clean                    │
└─────────────────┴──────────────────┴────────────┴────────────┴─────────┴──────────────────────────┘
```

## Error Handling

The CLI provides clear error messages for common issues:

```bash
# Missing API key
$ ./xyz.py info
Error: API key is required. Set XYZ_API_KEY environment variable or pass api_key parameter.

Setup Instructions:
1. Set your API key: export XYZ_API_KEY=sk_xyz_your_key_here
2. Set API URL (optional): export XYZ_API_URL=https://api.xyz-security.com
3. Contact admin@xyz-security.com for API key access

# Rate limit exceeded
$ ./xyz.py scan
Error: Rate limit exceeded: Limit: 100 requests per hour.

# Permission denied
$ ./xyz.py vuln CVE-2021-44228 -x
Error: Permission denied: Permission required: read:exploits
```

## Troubleshooting

### Common Issues

1. **API Key Issues**:
   ```bash
   # Check if API key is set
   echo $XYZ_API_KEY
   
   # Test API connection
   ./xyz.py info
   ```

2. **Connection Issues**:
   ```bash
   # Check API server status
   curl http://localhost:8000/health
   
   # Try with debug mode
   ./xyz.py --debug info
   ```

3. **Permission Issues**:
   - Contact your administrator to add required permissions
   - Check your user tier and upgrade if needed

### Debug Mode

Enable debug mode for detailed information:

```bash
./xyz.py --debug <command>
```

## Migration from Legacy CLI

If you're migrating from the direct-database CLI:

1. **Set up API access**:
   - Get an API key from your administrator
   - Set the `XYZ_API_KEY` environment variable

2. **Update scripts**:
   - Replace `./xyz scan -p package` with `./xyz.py package package`
   - Replace `./xyz scan -v CVE-ID` with `./xyz.py vuln CVE-ID`
   - Add `-x` flag for exploit information

3. **New features**:
   - Use `./xyz.py info` to see API capabilities
   - Use `./xyz.py recent` for recent vulnerabilities
   - Use `./xyz.py stats` for comprehensive statistics

## Support

- **Documentation**: API docs at your server's `/docs` endpoint
- **Issues**: Contact your API administrator
- **Rate Limits**: Check your tier and usage with your administrator