Findings API

Create, list, and manage security findings from assessments and scans.

List Findings

GET /api/v1/findings

Returns security findings for the authenticated organization.

Query Parameters

Parameter	Type	Default	Description
limit	integer	50	Maximum results (1-200)
offset	integer	0	Pagination offset
severity	string	-	Filter: critical, high, medium, low, info
status	string	-	Filter: open, in_progress, resolved, accepted, false_positive
assessment_id	UUID	-	Filter by assessment

Example Request

curl "https://api.clawgrc.com/api/v1/findings?severity=critical&status=open" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "findings": [
    {
      "id": "finding-uuid",
      "org_id": "org-uuid",
      "assessment_id": "assess-uuid",
      "severity": "critical",
      "title": "SQL injection in user search endpoint",
      "description": "The /api/users/search endpoint is vulnerable to SQL injection...",
      "cwe_id": "CWE-89",
      "cvss_score": 9.8,
      "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H",
      "status": "open",
      "remediation": "Use parameterized queries instead of string concatenation.",
      "affected_resource": "/api/users/search",
      "evidence": {},
      "created_at": "2025-01-15T10:05:23Z",
      "updated_at": "2025-01-15T10:05:23Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}

---

Create Finding

POST /api/v1/findings

Create a new security finding.

Request Body

Field	Type	Required	Description
title	string	Yes	Concise vulnerability description
severity	string	Yes	critical, high, medium, low, info
description	string	No	Detailed explanation
assessment_id	UUID	No	Link to an assessment
cwe_id	string	No	CWE identifier (e.g., CWE-79)
cvss_score	number	No	CVSS v3.1 base score (0.0-10.0)
cvss_vector	string	No	CVSS vector string
remediation	string	No	Recommended fix
affected_resource	string	No	What system/component is affected
evidence	object	No	Supporting evidence data

Example Request

curl -X POST https://api.clawgrc.com/api/v1/findings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Cross-site scripting in comment form",
    "severity": "medium",
    "description": "Reflected XSS via the comment body parameter.",
    "cwe_id": "CWE-79",
    "cvss_score": 6.1,
    "remediation": "Sanitize user input and encode output.",
    "affected_resource": "/api/comments"
  }'

Example Response (201 Created)

{
  "id": "finding-uuid",
  "title": "Cross-site scripting in comment form",
  "severity": "medium",
  "status": "open",
  "created_at": "2025-01-15T14:30:00Z"
}

---

Get Finding

GET /api/v1/findings/:id

Returns a single finding with full details.

---

Update Finding

PUT /api/v1/findings/:id

Update a finding's status, remediation, or other fields.

Request Body

Field	Type	Description
status	string	open, in_progress, resolved, accepted, false_positive
remediation	string	Updated remediation guidance
description	string	Updated description

Example Request

curl -X PUT https://api.clawgrc.com/api/v1/findings/finding-uuid \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "resolved",
    "remediation": "Fixed by using parameterized queries in PR #1234."
  }'