CRA Assessment API Reference

All endpoints are under /api/v1/assessment/ and require API key authentication via Authorization: Bearer <key>.

Scopes: assessment:read for GET endpoints, assessment:write for POST/PUT.

Products

Create Product

POST /api/v1/assessment/products

{
  "name": "my-product",
  "version": "1.0.0",
  "ruleset_id": "uuid",
  "application_id": "uuid (optional, links to Fleet app)",
  "repo_url": "https://github.com/org/repo (optional)"
}

Response: { "data": { "id": "uuid", "name": "my-product", ... } }

List Products

GET /api/v1/assessment/products

Get Product

GET /api/v1/assessment/products/{id}

Gap Analysis

GET /api/v1/assessment/products/{id}/gap-analysis

Response:

{
  "data": {
    "total_requirements": 401,
    "assessed": 150,
    "compliance_percentage": "37.4",
    "status_breakdown": {
      "not_started": 251,
      "in_progress": 10,
      "needs_evidence": 30,
      "compliant": 80,
      "non_compliant": 20,
      "not_applicable": 10
    },
    "gaps": [
      { "requirement_id": "CRYPTO-01-R1", "status": "non_compliant", "notes": "MD5 detected" }
    ]
  }
}

Scans

Ingest Scan Results

The primary integration point for CI pipelines. Accepts the full output of fleet scan --output json.

POST /api/v1/assessment/products/{id}/scans

{
  "commit_sha": "abc123",
  "branch": "main",
  "ci_provider": "github",
  "summary": { "total": 56, "pass": 30, "fail": 12, "needs_review": 14 },
  "findings": [
    {
      "requirement_id": "CRYPTO-01-R1",
      "risk_id": "CRYPTO-01",
      "status": "fail",
      "confidence": 0.85,
      "detector": "crypto",
      "message": "MD5 usage detected",
      "source_locations": [{ "file": "src/auth.rs", "line": 42, "snippet": "md5::compute()" }]
    }
  ],
  "evidence": [
    {
      "requirement_id": "CRYPTO-01-R1",
      "evidence_type": "auto",
      "source": "scanner",
      "content": "Requirement CRYPTO-01-R1 assessed as fail...",
      "content_hash": "sha256:abc...",
      "status": "draft"
    }
  ]
}

Response: { "data": { "scan_id": "uuid", "findings_count": 56, "evidence_count": 56 } }

List Scans

GET /api/v1/assessment/products/{id}/scans

Get Scan

GET /api/v1/assessment/scans/{id}

List Findings

GET /api/v1/assessment/scans/{id}/findings

Evidence

List Evidence for Product

GET /api/v1/assessment/products/{id}/evidence

List Evidence by Requirement

GET /api/v1/assessment/products/{product_id}/evidence/{requirement_id}

Upload Manual Evidence

For Doc/Test evidence types — submit documentation, test reports, architecture reviews.

POST /api/v1/assessment/products/{id}/evidence/upload

{
  "requirement_id": "VH-DISC-01-R1",
  "evidence_type": "doc",
  "content": "Coordinated disclosure policy published at https://example.com/security. Policy covers 90-day disclosure timeline, reporter credits, and scope.",
  "created_by": "james@crabnebula.dev",
  "artifacts": [{ "name": "disclosure-policy.pdf", "storage_key": "s3://evidence/..." }]
}

Assessment Entries

List Assessment Status

GET /api/v1/assessment/products/{id}/assessments

Update Assessment Status

PUT /api/v1/assessment/products/{id}/assessments

{
  "requirement_id": "VH-REG-01-R1",
  "status": "compliant",
  "notes": "ENISA notification process documented and tested"
}

Valid statuses: not_started, in_progress, needs_evidence, compliant, non_compliant, not_applicable

Finding Overrides

Create Override

POST /api/v1/assessment/products/{id}/overrides

{
  "requirement_id": "CRYPTO-01-R1",
  "override_type": "false_positive",
  "justification": "MD5 is used only for non-security cache key generation, not for cryptographic purposes. See src/cache.rs:42.",
  "created_by": "james@crabnebula.dev"
}

Override types:

Type	Effect	Assessment Status
`false_positive`	Suppressed in future scans	`not_applicable`
`false_negative`	Manually reported risk scanner missed	`non_compliant`
`accepted_risk`	Real risk, documented acceptance	`compliant`
`deferred`	Acknowledged, remediation postponed	`in_progress`

For deferred, include review_date:

{
  "requirement_id": "NET-SVC-02-R1",
  "override_type": "deferred",
  "justification": "Rate limiting implementation planned for v1.2 release",
  "created_by": "james@crabnebula.dev",
  "review_date": "2026-06-01T00:00:00Z"
}

For false_negative, include description and optionally source_locations:

{
  "requirement_id": "INPUT-01-R1",
  "override_type": "false_negative",
  "justification": "Scanner missed SQL injection in dynamic query builder",
  "created_by": "security-team",
  "description": "Custom ORM bypasses parameterized queries for complex filters",
  "source_locations": [{ "file": "src/db/query_builder.rs", "line": 156, "snippet": "format!(\"WHERE {}\"...)" }]
}

List Active Overrides

GET /api/v1/assessment/products/{id}/overrides

Revoke Override

POST /api/v1/assessment/overrides/{id}/revoke

{
  "revoked_by": "james@crabnebula.dev",
  "reason": "MD5 usage removed in commit abc123, override no longer needed"
}

Remediations

Create Remediation

POST /api/v1/assessment/products/{id}/remediations

{
  "requirement_id": "CRYPTO-01-R1",
  "finding_id": "uuid (optional)",
  "description": "Replace MD5 with SHA-256 for all hash operations",
  "created_by": "james@crabnebula.dev",
  "assigned_to": "dev-team",
  "pull_request_url": "https://github.com/org/repo/pull/42",
  "ticket_url": "https://linear.app/team/ENG-123"
}

List Remediations

GET /api/v1/assessment/products/{id}/remediations

Update Remediation Status

PUT /api/v1/assessment/remediations/{id}/status

{ "status": "implemented" }

Valid statuses: planned -> in_progress -> implemented -> verified -> closed

Verify Remediation

Links a verification scan to the remediation, confirming the fix resolved the finding.

POST /api/v1/assessment/remediations/{id}/verify

{
  "verified_by": "qa-team",
  "scan_id": "uuid (optional, links to the scan that confirmed the fix)"
}

Bulk Triage

Process multiple findings in one call.

POST /api/v1/assessment/products/{id}/triage

{
  "triaged_by": "james@crabnebula.dev",
  "actions": [
    { "requirement_id": "CRYPTO-01-R1", "action": "reject", "justification": "Confirmed, needs fix" },
    { "requirement_id": "NET-SVC-04-R2", "action": "false_positive", "justification": "Debug endpoint is test-only" },
    { "requirement_id": "LOG-PROT-01-R2", "action": "accept", "justification": "Verified tokens are never logged" },
    { "requirement_id": "NET-SVC-02-R1", "action": "defer", "justification": "Planned for v1.2", "review_date": "2026-06-01T00:00:00Z" }
  ]
}

Actions: accept, reject, false_positive, accepted_risk, defer

Response:

{
  "data": {
    "processed": 4,
    "overrides_created": 2,
    "assessments_updated": 4
  }
}

Rulesets

Create Ruleset

POST /api/v1/assessment/rulesets

{
  "name": "cra-custom",
  "version": "1.0.0",
  "description": "Custom ruleset for our product category",
  "catalog_json": { "version": "1.0.0", "categories": [...] }
}

List Rulesets

GET /api/v1/assessment/rulesets

Get Ruleset (with full catalog)

GET /api/v1/assessment/rulesets/{id}

Publish Ruleset

POST /api/v1/assessment/rulesets/{id}/publish

Only draft rulesets can be published. Published rulesets are immutable.

Questionnaires

Start Session

POST /api/v1/assessment/products/{id}/questionnaire

Submit Answer

POST /api/v1/assessment/questionnaire/{session_id}/answer

{
  "requirement_id": "VH-REG-01-R1",
  "answer": "ENISA notification process documented in internal wiki. Contact: security@company.com. SLA: 24h early warning, 72h full notification.",
  "attachments": [{ "name": "enisa-process.pdf", "storage_key": "s3://..." }]
}

Complete Session

POST /api/v1/assessment/questionnaire/{session_id}/complete

SBOM / CBOM Records

List Records

GET /api/v1/assessment/products/{id}/sbom

Returns both SBOM and CBOM records. Filter by bom_type field (sbom or cbom).

Error Format

All errors follow the Fleet standard:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Justification is required for all overrides"
  }
}