Vigolium API Reference, Findings

List, retrieve, and delete vulnerability findings with filtering, pagination, and severity-based queries.

GET /api/findings, List Findings

Returns paginated vulnerability findings.

Query parameters:

Parameter	Type	Default	Description
limit	int	50	Number of findings to return (max 500)
offset	int	0	Offset for pagination
domain	string		Filter by hostname (supports * wildcards)
severity	string		Filter by severity (comma-separated): critical, high, medium, low, info
scan_id	string		Filter by scan UUID
module_name	string		Filter by module name
module_type	string		Filter by module type: active or passive
finding_source	string		Filter by finding source: dynamic-assessment, known-issue-scan, agent, audit, oast, extension, import
search	string		Search across description, module ID, matched_at
sort	string	found_at	Sort field: found_at, created_at, severity, module_name, module_id, confidence
order	string	desc	Sort order: asc or desc

# List all findings
curl -s http://localhost:9002/api/findings | jq .

# Filter by severity
curl -s 'http://localhost:9002/api/findings?severity=critical,high' | jq .

# Filter by domain and module
curl -s 'http://localhost:9002/api/findings?domain=example.com&module_name=xss' | jq .

# Filter by module type
curl -s 'http://localhost:9002/api/findings?module_type=passive' | jq .

# Filter by finding source
curl -s 'http://localhost:9002/api/findings?finding_source=dynamic-assessment' | jq .

# Search findings
curl -s 'http://localhost:9002/api/findings?search=reflected' | jq .

{
  "data": [
    {
      "id": 1,
      "http_record_uuids": ["abc-123"],
      "scan_uuid": "scan-456",
      "module_id": "xss-scanner",
      "module_name": "XSS Scanner",
      "module_type": "active",
      "module_short": "Detects reflected cross-site scripting via parameter injection",
      "finding_source": "dynamic-assessment",
      "description": "Reflected XSS via parameter 'q'",
      "severity": "high",
      "confidence": "firm",
      "tags": ["xss", "reflected"],
      "matched_at": ["https://example.com/search?q=test"],
      "extracted_results": ["<script>alert(1)</script>"],
      "additional_evidence": [
        "GET /search?q=%3Cimg+src%3Dx+onerror%3Dalert(1)%3E HTTP/1.1\r\nHost: example.com\r\n\r\n\n---------\nHTTP/1.1 200 OK\r\nContent-Type: text/html\r\n\r\n..."
      ],
      "request": "GET /search?q=%3Cscript%3Ealert(1)%3C/script%3E HTTP/1.1\r\nHost: example.com\r\n\r\n",
      "response": "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\n\r\n...",
      "finding_hash": "e3b0c44298fc1c14",
      "found_at": "2026-02-16T15:05:00Z",
      "created_at": "2026-02-16T15:05:00Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0,
  "has_more": false
}

---

GET /api/findings/:id, Get Finding Detail

Returns a single finding by its numeric ID.

curl -s http://localhost:9002/api/findings/1 | jq .

{
  "id": 1,
  "http_record_uuids": ["abc-123"],
  "scan_uuid": "scan-456",
  "module_id": "xss-scanner",
  "module_name": "XSS Scanner",
  "module_type": "active",
  "module_short": "Detects reflected cross-site scripting via parameter injection",
  "finding_source": "dynamic-assessment",
  "description": "Reflected XSS via parameter 'q'",
  "severity": "high",
  "confidence": "firm",
  "tags": ["xss", "reflected"],
  "matched_at": ["https://example.com/search?q=test"],
  "extracted_results": ["<script>alert(1)</script>"],
  "additional_evidence": [
    "GET /search?q=%3Cimg+src%3Dx+onerror%3Dalert(1)%3E HTTP/1.1\r\nHost: example.com\r\n\r\n\n---------\nHTTP/1.1 200 OK\r\nContent-Type: text/html\r\n\r\n..."
  ],
  "request": "GET /search?q=%3Cscript%3Ealert(1)%3C/script%3E HTTP/1.1\r\nHost: example.com\r\n\r\n",
  "response": "HTTP/1.1 200 OK\r\nContent-Type: text/html\r\n\r\n...",
  "finding_hash": "e3b0c44298fc1c14",
  "found_at": "2026-02-16T15:05:00Z",
  "created_at": "2026-02-16T15:05:00Z"
}

Error responses:

Code	Condition
400	Invalid ID (not a number)
404	Finding not found
503	Database unavailable

---

PATCH /api/findings/:id/status, Update Finding Status

Sets the workflow status on a finding (e.g. open / triaged / closed). The status field is opaque to the server — any string is accepted.

curl -s -X PATCH http://localhost:9002/api/findings/42/status \
  -H "Content-Type: application/json" \
  -d '{"status": "triaged"}' | jq .

{
  "id": 42,
  "status": "triaged"
}

Status	Description
200	Status updated
400	Invalid ID or body
404	Finding not found
503	Database not configured

Since v0.5.3 the status is a real lifecycle, matching vigolium finding mark: draft → triaged → confirmed → fixed, with false_positive and accepted_risk as dismissed exits. Dismissed findings are left out of the --fail-on gate, scan diff and finding --new-since by default.

---

POST /api/findings/:id/verify, Verify a Finding

Added in v0.5.3 — vigolium finding verify over REST (operator and admin). Re-runs the module behind one finding against the request it originally scanned and records whether it reproduces. :id is the numeric ID or the finding hash (12+ character prefix); the lookup is scoped to X-Project-UUID, so a finding from another project returns 404 (error_code: finding_not_found). The call is synchronous — it answers when the module run ends.

Verdict	Meaning
confirmed	The module reported the same finding again
not_reproduced	The module ran against a responding target and did not
inconclusive	Target unreachable, module timed out or failed, or the baseline could not be reconstructed
unsupported	No deterministic re-run exists (agent, audit, OAST and known-issue-scan findings; an ext-* module the project’s extension config does not load)

Request body (all optional):

Field	Type	Description
dry_run	bool	Return the reconstruction (module, baseline, insertion point); send and write nothing
no_write	bool	Run, but do not store the verdict
mark	bool	Also set the status: not_reproduced → false_positive, confirmed → confirmed (not with dry_run / no_write)
refetch	bool	Passive findings: fetch a fresh response instead of re-analyzing the stored one
rate_limit	number	Max requests/second (0 = unlimited; fractions allowed)
timeout	string	Go duration bounding the run (default 2m, at most 10m; one request is capped at 15 s)

curl -s -X POST http://localhost:9002/api/findings/42/verify \
  -H 'Content-Type: application/json' \
  -d '{"mark":true}' | jq .

The response is the same result object vigolium finding verify -j emits.

---

DELETE /api/findings/:id, Delete Finding

Deletes a single finding by its numeric ID. Associated finding_records junction rows are also removed.

curl -s -X DELETE http://localhost:9002/api/findings/42 | jq .

Response:

{
  "message": "finding deleted",
  "id": 42
}

Status	Description
200	Finding deleted
400	Invalid ID (not a number)
404	Finding not found
503	Database not configured

---

Finding Fields

additional_evidence

Type: string[] (optional, omitted when empty)

Stores extra HTTP request/response pairs associated with a finding. Each entry is a single string containing a raw request and raw response separated by the delimiter \n---------\n.

This field is populated in two ways:

1. Modules and extensions: A module or JS extension can attach supplementary evidence when creating a finding (e.g., multiple payloads tried, confirmation requests, or baseline comparisons).
2. Deduplication: When duplicate findings are merged (same module_id, severity, and matched_at URL), the request/response pairs from the removed duplicates are automatically collected into the surviving finding’s additional_evidence.

Example entry format:

GET /api?id=1'+OR+1=1 HTTP/1.1\r\nHost: example.com\r\n\r\n
---------
HTTP/1.1 500 Internal Server Error\r\n\r\n{"error":"syntax error"}

To parse an entry, split on \n---------\n, the first part is the request, the second is the response.