Threat Remediation API

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:#ffcccc

Authentication

All requests require an API key in the Authorization header:

curl -H "Authorization: Bearer YOUR_API_KEY" \  https://api.cleanstart.dev/v1/threats/scan

Generating API Keys

clnstrt-cli auth generate-key \  --name "Production Scanner" \  --expiration 90d \  --scopes threats:read,sbom:read,reports:write

Key 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/v1

Rate 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: 1699560000

Core 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

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.