Threat Remediation API Endpoints and Usage
The Threat Remediation API provides programmatic access to CleanStart's supply chain security intelligence, enabling automated vulnerability scanning, threat assessment, and remediation guidance. It powers integrations with CI/CD systems, SIEMs, and security platforms.
The following diagram illustrates the Threat Remediation API workflow from image submission through remediation:
graph TD A["CI/CD Pipeline<br/>Image Built"] -->|Submit| B["POST /threats/scan<br/>Threat Remediation API"] B -->|Auth| C["Authorization:<br/>Bearer Token"] B -->|Payload| D["image URI<br/>include_transitive<br/>fail_threshold"] C -->|Validate| E["API Key<br/>Scopes<br/>Rate Limit"] E -->|Valid| F["Scan Engine<br/>Initialize"] F -->|Fetch| G["Container Image<br/>Registry"] G -->|Analyze| H["SBOM<br/>Generation"] H -->|Database| I["Vulnerability<br/>Database"] I -->|Cross-ref| J["CVE<br/>Database"] J -->|Supply Chain| K["Threat<br/>Models"] I -->|Results| L["Classification"] J -->|Results| L K -->|Results| L L -->|Categorize| M["Critical<br/>Vulnerabilities"] L -->|Categorize| N["High<br/>Vulnerabilities"] L -->|Categorize| O["Medium<br/>Vulnerabilities"] M -->|Generate| P["Response:<br/>scan_id<br/>vulnerabilities<br/>threats"] N -->|Generate| P O -->|Generate| P P -->|Check| Q["Threshold<br/>Comparison"] Q -->|Pass| R["Status: PASS<br/>Proceed to Deploy"] Q -->|Fail| S["Status: FAIL<br/>Remediation Required"] R -->|Notify| T["CI/CD:<br/>Green Signal"] S -->|Return| U["Remediation<br/>Guidance<br/>Upgrade Path"] U -->|Fix| V["Update Packages<br/>Rebuild Image"] V -->|Resubmit| B style B fill:#99ccff style E fill:#99ccff style L fill:#ffff99 style R fill:#99ff99 style S fill:#ffccccAuthentication
All requests require an API key in the Authorization header:
curl -H "Authorization: Bearer YOUR_API_KEY" \ https://api.cleanstart.dev/v1/threats/scanGenerating API Keys
clnstrt-cli auth generate-key \ --name "Production Scanner" \ --expiration 90d \ --scopes threats:read,sbom:read,reports:writeKey scopes include threats:read for querying threat intelligence, sbom:read for analyzing SBOMs, reports:write for generating and storing reports, and remediation:write for tracking remediation progress.
Base URL
https://api.cleanstart.dev/v1Rate Limits
The Standard rate limit is 1,000 requests per minute and 10,000 per hour. Burst capacity allows 5,000 requests per minute for brief periods. Response Headers include:
X-RateLimit-Limit: 1000X-RateLimit-Remaining: 995X-RateLimit-Reset: 1699560000Core Endpoints
1. Scan Image for Threats
POST /threats/scan
Scan a container image against vulnerability databases and supply chain threat models.
Request:
curl -X POST https://api.cleanstart.dev/v1/threats/scan \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image": "gcr.io/my-project/app:latest", "include_transitive": true, "fail_threshold": "high" }'Parameters: The image parameter (string, required) specifies the container image URI. The include_transitive parameter (boolean) controls whether indirect dependencies are included. The fail_threshold parameter (string) causes the scan to fail if severity is at or above the threshold (critical, high, medium, or low). The max_vulnerabilities parameter (integer) causes the scan to fail if the vulnerability count exceeds the specified limit.
Response:
{ "scan_id": "scan_abc123", "image": "gcr.io/my-project/app:latest", "timestamp": "2024-01-15T10:30:00Z", "vulnerabilities": { "critical": 2, "high": 5, "medium": 12, "low": 8 }, "threats": [ { "threat_id": "typo-npm-1234", "type": "typosquatting", "package": "npm:lodash-core", "severity": "critical", "description": "Malicious package mimicking lodash" } ], "passed": false}2. Analyze SBOM
POST /sbom/analyze
Analyze a software bill of materials for known vulnerabilities and supply chain risks.
Request:
curl -X POST https://api.cleanstart.dev/v1/sbom/analyze \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "sbom": "@sbom.spdx", "format": "spdx", "include_threat_intel": true }'Parameters: The sbom parameter (string, required) accepts the SBOM content or file reference. The format parameter (string) specifies either spdx or cyclonedx format. The include_threat_intel parameter (boolean) controls whether threat intelligence data is included, and the include_risk_scores parameter (boolean) controls whether risk scores are calculated.
Response:
{ "analysis_id": "analysis_xyz789", "total_components": 145, "vulnerable_components": 12, "findings": [ { "component": "npm:express@4.17.1", "vulnerability": "CVE-2023-1234", "severity": "high", "remediation": "Upgrade to express@4.18.2" } ], "risk_score": 7.2}3. Get Remediation Guidance
GET /threats/{threat_id}/remediation
Get detailed remediation steps and upgrade paths for a specific threat.
Request:
curl https://api.cleanstart.dev/v1/threats/CVE-2024-1234/remediation \ -H "Authorization: Bearer YOUR_API_KEY"Response:
{ "threat_id": "CVE-2024-1234", "package": "npm:lodash", "affected_versions": ["<4.17.21"], "remediation": { "steps": [ "Update package.json: lodash@^4.17.21", "Run npm install", "Rebuild and test application", "Deploy new image" ], "upgrade_path": "4.17.20 → 4.17.21", "estimated_time": "30 minutes", "breaking_changes": false }, "references": [ "https://github.com/lodash/lodash/security/advisories/GHSA-xxxx" ]}4. Check Provenance
POST /verification/provenance
Verify image provenance and attestations.
Request:
curl -X POST https://api.cleanstart.dev/v1/verification/provenance \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "image": "gcr.io/my-project/app:latest", "require_attestations": ["sbom", "slsa", "scan"] }'Response:
{ "image": "gcr.io/my-project/app:latest", "digest": "sha256:abc123...", "provenance": { "signed": true, "signer": "ci-system@company.iam.gserviceaccount.com", "attestations": { "sbom": { "present": true, "timestamp": "2024-01-15T09:00:00Z" }, "slsa": { "present": true, "level": 3 }, "vulnerability-scan": { "present": true, "passed": true } } }, "verification_passed": true}5. Generate Report
POST /reports/generate
Generate a security assessment report in HTML, PDF, or JSON format.
Request:
curl -X POST https://api.cleanstart.dev/v1/reports/generate \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "compliance", "images": ["gcr.io/my-project/app:latest"], "format": "pdf", "include_provenance": true }'Response:
{ "report_id": "report_abc123", "status": "pending", "format": "pdf", "estimated_completion": "30 seconds", "download_url": "https://api.cleanstart.dev/v1/reports/report_abc123/download"}Query Examples
Find Vulnerable Package Versions
curl "https://api.cleanstart.dev/v1/packages/search?name=lodash&vulnerable=true" \ -H "Authorization: Bearer YOUR_API_KEY"List Recent Threats
curl "https://api.cleanstart.dev/v1/threats?limit=50&sort=date_desc" \ -H "Authorization: Bearer YOUR_API_KEY"Monitor Supply Chain
curl "https://api.cleanstart.dev/v1/monitoring?organization=my-org&interval=24h" \ -H "Authorization: Bearer YOUR_API_KEY"Error Handling
Standard error responses follow this format:
{ "error": "invalid_request", "error_description": "Missing required parameter: image", "status": 400, "request_id": "req_xyz789"}HTTP status codes include 200 for success, 400 for invalid requests, 401 for unauthorized access (invalid API key), 403 for forbidden (insufficient scopes), 429 for rate limit exceeded, and 500 for server errors.
Integration Examples
GitHub Actions Workflow
- name: Scan image for threats env: API_KEY: ${{ secrets.CLEANSTART_API_KEY }} run: | curl -X POST https://api.cleanstart.dev/v1/threats/scan \ -H "Authorization: Bearer $API_KEY" \ -d '{"image":"ghcr.io/${{ github.repository }}:${{ github.sha }}"}'GitLab CI Pipeline
scan_threats: script: - curl -X POST https://api.cleanstart.dev/v1/threats/scan \ -H "Authorization: Bearer $CLEANSTART_API_KEY" \ -d "{\"image\":\"$CI_REGISTRY_IMAGE:$CI_COMMIT_SHA\"}"Webhooks
Register webhooks to receive scan results asynchronously:
curl -X POST https://api.cleanstart.dev/v1/webhooks/register \ -H "Authorization: Bearer YOUR_API_KEY" \ -d '{ "url": "https://your-system.com/webhook", "events": ["scan.completed", "threat.detected"], "secret": "webhook_secret_key" }'Pagination
# First pagecurl "https://api.cleanstart.dev/v1/threats?limit=20&offset=0" # Next pagecurl "https://api.cleanstart.dev/v1/threats?limit=20&offset=20" # Using cursorcurl "https://api.cleanstart.dev/v1/threats?limit=20&cursor=abc123"Best Practices
Implement API key rotation on a 90-day schedule to ensure that compromised keys have limited useful lifetime. Monitor your rate limit consumption by implementing result caching and using batch endpoints where available, reducing unnecessary API calls. Set clear fail thresholds that define your organization's security policies, ensuring consistent behavior across all scans. Audit all scans by logging API calls for compliance purposes, providing an audit trail of security activities. Handle errors gracefully by implementing retry logic with exponential backoff, allowing transient failures to be recovered automatically without data loss.
Support
For documentation, visit https://docs.cleanstart.dev/api. To report issues, go to https://github.com/cleanstart/api/issues. For email support, contact api-support@cleanstart.dev.