Audit Logs API

Overview

The Audit Log service can be used to monitor your Carbon Black Cloud organization for actions performed by Carbon Black Cloud console users and API keys. Audit logs are recorded for most CREATE, UPDATE and DELETE actions as well as a few READ actions. Audit logs will include a description of the action and indicate the actor who performed the action along with their IP to help determine if the User/API key are from an expected source.

Use Cases

  • Use Audit Logs to review actions performed by Carbon Black Cloud console users and API keys.
  • Search or export Carbon Black Cloud audit logs to your SIEM, Data Lake, or other security integration.

Requirements

  • Any Carbon Black Cloud product

Resources

Authentication

Determine whether you use Carbon Black Cloud or VMware Cloud Services Platform to manage identity and authorization, or see the Carbon Black Cloud API Access Guide for complete instructions.


Carbon Black Cloud Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with Role-Based Access Control; All APIs and Services authenticate via API Keys. To access the data in Carbon Black Cloud via API, you must set up a key with the correct permissions for the calls you want to make and pass it in the HTTP Headers.

Environment
Available on majority of environments; Use the Carbon Black Cloud Console URL, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/audit_log/v1/orgs/{org_key}/logs/_export
  • {cbc-hostname}/audit_log/v1/orgs/{org_key}/logs/_queue
  • {cbc-hostname}/audit_log/v1/orgs/{org_key}/logs/_search

Access Level
Before you create your API Key, you need to create a "Custom" Access Level including each category:
  • Audit Logs > View and Export Audits > org.audits, allow permission to READ

API Key
When creating your API Key, use the Access Level Type of "Custom" and select the Access Level you created. Details on constructing and passing the API Key in your requests are available here.


Cloud Services Platform Managed Identity and Authentication
Customize your access to the Carbon Black Cloud APIs with OAuth Access Control; API access is controlled using OAuth apps or User API Tokens. This is currently limited to the UK Point of Presence and AWS GovCloud (US).

Environment
Available on Prod UK and AWS GovCloud (US). Full list of environments is available here; Use the Carbon Black Cloud Console URL from Cloud Services Platform, as described here.

API Route
Replace the {cbc-hostname} and {org_key} with the URL of your Environment and the org_key for your specific Org.
  • {cbc-hostname}/audit_log/v1/orgs/{org_key}/logs/_export
  • {cbc-hostname}/audit_log/v1/orgs/{org_key}/logs/_queue
  • {cbc-hostname}/audit_log/v1/orgs/{org_key}/logs/_search

Access Level
Before you create your OAuth App, you need to create a custom Role with the following permissions under IDENTITY & ACCESS MANAGEMENT > Roles > VMware Carbon Black Cloud:
  • _API.Audits:org.audits:READ, allow permission to READ

API Authentication
The Cloud Services Platform supports several authentication options, Access Token, API Token, and for backward compatibility, X-Auth-Token. To learn about the differences or how to use the authentication methods see the Authentication Guide.


API Calls

Common Request Attributes

Create Time Filter

The audit logs api exposes create_time which can be filtered using the time filter object.

The time filter object can be defined with either start and end OR range. Supplying range with start or end is invalid.

Field Definition Data Type Example
start The lower bound of the time range. Requires end and must be a timestamp before end. ISO 8601 Date String 2023-04-01T00:00:00.000Z
end The upper bound of the time range Requires start and must be a timestamp after start ISO 8601 Date String 2023-04-15T00:00:00.000Z
range Relative time range for the request (defined below) String -2w

The format of range is -<quantity><units> where quantity is an integer, and units is one of:

  • M: month(s)
  • w: week(s)
  • d: day(s)
  • h: hour(s)
  • m: minute(s)
  • s: second(s)

Examples

A 2-week query using explicit start and end timestamps 
{
  "start": "2023-04-01T00:00:00.000Z",
  "end": "2023-04-15T00:00:00.000Z"
}
A 2-week query using a relative range 
{
  "range": "-2w",
}

Search Audit Logs

Search for audit logs using query, criteria and exclusion operators.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.audits READ Majority of environments
VMware Cloud Services Platform _API.Audits:org.audits:READ N/A - included in permission name Prod UK and AWS GovCloud (US)

Request 
POST {cbc-hostname}/audit_log/v1/orgs/{org_key}/logs/_search


Request Body - application/json

{
  "criteria": {
    "actor_ip": [ "<string>" ],
    "actor": [ "<string>" ],
    "request_url": [ "<string>" ],
    "description": [ "<string>" ],
    "flagged": <boolean>,
    "verbose": <boolean>,
    "create_time": {
      "start": "<string>",
      "end": "<string>",
      "range": "<string>"
    }
  },
  "exclusions": {
    "actor_ip": [ "<string>" ],
    "actor": [ "<string>" ],
    "request_url": [ "<string>" ],
    "description": [ "<string>" ],
    "flagged": <boolean>,
    "verbose": <boolean>,
    "create_time": {
      "start": "<string>",
      "end": "<string>",
      "range": "<string>"
    }
  },
  "query": "<string>",
  "rows": "<string>",
  "start": "<string>",
  "sort": [{
    "field": "<string>",
    "order": "<string>"
  }]
}


Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object 
{
    "actor": ["user1@mydomain.com"]
}
exclusions Exclusions is a object that represents values that must not be in the results. Object 
{
    "actor_ip": ["16.123.34.57",]
}
query Query in lucene syntax and/or including value searches. String
rows Maximum number of rows to return. Integer Default: 20
Max: 10k
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "<string>",
  "order": "<string>"
}]
start What row to begin returning results from. Integer Default: 0
Max: start + rows can not exceed 10k


Response Codes

Code Description Content-Type Content
200 Successfully searched Audit Logs application/json See example below
400 Bad Request application/json 
{
    "error_code": "REQUEST_NOT_READABLE",
    "message": "Failed to read request",
    "args": []
}
401 User is not authenticated application/json 
{
    "success": false,
    "message": "User is not authenticated"
}
403 Access is denied application/json 
{
    "error_code": "FORBIDDEN",
    "message": "Access is denied",
    "args": []
}

Examples

Request 
POST https://defense.conferdeploy.net/audit_log/v1/orgs/ABCD1234/logs/_search
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "criteria": {
        "actor": ["user1@mydomain.com"]
    },
    "exclusions": {
        "actor_ip": ["16.123.34.57", "65.59.12.34"]
    },
    "query": "Logged in",
    "rows": 1000,
    "sort": [
        {
            "field": "create_time",
            "order": "ASC"
        }
    ]
}
Response Body 
{
    "num_found": 2,
    "num_available": 2,
    "results": [
        {
            "org_key": "ABCD1234",
            "actor_ip": "50.215.71.123",
            "actor": "user1@mydomain.com",
            "request_url": null,
            "description": "Logged in successfully",
            "flagged": false,
            "verbose": false,
            "create_time": "2023-11-02T18:13:44.276Z"
        },
        {
            "org_key": "ABCD1234",
            "actor_ip": "50.215.71.123",
            "actor": "user1@mydomain.com",
            "request_url": null,
            "description": "Logged in successfully",
            "flagged": false,
            "verbose": false,
            "create_time": "2023-11-02T16:29:59.793Z"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Export Audit Logs

Export audit logs in your organization using the job service.

To receive the actual JSON or CSV results, you need to use the Job Service API. First, use the Get Job Details to get the status of the async job, then Download Job Output call to download the actual content.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.audits READ Majority of environments
VMware Cloud Services Platform _API.Audits:org.audits:READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 
POST {cbc-hostname}/audit_log/v1/orgs/{org_key}/logs/_export


Request Body - application/json

{
  "criteria": {
    "actor_ip": [ "<string>" ],
    "actor": [ "<string>" ],
    "request_url": [ "<string>" ],
    "description": [ "<string>" ],
    "flagged": <boolean>,
    "verbose": <boolean>,
    "create_time": {
      "start": "<string>",
      "end": "<string>",
      "range": "<string>"
    }
  },
  "exclusions": {
    "actor_ip": [ "<string>" ],
    "actor": [ "<string>" ],
    "request_url": [ "<string>" ],
    "description": [ "<string>" ],
    "flagged": <boolean>,
    "verbose": <boolean>,
    "create_time": {
      "start": "<string>",
      "end": "<string>",
      "range": "<string>"
    }
  },
  "format": "<string>",
  "query": "<string>",
  "rows": "<string>",
  "start": "<string>",
  "sort": [{
    "field": "<string>",
    "order": "<string>"
  }]
}


Body Schema

Field Definition Data Type Values
criteria Criteria is an object that represents values that must be in the results. Object 
{
    "actor": ["user1@mydomain.com"]
}
format The format of the export String csv, or json
exclusions Exclusions is a object that represents values that must not be in the results. Object 
{
    "actor_ip": ["16.123.34.57",]
}
query Query in lucene syntax and/or including value searches. String
rows Maximum number of rows to return. Integer Default: all results
sort Sort is a collection of sort parameters that specify a field and order to sort the results. Array 
[{
  "field": "<string>",
  "order": "<string>"
}]
start What row to begin returning results from. Integer Default: 0


Response Codes

Code Description Content-Type Content
200 Successfully exported Audit Logs application/json See example below
400 Bad Request application/json 
{
    "error_code": "REQUEST_NOT_READABLE",
    "message": "Failed to read request",
    "args": []
}
401 User is not authenticated application/json 
{
    "success": false,
    "message": "User is not authenticated"
}
403 Access is denied application/json 
{
    "error_code": "FORBIDDEN",
    "message": "Access is denied",
    "args": []
}

Examples

Request 
POST https://defense.conferdeploy.net/audit_log/v1/orgs/ABCD1234/logs/_export
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Content-Type: "application/json"
Request Body 
{
    "criteria": {
        "actor": ["user1@mydomain.com"]
    },
    "exclusions": {
        "actor_ip": ["16.123.34.57", "65.59.12.34"]
    },
    "sort": [
        {
            "field": "create_time",
            "order": "ASC"
        }
    ],
    "query": "Logged in",
    "format": "csv"
}
Response Body 
{
    "job_id": 12700852
}
To download or review the Carbon Black Cloud Postman collection, click here.

Fetch from Audit Log Queue

Get the next group of audit logs in the queue.

Each API key has their own queue and will be initialized with the last 3 days of Audit Logs.


API Permissions Required

Identity Manager Permission (.notation name) Operation(s) Environment
Carbon Black Cloud org.audits READ Majority of environments
VMware Cloud Services Platform _API.Audits:org.audits:READ N/A - included in permission name Prod UK and AWS GovCloud (US)


Request 

GET {cbc-hostname}/audit_log/v1/orgs/{org_key}/logs/_queue

Response Codes

Code Description Content-Type Content
200 Successfully retrieved audit logs application/json See example below
400 Bad Request application/json 
{
    "error_code": "REQUEST_NOT_READABLE",
    "message": "Failed to read request",
    "args": []
}
401 User is not authenticated application/json 
{
    "success": false,
    "message": "User is not authenticated"
}
403 Access is denied application/json 
{
    "error_code": "FORBIDDEN",
    "message": "Access is denied",
    "args": []
}

Examples

Request 
GET https://defense.conferdeploy.net/audit_log/v1/orgs/ABCD1234/logs/_queue
Request Headers 
X-AUTH-TOKEN: "ABCDEFGHIJKLMNO123456789/ABCD123456"
Response Body 
{
    "num_found": 2,
    "num_available": 2,
    "results": [
        {
            "org_key": "ABCD1234",
            "actor_ip": "50.215.71.123",
            "actor": "user1@mydomain.com",
            "request_url": null,
            "description": "Logged in successfully",
            "flagged": false,
            "verbose": false,
            "create_time": "2023-11-02T18:13:44.276Z"
        },
        {
            "org_key": "ABCD1234",
            "actor_ip": "50.215.71.123",
            "actor": "user1@mydomain.com",
            "request_url": null,
            "description": "Logged in successfully",
            "flagged": false,
            "verbose": false,
            "create_time": "2023-11-02T16:29:59.793Z"
        }
    ]
}
To download or review the Carbon Black Cloud Postman collection, click here.

Fields

Audit Log

Field Definition Data Type Values
actor_ip IP address of the entity that caused the creation of this audit log String
actor Name of the entity that caused the creation of this audit log String
create_time Timestamp when this audit log was created in ISO-8601 string format String
description Text description of this audit log String
flagged Whether the audit has been flagged Boolean
org_key Organization Key String
request_url URL of the request that caused the creation of this audit log String
verbose Whether the audit has been marked verbose Boolean

Last modified on March 11, 2024