Audit Log API Access Level Migration

The Access Level Type API will be deactivated on October 31, 2024.

Calls to the Audit Log API must be updated to use an API Key with the Access Level type Custom.

Overview

The Audit Log API has been updated to authenticate using a Custom type API Access Level that has been granted the org.audits permission.

This guide will assist in migrating integrations that use the integrationServices/v3/auditlogs API from using an API type access level to using a Custom type access level.

Guides and Resources


About the Audit Log API

Note: The audit logs api is a read-once endpoint. This has not changed.

  • When the Audit Log permission is added to an API Key, three days of historical records are put on the queue.
  • Each API Key is an individual Audit Log queue.
  • Each time the audit log API is called with that API Key, available records are consumed.
  • This has not changed; it is the same behavior as for the API type Access Level.

If you did not update prior to July 31st 2024

  • If it is less than three days since the API began failing, follow the How To Update instructions. The new API key will initiate a queue with three days of historical data.
  • If it is more than three days and you need to have all data
    • Follow the How To Update instructions, and
    • Use the Search Audit Logs API Endpoint to get missed data. The new Audit Log API response returns different field names than the previous version of Audit Log. For successful ingest, please review the field mappings used in your integrated application.

How To Update

  1. Identify the integrations that ingest Audit Logs from Carbon Black Cloud. Each will need a different API Key because the API provides access to a read once queue. See About the Audit Log API for details.

  2. Determine which option will be work best in your scenario:

    1. A new API Key that only has permission to call the Audit Log records
    2. Add the permission to an existing key. This will simplify integrations that today require two keys, one with an access level type API for Audit Logs and another of type Custom for everything else. Ensure you have the API Secret Key available for this key (it should be stored somewhere securely upon creation, because it cannot be retrieved after initial creation).

  1. If you are creating a new key:

    1. In the Carbon Black Cloud Console, go to API keys Settings > API Access, then Access Levels Tab.
    2. Use the Add Access Level button.
    3. Fill in the information fields.
    4. Choose Audit Logs > View and Export Audits > org.audits READ permission.
    5. Click Save.
    1. Go to the API Keys Tab
    2. Click Add API Key
    3. Fill in the information fields.
    4. Choose Access Level type Custom
    5. Choose the Custom Access Level created earlier
    6. Click Save.
    7. Store the API Secret securely, because it cannot be retrieved after initial creation. This is a password for API Access and is needed in the next steps.
    8. Go to the integration
    9. Update the credentials with those just created at step 12
    10. Your integration will begin ingesting the Audit Logs using the new Custom type API key

  1. If you are adding the permission to an existing key:

    1. In the Carbon Black Cloud Console, go to API keys Settings > API Access.
    2. Find the key you want to use.
      1. Ensure you have the credentials available.
      2. Note the Access Level it uses.
    3. Go to the Access Levels Tab.
    4. Find the Access Level the key is using
    5. Click the pencil icon to edit
    6. Choose Audit Logs > View and Export Audits > org.audits READ permission.
    7. Click Save
    8. No other updates to the integration are needed. Your integration will begin ingesting the Audit Logs using the new Custom type API key



Note:

If other integrations are using an API Key with Access Level type API or LIVE_RESPONSE, they need to be updated to use an API Key with Access Level type Custom. Both Access Level types API and LIVE_RESPONSE will be deactivated on 31st October 2024.

If integrations are using any of the APIs listed for deactivation in the API and Schema Migration Guide they will need to be migrated to a new API. Most deprecated API routes are scheduled for deactivation on 31st July 2024. SIEM Notifications are scheduled for deactivation on 31st October 2024.


Removing unused API Keys

When a key is not being used by any integration it should be removed, similar to removing user accounts when people no longer require access.


Carbon Black Cloud Python SDK Migration

If you are using the Carbon Black Cloud Python SDK (lovingly known as the CBC SDK), the credentials will need to be updated with the API Id and Key that has Custom type API Access Level that has been granted the org.audits permission.

In many use cases, adding the org.audits permission to an existing API Key and configuring the SDK to use this key will make integration configuration simpler.

If you are still using CBAPI, it’s time to upgrade and get all the benefits of the new Carbon Black Cloud features and improvements in the SDK.


Last modified on June 3, 2024