# 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

| Parameter                | Type     | Required | Description                                                          |
|--------------------------|----------|----------|----------------------------------------------------------------------|
| `applicationId`         | integer  | yes      | Internal numeric application id.                                     |
| `applicationPublicId`   | string   | yes      | Public/external application identifier.                              |
| `reportId`              | string   | yes      | Identifier for the vulnerability report (UUID or server-side id).   |

## 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"
  }'
```