contrast-vulnerability-metrics 0.1.0
A command-line tool for analyzing vulnerability metrics in Contrast Security applications.
Requires Python: >=3.8

# contrast-vulnerability-metrics
A command-line tool for analyzing vulnerability metrics and time-to-remediation in Contrast Security applications. This tool helps analyze vulnerability trends and remediation timelines across your application portfolio.

## Features
- Fast, asynchronous API querying with concurrent requests
- Configurable date ranges for analysis 
- Progress tracking for large datasets
- CSV export for detailed metrics
- Summary statistics by severity level
- Configurable batch size and concurrency
- Environment-based configuration
- Rich terminal output with color-coded results
- Enhanced error handling and retry logic

## Installation
1. Install:
```bash
pip install contrast-vulnerability-metrics
```

2. Create a `.env` file with your Contrast Security credentials:
```ini
CONTRAST_BASE_URL=https://app.contrastsecurity.com/Contrast
CONTRAST_ORG_UUID=your-org-uuid
CONTRAST_API_KEY=your-api-key 
CONTRAST_AUTH=your-auth-header
```

## Usage
Basic usage:
```bash
contrast-vulnerability-metrics analyze
```

With all options:
```bash
contrast-vulnerability-metrics analyze \
--csv output.csv \
--batch-size 200 \
--concurrent-requests 20 \
--use-closed-time \
--start-date 2024-01-01 \
--end-date 2024-03-31 \
--verbose
```

### Options
- `--csv`: Output file path for detailed CSV results
- `--batch-size`: Number of vulnerabilities to fetch per request (default: 100)
- `--concurrent-requests`: Maximum number of concurrent API requests (default: 10)
- `--use-closed-time/--use-last-seen`: Use closed_time instead of last_time_seen for remediation calculations (default: use closed time)
- `--start-date`: Start date for filtering (YYYY-MM-DD format)
- `--end-date`: End date for filtering (YYYY-MM-DD format) 
- `--days-back`: Number of days back from today to include
- `--verbose`: Enable verbose logging

## Output
The tool provides a summary of vulnerability metrics including average and median time-to-remediation by severity level:

Example output:
```
                 Vulnerability Metrics Summary                 
╭──────────┬────────────────────┬─────────────────────┬───────╮
│          │  Avg Time to Close │      Median Time to │       │
│ Severity │             (Days) │        Close (Days) │ Count │
├──────────┼────────────────────┼─────────────────────┼───────┤
│ CRITICAL │                658 │                 656 │     4 │
│ HIGH     │                158 │                 158 │     1 │
│ MEDIUM   │               1635 │                1635 │     1 │
│ OVERALL  │                737 │                 656 │     6 │
╰──────────┴────────────────────┴─────────────────────┴───────╯
```

## CSV Output Format
The CSV output includes two sections:
1. Summary statistics by severity
2. Detailed vulnerability metrics including:
   - UUID
   - Severity  
   - First Seen
   - Last Seen
   - Closed Time
   - Days to Last Seen
   - Days to Remediation

## Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| CONTRAST_BASE_URL | Contrast Security API URL | https://app.contrastsecurity.com/Contrast |
| CONTRAST_ORG_UUID | Organization UUID | 12345678-90ab-cdef-1234-567890abcdef |
| CONTRAST_API_KEY | API Key | your-api-key |
| CONTRAST_AUTH | Authorization header | base64-encoded-credentials |

## Development
Requirements:
- Python 3.8+
- httpx
- typer
- rich
- python-dotenv
- tqdm

## License
MIT License

## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run the tests
5. Submit a pull request

## Support
For issues, questions, or contributions, please open an issue in the GitHub repository.