Working with Operations

Operations enable ThreatQ to integrate with external intelligence providers, enrichment services, and automation workflows. Using the ThreatQ SDK, you can discover available operations, review supported actions, and execute those actions against ThreatQ objects such as indicators, events, adversaries, and files. This section demonstrates how to interact with Operations programmatically.

Topics Covered

• Import the Operation Object

• List Available Operations and Actions

• Execute an Operation Action

Import the Operation Object

Before interacting with operations, import the Operation class:

from threatqsdk import Operation

List Available Operations and Actions

To retrieve all enabled operations configured in ThreatQ, use the list_from_tq() class method. This method returns a list of Operation objects.

Copy Code

To display each operation and its available actions:

for o in ops:
    print(op.name)
    for action in o.actions:
        print(
            '{}: {}'.format(
                action['name'],
                action['description']
            )
        )
    print('\n')

Copy Code

Example output:

passive_total
get_passive_dns: Retrieve Passive DNS associated with Indicators
get_WHOIS: Get WHOIS
enrich: Enrichment
get_samples: Get Malware Samples
query_for_registered_domains: Searches WHOIS data by Email Address to return all domains registered to that Email Address
vulners
search_CVE: Query CVE against Vulners DB

This allows you to identify which integrations are available and the actions each operation supports.

Execute an Operation Action

To execute an operation action, create an Operation instance using the operation's friendly name.

The following example creates an instance for the PassiveTotal operation:

Copy Code

Execute Method Parameters

The execute() method accepts the following parameters:

Execute an Action with Parameters

Some operations require additional parameters. The following example executes the VirusTotal search_domain action against an indicator:

op = Operation(tq, "virustotal")
iid = 2
result = op.execute(
    "search_domain",
    iid,
    "indicator",
    parameters={
        "threshold": "10",
        "av_scan_info": [
            "malicious",
            "suspicious",
            "harmless",
            "undetected",
            "av_info"
        ],
        "supporting_context": [
            "0",
            "1"
        ],
        "relationships": [
            "0",
            "2",
            "1",
            "3",
            "4"
        ],
        "indicator_status": "Active"
    }
)

Copy Code

The action executes using the supplied parameters and returns the results in JSON format.

Execute an Action Without Parameters

For actions that do not require additional configuration, simply provide the action name, object ID, and object type.

The following example executes the Get WHOIS action against an indicator with ID 43:

op = Operation(tq, 'passive_total')
iid = 43
response = op.execute(
    'get_WHOIS',
    iid,
    'indicator'
)

Copy Code

Processing Results

The execute() method returns the operation response as a JSON object. Depending on the operation, results may contain:

• New indicators

• Attributes

• Relationships

• Enrichment data

• Raw provider response data

Using the WHOIS action as an example, the following output demonstrates the type of information returned by the action. The response includes extracted indicators, enriched WHOIS attributes, and the complete raw WHOIS record, providing analysts with both structured intelligence and the original source data for further investigation and validation.

{
    "indicators": [
        {
            "type": "Email Address",
            "value": "abuse@godaddy.com"
        },
        {
            "type": "FQDN",
            "value": "ns11.domaincontrol.com"
        },
        {
            "type": "FQDN",
            "value": "ns12.domaincontrol.com"
        },
        {
            "type": "FQDN",
            "value": "whois.godaddy.com"
        }
    ],
    "attributes": [
        {
            "name": "Registrant Contact Name",
            "value": "******** ********"
        },
        {
            "name": "Registrar",
            "value": "GoDaddy.com, LLC"
        },
        {
            "name": "Updated At",
            "value": "May 23 2017 11:52:46 AM "
        },
        {
            "name": "Registered Date",
            "value": "May 22 2014 05:11:26 PM "
        },
        {
            "name": "Expires At",
            "value": "May 22 2018 05:11:26 PM "
        }
    ],
    "raw_data": {
        "contactEmail": "abuse@godaddy.com",
        "whoisServer": "whois.godaddy.com",
        "name": "******** ********",
        "billing": [],
        "nameServers": [
            "ns11.domaincontrol.com",
            "ns12.domaincontrol.com"
        ],
        "registered": "2014-05-22T17:11:26.000-0700",
        "lastLoadedAt": "2017-12-19T11:13:18.419-0800",
        "telephone": "N/A",
        "registryUpdatedAt": "2017-05-23T11:52:46.000-0700",
        "admin": [],
        "expiresAt": "2018-05-22T17:11:26.000-0700",
        "tech": [],
        "registrar": "GoDaddy.com, LLC",
        "domain": "aadroid.net",
        "organization": "N/A",
        "zone": [],
        "registrant": {
            "name": "******** ********",
            "email": "abuse@godaddy.com"
        }
    }
}

In the WHOIS example, the response includes:

• Extracted indicators such as email addresses and name servers.

• Enriched attributes including registrar, registration dates, and expiration dates.

• The complete raw WHOIS response for additional analysis.