Findings

The Findings API provides access to vulnerability findings discovered by S4E scans. You can list, filter, update status, and export findings.

List Findings

GET /api/findings

Query Parameters

Parameter Type Default Description
severity string all Filter: critical, high, medium, low, info. Comma-separated for multiple.
status string all Filter: open, confirmed, resolved, false_positive, accepted_risk.
asset_id string Filter by asset ID.
scan_id string Filter by scan ID.
cvss_min number Minimum CVSS score.
cvss_max number Maximum CVSS score.
search string Full-text search in title and description.
page integer 1 Page number.
per_page integer 20 Results per page (max 100).
sort_by string discovered_at Sort field: severity, cvss, discovered_at, title.
sort_order string desc Sort direction: asc, desc.

Example

curl -X GET "https://api.s4e.io/api/findings?severity=critical,high&status=open&sort_by=cvss&sort_order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "data": [
    {
      "id": "f-91827",
      "title": "SQL Injection in /api/login",
      "severity": "critical",
      "cvss": 9.8,
      "status": "open",
      "asset": {
        "id": "a-1001",
        "name": "api.example.com",
        "type": "domain"
      },
      "scan_id": "sc-44021",
      "description": "User input is passed directly to SQL query without parameterization.",
      "remediation": "Use parameterized queries or an ORM to prevent SQL injection.",
      "references": [
        "https://cwe.mitre.org/data/definitions/89.html",
        "https://owasp.org/www-community/attacks/SQL_Injection"
      ],
      "discovered_at": "2026-04-28T12:05:00Z",
      "updated_at": "2026-04-28T12:05:00Z"
    }
  ],
  "meta": {
    "total": 156,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Get Finding Details

GET /api/findings/{id}

Returns complete finding information including evidence, remediation steps, and references.

curl -X GET "https://api.s4e.io/api/findings/f-91827" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "id": "f-91827",
    "title": "SQL Injection in /api/login",
    "severity": "critical",
    "cvss": 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",
    "asset": {
      "id": "a-1001",
      "name": "api.example.com",
      "type": "domain"
    },
    "scan_id": "sc-44021",
    "description": "The /api/login endpoint passes the 'username' parameter directly into a SQL query without sanitization, allowing an attacker to execute arbitrary SQL commands.",
    "remediation": "Use parameterized queries or an ORM. Validate and sanitize all user input. Apply the principle of least privilege to database accounts.",
    "evidence": {
      "url": "https://api.example.com/api/login",
      "method": "POST",
      "parameter": "username",
      "payload": "admin' OR '1'='1",
      "response_indicator": "Login successful with injected payload."
    },
    "references": [
      "https://cwe.mitre.org/data/definitions/89.html",
      "https://owasp.org/www-community/attacks/SQL_Injection"
    ],
    "tags": ["owasp-top-10", "injection"],
    "notes": [],
    "discovered_at": "2026-04-28T12:05:00Z",
    "updated_at": "2026-04-28T12:05:00Z"
  }
}

Update Finding Status

PUT /api/findings/{id}/status

Request Body

Field Type Required Description
status string Yes New status value.
note string No Reason or comment for the status change.

Status Values

Status Description
open Finding is unaddressed.
confirmed Finding has been verified as valid.
resolved Finding has been fixed.
false_positive Finding is not a real vulnerability.
accepted_risk Risk is acknowledged but not remediated.

Example

curl -X PUT "https://api.s4e.io/api/findings/f-91827/status" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "confirmed",
    "note": "Verified by manual testing. SQL injection confirmed."
  }'

{
  "data": {
    "id": "f-91827",
    "status": "confirmed",
    "updated_at": "2026-04-28T14:00:00Z",
    "updated_by": "[email protected]"
  }
}

Export Findings

POST /api/findings/export

Request Body

Field Type Required Description
format string Yes Export format: csv, json, pdf.
filters object No Same filters as the list endpoint.

Example

curl -X POST "https://api.s4e.io/api/findings/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "filters": {
      "severity": "critical,high",
      "status": "open"
    }
  }' \
  -o findings-export.csv

Note

PDF exports include executive summary charts and detailed finding descriptions. Large exports are processed asynchronously --- the response includes a download URL that becomes available when processing completes.

Finding Statistics

GET /api/findings/stats

Returns aggregated finding statistics:

curl -X GET "https://api.s4e.io/api/findings/stats" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "data": {
    "total": 246,
    "by_severity": {
      "critical": 5,
      "high": 18,
      "medium": 67,
      "low": 89,
      "info": 67
    },
    "by_status": {
      "open": 142,
      "confirmed": 38,
      "resolved": 51,
      "false_positive": 10,
      "accepted_risk": 5
    },
    "trend": {
      "last_30_days": {
        "new": 34,
        "resolved": 22,
        "net_change": 12
      }
    }
  }
}

Severity Levels

Level CVSS Range Description
critical 9.0 - 10.0 Immediate action required.
high 7.0 - 8.9 Should be addressed promptly.
medium 4.0 - 6.9 Address in normal remediation cycles.
low 0.1 - 3.9 Low-priority issues.
info 0.0 Informational findings, no risk.

Field Reference

Field Type Description
id string Unique finding identifier.
title string Finding title.
severity string Severity level.
cvss number CVSS v3.1 score.
cvss_vector string CVSS vector string.
status string Current status.
asset object Associated asset (id, name, type).
scan_id string Scan that discovered the finding.
description string Detailed description.
remediation string Recommended remediation steps.
evidence object Technical evidence (URL, payload, etc.).
references array External reference URLs.
tags array Classification tags.
discovered_at string ISO 8601 discovery timestamp.
updated_at string ISO 8601 last update timestamp.

Next Steps