Getting Started with the Threat Intelligence GraphQL API
Important
Before proceeding, complete the API Authentication steps in order to obtain a working client_id
and client_secret
.
Regions
The URL to access XDR APIs may differ according to the region your environment is deployed in:
- US1—
https://api.ctpx.secureworks.com
- US2—
https://api.delta.taegis.secureworks.com
- US3—
https://api.foxtrot.taegis.secureworks.com
- EU—
https://api.echo.taegis.secureworks.com
The examples in this XDR API documentation use https://api.ctpx.secureworks.com
throughout. If you are in a different region substitute appropriately.
The Secureworks Counter Threat Unit™ (CTU) provides threat intelligence publications to provide customers with threat context. These publications may be retrieved through the Threat Intelligence API.
Note
The Threat Intelligence API is updated approximately every four hours, but updates are not guaranteed to be provided within that interval.
Working with Threat Intelligence APIs ⫘
Download Available Threat Intel Indicator Lists ⫘
Use the following request to retrieve a list of Threat Intel indicator lists available for download. The list contains a link to each list which can be used directly without authentication, as authentication is built into the URL.
cURL ⫘
export ACCESS_TOKEN="<access_token>"
curl --request GET \
--url https://api.ctpx.secureworks.com/intel-requester/ti-list/latest \
--header "Authorization: Bearer ${ACCESS_TOKEN}"
Note
Windows users may need to use the following:
set ACCESS_TOKEN=<access_token>
curl --request GET --url https://api.ctpx.secureworks.com/intel-requester/ti-list/latest --header "Authorization: Bearer %ACCESS_TOKEN%"
Example Response ⫘
[{"link": "https://s3.us-east-2.amazonaws.com/ctpx-prod-threat-intel/scwx-attackerdb/ip/40/attackerdb-ip-third-party-threat-group-indicators-ip-list---mss-rev4207.csv?REDACTED_AUTH",
"name": "scwx-attackerdb/ip/40/attackerdb-ip-third-party-threat-group-indicators-ip-list---mss-rev4207.csv"},
{"link": "https://ctpx-prod-threat-intel.s3.us-east-2.amazonaws.com/ctp-attackerdb/ip/38/attackerdb-ip-ctu-threat-group-indicators-ip-list---mss-rev4200.csv?REDACTED_AUTH",
"name": "ctp-attackerdb/ip/38/attackerdb-ip-ctu-threat-group-indicators-ip-list---mss-rev4200.csv"},
{"link": "https://s3.us-east-2.amazonaws.com/ctpx-prod-threat-intel/scwx-attackerdb/ip/42/attackerdb-ip-ctu-botnet-indicators-ip-list---mss-rev4207.csv?REDACTED_AUTH",
"name": "scwx-attackerdb/ip/42/attackerdb-ip-ctu-botnet-indicators-ip-list---mss-rev4207.csv"},
{"link": "https://s3.us-east-2.amazonaws.com/ctpx-prod-threat-intel/scwx-attackerdb/domainname/43/attackerdb-domainname-ctu-threat-group-indicators-domain-list---mss-rev4184.csv?REDACTED_AUTH",
"name": "scwx-attackerdb/domainname/43/attackerdb-domainname-ctu-threat-group-indicators-domain-list---mss-rev4184.csv"},
{"link": "https://s3.us-east-2.amazonaws.com/ctpx-prod-threat-intel/scwx-attackerdb/domainname/45/attackerdb-domainname-third-party-threat-group-indicators-domain-list---mss-rev4207.csv?REDACTED_AUTH",
"name": "scwx-attackerdb/domainname/45/attackerdb-domainname-third-party-threat-group-indicators-domain-list---mss-rev4207.csv"},
{"link": "https://s3.us-east-2.amazonaws.com/ctpx-prod-threat-intel/scwx-attackerdb/domainname/47/attackerdb-domainname-ctu-botnet-indicators-domain-list---mss-rev4207.csv?REDACTED_AUTH",
"name": "scwx-attackerdb/domainname/47/attackerdb-domainname-ctu-botnet-indicators-domain-list---mss-rev4207.csv"},
{"link": "https://s3.us-east-2.amazonaws.com/ctpx-prod-threat-intel/scwx-attackerdb/ip/38/attackerdb-ip-ctu-threat-group-indicators-ip-list---mss-rev4207.csv?REDACTED_AUTH",
"name": "scwx-attackerdb/ip/38/attackerdb-ip-ctu-threat-group-indicators-ip-list---mss-rev4207.csv"}]
Download Watchlist Indicators by Type ⫘
The following CTU threat intelligence indicator feeds have been identified as high-confidence lists and therefore may be retrieved using the threat watchlist TI API endpoint.
CTU Botnet Indicators IP List - MSS
CTU Threat Group Indicators IP List - MSS
Third Party Threat Group Indicators IP List - MSS
CTU Botnet Indicators Domain List - MSS
CTU Threat Group Indicators Domain List - MSS
Third Party Threat Group Indicators Domain List - MSS
MSS lists relate to threat activity containing high fidelity indicators suitable for automated blocking and detection. Run the following to retrieve the domain watchlist:
query threatWatchlist($type: ThreatParentType! = "DOMAIN")
{
threatWatchlist(type: $type)
{
type spec_version id sharing_id source_sharing_id target_sharing_id created modified description src_desc tgt_desc mitre_attack_categories relationship_type source_ref target_ref confidence indicator_class label tags start_time stop_time source_internal reference
}
}
Download Latest Threat Intel Publications ⫘
query threatLatestPublications($from: Int! = 0, $size: Int! = 3)
{
threatLatestPublications(from: $from, size: $size)
{
id Type Name Description Published Content TLP VID ReportID Reference Category Language
}
}
Threat Intelligence by Indicator ⫘
It is possible to use the threat intelligence API to retrieve CTU threat intelligence reports, threat groups, and/or associated malware families for a respective indicator (if the indicator has a relationship to the aformentioned threat objects in the dataset).
query threatIndicatorIntelligence($ID: String!)
{
threatIndicatorIntelligence(ID: $ID)
{
indicator { type spec_version id sharing_id name description created modified indicator_types pattern pattern_type pattern_version mitre_attack_categories valid_from valid_until kill_chain_phases { kill_chain_name phase_name } score original_indicator indicator_class ipv4 label dns { Domain Hostname Subdomain Tld } whois { DomainName RegistrarName ContactEmail WhoisServer NameServers CreatedDate UpdatedDate ExpiresDate StandardRegCreatedDate StandardRegUpdatedDate StandardRegExpiresDate Status AuditAuditUpdatedDate RegistrantEmail RegistrantName RegistrantOrganization RegistrantStreet1 RegistrantCity RegistrantState RegistrantPostalCode RegistrantCountry RegistrantFax RegistrantTelephone AdministrativeContactEmail AdministrativeContactName AdministrativeContactOrganization AdministrativeContactStreet1 AdministrativeContactCity AdministrativeContactState AdministrativeContactPostalCode AdministrativeContactCountry AdministrativeContactFax AdministrativeContactTelephone } url_info { Query Scheme Port Path RequestURI } tags location { Longitude Latitude } } identities { identity { type spec_version id sharing_id name description created modified roles identity_class sectors contact_information natural_key download_URL internal confidence reason label tags } relationship { type spec_version id sharing_id source_sharing_id target_sharing_id created modified description src_desc tgt_desc mitre_attack_categories relationship_type source_ref target_ref confidence indicator_class label tags start_time stop_time source_internal reference } } reports { report { type spec_version id name description created modified published object_refs content sharing_id tags } relationship { type spec_version id sharing_id source_sharing_id target_sharing_id created modified description src_desc tgt_desc mitre_attack_categories relationship_type source_ref target_ref confidence indicator_class label tags start_time stop_time source_internal reference } } malware { malware { type spec_version id sharing_id name description created modified malware_types family aliases kill_chain_phases { kill_chain_name phase_name } first_seen last_seen operating_system_refs architecture_execution_envs implementation_languages capabilities sample_refs label tags public_summary solution technical_details } relationship { type spec_version id sharing_id source_sharing_id target_sharing_id created modified description src_desc tgt_desc mitre_attack_categories relationship_type source_ref target_ref confidence indicator_class label tags start_time stop_time source_internal reference } } groups { group { type spec_version id sharing_id name Objectives Aliases Tools Motivation IntendedEffect TargetSectors Description ActiveSince LastKnownActivity tags } relationship { type spec_version id sharing_id source_sharing_id target_sharing_id created modified description src_desc tgt_desc mitre_attack_categories relationship_type source_ref target_ref confidence indicator_class label tags start_time stop_time source_internal reference } }
}
}
Next Steps ⫘
For more information, see the Threat Intelligence GraphQL API Documentation.