Retrieve Findings and Import Them to Google Sheets

Learn how to retrieve all findings using the Cobalt API and import them to Google Sheets.

Use this document with our Cobalt API documentation to retrieve Cobalt findings for all pentests.

Complete the following steps:

To use our API, you need a Cobalt account with membership in your organization. Your organization owner can create an account and assign you as a member. Your organization owner is typically the user who interacts with the Cobalt Customer Success Manager (CSM).

Step 1: Create an API Token in the Cobalt UI

To use the Cobalt API, you need a personal API token.

  1. Navigate to https://app.cobalt.io/settings/api-tokens.
  2. If needed, sign in to the app.
  3. Enter an API Token Name.
  4. Select Generate New Token.
  5. In the modal that appears, you should see your API Token, in the Secret Token field.

Save the API Token. After you close the overlay, you won’t see the full token again. If you lose it, you may have to revoke the token and start over.

Substitute the API token for YOUR-PERSONAL-API-TOKEN in the REST calls described on this page.

Step 2: Get Your Organization Token

Next, you can use the API token to authorize access to the Cobalt API. Take the API token that you generated. Substitute that value for YOUR-PERSONAL-API-TOKEN:

curl -X GET "https://api.cobalt.io/orgs" \
     -H "Accept: application/vnd.cobalt.v2+json" \
     -H "Authorization: Bearer YOUR-PERSONAL-API-TOKEN" \
     | jq .

Click to view a sample response.

From the output, save the value for token as your organization token. In our API documentation, you’ll see this as YOUR-V2-ORGANIZATION-TOKEN.

For more information, see our API reference documentation on the organizations orgs endpoint.

Step 3: Get All Findings

Now that you have the following information:

  • YOUR-PERSONAL-API-TOKEN
  • YOUR-V2-ORGANIZATION-TOKEN

You can retrieve all findings with the following REST call:

curl -X GET "https://api.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" \
  | jq .

Click to view a sample response.

For more information on each parameter, see our API reference documentation on how to get all findings.

If the command is successful, you’ll see

Message Meaning
200 OK Findings for all pentests retrieved

For a list of error codes, see the Errors section of our API reference.

Step 4: Import Findings to Google Sheets

Now that you have findings data in JSON format, you can import it to the spreadsheet software of your choice.

As an example, let’s import findings to Google Sheets.

  1. In Google Sheets, select Extensions > Apps Script.

  2. Use the Class UrlFetchApp service to import raw findings data. Refer to the Class SpreadsheetApp reference for details.

  3. Run the following script to download and import Cobalt findings. Replace YOUR-PERSONAL-API-TOKEN and YOUR-V2-ORGANIZATION-TOKEN with your values.

    function FETCH_DATA() {
  var url = 'https://api.cobalt.io/findings';
  var params = { headers: {
    'Accept': 'application/vnd.cobalt.v2+json',
    'Content-Type': 'application/vnd.cobalt.v2+json',
    'Authorization': 'Bearer YOUR-PERSONAL-API-TOKEN',
    'X-Org-Token': 'YOUR-V2-ORGANIZATION-TOKEN'
  }}
  var sheet = SpreadsheetApp.getActiveSheet();

  var response = JSON.parse(UrlFetchApp.fetch(url, params)).data;
  sheet.appendRow(Object.keys(response[0].resource));
  response.forEach((i) => 
    sheet.appendRow(
      Object.entries(i.resource)
      .map(([key, content]) => { 
        if(key == 'labels') {
          return content.map(c => c.name).join(',');
        }
        if(key == 'affected_targets') {
          return content.join(',');
        }
        if(key == 'log') {
          return JSON.stringify(content);
        }
        return content;
      })
    )
  );
}

Step 5: Visualize Findings Data

After importing raw findings data, you can create charts to visualize data. Here are some examples for Google Sheets.

  • Sum of impact points per target: Use a QUERY inside a spreadsheet. The request sums up Impact Points (column G) and groups them by Affected Targets (Column J):
    =TRANSPOSE(QUERY('Raw Data'!B:J, "SELECT J, SUM(G) group by J " , 1))
  • Chart representing severity: In Google Sheets, select Insert > Chart, and select Column I as the data source.
  • Chart representing likelihood: In Google Sheets, select Insert > Chart, and select Column H as the data source.
  • Chart showing the highest severity: Use the following command:
    =INDIRECT("'Raw Data'!B"&MATCH(MAX('Raw Data'!G:G),'Raw Data'!G:G,0))

The result may appear as shown in the image.

Findings data imported to Google Sheets

You can control who can access your Macros and Google Sheets. Fine-tune to which parts of your data specific users have access. This allows you to generate live reports without inviting users to the Cobalt platform.



Was this page helpful?

Yes No Create an Issue

Last modified June.06.2023