# ContrastAPI — Full API Reference

> Security intelligence API for AI models and developers.
> Base URL: https://api.contrastcyber.com
> Auth: None required (100 req/hr). Pro key: Authorization: Bearer cc_xxx (1000 req/hr).
> All responses are JSON. All endpoints include a "summary" field optimized for LLM consumption.

---

## CVE Intelligence

### GET /v1/cve/{cve_id}
Look up a single CVE by ID. Returns full details with EPSS score and KEV status.

**Parameters:**
- cve_id (path, required): CVE ID in format CVE-YYYY-NNNNN (e.g., CVE-2024-3094)

**Response:**
{
  "cve_id": "CVE-2024-3094",
  "summary": "CRITICAL (CWE-506) — Malicious code in xz/liblzma. CVSS 10.0. Actively exploited (CISA KEV). EPSS 93% exploitation probability.",
  "description": "...",
  "severity": "CRITICAL",
  "cvss_v3": 10.0,
  "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:C/C:H/I:H/A:H",
  "cwe_id": "CWE-506",
  "epss": {"score": 0.93, "percentile": 0.99},
  "kev": {"in_kev": true, "date_added": "2024-03-29"},
  "affected_products": ["xz-utils"],
  "published": "2024-03-29T00:00:00",
  "modified": "2024-04-01T00:00:00",
  "references": ["https://nvd.nist.gov/vuln/detail/CVE-2024-3094"]
}

**Errors:** 400 (invalid CVE format), 404 (CVE not found)

---

### GET /v1/cves
Search CVEs by product, severity, and/or date range.

**Parameters:**
- product (query, optional): Filter by product name, min 2 chars (e.g., "nginx", "apache")
- severity (query, optional): CRITICAL, HIGH, MEDIUM, or LOW
- days (query, optional): CVEs published within N days (1-365)
- limit (query, optional): Max results, default 50 (1-200)

**Example:** GET /v1/cves?product=nginx&severity=HIGH&days=90&limit=10

**Response:**
{
  "count": 3,
  "summary": "3 CVEs found (nginx, HIGH, last 90d)",
  "results": [...]
}

---

### GET /v1/cves/recent
Get recently published CVEs.

**Parameters:**
- hours (query, optional): CVEs from last N hours, default 24 (1-168)
- limit (query, optional): Max results, default 50 (1-200)

**Response:**
{
  "count": 15,
  "hours": 24,
  "summary": "15 CVEs published in the last 24 hours",
  "results": [...]
}

---

### GET /v1/cves/kev
CISA Known Exploited Vulnerabilities — actively exploited CVEs.

**Parameters:**
- limit (query, optional): Max results, default 100 (1-500)

**Response:**
{
  "count": 50,
  "summary": "50 actively exploited CVEs (CISA KEV)",
  "results": [...]
}

---

### GET /v1/epss/{cve_id}
EPSS (Exploit Prediction Scoring System) score for a CVE.

**Parameters:**
- cve_id (path, required): CVE ID (e.g., CVE-2024-3094)

**Response:**
{
  "cve_id": "CVE-2024-3094",
  "epss_score": 0.93,
  "epss_percentile": 0.99
}

---

## Domain Intelligence

### GET /v1/domain/{domain}
Full domain intelligence report — runs all checks in parallel.

**Parameters:**
- domain (path, required): Domain name (e.g., example.com)

**Response:**
{
  "domain": "example.com",
  "summary": "example.com resolves to 93.184.216.34. Security grade B (72/100). SSL grade A by DigiCert. No WAF detected. Email security: B. 3 subdomains found.",
  "dns": {"a": ["93.184.216.34"], "mx": [...], "ns": [...], "txt": [...]},
  "reverse_dns": {"ip": "93.184.216.34", "ptr": "..."},
  "whois": {"registrar": "...", "creation_date": "1995-08-14", "expiry_date": "2025-08-13"},
  "ssl": {"common_name": "...", "issuer": "DigiCert", "not_after": "...", "san": [...], "grade": "A", "tls_version": "TLSv1.3", "days_remaining": 120},
  "email_security": {"spf": "v=spf1 ...", "dmarc": "v=DMARC1 ...", "dkim_selectors": ["default"], "grade": "A"},
  "subdomains": {"subdomains": ["www.example.com", "mail.example.com"], "count": 2},
  "certificates": {"total_certificates": 15, "certificates": [...]},
  "waf": {"detected": [], "waf_present": false},
  "threat": {"urlhaus_status": "clean", "urls_online": 0, "url_count": 0},
  "risk": {"score": 72, "max_score": 100, "grade": "B", "factors": [...]}
}

---

### GET /v1/dns/{domain}
DNS records only (A, AAAA, MX, NS, TXT, CNAME, SOA).

**Parameters:**
- domain (path, required): Domain name

**Response:**
{
  "domain": "example.com",
  "records": {"a": ["93.184.216.34"], "mx": [{"priority": 10, "host": "mail.example.com"}], ...}
}

---

### GET /v1/whois/{domain}
WHOIS registration data.

**Parameters:**
- domain (path, required): Domain name

**Response:**
{
  "domain": "example.com",
  "whois": {"registrar": "...", "creation_date": "...", "expiry_date": "...", "name_servers": [...]}
}

---

### GET /v1/subdomains/{domain}
Subdomain enumeration via DNS brute force + Certificate Transparency logs.

**Parameters:**
- domain (path, required): Domain name

**Response:**
{
  "domain": "example.com",
  "subdomains": ["www.example.com", "mail.example.com", "api.example.com"],
  "count": 3
}

---

### GET /v1/certs/{domain}
Certificate Transparency log entries from crt.sh.

**Parameters:**
- domain (path, required): Domain name

**Response:**
{
  "domain": "example.com",
  "total_certificates": 42,
  "certificates": [{"issuer": "...", "not_before": "...", "not_after": "...", "common_name": "..."}]
}

---

### GET /v1/ip/{ip}
IP intelligence — reverse DNS, open ports, vulnerabilities, hostnames via Shodan InternetDB.

**Parameters:**
- ip (path, required): IPv4 or IPv6 address (no private/reserved IPs)

**Response:**
{
  "ip": "93.184.216.34",
  "ptr": "example.com",
  "ports": [80, 443, 8080],
  "hostnames": ["example.com"],
  "vulns": ["CVE-2024-1234"],
  "cpes": ["cpe:/a:apache:httpd:2.4.51"],
  "tags": ["http", "https"],
  "summary": "93.184.216.34 → example.com. 3 open ports. 1 known vulnerability."
}

---

### GET /v1/threat/{domain}
Threat intelligence — check domain against URLhaus for known malware URLs.

**Parameters:**
- domain (path, required): Domain name

**Response:**
{
  "domain": "example.com",
  "urlhaus_status": "clean",
  "urls_online": 0,
  "url_count": 0,
  "threat_types": [],
  "tags": [],
  "urls": [],
  "summary": "example.com — no threats found in URLhaus"
}

---

### GET /v1/scan/headers/{domain}
Fetch a live domain's HTTP headers and analyze security posture.

**Parameters:**
- domain (path, required): Domain name

**Response:**
{
  "domain": "example.com",
  "status_code": 200,
  "url": "https://example.com/",
  "score": 65,
  "grade": "C",
  "findings": [{"header": "Content-Security-Policy", "present": false, "severity": "high", ...}],
  "headers_present": ["Strict-Transport-Security", "X-Content-Type-Options"],
  "headers_missing": ["Content-Security-Policy", "Permissions-Policy"]
}

---

## Code Security

### POST /v1/check/secrets
Detect hardcoded secrets in source code (14 patterns: AWS keys, GitHub tokens, JWTs, etc.).

**Request Body:**
{
  "code": "api_key = 'AKIAIOSFODNN7EXAMPLE'",
  "language": "python"
}

**Response:**
{
  "findings": [
    {
      "type": "aws_access_key",
      "severity": "critical",
      "line": 1,
      "match": "AKIAIOSFODNN7EXAMPLE",
      "description": "AWS Access Key ID detected",
      "remediation": "Use environment variables or AWS IAM roles"
    }
  ],
  "summary": "Found 1 hardcoded secret (1 critical)",
  "total": 1,
  "by_severity": {"critical": 1}
}

---

### POST /v1/check/injection
Detect SQL injection, command injection, and path traversal patterns.

**Request Body:**
{
  "code": "query = f'SELECT * FROM users WHERE id = {user_id}'",
  "language": "python"
}

**Response:**
{
  "findings": [{"type": "sql_injection", "severity": "high", "line": 1, ...}],
  "summary": "Found 1 injection pattern (1 high)",
  "total": 1,
  "by_severity": {"high": 1}
}

---

### POST /v1/check/headers
Validate HTTP security headers against best practices.

**Request Body:**
{
  "headers": {
    "content-security-policy": "default-src 'self'",
    "strict-transport-security": "max-age=31536000; includeSubDomains",
    "x-content-type-options": "nosniff",
    "x-frame-options": "DENY",
    "referrer-policy": "strict-origin-when-cross-origin",
    "permissions-policy": "camera=(), microphone=()"
  }
}

**Response:**
{
  "findings": [],
  "summary": "All 6 security headers present — score 100/100 (grade A)",
  "score": 100,
  "grade": "A",
  "headers_present": 6,
  "headers_missing": 0
}

---

### POST /v1/check/dependencies
Check software packages against the CVE database.

**Request Body:**
{
  "packages": [
    {"name": "lodash", "version": "4.17.15"},
    {"name": "express", "version": "4.17.1"}
  ]
}

**Response:**
{
  "findings": [{"package": "lodash", "version": "4.17.15", "cve_id": "CVE-2020-28500", ...}],
  "summary": "Found 1 CVE across 1 of 2 packages (1 high)",
  "total_cves": 1,
  "packages_affected": 1,
  "packages_clean": 1
}

---

## Error Responses

All errors return JSON:
{"error": "description of the error"}

Common status codes:
- 400: Invalid input (bad CVE format, invalid domain, missing fields)
- 401: Invalid API key
- 404: Resource not found (CVE not in database, no EPSS data)
- 429: Rate limit exceeded

---

## Rate Limits

- Keyless: 100 requests/hour per IP address (sliding window)
- Pro key: 1000 requests/hour per key (sliding window)
- Every response includes: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers
- Every response includes: X-Request-ID header for request tracing

### GET /v1/usage
Usage statistics for Pro key holders. Requires `Authorization: Bearer cc_xxx`.

**Response:**
{
  "total_requests": 1523,
  "last_24h": 89,
  "last_1h": 12,
  "hourly_limit": 1000,
  "hourly_remaining": 988,
  "top_endpoints": [{"endpoint": "/v1/cve/CVE-2024-3094", "count": 45}, ...]
}

---

## Data Sources

- NVD: 340,000+ CVEs (synced every 2 hours)
- EPSS: 323,000+ exploit probability scores (synced every 2 hours)
- CISA KEV: 1,500+ actively exploited vulnerabilities (synced every 2 hours)
- Shodan InternetDB: IP enrichment (ports, vulns, hostnames — free, no key)
- URLhaus (abuse.ch): Malware URL database (free, live queries)
- crt.sh: Certificate Transparency logs (live queries)
- DNS/WHOIS/SSL: Live queries per request