runZero API Client

A Python script to pull findings and vulnerabilities data from the runZero API and aggregate them by severity.

Features

• Pull findings data from runZero
• Pull vulnerabilities data from runZero
• Aggregate totals by severity level (Critical, High, Medium, Low, Info)
• Support for both API token and OAuth2 authentication
• Filter results with search queries
• Export data to JSON format
• Clean, formatted console output

Prerequisites

• Python 3.6 or higher
• runZero account with API access
• API token or OAuth2 credentials

Installation

1. Install dependencies:

pip install -r requirements.txt

2. Configure authentication (choose one method):

Method 1: Environment Variables (Recommended)

cp .env.example .env
# Edit .env and add your API token
export $(cat .env | xargs)

Method 2: Command Line Arguments See usage examples below.

Getting Your API Token

1. Log in to your runZero account at https://console.runzero.com
2. Navigate to Account Settings → API Clients or Export API
3. Create a new export token or API client
4. Copy the token/credentials

Usage

Basic Usage

# Using environment variable
export RUNZERO_API_TOKEN="your-token-here"
python runzero_api_client.py

Command Line Authentication

# Using API token
python runzero_api_client.py --api-token "your-token-here"

# Using OAuth2 credentials
python runzero_api_client.py --client-id "your-client-id" --client-secret "your-client-secret"

Advanced Usage

# Filter findings by severity
python runzero_api_client.py --search-findings "severity:critical"

# Filter vulnerabilities by severity
python runzero_api_client.py --search-vulns "severity:high OR severity:critical"

# Export results to JSON file
python runzero_api_client.py --output results.json

# Quiet mode (only save to file, no console output)
python runzero_api_client.py --output results.json --quiet

Search Query Examples

The --search-findings and --search-vulns parameters support runZero's query syntax:

# Only critical findings
--search-findings "severity:critical"

# Critical and high severity
--search-findings "severity:critical OR severity:high"

# Findings on specific hardware
--search-findings "hw:Cisco AND severity:critical"

# Combine multiple filters
--search-vulns "severity:high AND NOT status:resolved"

Output

The script provides:

1. Console Output: Formatted summary of findings and vulnerabilities by severity

FINDINGS BY SEVERITY
==================================================
Critical    : 45
High        : 123
Medium      : 567
Low         : 234
--------------------------------------------------
Total       : 969

VULNERABILITIES BY SEVERITY
==================================================
Critical    : 12
High        : 89
Medium      : 456
Low         : 789
--------------------------------------------------
Total       : 1,346

2. JSON Output (when using --output): Complete data including raw findings and vulnerabilities

API Endpoints Used

• GET /export/org/findings.jsonl - Export findings in JSONL format
• GET /export/org/vulnerabilities.json - Export vulnerabilities in JSON format

Documentation

• runZero API Documentation
• Understanding Findings
• Exposure Management

Troubleshooting

Authentication Errors

• Verify your API token is valid and not expired
• Ensure you have the correct permissions for the export API
• Check that you're using the correct authentication method

Rate Limiting

If you encounter rate limiting errors, the runZero API may have usage limits. Consider:

• Spacing out your requests
• Using search filters to reduce data volume
• Contacting runZero support for rate limit information

Connection Issues

• Verify you can reach console.runzero.com
• Check firewall and proxy settings
• Ensure you have internet connectivity

License

This script is provided as-is for use with runZero API.