Carbon Black Cloud Rate Limiting

Summary

We strive to ensure maximum uptime, availability and fidelity of our APIs within and across customer organization boundaries. However, the outsized API request volume from a small number of callers could degrade API performance for other organizations in the same Carbon Black Cloud environment. To prevent service outages from reoccurring, rate limits are being introduced. The limits may change or be rolled out to additional APIs and Carbon Black Cloud environments as needed.

The APIs will be rate limited by Request IP address and will be enforced through a polling mechanism and sliding window. This may allow for a few requests over the limit however once you receive a 429 Too Many Requests response then all requests will need to be stopped until the time specified in the Retry-After header. Any additional requests within that retry boundary will extend the time before another request will be allowed, as the rate is calculated for the rate limit period at each polling interval.

Scenario A

Limit: 1000 requests in a 5 minute period

Customer A sends a burst of 1000 requests in the first minute and by minute two they receive 429 Too Many Requests. Customer A will need to wait the full five minutes before their requests will be allowed.

Minute Requests Remaining Response
1 1000 0 200
2 1 -1 429
3 1 -2 429
4 1 -3 429
5 1 -4 429
6 1 995 200

Scenario B

Limit: 1000 requests in a 5 minute period

Customer B sends 250 requests per minute, after four minutes Customer B receives 429 Too Many Requests. Customer B needs to wait one minute before their requests will be allowed - approximately 250 requests would be allowed in that next minute period - however if they wait the full five minutes the limit will be completely reset to 1000 requests.

Minute Requests Remaining Response
1 250 750 200
2 250 500 200
3 250 250 200
4 250 0 200
5 1 -1 429
6 1 248 200

Scenario C

Limit: 1000 requests in a 5 minute period

Customer B sends 200 requests per minute thus never exceeding the rate limit as after five minutes the 200 API calls from the first minute are available again in the sixth minute.

Minute Requests Remaining Response
1 200 800 200
2 200 600 200
3 200 400 200
4 200 200 200
5 200 0 200
6 1 199 200

API Services

API Investigate (Enriched Events and Processes)

Creating new searches are limited to reduce overloading the searchers. Fetching the status or results of a search is not included in the limit.

Carbon Black Cloud Environment

Limit: 1000 requests in a 5 minute period

API Endpoints

The following POST requests share the same cumulative rate limit e.g. 500 requests to /search_jobs and 500 requests to /detail_jobs will cause the 1001st request to /summary_jobs to receive a 429 Too Many Requests response.

POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/processes/search_jobs
POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/processes/facet_jobs
POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/processes/detail_jobs
POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/processes/summary_jobs
POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/events/{process_guid}/_search
POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/events/{process_guid}/_facet
POST {cbc-hostname}/api/investigate/v1/orgs/{org_key}/processes/watchlist_evaluation
POST {cbc-hostname}/api/investigate/v1/orgs/{org_key}/enriched_events/aggregation_jobs/{aggregation_field}
POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/enriched_events/search_jobs
POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/enriched_events/facet_jobs
POST {cbc-hostname}/api/investigate/v2/orgs/{org_key}/enriched_events/detail_jobs

LiveQuery Service

The differential analysis search enforces different rate limits for different request options. Using the asynchronous option (async=true) will export the results to an AWS S3 download URL while using the search without async=true will return the results in the API response. Each option has a separate and different limit.

Carbon Black Cloud Environment

API Endpoints

{cbc-hostname}/livequery/v1/orgs/{org_key}/differential/runs/_search?async=true&format=json

Limit: 100 requests in a 5 minute period

{cbc-hostname}/livequery/v1/orgs/{org_key}/differential/runs/_search

Limit: 350 requests in a 5 minute period


Banning

Excessive usage can result in a temporary enforcement of rate limiting on any Carbon Black Cloud service.

If you or your application abuse the rate limits, the API Key and/or Organization will be restricted from making additional requests until a resolution can be made to prevent the abuse from reoccurring in the future.


Please reach out if you have concerns or need additional support

Last modified on November 1, 2022