Findings API

Findings API

Create, read, update, and delete security findings via the API.

Endpoints

Method	Endpoint	Description
GET	/findings	List all findings
GET	/findings/{id}	Get finding by ID
GET	/projects/{id}/findings	List project findings
POST	/findings	Create finding
PUT	/findings/{id}	Update finding
DELETE	/findings/{id}	Delete finding

Finding Object

{
  "id": "find_abc123",
  "project_id": "proj_xyz789",
  "title": "SQL Injection in Login Form",
  "severity": "High",
  "status": "open",
  "cvss_score": 8.6,
  "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:L",
  "cve_id": "CVE-2024-1234",
  "cwe_id": "CWE-89",
  "description": "A SQL injection vulnerability was identified...",
  "impact": "An attacker could extract sensitive data...",
  "remediation": "Use parameterized queries...",
  "references": [
    "https://owasp.org/www-community/attacks/SQL_Injection"
  ],
  "affected_assets": ["asset_123", "asset_456"],
  "tags": ["web", "injection", "owasp-top-10"],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-16T14:30:00Z"
}

List Findings

GET /findings

Query Parameters

Parameter	Type	Description
page	integer	Page number
limit	integer	Items per page
project_id	string	Filter by project
severity	string	Filter by severity
status	string	Filter by status
cve_id	string	Filter by CVE
search	string	Search title/description
sort	string	Sort field
order	string	asc or desc

Example Request

curl -X GET "https://{tenant}.nforged.com/api/v1/findings?severity=High&status=open" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response

{
  "success": true,
  "data": [
    {
      "id": "find_abc123",
      "project_id": "proj_xyz789",
      "title": "SQL Injection in Login Form",
      "severity": "High",
      "status": "open",
      "cvss_score": 8.6
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 23,
    "pages": 1
  }
}

Get Finding

GET /findings/{id}

Example Request

curl -X GET "https://{tenant}.nforged.com/api/v1/findings/find_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create Finding

POST /findings

Request Body

Field	Type	Required	Description
project_id	string	Yes	Project ID
title	string	Yes	Finding title
severity	string	Yes	Severity level
status	string	No	Finding status
cvss_score	number	No	CVSS 3.1 score
cvss_vector	string	No	CVSS vector string
cve_id	string	No	CVE identifier
cwe_id	string	No	CWE identifier
description	string	No	Technical description
impact	string	No	Impact statement
remediation	string	No	Fix recommendations
references	array	No	Reference URLs
affected_assets	array	No	Asset IDs
tags	array	No	Tags

Example Request

curl -X POST "https://{tenant}.nforged.com/api/v1/findings" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_xyz789",
    "title": "Cross-Site Scripting (XSS) in Search",
    "severity": "Medium",
    "status": "open",
    "cvss_score": 6.1,
    "cvss_vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:R/S:C/C:L/I:L/A:N",
    "cwe_id": "CWE-79",
    "description": "Reflected XSS vulnerability in search parameter",
    "impact": "Attacker could execute JavaScript in victim browser",
    "remediation": "Encode output and implement CSP",
    "affected_assets": ["asset_123"],
    "tags": ["xss", "web"]
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "find_def456",
    "project_id": "proj_xyz789",
    "title": "Cross-Site Scripting (XSS) in Search",
    "severity": "Medium",
    "status": "open",
    "created_at": "2024-01-16T09:00:00Z"
  }
}

Update Finding

PUT /findings/{id}

Example Request

curl -X PUT "https://{tenant}.nforged.com/api/v1/findings/find_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "remediated",
    "remediation": "Updated to use parameterized queries in v2.1.0"
  }'

Delete Finding

DELETE /findings/{id}

Example Request

curl -X DELETE "https://{tenant}.nforged.com/api/v1/findings/find_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Bulk Operations

Bulk Update

PUT /findings/bulk

{
  "ids": ["find_123", "find_456", "find_789"],
  "updates": {
    "status": "confirmed"
  }
}

Bulk Delete

DELETE /findings/bulk

{
  "ids": ["find_123", "find_456"]
}

Severity Values

Value	CVSS Range
Critical	9.0 - 10.0
High	7.0 - 8.9
Medium	4.0 - 6.9
Low	0.1 - 3.9
Informational	0.0

Status Values

Value	Description
open	Newly identified
confirmed	Verified
in_progress	Being remediated
remediated	Fix applied
verified	Fix confirmed
accepted_risk	Risk accepted
false_positive	Not a vulnerability

AI Generation

Generate finding content with AI:

POST /findings/generate

{
  "title": "SQL Injection",
  "context": "Found in login form parameter"
}

Response includes AI-generated description, impact, and remediation.

---

Next: Learn about the Assets API