ThreatQ v2.1.0

About the connector

ThreatQuotient is a threat intelligence platform that centrally manages and correlates unlimited external sources. This connector facilitates automated operation such as collects and interprets intelligence data from open sources and manages indicators.

This document provides information about the ThreatQ Connector, which facilitates automated interactions, with a ThreatQ server using FortiSOAR™ playbooks. Add the ThreatQ Connector as a step in FortiSOAR™ playbooks and perform automated operations with ThreatQ.

Version information

Connector Version: 2.1.0

Authored By: Fortinet

Certified: Yes

Release Notes for version 2.1.0

Following enhancements have been made to the ThreatQ Connector in version 2.1.0:

• Fixed an issue with reputation-related actions like IP, URL, Domain and File not working due to deprecation of rest APIs.
• Resolved an issue with the following actions as the input parameters Status ID and Indicator Type ID were static:
  • Create Indicator
  • Update Indicator

  These parameters have now been modified to fetch the IDs dynamically through a REST API call.

Installing the connector

Use the Content Hub to install the connector. For the detailed procedure to install a connector, click here.

You can also use the yum command as a root user to install the connector:

yum install cyops-connector-threatq

Prerequisites to configuring the connector

• You must have the credentials of ThreatQ server to which you will connect and perform automated operations.
• The FortiSOAR™ server should have outbound connectivity to port 443 on the ThreatQ server.

Minimum Permissions Required

• Not applicable

Configuring the connector

For the procedure to configure a connector, click here

Configuration parameters

In FortiSOAR™, on the Connectors page, click the ThreatQ connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:

Actions supported by the connector

The following automated operations can be included in playbooks and you can also use the annotations to access operations:

operation: Create Event

Input parameters

Output

The output contains the following populated JSON schema:

{
    "data": {
        "id": "",
        "description": "",
        "created_at": "",
        "sources": [],
        "type_id": "",
        "title": "",
        "happened_at": "",
        "hash": ""
    }
}

operation: Create Adversary

Input parameters

Output

The output contains the following populated JSON schema:

{
    "data": {
        "id": "",
        "name": "",
        "sources": [],
        "created_at": "",
        "updated_at": "",
        "description": ""
    }
}

operation: Create IOC

Input parameters

Output

The JSON output retrieves the details of the newly created indicator from ThreatQ.

The output contains the following populated JSON schema:

{
    "total": "",
    "data": [
        {
            "expires_at": "",
            "expires_calculated_at": "",
            "last_detected_at": "",
            "type_id": "",
            "created_at": "",
            "sources": [
                {
                    "name": "",
                    "type": "",
                    "expire_days": "",
                    "id": "",
                    "created_at": "",
                    "score": "",
                    "updated_at": ""
                }
            ],
            "value": "",
            "existing": "",
            "updated_at": "",
            "type": {
                "name": "",
                "id": "",
                "created_at": "",
                "score": "",
                "wildcard_matching": "",
                "updated_at": "",
                "class": ""
            },
            "hash": "",
            "id": "",
            "touched_at": "",
            "status_id": "",
            "expired_at": "",
            "description": "",
            "class": ""
        }
    ]
}

operation: Get Indicator Types

Input parameters

None.

Output

The JSON retrieves a list of all available indicator types from ThreatQ.

The output contains the following populated JSON schema:

{
    "total": "",
    "data": [
        {
            "id": "",
            "name": "",
            "wildcard_matching": "",
            "score": "",
            "created_at": "",
            "updated_at": "",
            "class": ""
        }
    ]
}

operation: Get Indicator Statuses

Input parameters

None. Include this operation in the ThreatQ playbook and you will get a list containing all available indicator statuses and their id values. You can use these IDs to create new indicators.

Output

The JSON retrieves a list of all available indicator statuses and their id values from ThreatQ.

The output contains the following populated JSON schema:

{
    "total": "",
    "data": [
        {
            "id": "",
            "name": "",
            "user_editable": "",
            "description": "",
            "visible": "",
            "include_in_export": "",
            "protected": "",
            "created_at": "",
            "updated_at": ""
        }
    ]
}

operation: Get Reputation

Input parameters

Output

The JSON output retrieves the reputation for the indicator from ThreatQ, based on the indicator name and type that you have specified.

The output contains the following populated JSON schema:

{
    "indicator_id": "",
    "indicator_type": "",
    "class": "",
    "score": {
        "indicator_id": "",
        "score_config_hash": "",
        "created_at": "",
        "updated_at": "",
        "manual_score": "",
        "generated_score": ""
    },
    "created_at": "",
    "related_adversaries": {
        "count": "",
        "details": []
    },
    "indicator_value": "",
    "indicator_status": "",
    "tq_link": "",
    "related_indicators": {
        "count": "",
        "details": []
    },
    "attributes": {
        "count": "",
        "details": []
    },
    "sources": "",
    "related_attachments": "",
    "related_signatures": "",
    "related_events": "",
    "description": "",
    "hash": ""
}

operation: Search Indicator

Input parameters

Output

The JSON output retrieves the details for the indicator from ThreatQ, based on the indicator name that you have specified.

The output contains the following populated JSON schema:

{
    "score": {},
    "indicator_id": "",
    "indicator_type": "",
    "created_at": "",
    "related_adversaries": {
        "count": "",
        "details": []
    },
    "indicator_value": "",
    "indicator_status": "",
    "tq_link": "",
    "related_indicators": {
        "count": "",
        "details": []
    },
    "attributes": {
        "count": "",
        "details": []
    },
    "sources": "",
    "related_attachments": "",
    "related_signatures": "",
    "related_events": "",
    "description": ""
}

operation: Get IP Reputation

Input parameters

Output

The JSON output retrieves the reputation for the IP from ThreatQ, based on the IP address you have specified.

The output contains the following populated JSON schema:

{
    "indicator_id": "",
    "indicator_type": "",
    "class": "",
    "score": {
        "indicator_id": "",
        "score_config_hash": "",
        "created_at": "",
        "updated_at": "",
        "manual_score": "",
        "generated_score": ""
    },
    "created_at": "",
    "related_adversaries": {
        "count": "",
        "details": []
    },
    "indicator_value": "",
    "indicator_status": "",
    "tq_link": "",
    "related_indicators": {
        "count": "",
        "details": []
    },
    "attributes": {
        "count": "",
        "details": []
    },
    "sources": "",
    "related_attachments": "",
    "related_signatures": "",
    "related_events": "",
    "description": "",
    "hash": ""
}

operation: Get Domain Reputation

Input parameters

Output

The JSON output retrieves the reputation for the domain from ThreatQ, based on the domain name you have specified.

The output contains the following populated JSON schema:

{
    "indicator_id": "",
    "indicator_type": "",
    "class": "",
    "score": {
        "indicator_id": "",
        "score_config_hash": "",
        "created_at": "",
        "updated_at": "",
        "manual_score": "",
        "generated_score": ""
    },
    "created_at": "",
    "related_adversaries": {
        "count": "",
        "details": []
    },
    "indicator_value": "",
    "indicator_status": "",
    "tq_link": "",
    "related_indicators": {
        "count": "",
        "details": []
    },
    "attributes": {
        "count": "",
        "details": []
    },
    "sources": "",
    "related_attachments": "",
    "related_signatures": "",
    "related_events": "",
    "description": "",
    "hash": ""
}

operation: Get URL Reputation

Input parameters

Output

The JSON output retrieves the reputation for the URL from ThreatQ, based on the URL type and value you have specified.

The output contains the following populated JSON schema:

{
    "indicator_id": "",
    "indicator_type": "",
    "class": "",
    "score": {
        "indicator_id": "",
        "score_config_hash": "",
        "created_at": "",
        "updated_at": "",
        "manual_score": "",
        "generated_score": ""
    },
    "created_at": "",
    "related_adversaries": {
        "count": "",
        "details": []
    },
    "indicator_value": "",
    "indicator_status": "",
    "tq_link": "",
    "related_indicators": {
        "count": "",
        "details": []
    },
    "attributes": {
        "count": "",
        "details": []
    },
    "sources": "",
    "related_attachments": "",
    "related_signatures": "",
    "related_events": "",
    "description": "",
    "hash": ""
}

operation: Get File Reputation

Input parameters

Output

The JSON output retrieves the reputation for the file from ThreatQ, based on the file type and value you have specified.

The output contains the following populated JSON schema:

{
    "indicator_id": "",
    "indicator_type": "",
    "class": "",
    "score": {
        "indicator_id": "",
        "score_config_hash": "",
        "created_at": "",
        "updated_at": "",
        "manual_score": "",
        "generated_score": ""
    },
    "created_at": "",
    "related_adversaries": {
        "count": "",
        "details": []
    },
    "indicator_value": "",
    "indicator_status": "",
    "tq_link": "",
    "related_indicators": {
        "count": "",
        "details": []
    },
    "attributes": {
        "count": "",
        "details": []
    },
    "sources": "",
    "related_attachments": "",
    "related_signatures": "",
    "related_events": "",
    "description": "",
    "hash": ""
}

operation: Get List of Indicators

Input parameters

Output

The JSON retrieves a list of available indicators from ThreatQ, based on the parameters that you have specified.

The output contains the following populated JSON schema:

{
    "total": "",
    "data": [
        {
            "created_at": "",
            "value": "",
            "touched_at": "",
            "updated_at": "",
            "last_detected_at": "",
            "sources": [
                {
                    "id": "",
                    "type": "",
                    "published_at": "",
                    "updated_at": "",
                    "tlp_id": "",
                    "created_at": "",
                    "name": "",
                    "pivot": {
                        "id": "",
                        "indicator_id": "",
                        "source_id": "",
                        "creator_source_id": ""
                    }
                }
            ],
            "id": "",
            "expires_at": "",
            "hash": "",
            "status": {
                "id": "",
                "name": "",
                "user_editable": "",
                "description": "",
                "visible": "",
                "include_in_export": "",
                "protected": "",
                "created_at": "",
                "updated_at": ""
            },
            "status_id": "",
            "type": {
                "id": "",
                "name": "",
                "wildcard_matching": "",
                "score": "",
                "created_at": "",
                "updated_at": "",
                "class": ""
            },
            "score": {
                "indicator_id": "",
                "created_at": "",
                "score_config_hash": "",
                "manual_score": "",
                "generated_score": "",
                "updated_at": ""
            },
            "expires_calculated_at": "",
            "type_id": "",
            "expired_at": "",
            "class": "",
            "description": ""
        }
    ]
}

operation: Get Related IOCs

Input parameters

Output

The JSON output retrieves the details for the related indicator(s) from ThreatQ, based on the indicator name you have specified.

The output contains the following populated JSON schema:

{
    "related_indicators": {
        "count": "",
        "details": [
            {
                "id": "",
                "value": "",
                "class": "",
                "hash": ""
            }
        ]
    }
}

operation: Get Event Types

Input parameters

You do not need to provide any input parameters for this operation. Include this operation in the ThreatQ playbook and you will get a list containing all available event types and their ID values.

Output

The JSON retrieves a list of all available event types from ThreatQ.

The output contains the following populated JSON schema:

{
    "total": "",
    "data": [
        {
            "id": "",
            "updated_at": "",
            "name": "",
            "user_editable": "",
            "created_at": ""
        }
    ]
}

operation: Search Event

Input parameters

Output

The JSON output retrieves the details for the specified event from ThreatQ, based on the event name you have specified. If the event that you have specified is not found, an error message is displayed.

The output contains the following populated JSON schema:

{
    "data": {
        "title": "",
        "created_at": "",
        "watchlist": [],
        "sources": [],
        "signatures": [],
        "id": "",
        "updated_at": "",
        "attachments": [],
        "description": "",
        "adversaries": [],
        "recipients": [],
        "type": {},
        "hash": "",
        "comments": [],
        "events": [],
        "type_id": "",
        "attributes": [],
        "happened_at": "",
        "spearphish": ""
    }
}

operation: Get List of Events

Input parameters

Output

The JSON retrieves a list of all available events from ThreatQ that match the parameters that you have specified.

The output contains the following populated JSON schema:

{
    "total": "",
    "data": [
        {
            "id": "",
            "hash": "",
            "description": "",
            "happened_at": "",
            "title": "",
            "created_at": "",
            "updated_at": "",
            "touched_at": "",
            "type_id": "",
            "sources": [
                {
                    "id": "",
                    "name": ""
                }
            ],
            "total_indicators": ""
        }
    ]
}

operation: Update Indicator

Input parameters

Output

The JSON output retrieves the details for the indicator from ThreatQ whose status you want to update.

The output contains the following populated JSON schema:

{
    "data": {
        "status_id": "",
        "class": "",
        "type_id": "",
        "value": "",
        "expires_at": "",
        "id": "",
        "description": "",
        "created_at": "",
        "hash": ""
    }
}

operation: Link IOCs

Input parameters

Output

The JSON output retrieves the details for the indicator (first) from ThreatQ to which you want to create a link containing the second indicator.

The output contains the following populated JSON schema:

{
    "total": "",
    "data": [
        {
            "created_at": "",
            "value": "",
            "touched_at": "",
            "updated_at": "",
            "last_detected_at": "",
            "id": "",
            "expires_at": "",
            "hash": "",
            "status_id": "",
            "expires_calculated_at": "",
            "pivot": {
                "id": "",
                "created_at": "",
                "updated_at": ""
            },
            "type_id": "",
            "expired_at": "",
            "class": "",
            "description": ""
        }
    ]
}

operation: Get List of Adversaries

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list of all ThreatQ adversaries is returned.

Output

The output contains the following populated JSON schema:

{
    "total": "",
    "data": [
        {
            "id": "",
            "hash": "",
            "description": "",
            "happened_at": "",
            "title": "",
            "created_at": "",
            "updated_at": "",
            "touched_at": "",
            "type_id": "",
            "sources": [
                {
                    "id": "",
                    "name": ""
                }
            ],
            "total_indicators": ""
        }
    ]
}

operation: Get Saved Searches

Input parameters

Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list of all saved searches filter queries is returned.

Output

The output contains the following populated JSON schema:

{
    "id": "",
    "name": "",
    "hash": "",
    "json": {
        "ui_query": {
            "columns": [],
            "criteria": {
                "matchType": [],
                "items": []
            },
            "filters": {
                "sources": {
                    "matchType": [],
                    "filterRange": {
                        "set-0": ""
                    },
                    "values": [
                        {
                            "source_name": "",
                            "set_id": ""
                        }
                    ]
                }
            },
            "objects": {
                "current": "",
                "selected": []
            },
            "filter_sets": [
                {
                    "id": "",
                    "operator": "",
                    "isNegated": "",
                    "expanded": ""
                }
            ]
        },
        "api_query": {
            "criteria": [],
            "filters": {
                "+and": [
                    {
                        "+or": [
                            {
                                "source_name": {
                                    "name": ""
                                }
                            }
                        ]
                    }
                ]
            }
        }
    },
    "created_at": "",
    "updated_at": ""
}

operation: Run Search Query

Input parameters

Output

The output contains the following populated JSON schema:

{
    "total": "",
    "data": [
        {
            "class": "",
            "score": "",
            "value": "",
            "touched_at": "",
            "id": "",
            "updated_at": "",
            "published_at": "",
            "created_at": "",
            "status_id": "",
            "hash": "",
            "type_id": "",
            "adversaries": [],
            "type": {
                "name": "",
                "id": "",
                "class": ""
            },
            "status": {
                "name": "",
                "id": "",
                "description": ""
            },
            "sources": [
                {
                    "indicator_id": "",
                    "indicator_status_id": "",
                    "published_at": "",
                    "source_id": "",
                    "id": "",
                    "created_at": "",
                    "source_type": "",
                    "creator_source_id": "",
                    "indicator_type_id": "",
                    "reference_id": "",
                    "updated_at": "",
                    "name": ""
                }
            ]
        }
    ],
    "offset": "",
    "limit": ""
}

operation: Add Attribute

Input parameters

Output

The output contains the following populated JSON schema:

{
    "total": "",
    "data": {
        "status": "",
        "result": ""
    }
}

operation: Remove Attribute

Input parameters

Output

The output contains the following populated JSON schema:

{
    "result": "",
    "status": ""
}

operation: Add Source

Input parameters

Output

The output contains the following populated JSON schema:

{
    "status": "",
    "result": ""
}

operation: Remove Source

Input parameters

Output

The output contains the following populated JSON schema:

{
    "result": "",
    "status": ""
}

operation: Get Related Objects

Input parameters

Output

The output contains the following populated JSON schema:

{
    "data": [
        {
            "id": "",
            "hash": "",
            "class": "",
            "pivot": {
                "id": "",
                "src_type": "",
                "dest_type": "",
                "created_at": "",
                "updated_at": "",
                "src_object_id": "",
                "dest_object_id": ""
            },
            "score": "",
            "value": "",
            "sources": [
                {
                    "name": ""
                }
            ],
            "type_id": "",
            "status_id": "",
            "sync_hash": "",
            "created_at": "",
            "deleted_at": "",
            "expired_at": "",
            "expires_at": "",
            "touched_at": "",
            "updated_at": "",
            "description": "",
            "last_detected_at": "",
            "expires_needs_calc": "",
            "expires_calculated_at": ""
        }
    ],
    "limit": "",
    "total": "",
    "offset": ""
}

operation: Link Two Objects

Input parameters

Output

The output contains the following populated JSON schema:

{
    "data": [
        {
            "id": "",
            "name": "",
            "pivot": {
                "id": "",
                "created_at": "",
                "updated_at": ""
            },
            "created_at": "",
            "touched_at": "",
            "updated_at": ""
        }
    ],
    "total": ""
}

operation: Unlink Two Objects

Input parameters

Output

The output contains the following populated JSON schema:

{
    "result": "",
    "status": ""
}

Included playbooks

The Sample - ThreatQ - 2.1.0 playbook collection comes bundled with the ThreatQ connector. This playbook contains steps using which you can perform all supported actions. You can see the bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the ThreatQ connector.

• Add Attribute
• Add Source
• Create Adversary
• Create Event
• Create IOC
• Get Domain Reputation
• Get Event Types
• Get File Reputation
• Get IP Reputation
• Get Indicator Statuses
• Get Indicator Types
• Get List of Adversaries
• Get List of Events
• Get List of Indicators
• Get Related IOCs
• Get Related Objects
• Get Reputation
• Get Saved Searches
• Get URL Reputation
• Link IOCs
• Link Two Objects
• Remove Attribute
• Remove Source
• Run Search Query
• Search Event
• Search Indicator
• Unlink Two Objects
• Update Indicator

Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during connector upgrade and delete.