NAV
Shell

Introduction

The Cobalt API gives you REST access to Orgs, Assets, Pentests, Findings, and Events, and is currently read-only.

Authentication

To authorize, give this a try:

curl https://api.cobalt.io/orgs \
  -H "Authorization: Bearer your-personal-API-token-here"

Make sure to replace your-personal-API-token-here with your actual API token.

Cobalt uses API tokens to allow access to various endpoints. You can create a new Cobalt API token from within your Cobalt profile.

Cobalt expects the API token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer your-personal-API-token-here

Our Living Documentation and API Explorer are located in Swagger and built with the OpenAPI specification.

Orgs

Get All Orgs

curl -X GET "https://api.cobalt.io/orgs" \
  -H "accept: application/vnd.cobalt.v1+json" \
  -H "Authorization: Bearer your-personal-api-token-here"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "1955",
        "name": "Acme Co",
        "token": "save-this-org-token"
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/long-web-app-redirect-to-acme-org"
        }
      }
    },
    {
      "resource": {
        "id": "2546",
        "name": "E Corp",
        "token": "or-save-this-org-token"
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/long-web-app-redirect-to-e-corp-org"
        }
      }
    }
  ]
}

This endpoint retrieves a list of organizations, i.e. orgs, that you belong to. Save the token field to be used in your X-Org-Token header in subsequent calls in querying for assets, findings, pentests and events that belong to that org.

HTTP Request

GET https://api.cobalt.io/orgs

Fields

FieldDescription
idThe Cobalt id of the org
nameThe name of the org
tokenThe org token you'll need in subsequent calls
urlThe links.ui.url will redirect an authorized user to this org in the Cobalt platform

Assets

Get All Assets

curl -X GET "https://api.cobalt.io/assets" \
  -H "accept: application/vnd.cobalt.v1+json" \
  -H "Authorization: Bearer your-personal-api-token-here" \
  -H "X-Org-Token: your-org-token-here"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "as_rvZRC5Y",
        "title": "Azure External Network ",
        "description": "Test text",
        "asset_type": "external_network",
        "attachments": []
      }
    }
 ]
}

This endpoint retrieves a list of assets that belong to the org specified in the header.

HTTP Request

GET https://api.cobalt.io/assets

Fields

FieldDescription
idThe Cobalt id of the asset
titleThe title of the asset
descriptionA description of the asset
asset_typeapi, cloud_config, external_network, internal_network, mobile, web, web_plus_api, web_plus_mobile

Pentests

Get All Pentests

curl -X GET "https://api.cobalt.io/pentests" \
  -H "accept: application/vnd.cobalt.v1+json" \
  -H "Authorization: Bearer your-personal-api-token-here" \
  -H "X-Org-Token: your-org-token-here"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "pt_rVShby8",
        "title": "API Test - February 2021",
        "objectives": "",
        "state": "new",
        "tag": "#PT5940",
        "asset_id": null,
        "platform_tags": [],
        "methodology": null,
        "targets": [],
        "start_date": null,
        "end_date": null
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/long-web-app-redirect-to-this-pentest"
        }
      }
    }
 ]
}

This endpoint retrieves a list of all pentests that belong to the org specified in the header.

HTTP Request

GET https://api.cobalt.io/pentests

Fields

FieldEnum Types
statenew, in_review, planned, cancelled, live, remediation, closed
urlThe links.ui.url will redirect an authorized user to this pentest in the Cobalt platform

Findings

Get All Findings

curl -X GET "https://api.cobalt.io/findings" \
  -H "accept: application/vnd.cobalt.v1+json" \
  -H "Authorization: Bearer your-personal-api-token-here" \
  -H "X-Org-Token: your-org-token-here"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "vu_2wXY3bq",
        "tag": "#PT3334_37",
        "title": "SQL Injection",
        "description": "A SQL injection attack...",
        "type_category": null,
        "labels": [
          {
            "name": "Your label"
          }
        ],
        "impact": 5,
        "likelihood": 4,
        "severity": "high",
        "affected_targets": [ ""],
        "proof_of_concept": null,
        "suggested_fix": "Ensure this...",
        "pentest_id": "pt_9Ig1234",
        "asset_id": "as_cwrsqsL",
        "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"
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/long-web-app-redirect-to-this-finding"
        }
      }
    }
 ]
}

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

Calculations

Cobalt Risk Input Fields

Cobalt Risk Classification

HTTP Request

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

Fields

FieldEnum Types
logcreated, impact_changed, likelihood_changed, state_changed
severitynull, low, medium, high (severity, aka criticality in our web app, will be null for findings where their likelihood/impact have not yet been set)
statenew, triaging, need_fix, wont_fix, valid_fix, check_fix, invalid, carried_over
type_categoryXSS, SQLi, … (about 30 more via the Cobalt Taxonomy)
urlThe links.ui.url will redirect an authorized user to this finding in the Cobalt platform

Get Specific Findings

curl -X GET "https://api.cobalt.io/findings?pentest=pt_9Ig" \
  -H "accept: application/vnd.cobalt.v1+json" \
  -H "Authorization: Bearer your-personal-api-token-here" \
  -H "X-Org-Token: your-org-token-here"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "vu_2wXY3bq",
        "tag": "#PT3334_37",
        "title": "SQL Injection",
        "description": "A SQL injection attack...",
        "type_category": null,
        "labels": [],
        "impact": 4,
        "likelihood": 4,
        "severity": "high",
        "affected_targets": [ ""],
        "proof_of_concept": null,
        "suggested_fix": "Ensure this...",
        "pentest_id": "pt_9Ig",
        "asset_id": "as_cwrsqsL",
        "log": [],
        "state": "need_fix"
      },
      "links": {
        "ui": {
          "url": "https://api.cobalt.io/links/long-web-app-redirect-to-this-finding"
        }
      }
    }
 ]
}

You can filter for findings scoped to a specific pentest or asset.

HTTP Requests

GET https://api.cobalt.io/findings?pentest=pt_9Ig

GET https://api.cobalt.io/findings?asset=as_cwrsqsL

URL Parameters

ParameterDefaultDescription
pentestn/aIf specified, returns findings scoped to this pentest id, e.g. https://api.cobalt.io/findings?pentest=pt_9Ig
assetn/aIf specified, returns findings scoped to this asset id, e.g. https://api.cobalt.io/findings?asset=as_cwrsqsL

Events

Get All Events

curl -X GET "https://api.cobalt.io/events" \
  -H "accept: application/vnd.cobalt.v1+json" \
  -H "Authorization: Bearer your-personal-api-token-here" \
  -H "X-Org-Token: your-org-token-here"

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "277603",
        "action": "comment_created",
        "subject": {
          "id": "277603",
          "type": "comment"
        }
      }
    },
    {
      "resource": {
        "id": "277600",
        "action": "pentest_deleted",
        "subject": {
          "id": "277600",
          "type": "program"
        }
      }
    },
    {
      "resource": {
        "id": "277567",
        "action": "finding_created",
        "subject": {
          "id": "277567",
          "type": "vulnerability"
        }
      }
    }
 ]
}

This endpoint retrieves a list of all events happening across the org specified in the header.

HTTP Request

GET https://api.cobalt.io/events

Tokens

Get All Tokens

curl -X GET "https://api.cobalt.io/tokens" \
  -H "accept: application/vnd.cobalt.v1+json" \
  -H "Authorization: Bearer your-personal-api-token-here" 

The above command returns JSON structured like this:

{
  "data": [
    {
      "resource": {
        "id": "34",
        "last_characters": "9qy7",
        "expire_at": null
      }
    }
 ]
}

This endpoint retrieves a list of all tokens that belong to you.

HTTP Request

GET https://api.cobalt.io/tokens

Fields

FieldDescription
idInteger field used in the POST request to refresh your token
last_charactersLast four characters of your token for recall
expire_atnull (not currently implemented)

Refresh Token

curl -X POST "https://api.cobalt.io/tokens/token-id-here/refresh" \
  -H "accept: application/vnd.cobalt.v1+json" \
  -H "Authorization: Bearer your-personal-api-token-here" 

The above command returns JSON structured like this:

{
  "id": "40",
  "secret": "your-new-personal-API-token-here",
  "expire_at": null
}

You can obtain a new token with a POST request to the token refresh endpoint, referencing the token id fetched from the GET tokens endpoint.

For example, with a valid API token you would first make a GET request to list your tokens, note your current token id in this response, and then use that id in the refresh endpoint URL. This will give you a new token back as secret - note it, as your old token will no longer work.

If you've forgotten your token, you can always re-authenticate in the Cobalt web app, go to your profile, revoke and generate a new token.

HTTP Request

POST https://api.cobalt.io/tokens/token-id-here/refresh

Fields

FieldDescription
idYour new API token id
secretYour new personal API token - note it for future API requests
expire_atnull (not currently implemented)

Errors

The Cobalt API uses the following error codes:

Error CodeMeaning
400Bad Request – Your request is not good
401Unauthorized – Your API token is wrong
403Forbidden – You don't have access to this
404Not Found – The specified request could not be found
405Method Not Allowed – You tried to access Cobalt data with an invalid method
406Not Acceptable – You requested a format that isn't json
410Gone – The requested endpoint has been removed from Cobalt servers
418I'm a teapot
422Unprocessable Entity – The content and syntax are correctly formed, but something else is off.
429Too Many Requests – You're making requests too often! Slow down!
500Internal Server Error – We had a problem with our server. Try again later.
503Service Unavailable – We're temporarially offline for maintanance. Please try again later.