---
title: "Findings"
description: "States"
canonical_url: "https://docs.cobalt.io/articles/findings-D4kEiuzfAW"
md_url: "https://docs.cobalt.io/articles/findings-D4kEiuzfAW.md"
---
# Findings

## **States**

The table below describes how the finding state values used by the API correspond to finding states shown in the user interface.

| **API Value** | **UI Name** | **Description** |
|----|----|----|
| new | Draft | A pentester has created a draft finding but has not yet submitted it for triaging |
| triaging | Triaging | The finding is being triaged |
| need_fix | Pending Fix | The finding is valid and needs to be fixed |
| check_fix | Ready for Retest | A fix is awaiting validation by a pentester |
| valid_fix | Fixed | The finding was fixed and validated by a pentester |
| wont_fix | Accepted Risk | The risk has been accepted. The finding will not be fixed |
| carried_over | Carried Over | The finding was carried over from a previous pentest |
| not_applicable | Not Applicable | The finding is not applicable |
| invalid | Invalid | The finding is invalid |
| duplicate | Invalid | The finding is invalid (deprecated state) |
| stale | Invalid | The finding is invalid (deprecated state) |
| out_of_scope | Invalid | The finding is invalid (deprecated state) |

## **Get All Findings**

This endpoint retrieves a list of all pentest findings that belong to the organization specified in the `X-Org-Token header`, filterable by `pentest_id` or `asset_id`. The `log` array presents a history of each finding and corresponding timestamp.

### **Calculations**

We follow the standard risk model described by OWASP, where:

`Risk = Impact * Likelihood`

Cobalt Risk Input Fields:

* `impact`: 1, 2, 3, 4, or 5
* `likelihood`: 1, 2, 3, 4, or 5

Cobalt Risk Classification (`severity`, a.k.a. `criticality`):

| **Category** | **Score** | **Description** |
|----|----|----|
| `critical` | 25 | Includes vulnerabilities that require immediate attention. |
| `high` | 16-24 | Impacts the security of your application/platform/hardware, including supported systems. Includes high probability vulnerabilities with a high business impact. |
| `medium` | 5-15 | Includes vulnerabilities that are: medium risk, medium impact; low risk, high impact; high risk, low impact. |
| `low` | 2-4 | Specifies common vulnerabilities with minimal impact. |
| `informational` | 1 | Notes vulnerabilities of minimal risk to your business. |

### **HTTP Request**

`GET https://api.us.cobalt.io/findings`

### **URL Parameters**

| **Parameter** | **Default** | **Description** |
|----|----|----|
| `cursor` | N/A | Used for [pagination](https://docs.cobalt.io/en-us/articles/pagination-vzZ5elaKl7). Example: `https://api.us.cobalt.io/findings?cursor=a1b2c3d4` |
| `limit` | `10` | If specified, returns only a specified amount of findings. Example: `https://api.us.cobalt.io/findings?limit=`5 |
| `pentest` | N/A | If specified, returns findings scoped to this pentest id. Example: `https://api.us.cobalt.io/findings?pentest=pt_PEtv4dqnwGV2efZhLw3BM5` |
| `asset` | N/A | If specified, returns findings scoped to this asset id. Example: h`ttps://api.us.cobalt.io/findings?asset=as_HcChCMueiPQQgvckmZtRSd` |
| `state` | N/A | If specified, returns findings that match `state`. See Response Fields below for example `state` values. Example: `https://api.us.cobalt.io/findings?state=check_fix`. Returns an empty list if no findings match the `state` filter. |
| `severity` | N/A | If specified, returns findings that match `severity`. See Response Fields below for example `severity` values. Example: `https://api.us.cobalt.io/findings?severity=medium`. Returns an empty list if no findings match the `severity` filter. |
| `labels_contains_all[]` | N/A | If specified, returns findings that contain all specified labels. This query parameter can be specified multiple times. Returns an empty list if no matches are found. Example: `https://api.us.cobalt.io/findings?labels_contains_all[]=Awaiting Feedback&labels_contains_all[]=Retest Blocked` |
| `sort` | N/A | If specified, returns findings sorted by one of the chosen parameters: `severity`, `impact`, `state`, `created_at` and `updated_at`. When defined, findings are sorted in ascending order by the sort parameter. To sort in descending order, use a `-` before the sort parameter. Example: `https://api.us.cobalt.io/findings?sort=-severity.` |
| `created_at_lte` | N/A | If specified, returns findings where the created_at timestamp is less than or equal to the input timestamp. ISO8601 is the supported input timestamp format. Returns an empty list if no findings match the filter. Example: `https://api.us.cobalt.io/findings?created_at_lte=2020-02-20T15:28:10.335Z` |
| `created_at_gte` | N/A | If specified, returns findings where the created_at timestamp is greater than or equal to the input timestamp. ISO8601 is the supported input timestamp format. Returns an empty list if no findings match the filter. Example: `https://api.us.cobalt.io/findings?created_at_gte=2020-02-20T15:28:10.335Z` |
| `updated_at_lte` | N/A | If specified, returns findings where the updated_at timestamp is less than or equal to the input timestamp. ISO8601 is the supported input timestamp format. Returns an empty list if no findings match the filter. Example: `https://api.us.cobalt.io/findings?updated_at_lte=2020-02-20T15:28:10.335Z` |
| `updated_at_gte` | N/A | If specified, returns findings where the updated_at timestamp is greater than or equal to the input timestamp. ISO8601 is the supported input timestamp format. Returns an empty list if no findings match the filter. Example: `https://api.us.cobalt.io/findings?updated_at_gte=2020-02-20T15:28:10.335Z` |
| `image_attachments_render_format` | `markdown` | If specified, returns image attachments with the specified render format. Supported values are `markdown` and `token`. Example: `https://api.us.cobalt.io/findings?image_attachments_render_format=token`. See the Image Attachments section for more information |

### **Response Fields**

| **Field** | **Enum Types** |
|----|----|
| `log` | `created`, `impact_changed`, `likelihood_changed`, `state_changed` |
| `severity` | `null`, `low`, `medium`, `high` (aka `criticality`. will be null if likelihood/impact have not yet been set by the pentester) |
| `severity_justification` | Optional; The justification for the severity rating |
| `prerequisites` | Optional; The prerequisites required for reproducing the vulnerability |
| `http_request` | Optional; An example HTTP request for reproducing the vulnerability |
| `state` | See [Finding States Documentation](https://docs.cobalt.io/en-us/articles/findings-D4kEiuzfAW#h-states) |
| `type_category` | XSS, SQLi, … (about 30 more via the Cobalt Taxonomy) |
| `attachments` | A list of finding attachments. Attachment download URLs are pre-authorized and will expire after 10 minutes. |
| `cvsss` | A list of associated [CVSS](https://www.first.org/cvss/) records |
| `ref_key` | A user-defined field for adding unique identifiers to findings, aiding tracking and linking to external systems. |
| `predecessor_id` | The ID of the original finding that this finding was created from during the carry-over process. `null` if this finding was not created via the carry-over process. |
| `successor_id` | The ID of the finding that was created from this finding during the carry-over process. `null` if this finding was not carried over. |
| `links.ui.url` | A link to redirect an authorized user to this finding in the Cobalt web application |

### **Image Attachments**

Several finding response fields support image attachments. By default, these attachments are rendered in our response JSON as markdown. For example: `![screenshot.png](https://api.us.cobalt.io/v1/attachments/att_xxxxxxx/preview)`. This format is not useful for users who want to programmatically download the attachments and associate them with a specific position in the finding response. For this use case, we support a token format, which renders the attachment as a token that can be used to download the attachment. For example: `<CobaltImageAttachment at_KYKDAhZPXuQ4BW23g8i9QN>`. The token format allows users to employ a technology such as RegEx to search the finding response fields for image attachments and extract the image attachment IDs. In the example token, `at_KYKDAhZPXuQ4BW23g8i9QN` is the attachment ID. Users can use the attachment ID to locate the full attachment information by searching the `attachments` array in the finding response for an object with a matching ID. The attachment object includes a `download_url` field that can be used to download the attachment.

```javascript
curl -X GET "https://api.us.cobalt.io/findings" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"
```

The above command returns JSON structured like this:

```javascript
{
  "data": [
    {
      "resource": {
        "id": "vl_3sP2RCWWUajc3oRXmbQ4j9",
        "tag": "#PT3334_37",
        "title": "XSS vulnerability",
        "description": "Cross-Site Scripting (XSS) attacks are a type of injection, in which malicious scripts...",
        "type_category": "Cross-Site Scripting (XSS)",
        "labels": [
          {
            "name": "Your label"
          }
        ],
        "impact": 5,
        "likelihood": 4,
        "severity": "high",
        "affected_targets": [
          "https://example.com",
          "192.168.1.1"
        ],
        "proof_of_concept": "Here you can see...",
        "severity_justification": "The vulnerability can cause a lot of damage",
        "suggested_fix": "Ensure this...",
        "prerequisites": "Credentials are needed",
        "pentest_id": "pt_PEtv4dqnwGV2efZhLw3BM5",
        "http_request": "HTTP GET / ...",
        "asset_id": "as_HcChCMueiPQQgvckmZtRSd",
        "log": [
          {
            "action": "created",
            "timestamp": "2021-04-01T15:13:24.322Z"
          },
          {
            "action": "likelihood_changed",
            "value": 4,
            "timestamp": "2021-04-01T15:14:05.856Z"
          },
          {
            "action": "impact_changed",
            "value": 5,
            "timestamp": "2021-04-01T15:14:05.856Z"
          },
          {
            "action": "state_changed",
            "value": "need_fix",
            "timestamp": "2021-04-01T15:14:06.757Z"
          },
          {
            "action": "state_changed",
            "value": "check_fix",
            "timestamp": "2021-04-01T15:14:57.845Z"
          }
        ],
        "state": "check_fix",
        "created_at": "2022-09-26T18:35:18.759Z",
        "updated_at": "2022-09-26T18:36:57.462Z",
        "attachments": [
          {
            "id": "at_LA5GcEL4HRitFGCHREqmzL",
            "file_name": "rainbow.jpeg",
            "download_url": "https://s3.amazonaws.com/acmecorp/uploads/attachment/file/12345/rainbow.jpeg?something=1"
          }
        ],
        "cvsss": [
          {
            "score": 5.3,
            "severity": "Medium",
            "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:N/A:N",
            "version": "3.1"
          }
        ],
        "ref_key":"#ExampleRef",
        "predecessor_id": null,
        "successor_id": null
      },
      "links": {
        "ui": {
          "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
        }
      }
    }
  ],
  "pagination": {
    "next_page": "/findings?cursor=a1b2c3d4",
    "prev_page": "/findings?cursor=4d3c2b1a"
  }
}
```


:::info
Remember - you can only request findings scoped to the organization specified in the `X-Org-Token` header.

:::


---

## **Get a Finding**

This endpoint retrieves a specific finding that belong to the organization specified in the `X-Org-Token` header.

### **HTTP Request**

`GET https://api.us.cobalt.io/findings/YOUR-FINDING-IDENTIFIER`

### **URL Parameters**

| **Parameter** | **Default** | **Description** |
|----|----|----|
| `image_attachments_render_format` | `markdown` | If specified, returns image attachments with the specified render format. Supported values are `markdown` and `token`. Example: `https://api.us.cobalt.io/findings/YOUR-FINDING-IDENTIFIER?image_attachments_render_format=token`. See the Image Attachments section for more information |

### **Response Fields**

| **Field** | **Enum Types** |
|----|----|
| `log` | created, impact_changed, likelihood_changed, state_changed |
| `severity` | null, low, medium, high (aka `criticality`. will be null if likelihood/impact have not yet been set by the pentester) |
| `severity_justification` | Optional; The justification for the severity rating |
| `prerequisites` | Optional; The prerequisites required for reproducing the vulnerability |
| `http_request` | Optional; An example HTTP request for reproducing the vulnerability |
| `state` | See [Finding States Documentation](https://docs.cobalt.io/en-us/articles/findings-D4kEiuzfAW#h-states) |
| `type_category` | XSS, SQLi, … (about 30 more via the Cobalt Taxonomy) |
| `attachments` | A list of finding attachments. Attachment download URLs are pre-authorized and will expire after 10 minutes. |
| `cvsss` | A list of associated [CVSS](https://www.first.org/cvss/) records |
| `ref_key` | A user-defined field for adding unique identifiers to findings, aiding tracking and linking to external systems. |
| `predecessor_id` | The ID of the original finding that this finding was created from during the carry-over process. `null` if this finding was not created via the carry-over process. |
| `successor_id` | The ID of the finding that was created from this finding during the carry-over process. `null` if this finding was not carried over. |
| `url` | The links.ui.url will redirect an authorized user to this finding in the Cobalt platform |

### **Image Attachments**

Several finding response fields support image attachments. By default, these attachments are rendered in our response JSON as markdown. For example: `![screenshot.png](https://api.us.cobalt.io/v1/attachments/att_xxxxxxx/preview)`. This format is not useful for users who want to programmatically download the attachments and associate them with a specific position in the finding response. For this use case, we support a token format, which renders the attachment as a token that can be used to download the attachment. For example: `<CobaltImageAttachment at_KYKDAhZPXuQ4BW23g8i9QN>`. The token format allows users to employ a technology such as RegEx to search the finding response fields for image attachments and extract the image attachment IDs. In the example token, `at_KYKDAhZPXuQ4BW23g8i9QN` is the attachment ID. Users can use the attachment ID to locate the full attachment information by searching the `attachments` array in the finding response for an object with a matching ID. The attachment object includes a `download_url` field that can be used to download the attachment.

```javascript
curl -X GET "https://api.us.cobalt.io/findings/YOUR-FINDING-IDENTIFIER" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"
```

The above command returns JSON structured like this:

```javascript
{
  "resource": {
    "id": "vl_3sP2RCWWUajc3oRXmbQ4j9",
    "tag": "#PT5940",
    "title": "XSS vulnerability",
    "description": "Cross-Site Scripting (XSS) attacks are a type of injection, in which malicious scripts...",
    "type_category": "Cross-Site Scripting (XSS)",
    "labels": [
      {
        "name": "Your label"
      }
    ],
    "impact": 5,
    "likelihood": 4,
    "severity": "high",
    "affected_targets": [
      "https://example.com",
      "192.168.1.1"
    ],
    "proof_of_concept": "Here you can see...",
    "severity_justification": "The vulnerability can cause a lot of damage",
    "suggested_fix": "Ensure this...",
    "prerequisites": "Credentials are needed",
    "pentest_id": "pt_PEtv4dqnwGV2efZhLw3BM5",
    "http_request": "HTTP GET / ...",
    "asset_id": "as_HcChCMueiPQQgvckmZtRSd",
    "log": [
      {
        "action": "created",
        "timestamp": "2021-09-22T18:43:01.677Z"
      }
    ],
    "state": "new",
    "created_at": "2022-09-26T18:35:18.759Z",
    "updated_at": "2022-09-26T18:36:57.462Z",
    "attachments": [
      {
        "id": "at_LA5GcEL4HRitFGCHREqmzL",
        "file_name": "rainbow.jpeg",
        "download_url": "https://s3.amazonaws.com/acmecorp/uploads/attachment/file/12345/rainbow.jpeg?something=1"
      }
    ],
    "cvsss": [
      {
        "score": 5.3,
        "severity": "Medium",
        "vector": "CVSS:3.1/AV:N/AC:L/PR:N/UI:N/S:U/C:L/I:N/A:N",
        "version": "3.1"
      }
    ],
    "ref_key":"#ExampleRef",
    "predecessor_id": null,
    "successor_id": null
  },
  "links": {
    "ui": {
      "url": "https://api.us.cobalt.io/links/eyJ0eXBlIjoic29tZXRoaW5nIiwib3JnU2x1ZyI6ImNvYmFsdCIsInBlbnRlc3RUYWciOiJz="
    }
  }
}
```



:::info
Remember - you can only request a finding scoped to the organization specified in the `X-Org-Token` header.

:::

## **View Available Finding States**

This endpoint retrieves the current state of a finding as well as possible next states.

### **HTTP Request**

`GET https://api.us.cobalt.io/findings/YOUR-FINDING-ID/possible_states`

### **URL Parameters**

| **Parameter** | **Description** |
|----|----|
| `YOUR-FINDING-ID` | A unique ID representing the finding. Starts with `vl_` |

### **Response Fields**

| **Field** | **Description** |
|----|----|
| `current_state` | The current state of the finding. |
| `possible_states` | A list of states that the finding can be transitioned to. See [Finding States Documentation](https://docs.cobalt.io/en-us/articles/findings-D4kEiuzfAW#h-states) |

```javascript
curl -X GET "https://api.us.cobalt.io/findings/YOUR-FINDING-ID/possible_states" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN"
```

The above command returns JSON structured like this:

```javascript
{
  "resource": {
    "current_state": "invalid",
    "possible_states": [
      "triaging",
      "need_fix",
      "duplicate",
      "out_of_scope"
    ]
  }
}
```


---

## **Update Finding State**

This endpoint updates the current state of a finding.

### **HTTP Request**

`PATCH https://api.us.cobalt.io/findings/YOUR-FINDING-ID`

### **URL Parameters**

| **Parameter** | **Description** |
|----|----|
| `YOUR-FINDING-ID` | A unique ID representing the finding. Starts with `vl_` |

### **Body**

| **Field** | **Description** |
|----|----|
| `state` | The desired next state of the finding. Should be one of the possible [states](https://docs.cobalt.io/en-us/articles/findings-D4kEiuzfAW#h-states). |

```javascript
curl -X PATCH "https://api.us.cobalt.io/findings/YOUR-FINDING-ID" \
  -H "Accept: application/vnd.cobalt.v2+json" \
  -H "Content-Type: application/vnd.cobalt.v2+json" \
  -H "Idempotency-Key: A-UNIQUE-IDENTIFIER-TO-PREVENT-UNINTENTIONAL-DUPLICATION" \
  -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
  -H "X-Org-Token: YOUR-V2-ORGANIZATION-TOKEN" \
  -d '{"state":"triaging"}'
```