Signatures REST API

The Signatures REST API allows clients to submit vulnerability signature/evidence items and reachability information for a particular application vulnerability report. Use these endpoints to attach additional evidence (fingerprints, code locations, tool metadata, etc.) to a report, and to indicate whether a vulnerability is reachable for the given application and report.

Warning
This is an experimental REST API.

Methods supported:

• POST

Base endpoints:

POST /api/experimental/signatures/vulnerability/applications/{applicationId}/reports/{reportId}

POST /api/experimental/signatures/vulnerability/application/publicId/{applicationPublicId}/report/{reportId}

POST /api/experimental/signatures/vulnerability/applications/{applicationId}/reports/{reportId}/reachable

POST /api/experimental/signatures/vulnerability/application/publicId/{applicationPublicId}/report/{reportId}/reachable

Note
Use the {applicationId} variant when you have the internal numeric application id. Use the {applicationPublicId} variant when you have the public/external application identifier.

Authentication and permissions

These endpoints use the same authentication and permission model as other Lifecycle REST APIs. Include a valid authentication token or credentials appropriate to your deployment, and ensure the calling user or token has the required permissions to submit signatures and reachability information.

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

Path parameters

Submit signatures

POST /api/experimental/signatures/vulnerability/applications/{applicationId}/reports/{reportId}

POST /api/experimental/signatures/vulnerability/application/publicId/{applicationPublicId}/report/{reportId}

Purpose
Submit one or more signature objects (evidence, fingerprints, analysis metadata) for the specified application report.

Request

• Content-Type: application/json
• Body: JSON object containing an array field signatures with one or more signature objects.

Example - single signature

{
  "signatures": [
    {
      "vulnerabilityId": "CVE-2024-12345",
      "source": "static-analysis",
      "fingerprint": "sha256:abcdef123456...",
      "evidence": "src/main/java/com/example/Unsafe.java:doDangerous()",
      "details": {
        "filePath": "src/main/java/com/example/Unsafe.java",
        "lineStart": 120,
        "lineEnd": 128,
        "method": "doDangerous",
        "tool": "ExampleScanner",
        "analysisId": "scan-2026-01-15-01",
        "confidence": "high"
      },
      "notes": "Added by automated CI scanner",
      "timestamp": "2026-02-01T12:34:56Z"
    }
  ]
}

Example - bulk signatures

{
  "signatures": [
    { "vulnerabilityId": "CVE-2024-12345", "fingerprint": "sha256:aaa...", "source": "dynamic-analysis" },
    { "vulnerabilityId": "CVE-2024-23456", "fingerprint": "sha256:bbb...", "source": "static-analysis" }
  ]
}

Note Must include vulnerabilityId.

Provide fingerprint (or unique id) for dedup/idempotency.

Prefer structured details (e.g., filePath, lineStart, lineEnd, method, tool, confidence).

API is experimental - object shape may change.

Responses

• 200 OK - signatures processed successfully (synchronous).
• 202 Accepted - accepted and queued for background/asynchronous processing.
• 400 Bad Request - malformed JSON or invalid top-level request.
• 401 Unauthorized - authentication error.
• 404 Not Found - specified application or report not found.
• 422 Unprocessable Entity - validation failure for one or more signatures; response contains details.

Example - cURL

curl -u admin:password \
  -X POST "https://<iq-server>/api/experimental/signatures/vulnerability/applications/12345/reports/abcd-ef01-2345" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "signatures":[
      {
        "vulnerabilityId":"CVE-2024-12345",
        "source":"static-analysis",
        "fingerprint":"sha256:abcdef123...",
        "evidence":"src/main/java/com/example/Unsafe.java:line 125",
        "details":{"filePath":"src/main/java/com/example/Unsafe.java","lineStart":120,"lineEnd":128,"confidence":"high"}
      }
    ]
  }'

Typical success response (example)

{
  "status": "accepted",
  "processed": 1,
  "queued": 0,
  "signatures": [
    { "fingerprint": "sha256:abcdef123...", "result": "accepted", "signatureId": "sig-123456" }
  ]
}

Submit reachability information

POST /api/experimental/signatures/vulnerability/applications/{applicationId}/reports/{reportId}/reachable

POST /api/experimental/signatures/vulnerability/application/publicId/{applicationPublicId}/report/{reportId}/reachable

Purpose
Attach reachability information for vulnerabilities in the specified report (whether the vulnerability is reachable, evidence and a confidence level).

Request

• Content-Type: application/json
• Body: either a single reachability object or a reachability array for multiple vulnerabilities.

Example - Single vulnerability

{
  "vulnerabilityId": "CVE-2024-12345",
  "reachable": true,
  "evidence": "Call graph shows tainted data reaching doDangerous()",
  "confidence": "medium",
  "timestamp": "2026-02-01T12:34:56Z",
  "author": "automated-analysis"
}

Example - Bulk reachability

{
  "reachability": [
    { "vulnerabilityId": "CVE-2024-12345", "reachable": true, "confidence": "high" },
    { "vulnerabilityId": "CVE-2024-23456", "reachable": false, "confidence": "low" }
  ]
}

Responses

• 200 OK - reachability information accepted and applied.
• 202 Accepted - accepted and queued for processing.
• 400 / 401 / 404 / 422 - same semantics as the signatures endpoints.

Example cURL

curl -u admin:password \
  -X POST "https://<iq-server>/api/experimental/signatures/vulnerability/applications/12345/reports/abcd-ef01-2345/reachable" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "vulnerabilityId":"CVE-2024-12345",
    "reachable":true,
    "evidence":"Dynamic analysis verified path",
    "confidence":"high"
  }'