Watchlists provide custom detection and continuous monitoring of your environment for potential threats and suspicious activity.

Watchlists are comprised of reports; reports are comprised of IOCs.

  • Watchlist: A collection of reports; defines the purpose
  • Report: A collection of IOCs; organizes IOCs
  • IOC: Indicator of Compromise; for example, hashes, IPs, domains, or queries
Tip: You can also use the Watchlist API manage watchlists for your organization throughout their lifecycle - creation, update and removal - as well as associated reports and IOCs.

Watchlist Data Retention

Watchlist hits and their related events and alerts are available in the console for a limited time.

  • Alerts and the events linked to them are stored for 180 days.
  • Events not associated with any alerts are stored for 30 days.
  • Watchlist hits are stored and viewable in the console for 180 days.
    Note: Events associated with watchlist hits are stored for 30 days.
    Restriction: Therefore, in cases where a Watchlist hit is older than 30 days, your ability to investigate the associated events will be limited.

Historical Data

In the process of creating a watchlist, you can apply the watchlist to historical data. You get more insight on an alert by evaluating all of its past data that is available in the console. The time window for storing historical event data is 30 days.

To locate the option for historical data lookup, either navigate to the Watchlists page, or the Investigate page in the Carbon Black Cloud console.
  • On the Enforce > Watchlists page:
    • Select a custom watchlist, click the Take Action drop-down menu, and locate the Historical data option.
    • Select Add Watchlists, click the Build tab, check a report, and click Add. Select Create new watchlist and locate the Evaluate on all existing data (runs once) option.
  • On the Investigate page, enter a search query in the search bar, and click Add search to threat report. Select Select watchlist and locate the Evaluate on all existing data (runs once) option
You can select either of the Historical data option or the Evaluate on all existing data (runs once) option. Both options generate a network request to the same API endpoint, with the same request payload fields.
  • The network request URL is https://CBC_console_address/api/investigate/v1/orgs/org_name/processes/watchlist_evaluation, where the values for CBC_console_address and org_name are the same for both options.
  • The request payload fields are the watchlist_id and the report_id.
  • In the request payload, the duration of the historical lookup is the user's entire historical data set. The time window for storing the historical event data is 30 days.

Watchlist Search Time Window

A watchlist searches within a one-hour time window. However, a search on the Investigate page extends over that one-hour time window. As a result, an Investigate page search can display additional activity after the watchlist one-hour time window that no longer matches the watchlist, the report, or the IOC query filter.

If an IOC query searches for process metadata that does not change over the lifetime of the process, the watchlist hits and the Investigate page hits display the same information. Some examples of process metadata that do not change include the following: 

process_name, process_cmdline

If an IOC query contains a filter on an event field, then the watchlist hits and the Investigate page hits might differ. The difference between watchlist hits and Investigate page hits apply to event field searches that happen at various points in the life of the process and are not constant. Some examples of event fields that are not constant include the following:

childproc_, netconn_, filemod_, regmod_, modload_, scriptload_, fileless_scriptload_
Note: Any particular watchlist process count and hits count can be different because a single process can repeatedly cause the watchlist hit during a specific time period.