Metadata-Version: 2.4
Name: riskscore-api
Version: 0.1.1
Summary: Python SDK for the RiskScore CVE API (api.riskscore.dev)
License: MIT
Project-URL: Homepage, https://api.riskscore.dev
Project-URL: Documentation, https://api.riskscore.dev/docs
Project-URL: Repository, https://github.com/riskscore/python-sdk
Keywords: cve,security,vulnerability,riskscore,nvd,kev
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# riskscore — Python SDK

Python client for the [RiskScore API](https://api.riskscore.dev) — composite CVE risk scores combining CVSS, EPSS, and CISA KEV into a single 0–100 signal.

**Free tier: 100 requests/day. No credit card required.**

## Installation

```bash
pip install riskscore
```

## First API Call (under 10 lines)

```python
from riskscore import RiskScoreClient

client = RiskScoreClient(api_key="YOUR_API_KEY")
result = client.get_cve("CVE-2021-44228")
print(result["cve_id"], result["risk_score"]["score"], result["risk_score"]["severity_label"])
# CVE-2021-44228 100 CRITICAL
```

Get your free API key at [riskscore.dev](https://riskscore.dev) — no credit card, takes 30 seconds.

## Usage Examples

### 1. Single CVE Lookup

```python
from riskscore import RiskScoreClient

client = RiskScoreClient(api_key="YOUR_API_KEY")

cve = client.get_cve("CVE-2021-44228")
print(cve["cve_id"])                        # CVE-2021-44228
print(cve["risk_score"]["score"])           # 100
print(cve["risk_score"]["severity_label"])  # CRITICAL
```

### 2. Bulk Scoring

Score multiple CVEs in a single request (free tier: 10 per call, Pro/Enterprise: 100):

```python
from riskscore import RiskScoreClient

client = RiskScoreClient(api_key="YOUR_API_KEY")

results = client.bulk_score([
    "CVE-2021-44228",
    "CVE-2022-26134",
    "CVE-2023-44487",
    "CVE-2024-3400",
    "CVE-2021-45046",
])

for item in results:
    print(f"{item['cve_id']:20s}  score={item['risk_score']['score']:3d}  severity={item['risk_score']['severity_label']}")
```

### 3. Explain Mode

Get a score breakdown plus a plain-English explanation of what's driving the risk:

```python
from riskscore import RiskScoreClient

client = RiskScoreClient(api_key="YOUR_API_KEY")

cve = client.get_cve("CVE-2021-44228", explain=True)

# Component breakdown
components = cve["risk_score"]["components"]
print(f"CVSS:  {components['cvss_score']} → {components['cvss_contribution']} pts")
print(f"EPSS:  {components['epss_score']} → {components['epss_contribution']} pts")
print(f"KEV:   {'yes' if components['kev_listed'] else 'no'} → {components['kev_contribution']} pts")

# Plain English
if "explanation" in cve:
    print("\n" + cve["explanation"]["plain_english"])
```

## All Available Methods

### `get_cve(cve_id, explain=False)`
Look up a single CVE by ID.

### `bulk_score(cve_ids, explain=False)`
Score multiple CVEs in one request.

### `search(keyword=None, vendor=None, kev=None, cvss_min=None, page=1, per_page=20)`
Search and filter CVEs.

```python
results = client.search(keyword="log4j", kev=True, per_page=5)
for r in results["results"]:
    print(r["cve_id"], r["risk_score"])
```

### `watchlist_add(cve_id)` / `watchlist_get(changed_only=False)` / `watchlist_remove(cve_id)`
Manage your CVE watchlist.

### `me()`
View your key tier, limits, and daily usage.

### `rate_limit_status()`
Check remaining quota for the current time window.

## Error Handling

```python
from riskscore import RiskScoreClient, RiskScoreError

client = RiskScoreClient(api_key="YOUR_API_KEY")

try:
    cve = client.get_cve("CVE-INVALID-9999")
except RiskScoreError as e:
    print(e.status_code, e)
```

## Free Tier

| Plan | Requests/day | Bulk limit |
|------|-------------|------------|
| Free | 100 | 10 CVEs |
| Pro | 10,000 | 100 CVEs |
| Enterprise | Unlimited | 1,000 CVEs |

No credit card required for the free tier.

## Links

- **Homepage:** https://riskscore.dev
- **API docs:** https://api.riskscore.dev/docs
- **OpenAPI spec:** https://api.riskscore.dev/openapi.json
- **PyPI:** https://pypi.org/project/riskscore/
