Searching the Threat Library

The ThreatLibrary class provides a flexible interface for searching and retrieving objects from the Threat Library. Searches can be executed using either a custom API query or a saved search (collection) created within ThreatQ. Results can be returned individually or in batches, making the ThreatLibrary class well-suited for integrations, data exports, enrichment workflows, and large-scale processing operations.

Initialize the ThreatLibrary Class

Begin by importing and creating an instance of the ThreatLibrary class:

Copy Code

Execute a Custom Search

If you want to build your own query, provide a valid Threat Library API query structure. The following example searches for objects sourced from Analyst that have a Confidence attribute set to High:

Copy Code

The easiest way to understand Threat Library query syntax is to inspect search requests generated by the ThreatQ user interface using your browser's developer tools.

Use a Saved Search

ThreatQ saved searches (collections) can also be executed through the SDK. After creating a saved search in the Threat Library, retrieve it by name:

Copy Code

This method retrieves the saved search definition and associated metadata, including the search query, name, and unique hash.

Execute a Search

Once a query or saved search has been defined, use the execute() method to retrieve results.

Using a Custom Query

Copy Code

Using a Saved Search

Copy Code

The execute() method is implemented as a generator and yields results incrementally. By default, objects are returned one at a time.

Execute Parameters

The execute() method supports the following parameters:

Parameter	Type	Description
object_type	str	Object type to retrieve (for example: indicators, events, adversaries)
custom_query	dict	Custom search query when not using a saved search
page_limit	int	Number of records returned per API request (default: 1000)
page_offset	int	Starting offset for the search (default: 0)
max_results	int	Maximum number of results to return (default: unlimited)
yield_batches	bool	Return batches of results instead of individual objects (default: False)
fields	list	Specific fields to return from the API

Performance Considerations

When processing large datasets, specifying the fields parameter can significantly reduce memory consumption and improve performance by returning only the data required.

Example:

for indicator in search.execute(
    'indicators',
    fields=['value']
):
    print(indicator)

Batch Processing Example

The following example executes a saved search, transforms the results, and uploads them to an external system in batches:

from threatqsdk import ThreatLibrary
search = ThreatLibrary(tq)
search.get_saved_search('High Confidence Indicators')
uploaded = 0
for data in search.execute(
    'indicators',
    page_limit=100,
    yield_batches=True,
    fields=['value']
):
    to_upload = []
    for indicator in data:
        to_upload.append(
            convert_to_payload(indicator)
        )
    print(
        'Uploading batch of {} indicators'.format(
            len(to_upload)
        )
    )
    upload_bundle(to_upload)

Using yield_batches=True returns each page of results as a collection, allowing more efficient bulk processing.

Create a Saved Search

The ThreatLibrary class can also create saved searches programmatically.

Saved searches may be:

• Named – Visible within the ThreatQ user interface.

• Unnamed – Accessible only through a generated search hash and URL.

The following example creates a named saved search that looks for ransomware-related keywords:

from threatqsdk import ThreatLibrary
search = ThreatLibrary(tq)
search.create_search(
    name='Ransomware Search',
    keywords=[
        'NotPetya',
        'CryptoLocker',
        'WannaCry'
    ]
)

Once created, the search can be executed using the execute() method.

Create Search Parameters

The create_search() method supports the following parameters:

Parameter	Type	Description
name	str	Name of the saved search. Optional.
keywords	list	List of keywords to search using OR logic. Optional.
api_query	dict	Predefined Threat Library API query to save directly. Optional.