ThreatStream API Reference Guide

Anomali ThreatStream API
Reference Guide
March 29, 2023

Copyright Notice
© 2023 Anomali, Inc. All rights reserved.
ThreatStream is a registered servicemark. Optic, Anomali Harmony, and Anomali Reports are registered trademarks.
All other brands, products, and company names used herein may be trademarks of their respective owners.
Support
Support Portal https://support.threatstream.com
Email support@threatstream.com
Phone +1 844-4-THREATS
Twitter @threatstream
Documentation Updates
Date Description
3/29/2023 Updated the list of iTypes in "Indicator Types in ThreatStream API" on page 181.
3/17/2023 Updated descriptions of the skip _associations and skip_intelligence attributes and added the
endpoint for retrieving a list of entities of the specified Threat Model type in the "Threat Model " on page 89
section; added API calls for accessing data returned from the AbuseIPDB and Shodan enrichments in
"Intelligence Enrichments" on page 53, updated "Import (without approval)" on page 29
2/2/2023 Updated the description of the search_filter attribute in "Intelligence" on page 40.
1/12/2023 Updated "Investigation" on page 59.
12/20/2022 Added the description of the remote_api attribute, added "Threat Model Entity Tags in Bulk" on page 162.
11/14/2022 Added "Managing up to 10,000 Tags in Bulk" on page 159. Updated "API Metadata" on page 8, the
description of the is_public attribute in "Intelligence" on page 40 and "Threat Model " on page 89, the
description of the tags attribute.
9/14/2022 Updated "Tipreport" on page 138.
8/10/2022 Updated "Import (with approval)" on page 19, "Import (without approval)" on page 29, "Intelligence" on
page 40, "Observable Cloning" on page 52, and "Observable Tags in Bulk" on page 157.
7/19/2022 Updated "Import (with approval)" on page 19 and "Import (without approval)" on page 29.
7/8/2022 Updated "Import (with approval)" on page 19, updated "Import (without approval)" on page 29, added a note
to "Investigation" on page 59.
Anomali ThreatStream API Page 2 of 209

CONTENTS
Introduction 6
Prerequisites 6
Accessing the API 6
Using API to Access ThreatStream OnPrem 9
Appstorehistory 11
Confidence 13
Feed 15
Import 19
Import (with approval) 19
Import (without approval) 29
Import Observables from STIX files 38
Intelligence 40
Search Filter 51
Observable Cloning 52
Intelligence Enrichments 53
AbuseIPDB 56
Request 56
Example 56
Response 56
Example 56
Shodan Database 57
Request 57
Example 57
Response 57
Example 58
Investigation 59
Investigationelement 63

Reference Guide
Investigationanalysis 64
Rules 66
Sandbox 73
Sandbox Search 77
Snapshot 79
SSO History 87
Threat Model 89
Threat Model Search 89
Actors 97
Attack Patterns 103
Campaigns 113
Incidents 119
Malware 124
Signatures 133
Tipreport 138
TTPs (Tactics, Techniques, and Procedures) 144
Vulnerabilities 149
Managing Threat Model Associations 154
Threat Model Entity and Observable Tags 156

Observable Tags in Bulk 157
Threat Model Entity Tags in Bulk 162
User Administration 164
User Audit 168
Whitelist 173
Appendix A: Intelligence Fields in ThreatStream API 177
Appendix B: Indicator Types in ThreatStream API 181

Reference Guide
Appendix C: Fraud Indicator Types for ThreatStream OnPrem 204
Appendix D: Threat Types in ThreatStream 205
Send Documentation Feedback 209

Introduction
Anomali ThreatStream is accessible through REST APIs, which are available to all Enterprise
customers. The APIs offers bi-directional interaction with the ThreatStream platform.
The APIs allow you to pull threat intelligence from the ThreatStream platform for use with other third-
party tools, import observables into ThreatStream from any source, manage threat model entities
and investigations, and so on.
Prerequisites
l A user ID and API key is required to access ThreatStream through the APIs. If you do not have
these credentials, contact your ThreatStream Org Admin to create an account.
l APIs return attributes in the JavaScript Object Notation (JSON) format; therefore, familiarity with
JSON is recommended.
Accessing the API

To access the API, use the following base URL:
https://api.threatstream.com/api/<api_version>/<resource>/
where
<api_version> is either v1 or v2. Refer to each API call to determine the version to use.
<resource> is API endpoint; for example, import, intelligence, tipreport
Authenticating to ThreatStream
Making requests through the API requires authenticating to ThreatStream using your username—the
email address associated with your ThreatStream account—and your dedicated API Key. You can
reference your username and API Key on the My Profile tab within ThreatStream settings.

Reference Guide
Introduction
Specifying your username and API Key in the header of the request is the most secure method of
authentication. Anomali recommends using this authentication method, as shown in the following
example:
curl 'https://api.threatstream.com/api/v2/intelligence/?itype=bot_ip' -H
'Authorization: apikey <username>:<api_key>'
Note: Specifying usernames and API Keys in the URL of the request will be deprecated as an
available authentication method for ThreatStream in a future release.
Using Operators
The first API operator called after the resource must start with a question mark and subsequent
operators must begin with an ampersand.
Example:
curl 'https://api.threatstream.com/api/v2/intelligence/?itype=bot_
ip&status=active' -H 'Authorization: apikey <username>:<api_key>'

Reference Guide
Introduction
API Metadata
The following is an example of typical ThreatStream API metadata:
l total_count—the total number of results that can be retrieved by the API call.
l approximate_count—set to true in cases where API calls yield exceptionally large datasets to
indicate that the total count may not include all results.
Note: The approximate_count metadata attribute is only included in API query responses
under certain conditions. Typically, these are scenarios where results are exceptionally large
and approximation improves application performance.
l took—time in milliseconds ThreatStream took to retrieve the data.
l next—call that can be used to iteratively retrieve the next set of data in the total results.
l limit—number of results returned when API call is made. See "Limiting Results" below.
l offset—the current result row number. Used when iteratively retrieving large datasets. See
"Using “next” to Iteratively Retrieve Datasets" below.
Limiting Results
The limit variable controls the number of results returned every time an API call is made; the total
number of results may be much larger than returned in one API call.
If limit is not specified, 20 results are returned with each API call. Specifying limit=0 will return up
to a maximum of 1000 results (if available).
Using “next” to Iteratively Retrieve Datasets

In cases where the total number of results is larger than can be retrieved in one API call, use the next
field of the returned metadata to make iterative API calls until all results have been returned.
Note: For Intelligence API calls, if results number greater than 10,000, Anomali recommends
using update_id—instead of the next field—to iteratively retrieve the full dataset. See "Using
“update_id” to Retrieve Large Intelligence Datasets" on page 48 for more information.

Reference Guide
Introduction
Example:
curl 'https://api.threatstream.com/api/v2/intelligence/?limit=5' -H
The above API call yields the following metadata:
meta: {
total_count: 6414,
took: 7,
next: "/api/v2/intelligence/<link_to_next_page>",
limit: 5,
offset: 0}
where <link_to_next_page> is the value specified by the metadata in your results.
Therefore, you would use the following API call to retrieve the next five results:
curl 'https://api.threatstream.com/api/v2/intelligence/<link_to_next_page>' -H
where <link_to_next_page> is the value to use to retrieve the next set of results
Repeat this process iteratively until next = null. The total number of results you will retrieve by making
the intelligence API call iteratively is 6414.
Note: The total_count value may not represent the full dataset if approximate_count is set to
true in the metadata.
Filtering Results
You can filter returned results by specifying the attribute and a value. For example, “itype=bot_ip”.
Refer to each API call attributes to determine the attributes you can filter on and the operators you
can use for those attributes.
Using API to Access ThreatStream OnPrem

All APIs described in this guide can be used to query ThreatStream OnPrem deployments. To query
a ThreatStream OnPrem deployment, simply replace api.threatstream.com with the IP address or
FQDN that you use to access your ThreatStream OnPrem.
For example, the following call returns observables from your ThreatStream OnPrem deployment
using the Intelligence API:
curl "https://<ThreatStream_OnPrem_IP_or_
FQDN>/api/v2/intelligence/?&status=active&itype=fraud_email" -H 'Authorization:
apikey <username>:<api_key>'
where

Reference Guide
Introduction
<OnPrem_IP_or_FQDN> is the IP address or FQDN you use to access your ThreatStream OnPrem,

such as 192.168.10.168.
From your ThreatStream OnPrem deployment, you can also access ThreatStream Cloud intelligence
by setting the remote_api parameter to true.
For example, the following call returns the details of a remote vulnerability whose ID is 21:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/vulnerability/21/?remote_
api=true" -H 'Authorization: apikey <username>:<api_key>'
where
<OnPrem_IP_or_FQDN> is the IP address or FQDN you use to access your ThreatStream OnPrem,

such as 192.168.10.165.
<username> is the username you use to access ThreatStream OnPrem.
<api_key> is the API Key provided on the My Profile tab within ThreatStream OnPrem.

Appstorehistory
To return a log of organization activity in the ThreatStream APP Store, including requests, failed
requests, approvals, rejections, or other changes.
Request
/api/v1/appstorehistory/
Bulk HTTP Method: GET
Response
Format: JSON
Number of rows returned (by default): 20
Attributes: See table below.
Attributes
Attribute Description
edit_type APP Store activity type. Possible types include:
l Accepted Paid—a user in your organization activated an APP Store service on

a paid basis.
l Accepted Trial—a user in your organization activated an APP Store service

on a trial basis.
l Activation—a user in your organization activated an APP Store service.
l Approved—a vendor approved your request for access to an APP Store

service.
l Credential Change—a user in your organization updated the credentials

required to activate an APP Store service.
l Declined—trial access request declined by the vendor.
l Ejection—a vendor removed access from your organization to an APP Store

service.
l Invite—a vendor invited your organization to activate an APP Store service.
l Leave/Deactivation—a user in your organization deactivated an APP Store

service.

Reference Guide
Appstorehistory
l Request—a user in your organization requested trial access to an APP Store

service.
l Request Unauthorized—a user made an unauthorized request for access to

an APP Store service.
l Unauthorized—a vendor sent an unauthorized invite to your organization.
email Email address of the user in your organization who performed the action.
Note: Email addresses are only shown for actions taken by users in your
organization. Actions taken by vendors do not list an email address.
id Unique ID of the APP store activity on the activity log.
name Name of the APP Store service.
resource_ Resource URI of the APP store activity on the activity log.
uri
timestamp Timestamp when the action was taken.
Example
Request:
curl "https://api.threatstream.com/api/v1/appstorehistory/" -H 'Authorization:
Response:
{
"edit_type": "Accepted Paid",
"id": 929,
"name": "Cofense Intelligence",
"resource_uri": "/api/v1/appstorehistory/929/",
"timestamp": "2020-06-05 20:32:56.511717+00:00"
}

Confidence
To return all observable confidence scores displayed on observable details pages.
Request
/api/v1/inteldetails/confidence_trend/
Request Attributes
type Type of intelligence details. Default: confidence
value Value of an observable for which confidence will be returned.
Response
Format: JSON
Response Attributes
min_confidence Lowest ThreatStream calculated confidence score for the observable.
average_confidence Average ThreatStream calculated confidence score for the observable.
max_confidence Highest ThreatStream calculated confidence score for the observable.
Example
Request:
curl "https://api.threatstream.com/api/v1/inteldetails/confidence_
trend/?type=confidence&value=118.172.14.234" -H 'Authorization: apikey
<username>:<api_key>'

Reference Guide
Confidence
Response:
{
"min_confidence": 66,
"average_confidence": 69,
"max_confidence": 70
}

Feed
To retrieve a list of intelligence feeds which are feeding your threat intelligence on ThreatStream.
Note: In ThreatStream, "feed" and "stream" are used interchangeably.
Request
/api/v1/feed/
HTTP Method: GET
Attributes: See the table below
Attributes
Attribute Type Description
expiry_time_in_ integer Length of time after import that observables remain active.
days
id integer Unique ID for the feed.
itype string Default indicator type assigned to observables imported from the
feed.
name string Name of the feed.
Response
Format: JSON
Attributes
active boolean Whether ThreatStream is currently receiving data from

the feed.
allow_unresolved_ N/A This attribute is for internal use and can be ignored.
domain
allow_update N/A This attribute is for internal use and can be ignored.

Reference Guide
Feed
child_page_url_template N/A This attribute is for internal use and can be ignored.
circles list Trusted circles with which data from streams is shared.
classification string Classification of the data from the feed—public or

private. By default, for feeds, data classification is
private.
confidence numeric Default confidence scores assigned to observables

from the stream. Level of certainty that an observable
is of the reported indicator type.
Confidence scores range from 0-100, in increasing

order of confidence.
config array Configuration settings for the feed.
created_ts datetime Time stamp of when the feed was created, in UTC
format.
description string Short description of the feed.
disable_notifications N/A This attribute is for internal use and can be ignored.
engine N/A This attribute is for internal use and can be ignored.
expiry_date N/A This attribute is for internal use and can be ignored.
expiry_source N/A This attribute is for internal use and can be ignored.
expiry_time_in_days integer Length of time after import that observables remain

active.
feed_category N/A This attribute is for internal use and can be ignored.
feed_type N/A This attribute is for internal use and can be ignored.
feedgroups N/A This attribute is for internal use and can be ignored.
fields string List of fields that come through the feed.
fields_mapping string List of fields that is saved to the database.
hidden N/A This attribute is for internal use and can be ignored.
id integer Unique ID for the feed.
id_regex N/A This attribute is for internal use and can be ignored.
imap_host N/A This attribute is for internal use and can be ignored.
imap_port N/A This attribute is for internal use and can be ignored.

Reference Guide
Feed
imap_subject_regexp N/A This attribute is for internal use and can be ignored.
interval string Interval at which ThreatStream scrapes the feed for

new data.
is_autoprov N/A This attribute is for internal use and can be ignored.
is_cloneable N/A This attribute is for internal use and can be ignored.
is_owner N/A This attribute is for internal use and can be ignored.
itype string Default indicator type assigned to observables

imported from the feed.
last_imported datetime Timestamp of when new data was actually imported to

ThreatStream.
last_scraped datetime Timestamp of when ThreatStream last scraped the

feed for new data.
last_updated datetime Timestamp of when feed settings were last changed.
name string Name of the feed.
notes N/A This attribute is for internal use and can be ignored.
organization array Organization which owns the feed. Contains id, name,
and resource_uri attributes.
reference_url N/A This attribute is for internal use and can be ignored.
resource_uri string Internal URL for the feed within ThreatStream.
severity N/A This attribute is for internal use and can be ignored.
should_reactivate_intel N/A This attribute is for internal use and can be ignored.
sleep_time N/A This attribute is for internal use and can be ignored.
source_confidence_ numeric Ratio (0-100) between source confidence and the

weight ThreatStream confidence score taken into account
when determining the confidence score displayed on
the ThreatStream user interface.
state string Current state (health) of the feed. Possible values:

success, no results, errors, no run.
tags list Additional comments and context associated with the

observable when it was imported from its original threat
feed.
url string URL where the feed is hosted.
use_proxy N/A This attribute is for internal use and can be ignored.

Reference Guide
Feed
Examples
1. To retrieve the first 100 feeds to which you have access on ThreatStream:
curl 'https://api.threatstream.com/api/v1/feed/?limit=100' -H
2. To retrieve a specific feed whose ID is 19:
curl 'https://api.threatstream.com/api/v1/feed/?id=19' -H 'Authorization:


Import
The approach you use to import data into ThreatStream depends largely on the data set you are
importing. For most imports, you will want to import the data through the API, and then review it within
the ThreatStream UI to approve the import. Doing so allows you to review the indicators being
imported. However, if the data you are importing is in a structured format, such as JSON, and strictly
follows the format described in this document, you can import it directly into ThreatStream, without
requiring you to review it first within the ThreatStream UI.
Note: Anomali recommends reviewing the indicator data being imported for all file formats
except JSON, which can be imported directly if the data is in the format described in this
document.
To import data in any format and require approval on ThreatStream before the import is complete:
See "Import (with approval)" below.
To import data without requiring an approval before the import is complete: See "Import (without
approval)" on page 29.
Import (with approval)

To import threat data (observables) into ThreatStream and require approval of the imported data
through the ThreatStream UI. Unstructured data can be specified in any format, such as JSON, CSV,
PDF, or plain text, and can be contained in a file or directly specified in the API call. You can also
import data from plain text intelligence streams by specifying a URL. Once data has been imported,
you must login to the ThreatStream UI and approve the import.
This method can be used to import unstructured and structured data. See "Supported Data Formats"
on page 24 for more information.
When importing unstructured data, all intelligence is associated with the same attributes—threat
type, classification, confidence. For example, if a file has two IP addresses, each IP will be assigned
the same indicator type based on the threat type you specify. See "Request Attributes" on the next
page for a list of global settings that can be specified for imported observables.
However, when importing structured data, you can specify a different itype and tags for each
observable in the structured file, which is different from the global settings. When a local setting is
specified, it overrides the global setting.
Request
/api/v2/intelligence/import/
Important: /api/v1/intelligence/ requests are now deprecated. Anomali recommends

using /api/v2/intelligence/ for all requests.

Reference Guide
Import
HTTP Method: POST
Request Attributes
These attributes specify global settings for imported observables. If an imported observable does not
have an explicitly specified value for these settings, the global setting is applied. However, if an
imported observable does have an explicitly specified value, it overrides the global value.
actors string IDs of the actors with which you want to associate the imported
intelligence.
campaigns string IDs of the campaigns with which you want to associate the
imported intelligence.
classification string Classification of the observable—public or private.
confidence numeric Level of certainty that an observable is of the reported indicator

type.
Confidence score can range from 0-100, in increasing order of

confidence.
If you want ThreatStream to use the confidence value that you

specify and not re-assess the value using its machine-learning
algorithms, see "source_confidence_weight" on page 22.
datatext string Text containing the observables you want to import.
default_state string Whether the import job must be approved from the
ThreatStream user interface before observables become
active.
When default_state is set to active, observables become

active upon submission, without requiring approval. In these
cases, an import job is created on ThreatStream which is
automatically approved.
You must have the Approve Import privilege in order to import

observables through the API with default_state set to
active.
If no value is specified for default_state, resulting import jobs

are in Ready to Review status and must be approved from the
ThreatStream user interface before observables become
active.

Reference Guide
Import
expiration_ts date Time stamp of when intelligence will expire on ThreatStream, in

UTC format. For example, 2017-01-26T00:00:00.
By default, the expiration_ts is set to 90 days from the current

date.
file string Path to the file from which the observables will be imported.
incidents string IDs of the incidents with which you want to associate the
intelligence_ string Source from which the intelligence originated.

source
is_anonymous boolean Whether you want to anonymize your organization information.

Users outside of your organization with access to the
observables will see "Analyst" in all fields that would otherwise
display an organization or user name.
True—if you want to anonymize organization information
False—if you do not want to anonymize your organization

information
malware string IDs of the malware with which you want to associate the
reject_benign boolean Whether benign observables—those assigned a confidence

score of 15 or less—are automatically excluded from the import
job.
True—if you want to reject benign observables
False—if you do not want to reject benign observables
By default, reject_benign is set to True.
remote_api (for boolean Whether intelligence is remote (stored on Cloud).

ThreatStream
This attribute does not need to be set to ingest local intelligence.
OnPrem only)
Only use this attribute when ingesting remote intelligence from
ThreatStream Cloud. Set this attribute to true in this case.
Do not set this attribute to false for ingesting local intelligence.

Doing so will generate errors.
severity string Gauges the potential impact of the indicator type the observable
is thought to be associated with.
Possible values: low, medium, high, very-high
Note: A default severity value is assigned to each imported

observable, based on its indicator type. (See Help for the

Reference Guide
Import
Severity field in the ThreatStream UI for a list of default severity

values for indicator types.) However, if you want to override the
default value, you can use this field.
source_ numeric Specifies the ratio between the amount of the source
confidence_weight confidence of each observable and the ThreatStream
confidence. For example, if this setting = 30%, when calculating
the final source_confidence, 30% weight is given to the
confidence specified by the source of the observable and 70%
weight is given to the confidence deemed by ThreatStream
(based on the machine-learning algorithms).
Notes:
l To use your source's confidence entirely, set source_

confidence_weight to 100.
l source_confidence_weight can only be specified as a

request attribute. It cannot be specified in the structured
CSV file.
l This is the same setting as the Confidence setting that you

specify in the ThreatStream UI when importing intelligence
in the Import Intelligence section and is taken into account
when "Trust My Confidence" is checked on the Import UI
page.
l This setting only applies to observables for which

classification is set to private, including those shared with
trusted circles.
tags string Tags applied to the imported observables.
Tags must be specified as follows:
tags=[{“name”:"my_tag",“tlp”:"red"},{"name":"my_
tag2",“tlp”:"white"},{"name":"my_tag3"}]
Tag Attributes:
l name—name of the tag that you want to add.
l tlp—the visibility setting for the tag. Possible values:
n red—private, or visible to your organization only.
n white—public, or visible to all ThreatStream users with

access to the data.
Default: white

Reference Guide
Import
Note: Adding public tags may be restricted by your Org

Admin.
In the example above, my_tag is private and my_tag2 and

my_tag3 are public.
threat_type string Type of threat associated with the imported observables.

ThreatStream assigns observable types based on the threat
type you specify. For a complete list of threat types, see Threat
Types in ThreatStream.
If you specify a threat type not associated with observable types

that map to the observables you import, imported observables
will be assigned malware indicator types by default. For
example, if you import a file hash and specify the adware threat
type—whose only indicator type association is "adware_
domain"—ThreatStream will assign the malware_md5 indicator
type by default.
tipreports string IDs of the tipreports with which you want to associate the
tlp string Traffic Light Protocol designation for the intelligence—red,

amber, green, white.
trustedcircles numeric ID of the trusted circle to which this threat data should be
imported. If you want to import the threat data to multiple trusted
circles, enter the list of comma-separated IDs.
To find the ID of a trusted circle, locate the trusted circle on

ThreatStream, click on its name. The URL displayed in the
address bar shows the ID. For example,
https://ui.threatstream.com/search?trusted_circle_ids=13.
ttps string IDs of the ttps with which you want to associate the imported
intelligence.
Type-specific mappings
Note: If you do not specify a threat_type in your request, you must specify indicator type
mappings for each of the following attributes. See Indicator Types for a complete list of
supported values. See "Fraud Indicator Types for ThreatStream OnPrem" on page 204 for a
list of indicator types exclusive to ThreatStream OnPrem.

Reference Guide
Import
domain_mapping string Indicator type to assign if a specific type is not associated with
an observable.
This is a global setting that applies to any imported domain-type

observable when an explicit itype is not specified for it.
email_mapping string Indicator type to assign if a specific type is not associated with
an observable.
This is a global setting that applies to any imported email-type

ip_mapping string Indicator type to assign if a specific type is not associated with
an observable.
This is a global setting that applies to any imported IP-type

md5_mapping string Indicator type to assign if a specific type is not associated with
an observable.
This is a global setting that applies to any imported MD5-type

url_mapping string Indicator type to assign if a specific type is not associated with
an observable.
This is a global setting that applies to any imported URL-type

Supported Data Formats

This API call can be used to import unstructured and structured data.
Unstructured Data
There are no specific requirements for unstructured data.
Structured Data
Follow these guidelines when importing structured data:
l The structured data must be contained in a valid CSV file with the following header line: value,
itype, tags. Optional columns include private_tags, is_anonymous, and tlp.

Reference Guide
Import
is_
privat anonymo
value itype tags e_tags us tlp
1.2.3.4 brute_ exploitation,phish true green

ip ing
https://example.com apt_ phishing sensitiv amber

url e
4d68462ca6071f9b6ad0fabea8 mal_ false red

bd1c9f md5
l The value header label is mandatory. This column must contain data.
l For domain, email, IP, MD5, and URL observables, itype, tags, and private_tags header
labels can be omitted if no data will be specified for these columns. For all other observables, you
must specify a value for itype. See "Import (with approval)" on page 19 of indicator types (itype).
l tags is a comma-separated list of tags. Tags included in the tags column are assigned the
Anomali Community visibility setting and visible to all users with access to the observable.
l private_tags is a comma-separated list of tags. Tags included in the private_tags column are
assigned the My Organization visibility setting and visible only to users in your organization.
l is_anonymous sets whether the organization and user information for the observable is
anonymized. Possible values include true and false. If no value is specified, observables will
not be anonymized.
l tlp sets a TLP color for the observable. Possible values include white, green, amber, and red.
l The data specified in itype and tags columns overrides the global settings specified in the
"Request Attributes" on page 20 settings. For example, if the structured CSV contains the
following: value=1.2.3.4, itype=phish_ip, and Request Attribute ip_mapping=mal_ip, then itype
for the observable 1.2.3.4 will be set to phish_ip because the setting in the file (local value) will
override the Request Attribute setting (global value).
l If the itype and tags columns are empty, the data for these columns is derived from the
"Request Attributes" on page 20 settings. For example, if value=1.2.3.4, itype is not specified in
the file, tags is not specified in the file, and the Request Attribute ip_mapping=mal_ip, then itype
for the observable will be set to mal_ip.
Examples
1. To import observables from a file. The file can contain unstructured or structured data.
curl example:

Reference Guide
Import
curl -X POST 'https://api.threatstream.com/api/v2/intelligence/import/' -F

"confidence=30" -F "classification=private" -F "threat_type=malware" -F
"file=@<filename>" -H 'Authorization: apikey <username>:<api_key>'
Python example:
def import_with_approval_using_file(username, api_key):

auth = 'apikey {}:{}'.format(username, api_key)
headers = {'Authorization': auth}
api_url = "https://api.threatstream.com/api/v2/intelligence/import/"
tags = [{'name': 'private_tag', 'tlp': 'red'}]
payload={
'classification': 'private',
'confidence': 70,
'threat_type': 'malware',
'tags': json.dumps(tags)
}
filename = '<name_of_your_file>' #this can be a .txt, .csv or .pdf file
files = {'file': open(filename, 'rb')}
response = requests.post(api_url, headers=headers, data=payload, files=files)
print(response.text)
2. To import observables directly, by specifying them in the API call:
curl example:

"confidence=70" -F "classification=private" -F "threat_type=apt" -F
"datatext=<text_to_parse_and_import>" -H 'Authorization: apikey
Python example:
def import_with_approval_using_datatext(username, api_key):

url = "https://api.threatstream.com/api/v2/intelligence/import/"
tags = [{'name': 'public_tag'}, {'name': 'private_tag', 'tlp': 'red'}]
payload={
'confidence': 65,
'tags': json.dumps(tags),
'datatext': <text_to_parse_and_import>'
}
response = requests.post(url, headers=headers, data=payload)

Reference Guide
Import
3. To import observables from a plain text intelligence stream by specifying a URL:
curl example:

"confidence=60" -F "classification=private" -F "threat_type=c2" -F
"url=<url_for_plain_text_stream>" -H 'Authorization: apikey <username>:<api_
key>'
Python example:
def import_with_approval_using_url(username, api_key):

api_url = "https://api.threatstream.com/api/v2/intelligence/import/"
tags = [{'name': 'public_tag'}, {'name': 'private_tag', 'tlp': 'red'}]
url = "<your_url>"
payload={
'confidence': 70,
'tags': json.dumps(tags),
'url': url
}
response = requests.post(api_url, headers=headers, data=payload)
4. To import observables associated with tags that are private to your organization

"threat_type=malware" -F "datatext=<text_to_parse_and_import>" -F
"classification=private" -F "confidence=40" -F 'tags=[{"name":"my_tag",
"tlp":"red"},{"name":"another_private_tag", "tlp":"red"}]' -H
5. To import observables and share them with trusted circles whose ids are 1 and 2:

"confidence=80" -F "classification=private" -F "trustedcircles=1,2" -F
"threat_type=phish" -F "datatext=<text_to_parse_and_import>" -H
6. To automatically approve imported observables. An import job is created and observables are
set to active.

"classification=private" -F "threat_type=malware" -F 'tags=
[{"name":"tag1","tlp":"red"}]' -F "datatext=<text_to_parse_and_import>" -F
"default_state=active" -H 'Authorization: apikey <username>:<api_key>'

Reference Guide
Import
7. To import observables and create an association between the import job and an Actor whose ID
is 77:

"actors=77" "threat_type=apt" -F "datatext=<text_to_parse_and_import>" -H
Response
HTTP 202 Accepted {"import_session_id": IMPORT_SESSION_ID, "success": STATUS, "job_id":
BACKGROUND_JOB_ID}
where
import_session_id is the ID for the import job. You will need this ID to check the status of the
import job.
job_id is an identifier for the job on ThreatStream.
Example Response:
{"job_id": "6194c7c0-53ae-41fc-a6f0-dc3d174f02e2", "success": true, "import_session_id": "482"}
Checking status of an Import job

Use this API call to periodically poll the status of an import job:
curl -X GET 'https://api.threatstream.com/api/v1/importsession/import_session_

id/' -H 'Authorization: apikey <username>:<api_key>'
where import_session_id is the identifier that was returned in the response of the Import call.
This call returns one of the following statuses in the "status" attribute:
l processing—the import process is in progress. Keep polling periodically.
l errors—the import process failed.
l done—the import process has completed.
At this point, the call also returns numIndicators and numRejected attributes that denote the
number of observables that were accepted for importing and the observables that were rejected,
respectively. This information is the same as the one displayed on the Import Review page of the
ThreatStream UI.
Getting Observable ID in an Import Job
Note: Before executing this call, make sure that the import job belongs to your organization.
Use this API to get IDs of the observables in an import job.
curl -X GET 'https://api.threatstream.com/api/v1/importsession/<import_session_
id>/intelligence' -H 'Authorization: apikey <username>:<api_key>'
where <import_session_id> is the identifier of the import job.

Reference Guide
Import
This call returns the information about the import job. You can view IDs of the observables in the "id"
attribute.
Approving All Observables in an Import Job
Note:
l Before executing this call, make sure that the import job belongs to your organization.
l You must have the Approve Intel user permission to use this API call. Org Admins can grant
this permission from the ThreatStream user interface.
Use this API call to approve all observables in an import job:
curl -X PATCH 'https://api.threatstream.com/api/v1/importsession/<import_

session_id>/approve_all' -H 'Authorization: apikey <username>:<api_key>'
where <import_session_id> is the identifier of the import job.
Approving Selected Observables in an Import Job
Note:
l Before executing this call, make sure that the import job belongs to your organization.
l You must have the Approve Intel user permission to use this API call. Org Admins can grant
this permission from the ThreatStream user interface.
Use this API call to approve selected observables in an import job:
curl -X PATCH 'https://api.threatstream.com/api/v1/importsession/<import_

session_id>/approve_selected/?ids=<id1>,<id2>' -H 'Authorization: apikey
where
<import_session_id> is the identifier of the import job.
ids=<id1>,<id2> is a comma-separated list of IDs of the observables to be imported.
Import (without approval)

To import structured threat data (observables) into ThreatStream, without requiring approval of the
imported data through the ThreatStream UI. Data payload must be specified in a valid JSON format
that adheres to the guidelines in this article. JSON can be specified in a file or as a JSON object in
your API request. When you import observables through the Import (without approval) API, no import
session is created on the ThreatStream UI.

Reference Guide
Import
Notes:
l You must have the Approve Intel user permission to import without approval via the API.
Org Admins can grant this permission from the ThreatStream user interface.
l The size of the imported content must not exceed 10MB.
Request
/api/v2/intelligence/

HTTP Method: PATCH
The Import (without approval) API requires that you specify payload in JSON format. It has two
properties: meta—for specifying global settings which apply to all observables—and objects—
which specify settings per observable.
Specifying global settings is not mandatory. Per observable settings take precedent over global
settings in cases where both are specified for a given attribute. For example, if classification=private
in the meta section, and an imported observable has classification=public at the object level, the
indicator will be marked public.
Meta Attribute
The following table contains an attribute which can be specified in the meta section only.
allow_ boolean When set to true, domain observables included in the file which do
unresolved not resolve will be accepted as valid in ThreatStream and imported.
Note: If allow_unresolved is not set to true, unresolved

domains are always ignored.
Shared Attributes
The attributes in the table below can be used to specify settings in the meta or objects section of the
JSON file.
classification string Classification (visibility) of the indicator—public or private.
Default: public
confidence numeric Level of certainty that an observable is of the reported indicator

Reference Guide
Import
type.
Confidence score can range from 0-100, in increasing order of

confidence.
If you want ThreatStream to use the confidence value that you

specify and not re-assess the value using its machine-learning
algorithms, see"source_confidence_weight" below.
Note: ThreatStream only scores domain, IP, and URL

observables. For all other observable types, you must specify
a confidence value—either globally or per observable.
source_ numeric To use your specified confidence entirely, set source_

confidence_ confidence_weight to 100.
weight
Note: If you set source_confidence weight to 100, you must
specify a value for confidence. Additionally, all observables
with source_confidence_weight=100 are made private to
your organization, regardless of specified classification
settings.
expiration_ts date Time stamp of when intelligence will expire on ThreatStream, in

ISO format. For example, 2017-01-26T00:00:00.
By default, UTC time is used. You can specify your local time by
appending your timezone to the value. For example, to specify
PST: 2019-04-28T14:00:00-08:00
If a global or a local value is not specified for this attribute, by

default 90 days is configured.
remote_api (for boolean Whether intelligence is remote (stored on Cloud).

ThreatStream
This attribute does not need to be set to ingest local intelligence.
OnPrem only)
Only use this attribute when ingesting remote intelligence from
Do not set this attribute to false for ingesting local intelligence.

severity string Severity you want to assign to the observable when it is imported.
Default severity values are assigned based on the indicator type

of the observable.

Reference Guide
Import
Tag Attributes:

access to the data.
Default: white

Admin.
In the example above, my_tag is private and my_tag2 and my_

tag3 are public.
trustedcircles list ID of the trusted circle with which this threat data should be
shared. If you want to import the threat data to multiple trusted
circles, enter a list of comma-separated IDs.
Tip: To find the ID of a trusted circle, locate the trusted circle

on ThreatStream, click on its name. The URL displayed in the
https://ui.threatstream.com/search?trustedcircles=13.
Required Fields
Fields which must contain data vary based on the type of observable. The following table lists the
mandatory fields for each observable type.
Observable Type Required Fields
Domain domain, itype
Email email, itype, confidence
Hash md5, itype, confidence
IP srcip, itype
URL url, itype

Reference Guide
Import
Response
HTTP 202 Accepted
Note: This response indicates that the JSON you submitted was valid. However, in cases where
data is incorrect or required fields are left unspecified, observables can be ignored or imported
as false positive. For example, if confidence is not specified for md5 or email observables, the
observables are imported as false positive. Alternatively, if allow_unresolved is not set to true
when importing unresolved domains, these observables will be ignored.
Examples
1. To import private observables of different types:
curl example:
curl -X PATCH 'https://api.threatstream.com/api/v2/intelligence/' -H

'Content-Type: application/json' -H 'Authorization: apikey <username>:<api_
key>' --data @/<folder_path>/indicators.json
where indicators.json contains the following data:
{
"meta":{
"classification":"private",
"confidence":60
},
"objects":[
{
"srcip":"1.2.3.4",
"itype":"bot_ip",
"tags":[
{
"name": "private_tag",
"tlp": "red"
},
{
"name": "public_tag",
"tlp": "white"
}
],
"severity":"high"
},
{
"domain":"idfsdszqylwjzq.biz",
"itype":"mal_domain",

Reference Guide
Import
"severity":"very-high"
},
{
"url":"http://malicious.pl/wp-content/themes/credenza-wp/cr_
mss3.exe",
"itype":"mal_url",
"severity":"high"
},
{
"email":"email@domain.com",
"itype":"compromised_email",
"tags":[
{
"name": "private_tag",
"tlp": "red"
},
{
"name": "public_tag",
"tlp": "white"
}
],
"severity":"low"
},
{
"md5":"1d37556b8aeb5cb5fbf08cd5b4790075",
"itype":"apt_md5",
"severity":"medium",
"expiration_ts":"2017-01-26T00:00:00"
}
]
}
Python example:
def import_without_approval(username, api_key):

url = "https://api.threatstream.com/api/v2/intelligence/"
payload = {
"meta": {
"confidence": 60,
"allow_unresolved": True,
"classification": "private"
},
"objects": [

Reference Guide
Import
{
"value": ""msfbckupsc.com",
"itype": ""apt_domain",
"severity": "high",
"tags": [{"name": "private_tag", "tlp": "red"}]
},
{
"value": "106.210.164.198",
"itype": "mal_ip",
"severity": "high"
}
]
}
response = requests.patch(url, headers=headers, json=payload)
print (response.status_code)
print (response.content)
2. To import an IP address with the minimum required fields:
curl -X PATCH 'https://api.threatstream.com/api/v2/intelligence/?' -H

'Authorization: apikey <username>:<api_key>' -H 'Content-Type:
application/json' --data @/<folder_path>/indicators.json
{
"objects":[
{
"srcip":"5.253.63.134",
"itype":"bot_ip"
}
]
}
3. To import an email address with one private and one public tag:

{
"meta":{
"classification":"public",
"tags":[

Reference Guide
Import
{
"name":"private_tag",
"tlp":"red"
},
{
"name":"public_tag",
"tlp":"white"
}
]
},
"objects":[
{
"email":"email@test.com",
"itype":"apt_email"
}
]
}
4. To import an email address with the minimum required fields and globally configured
classification:

{
"meta":{
"classification":"private"
},
"objects":[
{
"email":"joe@example.com",
"itype":"mal_email"
}
]
}
5. To import a domain and use the specified confidence score entirely:


Reference Guide
Import
{
"meta":{
"source_confidence_weight":100
},
"objects":[
{
"domain":"www.example.com",
"itype":"apt_domain",
"confidence":99
}
]
}
6. To import IP addresses with confidence specified globally and per observable:

{
"meta":{
"confidence":100
},
"objects":[
{
"srcip":"345.678.45.7",
"itype":"mal_ip",
"confidence":50
},
{
"srcip":"322.609.78.33",
"itype":"apt_ip"
}
]
}
In the above example, the confidence value specified for the first observable overrides the
globally specified confidence value.

Reference Guide
Import
Import Observables from STIX files

To import STIX compatible threat data (observables) into ThreatStream.
Request
/api/v1/stix_import/
HTTP Method: POST
Attributes
classification string Classification of the observable—public or private.
confidence string Default confidence scores assigned to observables from the stream.
Level of certainty that an observable is of the reported indicator
type.
Confidence scores range from 0-100, in increasing order of

confidence.
file string Path and name of the file from which the observables will be
imported.
is_anonymous boolean Whether you want to anonymize your organization and user
information. Users outside of your organization with access to the
observables will see "Analyst" in all fields that would otherwise
display an organization or user name.
True—if you want to anonymize organization information
False—if you do not want to anonymize your organization

information
Tag Attributes:

Reference Guide
Import
access to the data.
Default: white

Admin.
In the example above, my_tag is private and my_tag2 and my_

tag3 are public.
trustedcircles integer ID of the trusted circle to which this threat data should be imported. If
you want to import the threat data to multiple trusted circles, enter
the list of comma-separated IDs.
Tip: To find the ID of a trusted circle, locate the trusted circle on

ThreatStream, click on its name. The URL displayed in the
Examples
1. To import observables from a STIX compatible file:
curl -X POST 'https://api.threatstream.com/api/v1/stix_import/' -F

“file=@<filepath>/<filename>" -F “classification=private" -F 'tags=
[{"name":"my_tag", "tlp":"red"}]' -F "confidence=60" -H 'Authorization:
2. To import observables and share them with trusted circles whose ids are 1 and 2:
curl -X POST 'https://api.threatstream.com/api/v1/stix_import/' -F

“file=@<filepath>/<filename>" -F “classification=private" -F 'tags=
[{"name":"my_tag", "tlp":"red"}]' -F "confidence=60" -F "trustedcircles=1,2"
-H 'Authorization: apikey <username>:<api_key>'

Intelligence
To retrieve threat intelligence from ThreatStream.
ThreatStream provides multiple methods for retrieving threat intelligence. Use the following criteria to
determine which method is appropriate for your needs:
Task Appropriate Method
Downloading small intelligence sets on an ad- Use the Intelligence API.

hoc basis.
Downloading large intelligence sets–those Use the Snapshot API. See "Snapshot" on
spanning thousands of pages–on an ad-hoc page 79 for more information.
basis.
Downloading large intelligence sets–those Use ThreatStream Integrator. Contact your

spanning thousands of pages–on a regular Anomali Support representative for more
basis. information.
You can specify criteria by which the intelligence should be retrieved, as shown in the examples
below.
Request
/api/v2/intelligence/

HTTP Methods:
Get a list of GET /api/v2/intelligence/

observables
Get a list of remote GET /api/v2/intelligence/?remote_api=true

observables (for
This attribute does not need to be set to retrieve local observables. Only
ThreatStream OnPrem
use this attribute when retrieving remote observables from
only)
Do not set this attribute to false for retrieving local observables. Doing
so will generate errors.

Reference Guide
Intelligence
Response
Format: JSON
Filtering of attributes: See the table below
Ordering of attributes: The attributes are sorted by the modified_ts attribute, in descending order
Attributes
Filter
Attribute Type Operators Description
asn string "exact", Autonomous System (AS) number associated

"startswith", with the indicator.
"contains"
can_add_ boolean "exact" Indicates whether a user can add public tags to a
public_tags Threat Model entity.
confidence long "exact", "lt", "lte", Level of certainty that an observable is of the
"gte", "gt" reported indicator type.
Confidence scores range from 0-100, in

increasing order of confidence, and is assigned
by ThreatStream based on several factors.
country string "exact", Country associated with the indicator.

"startswith",
"contains"
created_ts date "exact", "lt", "lte", When the indicator was first seen on the
"gte", "gt" ThreatStream cloud platform.
Date must be specified in this format:

YYYYMMDDThhmmss
where T denotes the start of the value for time, in

UTC time.
For example, 2014-10-02T20:44:35.
description n/a This attribute is for internal use and can be

ignored.

Reference Guide
Intelligence
Filter
expiration_ts date "exact", "lt", "lte", Time stamp of when intelligence will expire on
"gte", "gt" ThreatStream, in UTC time.
Note: expiration_ts can only be specified in

an advanced search query. See "Advanced
Search Queries" on page 49 for more
information.
feed_id long "exact" Numeric ID of the threat feed that generated the
indicator.
feed_id = 0 for user-created indicators.
id string Not available for Unique ID for the indicator.

filtering
This identifier is assigned to the indicator when it
is first created on ThreatStream. Unlike update_
id, this identifier never changes as long as the
indicator is available on ThreatStream.
import_ long "exact" ID of import session in which the indicator was
session_id imported.
import_session_id=0 if the indicator came in

through a threat feed.
ip string "exact", The IP address associated with the indicator if

"startswith", the imported indicator is a domain or a URL.
"contains"
is_anonymous boolean "exact" Whether the organization and user information is

anonymized when the observable is accessed
by users outside of the owner organization.
is_editable boolean Not available for Indicates whether the imported entity can be
filtering updated by an intelligence source.
This attribute is reserved for intelligence source

providers and can be ignored.

Reference Guide
Intelligence
Filter
is_public string/ "exact" Visibility of the indicator—public or private.

boolean
0/False—if the indicator is private or belongs to a
Trusted Circle
1/True—if the indicator is public
Default: 0/False
Note: This attribute is treated as a string or

boolean in requests and as boolean in
responses.
itype string "exact", Indicator type. See Indicator Types. See "Fraud
"startswith", Indicator Types for ThreatStream OnPrem" on
"contains" page 204 for a list of indicator types exclusive to
ThreatStream OnPrem.
latitude double "exact", "lt", "lte", Latitude associated with the Geo location of the
"gte", "gt" IP.
longitude double "exact", "lt", "lte", Longitude associated with the Geo location of
"gte", "gt" the IP.
meta.detail string "exact", A string that contains a tag associated with the
"startswith", indicator; the tag can be used to search for
"contains" related indicators.
meta.detail2 string "exact", Additional details associated with state of an

"startswith", indicator. For example, details such as why is an
"contains" indicator marked false positive.
meta.maltype string "exact", Tag that specifies the malware associated with
"startswith", an indicator.
"contains"
meta.registrant_ string Not available for Information available from WHOIS about the
* filtering domain of the indicator (if any) at the time it was
imported to ThreatStream.
meta.severity string "exact", Severity assigned to the indicator through

"startswith", machine-learning algorithms ThreatStream
"contains" deploys.

Reference Guide
Intelligence
Filter
modified_ts date "exact", "lt", "lte", When the indicator was last updated on the
"gte", "gt" ThreatStream Cloud platform.

YYYYMMDDThhmmss
where T denotes the start of the value for time, in

UTC time.
For example, 2014-10-02T20:44:35
See "Using the Intelligence API in Continuous

Operations" on page 49 on how to use this
attribute for retrieving intelligence.
org string "exact", Registered owner (organization) of the

"startswith", IP address associated with the indicator.
"contains"
owner_ long Not available for ID of the (ThreatStream) organization that

organization_id filtering brought in the indicator, either through a threat
feed or through the import process.
rdns string "exact", Domain name (obtained through reverse domain

"startswith", name lookup) associated with the IP address
"contains" that is associated with the indicator.
retina_ long "exact", "lt", "lte", Confidence score assigned to the observable by
confidence "gte", "gt" Anomali machine learning algorithms.
search_filter integer "exact" ID of the saved search filter you want to execute.
There are two methods of retrieving saved

search filter IDs:
1. Through the ThreatStream user interface.

Visit
https://ui.threatstream.com/search/filter
and note the value in the ID column for the
filter of interest.
2. Through the API. See "Search Filter" on

page 51 for more information.

Reference Guide
Intelligence
Filter
Important: When you use the search_

filter attribute to execute search, make
sure that this is the only attribute in the API
request. See example 10 on page 51.
This does not apply to using the search_
filter attribute in ThreatStream OnPrem.
For more details, see the note below.
Note: For ThreatStream OnPrem users

only: the Intelligence API does not support a
merged view of local and remote threat
intelligence when you use the search_
filter attribute in your query.
l If the search filter is stored locally (on

ThreatStream OnPrem), the filter is
applied to the local intelligence and,
consequently, returns matches to local
intelligence.
l If the search filter is stored remotely (on

ThreatStream Cloud), it is applied on the
remote intelligence and return matches
to remotely stored intelligence.
However, this attribute must be
accompanied with another attribute,
remote_api, to run it remotely from
ThreatStream OnPrem, as shown in the
following example:
curl 'https://<OnPrem_IP_or_
FQDN>/api/v2/intelligence/?searc
h_filter=<filter_id>&remote_
api=true' -H 'Authorization:
If the remote_api parameter is not used

for a search filter stored remotely (on
ThreatStream Cloud), the above
command will result in an error.
sort n/a This attribute is for ThreatStream's internal use

and can be ignored.

Reference Guide
Intelligence
Filter
source string Not available for Usually an obfuscated description of the source
filtering of the indicator; the description may not be
obfuscated if the user belongs to your
organization.
Examples of source names: threat feed name,

Analyst (if the user name is obfuscated).
source_created datetime "exact", "lt", "lte", Time stamp of when the entity was created by its
"gte", "gt" original source.
source_ datetime "exact", "lt", "lte", Time stamp of when the entity was last updated
modified "gte", "gt" by its original source.
source_ integer "exact", A risk score from 0 to 100, provided by the

reported_ "gt","lt","gte","lt source of the indicator.
confidence e"
status string "exact" Status assigned to the indicator.
For example, active, inactive, falsepos.
subtype string "exact" For hash observables—those with type=md5—

subtype provides additional metadata on the
type of hash associated with the observable.
Possible values: MD5, SHA1, SHA256,

SHA512.
tags string "exact", Tags applied to the specified observables.

"startswith",
"contains"
tags=[{“name”:"my_tag",“tlp”:"red"},
{"name":"my_tag2",“tlp”:"white"},
{"name":"my_tag3"}]
Tag Attributes:
l tlp—the visibility setting for the tag.

Possible values:
n red—private, or visible to your

organization only.
n white—public, or visible to all

ThreatStream users with access to the
data.

Reference Guide
Intelligence
Filter
Default: white
Note: Adding public tags may be

restricted by your Org Admin.
In the example above, my_tag is private and

my_tag2 and my_tag3 are public.
threatscore integer Not available for Deprecated.

(deprecated) filtering
threat_type string "exact" Summarized threat type of the indicator. For

example, malware, compromised, apt, c2, and
so on.
tlp string "exact" Traffic Light Protocol designation for the

intelligence—red, amber, green, white.
trusted_circle_ integer "exact" IDs of the trusted circles with which the indicator
ids is shared.
type string "exact" Type of indicator—domain, email, ip, md5,

string, url.
update_id integer "exact", An incrementing numeric identifier associated

"gt","lt","gte","lt with each update to intelligence on
e" ThreatStream.
Every time indicator data changes

on ThreatStream (for example, if it is updated or
expires), the update_id of the indicator is
incremented and stored in the indicator.
This identifier is mostly used by software that

interact with ThreatStream to download
intelligence, such as ThreatStream Link and
ThreatStream APIs.
See "Using “update_id” to Retrieve Large

Intelligence Datasets" on the next page for more
details.
uuid string UUID (universally unique identifier) assigned to

the observable for STIX compliance.
value string "exact", Value of the observable. For example, value =

"startswith", <192.168.0.10> or value =
"contains" <http://www.google.com>.
workgroups n/a Not used.

Reference Guide
Intelligence
Using “update_id” to Retrieve Large Intelligence Datasets

For the Intelligence API, in cases where the total number of results is greater than 10,000, Anomali
recommends using update_id to return the full dataset via iterative API calls. Using the update_id
method ensures large datasets are retrieved without impacting performance.
This method involves appending the following to your API call:
update_id__gt=0&order_by=update_id
After the first call is made, locate the update_id of the last returned object. The following is an
example:
Use this value for the update_id__gt variable in your next API call. Repeat this process iteratively
until no further results are returned.
Example:
You run the following API call to retrieve all active intelligence that has been added or modified since
January 10, 2018:
curl 'https://api.threatstream.com/api/v2/intelligence/?modified_ts__gt=2018-01-
10&status=active&update_id__gt=0&order_by=update_id' -H 'Authorization: apikey
The update_id of the last retrieved result—the 1,000th result in this case—is 11849.
Therefore, the next API call you would make is:
curl 'https://api.threatstream.com/api/v2/intelligence/?modified_ts__gt=2018-01-
10T00:00:00&status=active&update_id__gt=11849&order_by=update_id' -H

Reference Guide
Intelligence
Using the Intelligence API in Continuous Operations

If you call the Intelligence API through an automated script for continuous synchronization, follow the
guidance in this section to ensure you retrieve all available data within the time frame of interest. Data
ingested by ThreatStream is not available instantaneously. To reduce the chance of missing data still
being processed by ThreatStream at the time of script execution, use update_id to iteratively
retrieve data and set modified_ts__lt to one minute before the current UTC time stamp.
Example:
curl 'https://api.threatstream.com/api/v2/intelligence/?modified_ts__lt=<minus_
1_minute>&status=active&update_id__gt=0&order_by=update_id' -H 'Authorization:
where <minus_1_minute> is the time stamp of the current time minus one minute in
YYYYMMDDThhmmss format
Advanced Search Queries

Most filtering criteria can be specified using filter operators described in this document. However, if
you need to specify a complex filter, you can use an advanced search query. This method allows you
to specify queries similar to those you formulate on the Advanced search screen on the
ThreatStream user interface. To specify a filter language query, use this syntax in the API call:
&q=<filter_language_query>. The filter operators used for the filter language query are the
symbolic form (=, <, >, and so on) and not the descriptive form (exact, lt, gt, and so on) and the query
must be URL encoded. See "To retrieve intelligence using an advanced search query:" on the next
page for an example.
Examples
As Intelligence API calls can yield large numbers of results, the following examples use the limit
attribute to limit the number of results displayed in an API call.
By default, if the limit parameter is not specified, 20 records are fetched at a time. However, when
limit=0, a maximum of 1000 the total records that meet the query are fetched.
If the total records returned exceed the defined limit or number greater than 1,000 but fewer than
10,000, use the next field of the returned metadata to make iterative API calls until all records are
returned. If total records number greater than 10,000, follow the directions under "Using “update_id”
to Retrieve Large Intelligence Datasets" on the previous page to fetch complete results.
1. To retrieve the 100 most recent threat intelligence entries in ThreatStream:
curl 'https://api.threatstream.com/api/v2/intelligence/?limit=100' -H
2. To retrieve the first 20 threat intelligence entries with a confidence greater than 80, and a
severity of “low”:
curl 'https://api.threatstream.com/api/v2/intelligence/?meta.severity=low&
confidence__gt=80' -H 'Authorization: apikey <username>:<api_key>'

Reference Guide
Intelligence
3. To retrieve all of the intelligence for indicator type "mal_ip" in ThreatStream since a particular
date and time:
curl
'https://api.threatstream.com/api/v2/intelligence/?status=active&modified_
ts__gte=2014-10-02T20:44:35&limit=0&is_public=1&itype=mal_ip' -H
4. To retrieve all of the intelligence in ThreatStream since a particular date AND country = "CN":
curl 'https://api.threatstream.com/api/v2/intelligence/?status=active&date_
last__gte=2014-10-02T20:44:35&is_public=1&limit=0&country__exact=CN' -H
5. To retrieve all of the intelligence in ThreatStream that is tagged with the value "energetic-bear":
curl 'https://api.threatstream.com/api/v2/intelligence/?status=active&is_
public=1&limit=0&tags.name=energetic-bear&' -H 'Authorization: apikey
6. To retrieve all intelligence that contains "myexample.com":
curl 'https://api.threatstream.com/api/v2/intelligence/?value__
contains=myexample.com&limit=0' -H 'Authorization: apikey <username>:<api_
key>'
Tip: For best results, values specified after the contains operator should be at least 3
characters.
7. To retrieve intelligence using an advanced search query:
curl 'https://api.threatstream.com/api/v2/intelligence/?limit=0&q=
(expiration_ts>=2022-01-30T08:00:00+AND+confidence>=90+AND+(itype="apt_
ip"+OR+itype="bot_ip"+OR+itype="c2_ip"))' -H 'Authorization: apikey
For more information on specifying advanced search queries, see "Advanced Search Queries"
on the previous page.
8. (Only on ThreatStream OnPrem) To retrieve 100 most recent threat intelligence entries stored
remotely (on ThreatStream Cloud):
curl 'https://api.threatstream.com/api/v2/intelligence/?limit=100&remote_
api=true' -H 'Authorization: apikey <username>:<api_key>'

Reference Guide
Intelligence
9. (Only on ThreatStream OnPrem) To retrieve remote intelligence based on a saved search filter
whose ID is 398 and which is stored remotely (on ThreatStream Cloud):
curl 'https://<OnPrem_IP_or_FQDN>/api/v2/intelligence/?search_
filter=398&remote_api=true' -H 'Authorization: apikey <username>:<api_key>'
10. (Only on ThreatStream OnPrem) To retrieve local intelligence based on a saved search filter
whose ID is 1002538 and which is stored locally (on ThreatStream OnPrem):
curl 'https://api.threatstream.com/api/v2/intelligence/?search_
filter=1002538' -H 'Authorization: apikey <username>:<api_key>'
Search Filter
To retrieve information on search filters saved from the ThreatStream user interface. After identifying
the ID of a search filter, you can execute a query by specifying the search filter ID in the search_filter
parameter of an Intelligence API request.
Request
/api/v1/search_filter/
HTTP Method: GET
Response
Format: JSON
The following is an example response for an individual saved search filter:
Example
To retrieve a list of search filters saved by your organization:
curl "https://api.threatstream.com/api/v1/search_filter/ -H 'Authorization:


Reference Guide
Intelligence
Observable Cloning
To create a separate instance of an observable. After identifying the ID of an observable, you can
execute a clone request by specifying the observable ID in an Intelligence API request.
When you clone an observable, an import session is initiated, which must be approved to add the
cloned observable to your threat intelligence.
Request
/api/v2/intelligence/<observable_id>/clone/

HTTP Method: POST
Response
HTTP 202 Accepted {"job_id": "<background_job_id>", "import_session_id": "<import_session_id>"}
where
job_id is an identifier for the job on ThreatStream.
import_session_id is the ID for the initiated import job. You will need this ID to review and approve
the import job.
Example Response:
{"job_id": "368ab6dc-7955-4fd7-aef9-b8cd5496fcb1", "import_session_id": "346928"}
Example
To clone an observable with ID 11202475 which belongs to another organization to your own
organization:
curl -X POST "https://api.threatstream.com/v2/intelligence/11202475/clone/ -H

After this, proceed with approving the initiated import job. See "Import (with approval)" on page 19 for
more details.

Intelligence Enrichments
This article details the ThreatStream API resources that pertain to the retrieval of third-party
observable enrichment data. You can use the API to retrieve enrichment data from the following
services:
l Passive DNS
l Recorded Future
l Risk IQ SSL
l AbuseIPDB
l Shodan Database
Note that enrichment data will not be returned for services to which your organization does not
subscribe.
Passive DNS
Use the Passive DNS API to return enrichment data for domain, IP, and URL observables available
to you on ThreatStream. The Passive DNS API leverages data from the following providers:
l Labs PDNS
l Farsight PDNS
l OpenDNS Investigate
l VirusTotal
l RiskIQ PDNS
Request
/api/v1/pdns/
HTTP Method: GET
Examples
To return Passive DNS enrichment data for a domain:
curl 'https://api.threatstream.com/api/v1/pdns/domain/<observable_value>/' -H
To return Passive DNS enrichment data for an IP address:

Reference Guide
curl 'https://api.threatstream.com/api/v1/pdns/ip/<observable_value>/' -H
Note: Passive DNS requests are limited to 20 per minute per user.
Response
Format: JSON
Example
Recorded Future
Use the Recorded Future API to return enrichment data for domain, IP, MD5, and URL observables
available to you on ThreatStream.
Request
/api/v1/recorded_future/
HTTP Method: GET
Examples
To return Recorded Future enrichment data for a domain:
curl 'https://api.threatstream.com/api/v1/recorded_future/search/domain/<domain_
value>/' -H 'Authorization: apikey <username>:<api_key>'
To return Recorded Future enrichment data for an IP address:
curl 'https://api.threatstream.com/api/v1/recorded_future/search/ip/<ip_value>/'
To return Recorded Future enrichment data for an MD5:
curl 'https://api.threatstream.com/api/v1/recorded_future/search/md5/<md5_
value>/' -H 'Authorization: apikey <username>:<api_key>'

Reference Guide
Response
Format: JSON
Example
Risk IQ SSL
Use the Risk IQ SSL API to return enrichment data for IP observables available to you on
ThreatStream.
Request
/api/v1/riskiq_ssl/
HTTP Method: GET
Examples
To return Risk IQ SSL enrichment data for an IP address:
curl 'https://api.threatstream.com/api/v1/riskiq_ssl/certificate/<ip_value>/' -H
Response
Format: JSON

Reference Guide
Example
AbuseIPDB
Use the Integration Package API to access data returned from the AbuseIPDB enrichment.
Request
/api/v1/integration_package/direct/ip/<IP_address>/?name=AbuseIPDB
HTTP Method: GET
Example
To return data from the AbuseIPDB enrichment:
curl 'https://api.threatstream.com/api/v1/integration_package/direct/ip/<IP_
address>/?name=AbuseIPDB' -H 'Authorization: apikey <username>:<api_key>'
Response
Format: JSON
Example
[
"status_code": 200,
"results": {
"data":{
"numDistinctUsers": 0,
"countryName": "USA",
"domain": "abcd.us",
"isp": "Telecomunications-US",

Reference Guide
"lastReportedAt": null,
"countryCode": "US"
"isPublic": true,
"usageType": null,
"reports": [],
"ipVersion": 4,
"hostnames": [],
"abuseConfidenceScore": 0,
"isWhitelisted": null,
"ipAddress": "190.15.150.101",
"totalReports": 0
},
Shodan Database
Use the Integration Package API to access data returned from the Shodan Database enrichment.
Request
/api/v1/integration_package/direct/ip/<IP_address>/?name=Shodan+Database
HTTP Method: GET
Example
To return data from the Shodan Database enrichment:
curl 'https://api.threatstream.com/api/v1/integration_package/direct/ip/<IP_
address>/?name=Shodan+Database' -H 'Authorization: apikey <username>:<api_key>'
Note: The Shodan Database title requires the + sign between the two words as spaces are not
permitted in URLs.
Response
Format: JSON

Reference Guide
Example
[
"status_code": 200,
"results": {
<JSON results here>
},
Notes:
l A call to the Shodan Database endpoint may invoke multiple endpoints, and some endpoints
may not pass data. Therefore, multiple status codes and results are returned as a list of
dictionaries.
l Some vendors may not support IPv6.

Investigation
To create, modify, delete, or retrieve investigations from the ThreatStream platform.
Note: While the Investigation API can be used to create investigations that contain entity
associations, it only displays a count of associations (elements) and cannot be used to retrieve a
list of entities associated with existing investigations. However, the Investigationelement API can
be used to do so. See "Investigationelement" on page 63 for more information. See
"Investigationanalysis" on page 64 for information on retrieving analysis associated with an
investigation.
Request
/api/v1/investigation/
HTTP Methods:
Create a new investigation POST /api/v1/investigation/
Get a list of investigations GET /api/v1/investigation/
Modify an existing investigation PATCH /api/v1/investigation/
Delete an investigation DELETE /api/v1/investigation/
Get a list of remote GET /api/v1/investigation/?remote_api=true

investigations (for
This attribute does not need to be set to retrieve local
ThreatStream OnPrem only)
investigations. Only use this attribute when retrieving remote
investigations from ThreatStream Cloud. Set this attribute to
true in this case.
Do not set this attribute to false for retrieving local

investigations. Doing so will generate errors.
Response
Format: JSON

Reference Guide
Investigation
Attributes
created_ts date Timestamp when the investigation was created.
description string Full text description of the investigation.
Note: If you modify an investigation using a PATCH request,

the description will be overwritten.
id string Unique ID for the investigation.
This identifier is assigned to the investigation when it is first

created on ThreatStream.
is_public boolean Deprecated. Investigations are always private to your

organization and cannot be made public.
Must be unspecified or set to is_public=0 for false (private).
Note: If you set is_public to 1 for public in POST requests,

you will see the following error message:
{"message": "Cannot create public
investigation"}
If you set is_public to 1 for public in PATCH requests, you

will see the following error message:
{"message": "Cannot set investigation to
public"}
modified_ts date Timestamp when the investigation was last modified.
name string Investigation name.
priority string Priority assigned to the investigation.
Example: very low, low, medium, high, very high
remote_api (for boolean Whether the investigation is remote (stored on Cloud). Value
ThreatStream returned for this attribute is true when the investigation is
OnPrem only) remote.
status string Status assigned to the investigation.
Example: completed, in-progress, pending, unassigned
tags list of Tags associated with the investigation.

strings

Reference Guide
Investigation
tlp integer TLP setting for the investigation. In the context of investigations,
the TLP color sets the maximum level of information that users
outside your organization have access to when viewing your
investigation.
assignee
assignee_id integer ID of the user or workgroup to which the investigation is assigned
assignee_type string Type of assignee: "user" or "tsworkgroup"
elements
elements integer Number of entities associated with the investigation.
r_type string Type of entity associated with the investigation. Possible values
listed below.
l Actors: actor
l Campaigns: campaign
l Incidents: incident
l Observables: intelligence2
l Signatures: signature
l Threat Bulletins: tip_report
l TTP: ttp
l Vulnerabilities: vulnerability
r_id integer Unique ID assigned to the entity.
add_related_ boolean When enabled, observables related to the entity you are
indicators associating with the investigation are also added.
add_related_indicators=1 for true (add)
add_related_indicators=0 for false (do not add)
Unused attributes
tips n/a Unused.
workgroups n/a Unused.

Reference Guide
Investigation
Examples
1. To retrieve the 20 most recent investigations:
curl 'https://api.threatstream.com/api/v1/investigation/?order_by=-created_
ts' -H 'Authorization: apikey <username>:<api_key>'
2. To retrieve a specific investigation:
curl 'https://api.threatstream.com/api/v1/investigation/<investigation_id>/'
3. To create an investigation without associations:
curl --request POST --data '{"assignee_id":"1","assignee_

type":"user","description":"<p>this is a high priority
investigation</p>","name":"Blank
Investigation","priority":"high","tlp":"green"}'
"https://api.threatstream.com/api/v1/investigation/" -H 'Authorization:
apikey <username>:<api_key>' -H "Content-Type:application/json" -v
4. To create an investigation and associate it with an actor, along with observables related to the
actor:
curl --request POST --data '{"name":"Actor

Investigation","tlp":"white","priority":"medium","elements":[{"r_
type":"actor","r_id":1017,"add_related_indicators":1}]}'
"https://api.threatstream.com/api/v1/investigation/" -H 'Authorization:
5. To update the description of an existing investigation whose ID is 258:
curl --request PATCH --data '{"description":"<p>bah bah bah</p>"}'

"https://api.threatstream.com/api/v1/investigation/258/" -H 'Authorization:
6. To delete an investigation whose ID is 254:
curl --request DELETE

"https://api.threatstream.com/api/v1/investigation/254/" -H 'Authorization:
7. (Only on ThreatStream OnPrem) To retrieve the 20 most recent investigations stored on Cloud:
curl 'https://api.threatstream.com/api/v1/investigation/?remote_
api=true&order_by=-created_ts'-H 'Authorization: apikey <username>:<api_
key>'

Reference Guide
Investigation
Investigationelement
To create or retrieve associations between entities and existing investigations.
Request
HTTP Methods: GET, POST
Add associations to an individual investigation POST /api/v1/investigationelement/
Get a list of investigations GET /api/v1/investigationelement/
Response
Format: JSON
Attributes: See table below
Attributes
investigation_id Unique ID assigned to the investigation.
r_type Type of entity associated with the investigation. Possible values listed below.
l Actors: actor
l Campaigns: campaign
l Incidents: incident
l Observables: intelligence2
l Signatures: signature
l Threat Bulletins: tip_report
l TTP: ttp
l Vulnerabilities: vulnerability
r_id Unique ID assigned to the entity.
add_related_ When enabled, observables related to the entity you are associating with the
indicators investigation are also added.
add_related_indicators=1 for true (add)
add_related_indicators=0 for false (do not add)

Reference Guide
Investigation
1. To retrieve entities associated with an individual investigation:
curl
"https://api.threatstream.com/api/v1/investigationelement/?investigation_
id=258" -H 'Authorization: apikey <username>:<api_key>'
Note: For information on iteratively retrieving large datasets, see "Limiting Results" on
page 8.
2. To associate a threat bulletin with an existing investigation:
curl --request POST --data '{"objects":[{"r_type":"tipreport","r_

id":"3173","investigation_id":"258"}]}'
"https://api.threatstream.com/api/v1/investigationelement/" -H
'Authorization: apikey <username>:<api_key>' -H "Content-
Type:application/json" -v
3. To associate a threat bulletin and its related observables with an existing investigation:
curl --request POST --data '{"objects":[{"r_type":"tipreport","r_

id":"3165","investigation_id":"258","add_related_indicators":1}]}'
"https://api.threatstream.com/api/v1/investigationelement/" -H
Type:application/json" -v
Note: This call can only be used when first associating a threat model entity with an
investigation. It cannot be used to refresh the investigation with observables that were
associated with the threat model entity since its initial association with the investigation.
Investigationanalysis
To retrieve analysis on entities associated with an individual investigation.
Request
/api/v1/investigationanalysis/
HTTP Method: GET
Response
Format: JSON

Reference Guide
Investigation
Example
To retrieve analysis associated with an individual investigation:
curl "https://api.threatstream.com/api/v1/investigationanalysis/?investigation_
id=258" -H 'Authorization: apikey <username>:<api_key>'

Rules
To create, modify, delete, or retrieve rules from the ThreatStream platform.
Request
/api/v1/rule/
HTTP Methods:
Create a new rule POST /api/v1/rule/
Get a list of rules GET /api/v1/rule/
Modify an existing rule PATCH /api/v1/rule/
Delete a rule DELETE /api/v1/rule/
Get a list of remote rules (for GET /api/v1/rule/?remote_api=true

ThreatStream OnPrem only)
Note: Organizations can configure up to 300 rules.
Attributes
Note: If creating a rule, you must specify name, keywords, and at least one Match Within
parameter (match_observables, match_reportedfiles, match_signatures, match_tips,
or match_vulnerabilities). All other parameters are optional.
actors array of IDs of the Actors with which you want to associate matched
integers or entities.
strings
campaigns array of IDs of the Campaigns with which you want to associate
integers or matched entities.
strings

Reference Guide
Rules
create_ boolean Whether you want to create a dedicated investigation the first
investigation time the rule is triggered. All intelligence in which keywords
appear are added to the investigation.
True—if you want to create an investigation for the rule
False—if you do not want to create an investigation for the

rule
Default: False
exclude_impacts array of Indicator types you want to exclude from rule matches.
strings
Example: actor_ipv6
See Indicator Types in ThreatStream for a complete list of

indicator types.
Note: Do not specify values for both match_impacts and

exclude_impacts in the same request. Indicator types
specified in match_impacts are filtered out if also
specified in exclude_impacts.
exclude_notify_ boolean Whether you want to exclude the rule from matching
org_whitelisted Observables that are included in your organization whitelist.
True—if you want to exclude whitelisted observables
False—if you do not want to exclude whitelisted observables
Default: False
exclude_notify_ boolean Whether you want to exclude keyword matches on

owner_org Observables imported by your organization from Keyword
Match or Hourly Digest email notifications.
incidents array of IDs of the Incidents with which you want to associate matched
strings
keywords array of Keywords for which you want the rule to match.
strings
Keywords added to rules must adhere to the following
requirements:
l IP addresses must be expressed as regular expressions.
Example: 192\.168\.
l IP subnets should be expressed using CIDR notation and

not as regular expressions.

Reference Guide
Rules
Example: 10.20.100.0/26
l Do not start or end keywords with .*
l Keywords must contain at least three characters.
malware array of IDs of the Malware with which you want to associate matched
strings
match_impacts array of Indicator types in which you want to look for rule matches at
strings the exclusion of all others.
Example: actor_ipv6
See Indicator Types in ThreatStream for a complete list of

indicator types.
Note: Do not specify values for both match_impacts and

exclude_impacts in the same request. Indicator types
specified in match_impacts are filtered out if also
specified in exclude_impacts.
match_ boolean Whether the rule should match keywords in newly created
observables Observables.
True—if you want to match Observables
False—if you do not want to match Observables
Default: False
reportedfiles Sandbox Reports.
True—if you want to match Sandbox Reports
False—if you do not want to match Sandbox Reports
Default: False
match_signatures boolean Whether the rule should match keywords in newly created
Signatures.
True—if you want to match Signatures
False—if you do not want to match Signatures
Default: False

Reference Guide
Rules
match_tips boolean Whether the rule should match keywords in newly created
Threat Bulletins.
True—if you want to match Threat Bulletins
False—if you do not want to match Threat Bulletins
Default: False
vulnerabilities Vulnerabilities.
True—if you want to match Vulnerabilities
False—if you do not want to match Vulnerabilities
Default: False
name string Name of the rule.
remote_api (for boolean Whether the rule is remote (stored on Cloud).

ThreatStream
This attribute does not need to be set to retrieve local rules.
OnPrem only)
Only use this attribute when retrieving remote rules from
Do not set this attribute to false for retrieving local rules.

signatures array of IDs of the Signatures with which you want to associate
strings
tags array of Tags applied to the matched entities.

strings
Tag Attributes:

access to the data.
Default: white

Reference Guide
Rules
Note: Adding public tags may be restricted by your

Org Admin.
In the example above, my_tag is private and my_tag2 and

my_tag3 are public.
tips array of IDs of the Threat Bulletins with which you want to associate
strings
ttps array of IDs of the TTPs with which you want to associate matched
strings
vulnerabilities array of IDs of the Vulnerabilities with which you want to associate
strings
Response
Format: JSON
Attributes
create_investigation Whether an investigation was created the first time the rule was triggered.
created_ts Time stamp of when the rule was created, in UTC format.
exclude_notify_org_ Whether Observables whitelisted by your organization are excluded from

whitelisted rule matches.
exclude_notify_ Whether keyword matches on Observables imported by your organization

owner_org are excluded from Keyword Match or Hourly Digest email notifications.
has_associations Whether the rule creates associations between specified entities and
matched entities.
id Unique ID assigned to the rule
investigation ID, Name, and Resource URI of the investigation created by the rule.
keywords A list of keywords associated with the rule.
match_actors Unused.

Reference Guide
Rules
match_campaigns Unused.
match_incidents Unused.
match_malware Unused.
match_observables Whether the rule matches keywords in newly created Observables.
match_reportedfiles Whether the rule matches keywords in newly created Sandbox Reports.
match_signatures Whether the rule matches keywords in newly created Signatures.
match_tips Whether the rule matches keywords in newly created Threat Bulletins.
match_ttps Unused.
match_vulnerabilities Whether the rule matches keywords in newly created Vulnerabilities.
matches Total number of keyword matches for the rule.
modified_ts Time stamp of when the rule was last modified, in UTC format.
name Name of the rule.
org_id ID associated with the organization that created the rule.
org_shared Unused.
organization ID, Name, and Resource URI associated with the organization that
created the rule.
remote_api (for Whether the rule is remote (stored on Cloud). Value returned for this
ThreatStream attribute is true when the rule is remote.
OnPrem only)
resource_uri Resource URI associated with the rule.
tags Tags applied to matched entities.
user User that created the rule.
user_id ID of the user that created the rule.
Examples
1. To create a rule that matches for the keyword "example" in newly created Threat Bulletins:
curl -XPOST -v "https://api.threatstream.com/api/v1/rule/" -H 'Content-Type:

application/json' -H 'Authorization: apikey <username>:<api_key>' -d '
{"name": "test_rule4", "keywords": ["key", "foobar"], "match_tips": true,
"keyword": "blank"}'

Reference Guide
Rules
2. To get a list of the 20 most recently configured rules:
curl 'https://api.threatstream.com/api/v1/rule/' -H 'Authorization: apikey

3. To update an existing rule whose ID is 56:
curl -X PATCH 'https://api.threatstream.com/api/v1/rule/56/' -F tags: "

[{"name":"new_tag","tlp":"white"}]" -H 'Authorization: apikey
4. To delete a rule whose ID is 210:
curl --request DELETE 'https://api.threatstream.com/api/v1/rule/?id__in=210'

-H 'Authorization: apikey <username>:<api_key>
5. (Only on ThreatStream OnPrem) To retrieve the 20 most recent rules stored on Cloud:
curl 'https://api.threatstream.com/api/v1/rule/?remote_ api=true&order_by=-

created_ts'-H 'Authorization: apikey <username>:<api_ key>'

Sandbox
To submit files or URLs to the ThreatStream hosted Sandbox.
Request
/api/v1/submit/new/
HTTP Method: POST
Request Attributes
file_has_ boolean If using Joe Sandbox to detonate a file, set this attribute to true if the
password file is password protected.
You must specify the password using the file_password attribute.
Note: Do not specify a value for the attribute if using Cuckoo or

VMRay for detonation.
file_password string If detonating a password protected file on Joe Sandbox, use this
attribute to specify the value of the password.
You must set file_has_password to true if using this attribute.
import_ boolean If you want to initiate an import job for observables discovered during
indicators detonation, set this value to true.
Default: true
report_radio- string Classification of the Sandbox submission—public or private.

classification
report_radio- string A comma-separated list that provides additional details for imported
notes observables. This information is displayed in the Tag column of the
ThreatStream UI. For example, "Credential-Exposure,compromised_
email"

Reference Guide
Sandbox
report_radio- string Platform on which the submitted URL or file will be detonated.
platform
Note: This attribute is required for Cuckoo and Joe Sandbox
detonations. Do not specify this value for VMRay detonations.
The following platforms are supported:
l For organizations using the Default ThreatStream Sandbox

(Cuckoo): WINDOWS7
l For organizations using the ThreatStream Joe Sandbox

offering: MACOSX, WINDOWS7, WINDOWS7OFFICE2010,
WINDOWS10x64
l For organizations using Joe Sandbox via an individual

subscription: ANDROID4.4, ANDROID5.1, ANDROID6.0, MACOSX,
WINDOWSXP, WINDOWSXPNATIVE, WINDOWS7, WINDOWS7NATIVE,
WINDOWS7OFFICE2010, WINDOWS7OFFICE2013, WINDOWS10,
WINDOWS10x64, MACOSXVM, LINUX, ANDROID9.0
You can obtain a list supported platforms by making this API call:
curl -XGET
'https://api.threatstream.com/api/v1/submit/parameters/
' -H 'Authorization: apikey <username>:<api_key>'
report_radio- string Specify the URL that you want to detonate.

url
OR
OR
Specify the file that you want to detonate. (Include the full path to the
report_radio- file.)
file
trusted_ string ID of the trusted circle to which the Sandbox data should be
circles associated. If you want to specify multiple trusted circles, enter the list
of comma-separated IDs.
To find the ID of a trusted circle, locate the trusted circle on

ThreatStream, click on its name. The URL displayed in the address
bar shows the ID. For example,

Reference Guide
Sandbox
use_ boolean If you want to use the Joe Sandbox service for detonation, set this
premium_ attribute to true.
sandbox
If no value is set for use_premium_sandbox, the default Cuckoo
sandbox is used.
Note: Cuckoo and ThreatStream Joe Sandbox services are

limited to 150 submissions per day.
use_vmray_ boolean If you want to use the VMRay sandbox service for detonation, set this
sandbox attribute to true.
If no value is set for use_premium_sandbox or use_vmray_sandbox,

the default Cuckoo sandbox is used.
Note: You must have an active VMRay integration on

ThreatStream in order to use the VMRay sandbox service.
vmray_max_ integer Specify the number of detonations you want VMRay to perform for
jobs the submission. If you specify a number greater than 1, VMRay
performs the detonations on different platforms. A Sandbox Report is
created on ThreatStream for each detonation that returns results.
Note: Only specify a value for this attribute if use_vmray_

sandbox is set to true.
Detonating Archive Files

You can use the Sandbox API to detonate archive files on the ThreatStream sandbox. Files within the
archive are detonated individually. Therefore, Anomali recommends adding a tag (using the report_
radio-notes attribute) to your sandbox submission when detonating archive files. After detonation,
you can use the tag to locate all the detonated files in a request to the /api/v1/submit/search API.
The following Sandbox Search request returns a list of detonated files for a submission tagged with
archive_detonation_2021-02-15:
curl 'https://api.threatstream.com/api/v1/submit/search/?q=archive_detonation_
2021-02-15' -H 'Authorization: apikey <username>:<api_key>'
See "Sandbox" on page 73 for more information on the Sandbox Search API.
Response
The response contains following attributes.

Reference Guide
Sandbox
success Whether the submission was successful or not. Possible values: true, false
reports Provides a report of the denotation. The following specifics are contained in the
report:
l status
l End point that provides the detonation status
l detail
l End point where the detonation report is located
Response Example: {"success": true, "reports": {"WINDOWS7": {"status": "/api/v1/submit/188/",

"detail": "/api/v1/submit/188/report/"}}}
Examples
Note: If you plan on cutting and pasting the following examples, be sure to remove any spaces
that are introduced in places where lines wrap in the document.
1. To submit a URL to the Cuckoo Sandbox:
curl -XPOST 'https://api.threatstream.com/api/v1/submit/new/' -F report_

radio-classification=private -F report_radio-platform=WINDOWS7 -F report_
radio-url="http://preppybeach.cl/wp-includes/images/ipad/" -F report_radio-
notes="Credential-Exposure,compromised_email" -H 'Authorization: apikey
2. To submit an archive file to the Cuckoo Sandbox:

radio-file="@/Users/jdoe/Downloads/archive.zip" -F report_radio-
notes=archive_detonation_2021-04-21 -H 'Authorization: apikey
3. To submit a file to the Cuckoo Sandbox:

radio-file="@/Users/jdoe/Downloads/ts_logo.png" -H 'Authorization: apikey
4. To submit a URL to the Joe Sandbox service:

radio-url="http://preppybeach.cl/wp-includes/images/ipad/" -F use_premium_

Reference Guide
Sandbox
sandbox=true -F report_radio-notes="Credential-Exposure,compromised_email" -
H 'Authorization: apikey <username>:<api_key>'
5. To submit a password protected file whose password is "infected" to the Joe Sandbox service:

radio-file="@/Users/jdoe/Downloads/ts_logo.png" -F file_has_password=true -F
file_password=infected -F use_premium_sandbox=true -H 'Authorization: apikey
6. To submit a URL to the VMRay sandbox service:
curl -X POST 'https://api.threatstream.com/api/v1/submit/new/' -F use_vmray_

sandbox=true -F vmray_max_jobs=3 -F report_radio-classification=private -F
report_radio-url="http://preppybeach.cl/wp-includes/images/ipad/" -F report_
radio-notes="Credential-Exposure,compromised_email" -H 'Authorization:
7. To submit a file to the VMRay sandbox service:
curl -X POST 'https://api.threatstream.com/api/v1/submit/new/' -F use_vmray_

sandbox=true -F vmray_max_jobs=3 -F report_radio-
file="@/Users/jdoe/Downloads/ts_logo.png" -F report_radio-notes="Credential-
Exposure,compromised_email" -H 'Authorization: apikey <username>:<api_key>'
Sandbox Search
To search for submissions your organization has made to the ThreatStream sandbox.
Request
/api/v1/submit/search/
HTTP Method: GET

Reference Guide
Sandbox
Request Attribute
q string Value of the keyword you want to query. Specifying a

value for this attribute queries the following fields:
l vendor
l platform
l status
l result
l notes (tags)
Example
To search for sandbox detonations using a keyword:
curl 'https://api.threatstream.com/api/v1/submit/search/?q=<keyword>' -H

Snapshot
To retrieve a snapshot of the threat intelligence from the ThreatStream cloud.
Snapshot is a point-in-time copy of the threat intelligence on ThreatStream.
ThreatStream provides multiple methods for retrieving threat intelligence. Use the following criteria to
determine which method is appropriate for your needs:
Task Appropriate Method
Downloading small intelligence sets on an ad- Use the Intelligence API. See "Intelligence" on
hoc basis. page 40 for more information.
Downloading large intelligence sets–those Use the Snapshot API.

spanning thousands of pages–on an had-hoc
basis.
Downloading large intelligence sets–those Use ThreatStream Integrator. Contact your

spanning thousands of pages–on a regular Anomali Support representative for more
basis. information.
You can set filters to specify criteria by which intelligence should be retrieved, as described in the
table below.
Note: Your organization can have no more than three snapshot processes running at once.
Request
/api/v1/snapshot/
HTTP Methods: GET, POST

Reference Guide
Snapshot
Attribute Element Description
custom_ A map containing the following elements: filter, whitelist/blacklist, field_

config whitelist/field_blacklist, chunk_size, format and use_org_whitelist.
For example,
"custom_config": {"filter": "state=\"active\"", "whitelist":

{"itype": ["mal_ip", "mal_domain"]}, "field_blacklist": ["asn",
"country"], "chunk_size": "1MB", "format": "json", "use_org_
whitelist": true}
filter Filter string to use as the search criteria for the intelligence.
Example: ... {"filter": "state=\"active\"

AND confidence >=70 AND date_last >=2015-05-
01T00:00:00", ...}
See Intelligence Fields for a complete list of fields you can

specify.
whitelist Only include indicators that match the specified fields and
values.
Syntax: "whitelist": {"<field_name_1>": ["value_1",

"value_2"...], "<field_name_2>": ["value_1",
"value_2"...]}
If multiple fields are specified in a list, then the “AND” boolean

operation is assumed among the fields.
Examples:
1. "whitelist": {"itype": ["mal_ip", "mal_domain"]}
Only indicators of type mal_ip and mal_domain will be

included in the snapshot. All others indicator types (itypes)
except these two will not be included.
2. "whitelist": {"country": ["CN"], "itype": ["mal_ip", "mal_

domain"]}
Only indicators for which country = CN AND indicator type

is either mal_ip or mal_domain will be included in the
snapshot.
Notes:
l You can only use either the whitelist or the blacklist

attribute in a snapshot call, but not both.
l See Intelligence Fields for a complete list of fields you can

specify.

Reference Guide
Snapshot
blacklist Exclude indicators that match the specified fields and values.
Syntax: "blacklist": {"<field_name_1>": ["value_1",

"value_2"...], "<field_name_2>": ["value_1",
"value_2"...]}
If multiple fields are specified in a list, then the “AND” boolean

operation is assumed among the fields.
Examples:
1. "blacklist": {"itype": ["mal_ip", "mal_domain"]}
Indicators of type mal_ip and mal_domain will be excluded

from the snapshot. All others indicator types (itypes) will be
included in the snapshot.
2. "blacklist": {"country": ["CN"], "itype": ["mal_ip", "mal_

domain"]}
Indicators for which country = CN AND indicator type is

either mal_ip or mal_domain will be excluded from the
snapshot. All other indicators will be included in the
snapshot.
Notes:
l You can only use either the whitelist or the blacklist

attribute in a snapshot call, but not both.

specify.

Reference Guide
Snapshot
field_whitelist Include only these fields in the results. Remove all other fields.
For example, if "field_whitelist": ["asn", "severity", "domain"],

only these fields will be included for each indicator in the
snapshot.
Notes:
l A field_whitelist can be used with a whitelist or a blacklist.
l When specifying a field_whitelist, make sure that you include

at least one of the intelligence fields. For csv and json
formats, these fields include domain, email, srcip, md5,
srcip, url. If you do so, no intelligence will be returned. For
csv_v2 and json_v2, the intelligence field for all observables
is value.
l Ensure that the combination of (whitelist + field_whitelist)

does not result in a field set that will always have empty
results. For example, "whitelist": {"itype": ["mal_ip", "mal_
domain"]} + "field_whitelist": ["asn", "severity", "url"], will
always result in no matches. Whitelist will only show mal IP
and mal domain information and the field_whitelist will only
show asn, severity, and url information, resulting in empty
results.

specify.

Reference Guide
Snapshot
field_blacklist Exclude these fields from the records that are returned.
For example, if "field_blacklist": ["confidence", "severity"], these

fields will be excluded for each indicator in the snapshot.
Notes:
l A field_blacklist can be used with a whitelist or a blacklist.
l When specifying a field_blacklist, make sure that you do not

blacklist all of the intelligence fields. For csv and json
formats, these fields include domain, email, srcip, md5,
srcip, url. For csv_v2 and json_v2, the intelligence field for
all observables is value.
l Ensure that the combination of (whitelist + field_blacklist)

does not result in a field set that will always have empty
results. For example, "whitelist": {"itype": ["apt_domain",
"mal_domain"]} + "field_blacklist": ["asn", "severity",
"domain"], will always result in no matches. Whitelist will only
show apt and mal domain information and the field_blacklist
will hide the domain information, resulting in empty results.

specify.
chunk_size Size of the snapshot file, in KB or MB. Specify the file size for the
snapshot file using this attribute.
To retrieve a successful snapshot, you must specify either

chunk_size or chunk_ioc_count. When a value is not specified
for this attribute, the API call returns an error. Do not specify
values for both attributes.
Note: If the chunk_size is small and cannot fit in an entire

snapshot, you will need to retrieve multiple chunks until all data
has been retrieved. If more data is available, the value of the
Status field is "inprogress". Continue to retrieve the data until
Status field value is "completed".
chunk_ioc_count Specifies the number of Indicators of Compromise (IOCs) a

snapshot can contain.
To retrieve a successful snapshot, you must specify either

chunk_size or chunk_ioc_count. Requests fail without values
specified for one of these attributes. Do not specify values for
both attributes.

Reference Guide
Snapshot
format Format of the snapshot.
Available formats: csv, csv_v2, json, json_v2, stix
Note: If you specify csv or json, only domain, email, MD5,

IP, and URL observables are included in snapshots.
Therefore to ensure complete data is returned Anomali
recommends using csv_v2 or json_v2.
use_org_ Specify whether your organization Import Whitelist should be

whitelist applied to the snapshot.
Possible values: true, false
When set to true, observables configured on your Import

Whitelist are filtered out of the snapshot.
If no value is specified, your Import Whitelist is not applied to the

snapshot.
intel_ integer A field to specify the intelligence version—v1 or v2. Currently,

version only v1 is supported.
Response
Format: CSV, JSON, or STIX
Attribute Type Filter Operators Description
id integer "lt", "lte", "gt", "gte" A unique identifier for the snapshot.
location string Not available for filtering Location header that specifies the
URL to use for checking the status of
snapshot creation and downloading
the snapshot files.
resource_uri string Not available for filtering URI for the snapshot on ThreatStream.
sha256sum string "exact" The sha256sum (to verify the integrity)

of the snapshot file that is available for
download.
Note: This attribute is only available in

the response.

Reference Guide
Snapshot
snapshot_ts datetime "lt", "lte", "gt", "gte" Timestamp when the snapshot was
started on ThreatStream.
status string Not available for filtering Status of snapshot creation. Status is
"inprogress" when snapshot files are
being created. Once all files have been
created, the Status is "completed".
Status may be "errors" if the snapshot
creation failed for any reason.
Possible values: inprogress,

completed, errors
Example
To obtain a full snapshot, in JSON format, in 1 MB chunks, that meets the specified criteria:
curl -XPOST 'https://api.threatstream.com/api/v1/snapshot/' -H 'Authorization:

apikey <username>:<api_key>' -H 'Content-Type: application/json' -d
'{
"intel_version":1,
"custom_config":{
"filter":"state=\"active\"",
"whitelist":{
"itype":[
"mal_ip",
"mal_domain"
]
},
"field_blacklist":[
"asn",
"country"
],
"format":"json_v2",
"use_org_whitelist":true,
"chunk_size":"1MB"
}
}'
A successful response contains a Location header, such as

https://api.threatstream.com/api/v1/snapshot/2/.
The Location header contains the ID of the snapshot. In the above example,
https://api.threatstream.com/api/v1/snapshot/2/, 2 is the snapshot ID. Use this ID when making
HTTP GET requests to retrieve the snapshot. If the snapshot contains multiple files, the HTTP GET
response will contain URLs of all the files along with the Status. If all files could not be retrieved with
one HTTP GET request, Status will be "inprogress". Continue to make requests until all files have
been retrieved. Once all files have been retrieved, the Status will change to "completed".

Reference Guide
Snapshot
curl 'https://api.threatstream.com/api/v1/snapshot/2/' -H 'Authorization: apikey

The above example assumes that the Location header is

https://api.threatstream.com/api/v1/snapshot/2/.
Output Sample
The calls to the status URL will return JSON and STIX output similar to the following:
{
"status":"inprogress",
"files":[
{
"download_url":"https://<download_URL_1>",
"sha256":"<SHA-256 sum of the file to be downloaded>",
"total_count":<count>
},
{
"download_url":"https://<download_URL_2>",
"sha256":"<SHA-256 sum of the file to be downloaded>",
"total_count":<count>
}
]
}
Error Codes
If the snapshot creation process fails, HTTP status codes reflect the reason for failure.

SSO History
To return a log of SSO activity for your organization in ThreatStream.
Request
/api/v1/ssohistory/
Response
Format: JSON
Attributes
action Actions logged by the SSO History API include:
l SSO Configuration Changed—logged when the Manage Users With

configuration is updated
l Permission Map Updated—logged when the user permission mapping

between AD Group names and ThreatStream permissions is updated
l Break-glass Account—logged when the break glass user configuration is

updated
l Login Attempt—logged users attempt to log in, regardless of outcome
l Login Success—logged when users successfully authenticate to

ThreatStream
l Login Fail—logged when users didn't succeed to authenticate to ThreatStream
l User Logged Out—logged when users log out of ThreatStream
l Create User—logged when a new user is created
l Reactivate User—logged when a previously deactivated user is activated
l User Permissions—logged when ThreatStream detects a change on AD user

permissions

Reference Guide
SSO History
Deployment Type of deployment configured to use SSO.

type
Possible values include Cloud and OnPrem
id Unique identifier for the logged action.
idp Name configured for your identity provider.
ts Timestamp of the logged action.
user_email Email address of the ThreatStream user associated with the logged action.
Example
Request:
curl "https://api.threatstream.com/api/v1/ssohistory/" -H 'Authorization: apikey
Response:
{
"action": "Login Attempt",
"deployment_type": "OnPrem",
"id": 1000000019,
"idp": "adfs-onprem",
"resource_uri": "/api/v1/ssohistory/1000000019/",
"ts": "2020-10-01T10:07:23.916639",
"user_email": "example@test.net"
}

Threat Model
The Anomali Threat Model is STIX (v1.2, v2.0, and v2.1) compatible and supports adding, managing,
importing, and exporting contextual, relationship, and workflow information for these types of Threat
Model entities: Actors, Attack Patterns, Campaigns, Courses of Action, Identities, Incidents,
Infrastructure, Intrusion Sets, Malware, Signatures, Threat Bulletins, Tools, TTPs, and
Vulnerabilities.
You can also create and associate threat bulletins in the Threat Model and associate them with all
Threat Model entities. See "Managing Threat Model Associations " on page 154for more information.
You can manage tags of Threat Model entities in bulk. See "Threat Model Entity Tags in Bulk" on
page 162 for more information.
The following Threat Model API resources are covered here:

Threat Model Search 89
Actors 97
Attack Patterns 103
Campaigns 113
Incidents 119
Malware 124
Signatures 133
Tipreport 138
TTPs (Tactics, Techniques, and Procedures) 144
Vulnerabilities 149
Managing Threat Model Associations 154
Threat Model Search

To search for Threat Model entities from ThreatStream.
Request
/api/v1/threat_model_search/
HTTP Method: GET
Response
Format: JSON

Reference Guide
Threat Model
Ordering of attributes: By default, attributes are sorted by the modified_ts attribute, in descending
order.
Attributes
alias string "exact", "startswith", Other names by which the actors

"contains" are known.
circles string Not available for filtering. Trusted circles with which the actor
is shared.
created_ts date "exact", "lt", "lte", "gte", Time stamp of when the entity was
"gt" created on ThreatStream, in UTC
format.
Date is in this format:

YYYYMMDDThhmmss
where T denotes the start of the

value for time.
For example, 2014-10-

02T20:44:35.
Note: This attribute is returned

in the response to a GET call
and is set by ThreatStream; it
cannot be configured.
end_date date "exact", "lt", "lte", "gte", Time when a campaign was known
"gt" to have ended.
Date must be specified in this

format: YYYYMMDDThhmmss and
in UTC format.

value for time.

02T20:44:35.
feed_id string "exact" Numeric ID of the threat feed that

provided the Threat Model entity.
id string Not available for filtering. Unique ID assigned to the entity.

Reference Guide
Threat Model
is_email boolean "exact" Whether the threat bulletin was

created as a result of an email
import.
is_public boolean "exact" Whether the entity is public or

private (including belonging to a
trusted circle).
False—if the entity is private or

belongs to a Trusted Circle
True—if the entity is public
Default: False
model_type string "exact" Type of Threat Model entity: actor,

attack pattern, campaign, incident,
malware, signature, tipreport
(Threat Bulletin), ttp, vulnerability.
modified_ts date "exact", "lt", "lte", "gte", Time stamp of when the entity was
"gt" last updated on ThreatStream, in
UTC format.

YYYYMMDDThhmmss

value for time.

02T20:44:35.
name string "exact", "startswith", Name of the entity.

"contains"
organization string Not available for filtering. Organization that owns the entity.
organization_id string "exact" ID of the organization that owns the

entity.
owner_user string Not available for filtering. ThreatStream user that created the
entity.
owner_user_id string "exact" ID of the ThreatStream user that

created the entity.
publication_status string "exact" Entities can be in new, pending_

review, review_requested,
reviewed, published statuses.

Reference Guide
Threat Model
published_ts datetime "exact", "lt", "lte", "gte", Time stamp of when the entity was
"gt" published on ThreatStream, in UTC
format.

YYYYMMDDThhmmss

value for time.

02T20:44:35.
remote_api (for boolean "exact" Whether the entity is remote (stored

ThreatStream on Cloud).
OnPrem only)
This attribute does not need to be
set to retrieve local entities. Only
use this attribute when retrieving
remote entities from ThreatStream
Cloud. Set this attribute to true in
this case.
Do not set this attribute to false for

retrieving local entities. Doing so
will generate errors.
resource_uri string Not available for filtering. URI for the entity.
signature$type string "exact" Type of signature. Possible values

include:
l Bro
l Carbon+Black+Query
l ClamAV
l Custom
l CybOX
l OpenIOC
l RSA+NetWitness
l Snort
l Splunk+Query
l Suricata

Reference Guide
Threat Model
l YARA
Note: You must specify

model_type=signature when
using signature$type in a
query.
source_created datetime "exact", "lt", "lte", "gte", Time stamp of when the entity was
"gt" created by its original source.
source_modified datetime "exact", "lt", "lte", "gte", Time stamp of when the entity was
"gt" last updated by its original source.
start_date date "exact", "lt", "lte", "gte", Time when a campaign was known
"gt" to have started.
Date must be specified in this

format: YYYYMMDDThhmmss and
in UTC format.

value for time.

02T20:44:35.
status string Not available for filtering. Status of a campaign: ongoing,

historic, future.
subtype string For hash observables—those with

type=md5—subtype provides
additional metadata on the type of
hash associated with the
observable.
Possible values: MD5, SHA1,

SHA256, SHA512.
tags string Additional comments and context

associated with the observable
when it was imported from its
original threat feed.
Note: The API response may return

several tags.* attributes (namely,
tags.id and tags.name). Those
attributes are for ThreatStream's
internal tracking and can be
ignored.

Reference Guide
Threat Model
trusted_circle_ids string "exact" Used for querying entities

associated with specified trusted
circles.
tlp string "exact" TLP setting associated with the

entity.

Reference Guide
Threat Model
value string "exact", "startswith", Threat Model keyword search.

"contains" Specifying a value yields the same
results as a keyword search
through the ThreatStream user
interface. The following fields are
queried:
Actors: Aliases, Description,

Name, Tags
Attack Patterns: Aliases,

Description, Name, Tags
Campaigns: Aliases, Description,

Name, Tags
Courses of Action: Description,

Name, Tags
Incidents: Name, Description,

Tags
Infrastructure: Aliases,
Identities: Description, Name,

Tags
Intrusion Sets: Aliases,

Malware: Aliases, Description,

Name, Tags
Signatures: Description, Name,

Tags
Threat Bulletins: Description,

Name, Tags
Tools: Aliases, Description, Name,

Tags
TTPs: Aliases, Description, Name,

Tags
Vulnerabilities: Aliases,
workgroups Not available for filtering. Not used.

Reference Guide
Threat Model
Examples
As Intelligence API calls can yield large numbers of results, the following examples use the limit
attribute to limit the number of results displayed in an API call.
By default, if the limit parameter is not specified, 20 records are fetched at a time. However, when
limit=0, a maximum of 1000 the total records that meet the query are fetched.
1. To retrieve the 100 most recently modified Threat Model entities in ThreatStream:
curl 'https://api.threatstream.com/api/v1/threat_model_search/?limit=100' -H
2. To retrieve the 10 most recently modified Threat Model entities from a feed whose ID is 72:
curl 'https://api.threatstream.com/api/v1/threat_model_
search/?limit=10&feed_id=72' -H 'Authorization: apikey <username>:<api_key>'
3. To retrieve the 20 (default) most recently modified Threat Model entities tagged with "malware"
and "community-threat-briefing":
curl 'https://api.threatstream.com/api/v1/threat_model_
search/?tags.name=malware,community-threat-briefing' -H 'Authorization:
4. To retrieve the 20 (default) most recently modified Threat Model entities that are shared with a
trusted circle whose ID is 20:
curl 'https://api.threatstream.com/api/v1/threat_model_search/?trusted_
circle_ids=20' -H 'Authorization: apikey <username>:<api_key>'
5. To retrieve the 20 (default) most recently modified Threat Model entities that are assigned the
TLP setting red:
curl 'https://api.threatstream.com/api/v1/threat_model_search/?tlp=red' -H
6. To retrieve a list of actors (20 by default if the limit parameter is not specified):
curl 'https://api.threatstream.com/api/v1/threat_model_search/?model_
type=actor' -H 'Authorization: apikey <username>:<api_key>'
7. To retrieve the actor whose name is "Fancy Bear":
type=actor&name=Fancy Bear' -H 'Authorization: apikey <username>:<api_key>'
8. To retrieve the 20 (default) most recently modified campaigns in "new" publication status:

Reference Guide
Threat Model
type=campaign&publication_status=new' -H 'Authorization: apikey
9. To retrieve the 20 (default) most recently modified signatures of the Snort type:
type=signature&signature$type=Snort' -H 'Authorization: apikey
10. To retrieve the 20 (default) most recently modified actors and signatures of the signature type
CybOX:
type=signature,actor&signature$type=CybOX' -H 'Authorization: apikey
11. (Only on ThreatStream OnPrem) To retrieve the 100 most recently modified Threat Model
entities from ThreatStream Cloud:
curl 'https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/threat_model_
search/?limit=100&remote_api=true' -H 'Authorization: apikey
12. (Only on ThreatStream OnPrem) To retrieve a list of actors (20 by default if the limit parameter is
not specified) from ThreatStream Cloud:
curl 'https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/threat_model_
search/?model_type=actor&remote_api=true' -H 'Authorization: apikey
Actors
To create, update, or retrieve actors from the ThreatStream platform.
Request
/api/v1/actor/
HTTP Methods: GET, POST, PATCH
Create a new actor POST /api/v1/actor/
Update the specified actor PATCH /api/v1/actor/{id}/
Get the specified actor GET /api/v1/actor/{id}/

Reference Guide
Threat Model
Get a list of actors Anomali recommends to use the /api/v1/threat_

model_search endpoint to retrieve the list of actors.
See "Threat Model Search" on page 89 for details.
For example,
GET /api/v1/threat_model_search/?model_
type=actor
Get a list of actors associated with a GET /api/v1/actor/associated_with_

specified indicator value or indicator ID intelligence/?value={value}
GET /api/v1/actor/associated_with_
intelligence/?ids={comma_separated_id_list}
For example,
GET /api/v1/actor/associated_with_
intelligence/?value=google.com returns all actors
who are associated with google.com.
Get a list of a specified entity type (such GET /api/v1/actor/{id}/<entity_type>/

as malware, campaign, andso on) that is
For example,
associated with the specified actor
GET /api/v1/actor/234673/malware/ returns all
malware objects associated with the specified actor.
Get a list of observables associated with GET /api/v1/actor/{id}/intelligence/

the specified actor
Response
Format: JSON
Notes
l Attributes with "related" data type return 0 to N number of values. For example, if a Threat Model
entity belongs to more than one trusted circle, both will be returned.
l For information on limiting results and returning large datasets while mitigating performance
impacts, see "Limiting Results" on page 8
Attributes
aliases string Other names by which the actor is known.

Reference Guide
Threat Model
campaigns related (see item Campaigns associated with the actor.

1 in "Notes" on
When creating an actor, specify the Campaign ID.
the previous
See "Campaigns" on page 113.
page)
circles related (see item IDs of the trusted circles with which the actor is
1 in "Notes" on shared.
the previous
page)
created_ts datetime Time stamp of when the actor was created on

ThreatStream, in UTC format.
Date is in this format: YYYYMMDDThhmmss
where T denotes the start of the value for time.
For example, 2014-10-02T20:44:35.
Note: This attribute is returned in the response

to a GET call and is set by ThreatStream; it
description string Free-form text associated with the actor.
incidents related (see item Incidents associated with the actor.

1 in "Notes" on
When creating an actor, specify the Incident ID. See
the previous
"Incidents" on page 119.
page)
intelligence related (see item Indicators associated with the actor on the
1 in "Notes" on ThreatStream platform.
the previous
When creating an actor, specify the indicator ID.
page)
See "Intelligence" on page 40.
is_public boolean Whether the actor is public or private (including

belonging to a trusted circle).
False—if the actor is private or belongs to a Trusted

Circle
True—if the actor is public
Default: False

Reference Guide
Threat Model
is_team boolean Whether the actor is a team or known to work as an

individual (as specified in the Team check box in the
UI).
True—actor is a team
False—actor is an individual
Default: False
limit numeric The limit variable controls the number of results

returned every time an API call is made; the total
number of results may be much larger than returned
in one API call.
If limit is not specified, 20 results are returned with

each API call. Specifying limit=0 will return up to a
maximum of 1000 results (if available).
modified_ts datetime Time stamp of when the actor was last updated on
For example, 2014-10-02T20:44:35.
Note: This attribute is returned in the response

to a GET call and is set by ThreatStream; it
name string Name of the actor.
Actor name is associated with your organization.

Therefore, the name must be unique within your
organization. However, two actors with the same
name can exist on ThreatStream as long as they
belong to different organizations.
The name can contain up to 255 characters.
Note: This is a required parameter for creating

an actor.

Reference Guide
Threat Model
publication_status string An actor can be in new, pending_review, review_

requested, reviewed, published statuses.
Note: An actor must be in published status for it

to be visible to other users outside your
organization.
remote_api (for boolean Whether the entity is remote (stored on Cloud).

ThreatStream OnPrem
Value returned for this attribute is true when the
only)
entity is remote.
signatures related (see item Signatures associated with the actor.

1 in "Notes" on
When creating an actor, specify the Signature ID.
page 98)
See "Signatures" on page 133.
skip_associations boolean By default, up to 1000 Threat Model and observable

associations are returned with GET requests for
(On ThreatStream
details of a Threat Model entity on ThreatStream
OnPrem only)
OnPrem. When a Threat Model entity has a large
number of associations, association retrieval can
take a long time and impact performance.
Therefore, Anomali recommends setting the skip_
associations parameter to true. This parameter
is only applicable to ThreatStream OnPrem.
For example,
GET /api/v1/actor/{id}/?skip_
associations=true
skip_intelligence boolean By default, up to 1000 Threat Model and observable

associations are returned with GET requests for
(On ThreatStream
details of a Threat Model entity on ThreatStream
OnPrem only)
OnPrem. When a Threat Model entity has a large
number of associations, association retrieval can
take a long time and impact performance.
intelligence parameter to true. This parameter
is only applicable to ThreatStream OnPrem.
For example,
GET /api/v1/actor/{id}/?skip_
intelligence=true

Reference Guide
Threat Model
soph_type string IDs of the sophistication type associated with the

actor. To obtain a list of IDs for sophistication type,
make an API call to
/api/v1/actorsophisticationtype/
This attribute specifies the level of sophistication

observed about the actor. The Sophistication levels
available on ThreatStream follow the Threat actor
Sophistication Vocabulary for STIX.
soph_desc string Free-form text description about the soph_type

attribute of the actor.
source_created datetime Time stamp of when the actor was created by its
original source.
source_modified datetime Time stamp of when the actor was last updated by
its original source.
start_date datetime Specify the time when this actor was first known to
be active.

YYYYMMDDThhmmss and in UTC format.
For example, 2014-10-02T20:44:35.
tags list Tags assigned to the actor.
A tag is a meaningful name or any other string value

assigned to identify the information.
For example, spear phishing,exploitation.
tlp string Traffic Light Protocol designation for the actor—red,

Note: The value is case-sensitive and must be

specified in lower case.
ttps related (see item TTP (Threat Bulletins) associated with the actor.
1 in "Notes" on
When creating an actor, specify the TTP ID. See
page 98)
"TTPs (Tactics, Techniques, and Procedures)" on
page 144.

Reference Guide
Threat Model
victims related (see item Victim type associated with the actor.
1 in "Notes" on
When creating an actor, specify the ID of the Victim
page 98)
type. To obtain a list of Victim types, make an
API call to /api/v1/victimtype/.
Examples
1. To update an existing actor whose ID is 223:
curl --request PATCH --data '{"name": "another test actor", "tlp": "orange",
"victims": [13]}' "https://api.threatstream.com/api/v1/actor/223/" -H
Type:application/json"
2. To get details of an existing actor whose ID is 223:
curl "https://api.threatstream.com/api/v1/actor/223/" -H 'Authorization:

3. To get the first 10 actors from ThreatStream:
curl "https://api.threatstream.com/api/v1/actor/?limit=10" -H
4. To create a private actor and set Victim IDs to 13 (for "Health Care") and 15 (for "Insurance"):
curl --request POST --data '{"name": "test actor", "tlp": "red", "tags":
["bad actor", "dummy tag"], "victims": [13, 15], "publication_status":
"published"}' "https://api.threatstream.com/api/v1/actor/" -H
5. (Only on ThreatStream OnPrem) To get details of a remote actor whose ID is 253:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/actor/253/?remote_
6. (Only on ThreatStream OnPrem) To skip associations when retrieving details of a local actor
with ID 234678:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/actor/234678/?skip_
associations=true" -H 'Authorization: apikey <username>:<api_key>'
Attack Patterns
To create, update, or retrieve attack pattern entities from the ThreatStream platform.

Reference Guide
Threat Model
Request
/api/v1/attackpattern/
Create a new attack pattern entity POST /api/v1/attackpattern/
Update the specified attack pattern entity PATCH /api/v1/attackpattern/{id}/
Get the specified attack pattern entity GET /api/v1/attackpattern/{id}/
Get a list of attack patterns Anomali recommends to use the /api/v1/threat_

model_search endpoint to retrieve the list of attack
patterns. See "Threat Model Search" on page 89 for
details.
For example,
type=atackpattern
Get a list of attack patterns associated GET /api/v1/attackpattern/associated_with_

with the specified indicator value or intelligence/?value={value}
indicator ID
GET /api/v1/attackpattern/associated_with_
For example,
GET /api/v1/attackpattern/associated_with_
intelligence/?value=google.com returns all
attack patterns that are associated with google.com.
Get a list of a specified entity type (such GET /api/v1/attackpattern/{id}/<entity_

as malware, campaign, and so on) that is type>/
associated with the specified attack For example,
pattern
GET /api/v1/attackpattern/234673/malware/
returns all malware objects associated with the attack
pattern.
Get a list of observables associated with GET /api/v1/attackpattern/

the specified attack pattern {id}/intelligence/
Response
Format: JSON

Reference Guide
Threat Model
Notes
Attributes
actors related (see item Actors associated with the attack pattern.
1 in "Notes"
When creating an attack pattern, specify the
above)
Actor ID. See "Actors " on page 97.
aliases string Other names by which the attack pattern is

known.
assignee_user integer ID of the user to which the attack pattern is

assigned
attackpatterns related (see item Attack pattern entities associated with the attack
1 in "Notes" pattern.
above)
body_content_type string Format used for the body text of the description:
markdown or richtext
Default: markdown
Note: Once specified, body_content_type

cannot be modified.
campaigns related (see item Campaigns associated with the attack pattern.
1 in "Notes"
above)
Campaign ID. See "Campaigns" on page 113.
can_add_public_tags boolean Indicator for whether a user can add public tags
to an attack pattern.
circles related (see item All Trusted Circles to which the attack pattern
1 in "Notes" belongs.
above)
courseofaction related (see item Course of action entities associated with the
1 in "Notes" attack pattern.
above)
Course of Action ID.

Reference Guide
Threat Model
created_ts datetime Time stamp of when the attack pattern was

created on ThreatStream, in UTC format.
For example, 2014-10-02T20:44:35.
Note: This attribute is returned in the

response to a GET call and is set by
ThreatStream; it cannot be configured.
description string The free-form text associated with the attack

pattern (as specified in the Description field in the
UI).
embedded_content_type string Not used.
embedded_content_url string Not used.
external_references related (see item Information about the references associated with
1 in "Notes" on the attack pattern.
the previous
page)
feed_id string Numeric ID of the threat feed that provided the

Threat Model entity.
id string ID of the attack pattern entity. This ID is

automatically assigned to the entity by
ThreatStream at the time of creation. You can
use this ID to associate the attack pattern entity
with other Threat Model entities.
identities related (see item Identities associated with the attack pattern.
1 in "Notes" on
the previous
Identity ID.
page)
incidents related (see item Incidents associated with the attack pattern.
1 in "Notes" on
the previous
Incident ID.
page)
infrastructure related (see item Infrastructure entities associated with the attack
1 in "Notes" on pattern.
the previous
page)
Infrastructure ID.

Reference Guide
Threat Model
intelligence related (see item Indicators associated with the attack pattern on
1 in "Notes" on the ThreatStream platform.
page 105)
indicator ID. See "Intelligence" on page 40.
intelligence_initiatives related (see item Intelligence Initiatives associated with the attack
page 105)
response to a GET call and is set an
intelligence source; it cannot be configured.
intrusionsets related (see item Intrusion sets associated with the attack pattern.
1 in "Notes" on
page 105)
Instrusion Set ID.
is_anonymous boolean Whether the attack pattern user and organization

information is anonymized
True—if information is anonymized
False—if information is not anonymized
is_cloneable string Whether the attackpattern entity can be cloned.
is_mitre boolean Whether the attack pattern is described in the

MITRE list.
True—if the attack pattern is described
False—if the attack pattern is not described
is_public boolean Whether the attack pattern is public or private

(including belonging to a trusted circle).
False—if the attack pattern is private or belongs

to a Trusted Circle
True—if the attack pattern is public
Default: False
kill_chain_phases array Name of the attack structure model.
Value: {"lockheed-martin": ["action-on-

objectives", "command-and-control",
"delivery", "exploitation",
"installation", "reconnaissance",
"weaponization"]}

Reference Guide
Threat Model
killchainstages related (see item List of attack structure phases.

1 in "Notes" on
Values: "action-on-objectives",
page 105)
"command-and-control", "delivery",
"exploitation", "installation",
"reconnaissance", "weaponization"
Note: You can set this attribute with the

PATCH API call only for the Attack Patterns
with the is_mitre=false attribute.
malwares related (see item Malware entities associated with the attack
page 105)
modified_ts datetime Time stamp of when attack pattern was last

updated on ThreatStream, in UTC format.
For example, 2014-10-02T20:44:35.

name string Name of the attack pattern.
Attack pattern name is associated with your

organization. Therefore, the name must be
unique within your organization. However, two
attack patterns with the same name can exist on
ThreatStream as long as they belong to different
organizations.
Note: This is a required parameter.
organization array of strings Information about the organization that created

the entity on ThreatStream.
organization_id integer ID of the organization that created the entity on

ThreatStream.

Reference Guide
Threat Model
owner_user array of strings Information about the user that created the entity
on ThreatStream.
owner_user_ID integer ID of the user that created the entity on

ThreatStream.
parent N/A The attribute is for internal use and can be

ignored.
publication_status string Attack pattern entities can be in new, pending_

review, review_requested, reviewed, or
published statuses.
Note: Attack pattern entities must be in

published status for it to be visible to other
users outside your organization.
published_ts datetime Time stamp of when attack pattern was

published on ThreatStream, in UTC format.
For example, 2014-10-02T20:44:35.


ThreatStream OnPrem
only)
entity is remote.
resource_uri string URI of the attack pattern entity on ThreatStream
signatures related (see item Signatures associated with the attack pattern.
1 in "Notes" on
page 105)
Signature ID. See "Signatures" on page 133.

Reference Guide
Threat Model
skip_associations boolean By default, up to 1000 Threat Model and

observable associations are returned with GET
(On ThreatStream
requests for details of a Threat Model entity on
OnPrem only)
ThreatStream OnPrem. When a Threat Model
entity has a large number of associations,
association retrieval can take a long time and
impact performance. Therefore, Anomali
recommends setting the skip_associations
parameter to true. This parameter is only
applicable to ThreatStream OnPrem.
For example,
GET /api/v1/atackpattern/{id}/?skip_
associations=true
skip_intelligence boolean By default, up to 1000 Threat Model and

(On ThreatStream
OnPrem only)
recommends setting the skip_intelligence
For example,
GET /api/v1/attackpattern/{id}/?skip_
intelligence=true
source_created datetime Time stamp of when the attack pattern was

originally created by the source, in UTC format.
For example, 2014-10-02T20:44:35.
source_modified datetime Time stamp of when the attack pattern was last
modified by the source, in UTC format.
For example, 2014-10-02T20:44:35.

Reference Guide
Threat Model
starred_by_me boolean Whether the user has starred the attack

pattern—added it to their favorites.
True—if the attack pattern is starred
False—if the attack pattern is not starred
starred_total_count integer How many times the attack pattern was starred
by all users.
tags list Tags assigned to the attack pattern.
A tag is a meaningful name or any other string

value assigned to identify the information.
tags_v2 related (see item Additional information on the tags assigned to the
1 in "Notes" on attack pattern.
page 105)
tipreports related (see item Threat bulletins associated with the attack
page 105)
When creating an attack pattern, specify the ID of
the threat bulletin.
tlp string Traffic Light Protocol designation for the attack

pattern—red, amber, green, white.
Note: The value is case-sensitive and must

be specified in lower case.
tools related (see item Tools associated with the attack pattern.
1 in "Notes" on
page 105)
ttps related (see item TTP (Threat Bulletins) associated with the attack
page 105)
TTP ID. See "TTPs (Tactics, Techniques, and
Procedures)" on page 144.
uuid string UUID (universally unique identifier) assigned to

the observable for STIX compliance.
votes array of integers How many times the users voted for the attack
pattern.

Reference Guide
Threat Model
vulnerability related (see item Vulnerabilities associated with the attack pattern.
1 in "Notes" on
When creating an attack pattern, specify the ID of
page 105)
the vulnerability.
watched_by_me boolean Whether the attack pattern is watched by the

user.
True—if the attack pattern is watched
False—if the attack pattern is not watched
watched_total_count integer How many users are watching the attack pattern.
workgroups list of strings Workgroups to which the attack pattern is visible.
Examples
1. To create a private attack pattern entity that is associated with a TTP whose ID is 63:
curl --request POST --data '{"name": "dummy test attack pattern", "tlp":
"red", "tags": ["attack pattern", "example tag"], "ttps": [63]}'
"https://api.threatstream.com/api/v1/attackpattern/" -H 'Authorization:
apikey <username>:<api_key>' -H "Content-Type:application/json"
2. To update an existing attack pattern entity whose ID is 27:
curl --request PATCH --data '{"name": "another dummy test attack pattern",
"tlp": "orange"}' "https://api.threatstream.com/api/v1/attackpattern/27/" -H
3. To get the details of an existing attack pattern entity whose ID is 27:
curl "https://api.threatstream.com/api/v1/attackpattern/27/" -H
4. To get the first 10 attack pattern entities from ThreatStream:
curl "https://api.threatstream.com/api/v1/attackpattern/?limit=10" -H
5. (Only on ThreatStream OnPrem) To get details of a remote attack patten whose ID is 28:
FQDN>/api/v1/attackpattern/28/?remote_api=true" -H 'Authorization: apikey
6. (Only on ThreatStream OnPrem) To skip associations when retrieving details of a local attack
pattern with ID 234678:

Reference Guide
Threat Model
FQDN>/api/v1/attackpattern/234678/?skip_associations=true" -H
Campaigns
To create, update or retrieve existing campaigns from the ThreatStream platform.
Request
/api/v1/campaign/
Create a new campaign POST /api/v1/campaign/
Update the specified campaign PATCH /api/v1/campaign/{id}/
Get the specified campaign GET /api/v1/campaign/{id}/
Get a list of campaigns Anomali recommends to use the /api/v1/threat_

model_search endpoint to retrieve the list of
campaigns. See "Threat Model Search" on page 89 for
details.
For example,
type=campaign
Get a list of campaigns associated with GET /api/v1/campaign/associated_with_

the specified indicator value or indicator intelligence/?value={value}
ID
GET /api/v1/campaign/associated_with_
For example,
GET /api/v1/campaign/associated_with_
campaigns that are associated with google.com.
Get a list of a specified entity type (such GET /api/v1/campaign/{id}/<entity_type>/

as malware, incident, and so on) that is
For example,
associated with the specified campaign
GET /api/v1/campaign/234673/malware/ returns
all malware objects associated with the specified
campaign.
Get a list of observables associated with GET /api/v1/campaign/{id}/intelligence/

the specified campaign

Reference Guide
Threat Model
Response
Format: JSON
Notes
Attributes
actors related Actor names associated with the campaign.

(see item 1
When creating a campaign, specify the Actor ID. See "Actors "
in "Notes"
on page 97.
above)
circles related All Trusted Circles to which the campaign belongs.

(see item 1
in "Notes"
above)
created_ts datetime Time stamp of when the campaign was created on

For example, 2014-10-02T20:44:35.
Note: This attribute is returned in the response to a GET

call and is set by ThreatStream; it cannot be configured.
description string The free-form text associated with the campaign (as specified
in the Description field in the UI).
end_date datetime Specify the time when this campaign is known to have ended.
Date must be specified in this format: YYYYMMDDThhmmss

and in UTC format.
For example, 2014-10-02T20:44:35.

Reference Guide
Threat Model
incidents related Incidents associated with the campaign.

(see item 1
When creating a campaign, specify the Incident ID. See
in "Notes"
"Incidents" on page 119.
on the
previous
page)
intelligence related Indicators associated with the campaign on the ThreatStream

(see item 1 platform.
in "Notes"
When creating a campaign, specify the indicator ID. See
on the
"Intelligence" on page 40.
previous
page)
is_public boolean Whether the campaign is public or private (including belonging

to a trusted circle).
False—if the campaign is private or belongs to a Trusted Circle
True—if the campaign is public
Default: False
limit numeric The limit variable controls the number of results returned
every time an API call is made; the total number of results may
be much larger than returned in one API call.
If limit is not specified, 20 results are returned with each

API call. Specifying limit=0 will return up to a maximum of
1000 results (if available).
modified_ts datetime Time stamp of when the campaign was last updated on
For example, 2014-10-02T20:44:35.


Reference Guide
Threat Model
name string Name of the campaign.
Campaign name is associated with your organization.

Therefore, the name must be unique within your organization.
However, two campaigns with the same name can exist on
ThreatStream as long as they belong to different organizations.
publication_status string A campaign can be in new, pending_review, review_requested,

reviewed, published statuses.
Note: A campaign must be in published status for it to be

visible to other users outside your organization.

ThreatStream
Value returned for this attribute is true when the entity is
OnPrem only)
remote.
signatures related Signatures associated with the campaign.

(see item 1
When creating a campaign, specify the Signature ID. See
in "Notes"
"Signatures" on page 133.
on
page 114)

associations are returned with GET requests for details of a
(On ThreatStream
Threat Model entity on ThreatStream OnPrem. When a Threat
OnPrem only)
Model entity has a large number of associations, association
retrieval can take a long time and impact performance.
associations parameter to true. This parameter is only
For example,
GET /api/v1/campaign/{id}/?skip_associations=true

Reference Guide
Threat Model

(On ThreatStream
OnPrem only)
intelligence parameter to true. This parameter is only
For example,
GET /api/v1/campaign/{id}/?skip_intelligence=true
source_created datetime Time stamp of when the campaign was created by its original
source.
source_modified datetime Time stamp of when the campaign was last updated by its
original source.
start_date datetime Specify the time when this campaign was first known to be
active.

and in UTC format.
For example, 2014-10-02T20:44:35.
status string Status of the campaign.
When creating a campaign, specify the Status ID. Use

/api/v1/campaignstatus/ to obtain a list of campaign statuses.
tags list Tags assigned to the campaign.
A tag is a meaningful name or any other string value assigned

to identify the information.
tlp string Traffic Light Protocol designation for the campaign—red,

Note: The value is case-sensitive and must be specified in

lower case.

Reference Guide
Threat Model
ttps related TTP (Threat Bulletins) associated with the Campaign.

(see item 1
When creating a campaign, specify the TTP ID. See "TTPs
in "Notes"
(Tactics, Techniques, and Procedures)" on page 144.
on
page 114)
victims related Victim type associated with the campaign.

(see item 1
When creating a campaign, specify the ID of the vvictim type.
in "Notes"
To obtain a list of victim types, make an API call to
on
/api/v1/victimtype/.
page 114)
Examples
1. To create a private campaign associated with an indicator whose ID is 165546:
curl --request POST --data '{"name": "dummy test campaign", "tlp": "red",
"tags": ["big campaign", "dummy tag"], "intelligence": [165546],
"publication_status": "published"}'
"https://api.threatstream.com/api/v1/campaign/" -H "Content-
Type:application/json" -H 'Authorization: apikey <username>:<api_key>'
2. To update an existing campaign whose ID is 1062:
curl --request PATCH --data '{"name": "another dummy test campaign", "tlp":
"orange"}' "https://api.threatstream.com/api/v1/campaign/1062/" -H "Content-
3. To get the detail of an existing campaign whose ID is 1062:
curl "https://api.threatstream.com/api/v1/campaign/1062/" -H 'Authorization:

4. To get the first 10 campaigns from ThreatStream:
curl "https://api.threatstream.com/api/v1/campaign/?limit=10" -H
5. (Only on ThreatStream OnPrem) To get the detail of a remote campaign whose ID is 1063:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/campaign/1063/?remote_
6. (Only on ThreatStream OnPrem) To skip associations when retrieving details of a local

campaign with ID 234678:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/campaign/234678/?skip_
associations=true" -H 'Authorization: apikey <username>:<api_key>

Reference Guide
Threat Model
Incidents
To create, update, or retrieve incidents from from the ThreatStream platform.
Request
/api/v1/incident/
Create a new incident POST /api/v1/incident/
Update the specified incident PATCH /api/v1/incident/{id}/
Get the specified incident GET /api/v1/incident/{id}/
Get a list of incidents Anomali recommends to use the /api/v1/threat_

For example,
type=incident
Get a list incidents associated with the GET /api/v1/incident/associated_with_

GET /api/v1/incident/associated_with_
For example,
GET /api/v1/incident/associated_with_
incidents that are associated with google.com.
Get a list of a specified entity type (such GET /api/v1/incident/{id}/<entity_type>/

as malware, campaign, and so on) that is
For example,
associated with the specified incident
GET /api/v1/incident/234673/malware/ returns
all malware objects associated with the specified
incident.
Get a list of observables associated with GET /api/v1/incident/{id}/intelligence/

the specified incident
Response
Format: JSON

Reference Guide
Threat Model
Notes
Attributes
actors related Actor names associated with the incident.

(see item 1
When creating an incident, specify the Actor ID. See "Actors " on
in "Notes"
page 97.
above)
circles related All Trusted Circles to which the incident belongs.

(see item 1
in "Notes"
above)
created_ts datetime Time stamp of when the incident was created on ThreatStream,
in UTC format.
For example, 2014-10-02T20:44:35.
Note: This attribute is returned in the response to a GET call

and is set by ThreatStream; it cannot be configured.
description string The free-form text associated with the incident (as specified in
the Description field in the UI).
end_date datetime Specify the time when this incident is known to have ended.
Date must be specified in this format: YYYYMMDDThhmmss and

in UTC format.
For example, 2014-10-02T20:44:35.
intelligence related Indicators associated with the incident on the ThreatStream

in "Notes"
When creating an incident, specify the indicator ID. See
above)

Reference Guide
Threat Model
is_public boolean Whether the incident is public or private (including belonging to a

trusted circle).
False—if the incident is private or belongs to a Trusted Circle
True—if the incident is public
Default: False
limit numeric The limit variable controls the number of results returned every
time an API call is made; the total number of results may be much
larger than returned in one API call.

API call. Specifying limit=0 will return up to a maximum of 1000
results (if available).
modified_ts datetime Time stamp of when the incident was last updated on
For example, 2014-10-02T20:44:35.

name string Name of the incident.
Incident name is associated with your organization. Therefore,

the name must be unique within your organization. However, two
incidents with the same name can exist on ThreatStream as long
as they belong to different organizations.

ThreatStream
Value returned for this attribute is true when the entity is remote.
OnPrem only)
sandbox_reports related Sandbox reports associated with the incident.

(see item 1
When creating an incident, specify the Sandbox report ID. See
in "Notes"
"Sandbox" on page 73.
on the
previous
page)

Reference Guide
Threat Model
signatures related Signatures associated with the incident.

(see item 1
When creating an incident, specify the Signature ID. See
in "Notes"
on
page 120)
skip_ boolean By default, up to 1000 Threat Model and observable associations

associations are returned with GET requests for details of a Threat Model
entity on ThreatStream OnPrem. When a Threat Model entity has
(On
a large number of associations, association retrieval can take a
ThreatStream
long time and impact performance. Therefore, Anomali
OnPrem only)
recommends setting the skip_associations parameter to
true. This parameter is only applicable to ThreatStream
OnPrem.
For example,
GET /api/v1/incident/{id}/?skip_associations=true
skip_intelligence boolean By default, up to 1000 Threat Model and observable associations

are returned with GET requests for details of a Threat Model
(On
entity ThreatStream OnPrem. When a Threat Model entity has a
ThreatStream
large number of associations, association retrieval can take a
OnPrem only)
recommends setting the skip_intelligence parameter to
OnPrem.
For example,
GET /api/v1/incident/{id}/?skip_intelligence=true
source_created datetime Time stamp of when the incident was created by its original
source.
source_modified datetime Time stamp of when the incident was last updated by its original
source.
start_date datetime Specify the time when this incident was first known to be active.
Date must be specified in this format: YYYYMMDDThhmmss and

in UTC format.
For example, 2014-10-02T20:44:35.

Reference Guide
Threat Model
status string Status of the incident.
When creating an incident, specify the Status ID. Use

/api/v1/incidentstatustype/ to obtain a list of incident
statuses.
status_desc string Free-form text associated with the status of the incident (as
specified in the Description field in the UI)
tags list Tags assigned to the incident.
A tag is a meaningful name or any other string value assigned to

identify the information.
tlp string Traffic Light Protocol designation for the incident—red, amber,
green, white.

lower case.
ttps related TTP (Threat Bulletins) associated with the incident.

(see item 1
When creating an incident, specify the TTP ID. See "TTPs
in "Notes"
on
page 120)
victims related Victim type associated with the incident.

(see item 1
When creating an incident, specify the ID of the victim type. To
in "Notes"
obtain a list of victim types, make an API call to
on
/api/v1/victimtype/.
page 120)
Examples
1. To create a private incident with status Open and associated with TTP whose ID is 63:
curl --request POST --data '{"name": "dummy test incident", "tlp": "red",
"tags": ["big incident", "dummy tag"], "ttps": [63], "status": 2, "status_
desc": "this is an open incident"}'
"https://api.threatstream.com/api/v1/incident/" -H 'Authorization: apikey
<username>:<api_key>' -H "Content-Type:application/json"
2. To update an existing incident whose ID is 79:
curl --request PATCH --data '{"name": "another dummy test incident", "tlp":
"orange", "status": 7, "status_desc": "this incident is closed"}'

Reference Guide
Threat Model
"https://api.threatstream.com/api/v1/incident/79/" -H "Content-
3. To get the detail of an existing incident whose ID is 79:
curl "https://api.threatstream.com/api/v1/incident/79/" -H 'Authorization:

4. To get the first 10 incidents from ThreatStream:
curl "https://api.threatstream.com/api/v1/incident/?limit=10" -H
5. (Only on ThreatStream OnPrem) To get the detail of a remote incident whose ID is 80:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/incident/80/?remote_
6. (Only on ThreatStream OnPrem) To skip associations when retrieving details of a local incident
with ID 12345:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/incident/12345/?skip_
Malware
To create, update, or retrieve malware entities from the ThreatStream platform.
Request
/api/v1/malware/
HTTP Methods: GET, POST, P ATCH
Create a new malware entity POST /api/v1/malware/
Update the specified malware entity PATCH /api/v1/malware/{id}/
Get the specified malware entity GET /api/v1/malware/{id}/
Get a list of malware entities Anomali recommends to use the /api/v1/threat_

For example,
type=malware

Reference Guide
Threat Model
Get a list of malware entities associated GET /api/v1/malware/associated_with_

with the specified indicator value or intelligence/?value={value}
indicator ID
GET /api/v1/malware/associated_with_
For example,
GET /api/v1/malware/associated_with_
malware that are associated with google.com.
Get a list of a specified entity type (such GET /api/v1/malware/{id}/<entity_type>/

as actor, campaign, and so on) that is
For example,
associated with the specified malware
GET /api/v1/malware/234673/actor/ returns all
actors associated with the specified walware.
Get a list of observables associated with GET /api/v1/malware/{id}/intelligence/

the specified malware
Response
Format: JSON
Notes
Attributes
actors related Actors associated with the malware.

(see item 1
When creating malware, specify the Actor ID. See "Actors " on
in "Notes"
page 97.
above)
aliases string Other names by which the malware is known.
attackpatterns related Attack patterns associated with the malware.

(see item 1
When creating malware, specify the Attack Pattern ID.
in "Notes"
above)

Reference Guide
Threat Model
body_content_type string Format used for the body text of the description: markdown or
richtext
Default: markdown
Note: Once specified, body_content_type cannot be

modified.
c2_port string Port utilized by associated command and control

infrastructure.
c2_protocol string Protocol utilized by associated command and control

infrastructure.
Possible values include: custom, dns, dns_txt, http, https
campaigns related Campaigns associated with the malware.

(see item 1
When creating malware, specify the Campaign ID. See
in "Notes"
"Campaigns" on page 113.
on the
previous
page)
capabilities string Capabilities associated with the malware.
Possible values include: accesses-remote-machines, anti-

debugging, anti-disassembly, anti-emulation, anti-memory-
forensics, anti-sandbox, anti-vm, captures-input-peripherals,
captures-output-peripherals, captures-system-state-data,
cleans-traces-of-infection, commits-fraud, communicates-with-
c2, compromises-data-availability, compromises-data-
integrity, compromises-system-availability, controls-local-
machine, degrades-security-software, degrades-system-
updates, determines-c2-server, emails-spam, escalates-
privileges, evades-av, exfiltrates-data, fingerprints-host, hides-
artifacts, hides-executing-code, infects-files, infects-remote-
machines, installs-other-components, persists-after-system-
reboot, prevents-artifact-access, prevents-artifact-deletion,
probes-network-environment, self-modifies, steals-
authentication-credentials, violates-system-operational-
integrity
circles related All Trusted Circles to which the malware belongs.

(see item 1
in "Notes"
on the
previous
page)

Reference Guide
Threat Model
courseofaction related Course of action entities associated with the malware.

(see item 1
When creating malware, specify the Course of Action ID.
in "Notes"
on
page 125)
created_ts datetime Time stamp of when the malware was created on

For example, 2014-10-02T20:44:35.

description string The free-form text associated with the malware (as specified in
the Description field in the UI).
embedded_ string Not used.

content_type
embedded_ string Not used.

content_url
execution_ string Execution platforms associated with the malware.

platforms
Possible values include: android, bios, bsd, ios, linux, macos,
uefi, unknown, windows
feed_id string Numeric ID of the threat feed that provided the Threat Model
entity.
first_seen datetime Time stamp of when the malware was first observed, in UTC
format.
For example, 2014-10-02T20:44:35.
id string ID of the malware entity. This ID is automatically assigned to

the entity by ThreatStream at the time of creation. You can use
this ID to associate the malware entity with other Threat Model
entities.

Reference Guide
Threat Model
identities related Identities associated with the malware.

(see item 1
When creating malware, specify the Identity ID.
in "Notes"
on
page 125)
implementation_ string Implementation languages used by the malware.

languages
Possible values include: applescript, bash, c, c#, c++, go, java,
javascript, lua
incidents related Incidents associated with the malware.

(see item 1
When creating malware, specify the Incident ID.
in "Notes"
on
page 125)
infrastructure related Infrastructure entities associated with the malware.

(see item 1
When creating malware, specify the Infrastructure ID.
in "Notes"
on
page 125)
intelligence related Indicators associated with the malware on the ThreatStream

in "Notes"
When creating malware, specify the indicator ID. See
on
page 125)
intrusionsets related Intrusion sets associated with the malware.

(see item 1
When creating malware, specify the Instrusion Set ID.
in "Notes"
on
page 125)
is_anonymous boolean Whether the threat bulletin user and organization information is
anonymized.
True—if information is anonymized
False—if information is not anonymized
is_family boolean Whether the entity is a malware family or single malware

(Required) instance.
True—if the entity is a malware family
False—if the entitiy is a single malware instance

Reference Guide
Threat Model
is_public boolean Whether the malware is public or private (including belonging

False—if the malware is private or belongs to a Trusted Circle
True—if the malware is public
Default: False
killchainstages N/A Not used.
last seen datetime Time stamp of when the malware was last observed, in UTC
format.
For example, 2014-10-02T20:44:35.
malware_types string Malware types associated with the malware.

(Required)
Possible values include: adware, backdoor, bootkit, bot, ddos,
downloader, dropper, keylogger, exploit-kit, ransomware,
remote-access-trojan, resource-exploitation, rogue-security-
software, rootkit, screen-capture, spyware, trojan, unknown,
virus, webshell, wiper, worm
malwares related Other malware entities associated with the Malware.

(see item 1
When creating malware, specify the ID of Malware of interest.
in "Notes"
on
page 125)
modified_ts datetime Time stamp of when the malware was last updated on
For example, 2014-10-02T20:44:35.


Reference Guide
Threat Model
name string Name of the malware.
Malware name is associated with your organization. Therefore,

the name must be unique within your organization. However,
two malware with the same name can exist on ThreatStream
as long as they belong to different organizations.
organization string Information about the organization that created the entity on
ThreatStream.
owner_user string Information about the user that created the entity on
ThreatStream.
parent N/A Not used.
publication_status string Malware entities can be in new, pending_review, review_

requested, reviewed, or published statuses.
Note: Malware entities must be in published status for it to

be visible to other users outside your organization.

ThreatStream
Value returned for this attribute is true when the entity is
OnPrem only)
remote.
sandbox_reports related Sandbox reports associated with the malware.

(see item 1
When creating malware, specify the Sandbox report ID. See
in "Notes"
"Sandbox" on page 73.
on
page 125)
signatures related Signatures associated with the malware.

(see item 1
When creating malware, specify the Signature ID. See
in "Notes"
on
page 125)

Reference Guide
Threat Model

(On ThreatStream
OnPrem only)
associations parameter to true. This parameter is only
For example,
GET /api/v1/malware/{id}/?skip_associations=true

(On ThreatStream
Threat Model entity ThreatStream OnPrem. When a Threat
OnPrem only)
intelligence parameter to true. This parameter is only
For example,
GET /api/v1/malware/{id}/?skip_intelligence=true
source_created datetime Time stamp of when the malware was originally created by the
source, in UTC format.
For example, 2014-10-02T20:44:35.
source_modified datetime Time stamp of when the malware was last modified by the
source, in UTC format.
For example, 2014-10-02T20:44:35.
tags list Tags assigned to the malware.
A tag is a meaningful name or any other string value assigned

to identify the information.

Reference Guide
Threat Model
tipreports related Threat Bulletins associated with the malware.

(see item 1
When creating malware, specify the ID of the Threat Bulletin.
in "Notes"
on
page 125)
tlp string Traffic Light Protocol designation for the malware—red, amber,
green, white.

lower case.
tools related Tools associated with the malware.

(see item 1
When creating malware, specify the ID of the Threat Bulletin.
in "Notes"
on
page 125)
ttps related TTP (Threat Bulletins) associated with the Malware.

(see item 1
When creating malware, specify the TTP ID. See "TTPs
in "Notes"
on
page 125)
vulnerability related Vulnerabilities associated with the malware.

(see item 1
When creating malware, specify the ID of the vulnerability.
in "Notes"
on
page 125)
Examples
1. To create a private malware entity that is associated with a TTP whose ID is 63:
curl --request POST --data '{"name": "dummy test malware", "tlp": "red",
"tags": ["malware", "example tag"], "ttps": [63], "is_family": false,
"malware_types": ["screen-capture"]}'
"https://api.threatstream.com/api/v1/malware/" -H 'Authorization: apikey
2. To update an existing malware entity whose ID is 79:
curl --request PATCH --data '{"name": "another dummy test malware", "tlp":
"orange"}' "https://api.threatstream.com/api/v1/malware/79/" -H

Reference Guide
Threat Model
3. To get the details of an existing malware entity whose ID is 79:
curl "https://api.threatstream.com/api/v1/malware/79/" -H 'Authorization:

4. To get the first 10 malware entities from ThreatStream:
curl "https://api.threatstream.com/api/v1/malware/?limit=10" -H
5. (Only on ThreatStream OnPrem) To get the detail of a remote malware entity whose ID is 80:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/malware/80/?remote_
6. (Only on ThreatStream OnPrem) To skip associations when retrieving details of a local malware
entity with ID 123456:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/malware/123456/?skip_
Signatures
To create, update or retrieve signatures from the ThreatStream platform.
Request
/api/v1/signature/
Create a new signature POST /api/v1/signature/
Update the specified signature PATCH /api/v1/signature/{id}/
Get the specified signature GET /api/v1/signature/{id}/
Get a list of signatures Anomali recommends to use the /api/v1/threat_

For example,
type=signature

Reference Guide
Threat Model
Get a list of signatures associated with the GET /api/v1/signature/associated_with_

GET /api/v1/signature/associated_with_
intelligence/?ids={comma_separated_id_
list}
For example,
GET /api/v1/signature/associated_with_
Signatures that are associated with google.com.
Get a list of a specified entity type (such as GET /api/v1/signature/{id}/<entity_type>/

malware, actor, campaign, and so on) that
For example,
is associated with the specified signature
GET /api/v1/signature/234673/actor/ returns
all actors associated with the specified signature.
Get a list of observables associated with GET /api/v1/signature/{id}/intelligence/

the specified signature
Response
Format: JSON
Notes
Attributes
circles related All Trusted Circles to which the signature belongs.

(see item
1 in
"Notes"
above)

Reference Guide
Threat Model
created_ts datetime Time stamp of when the signature was created on ThreatStream,
in UTC format.
For example, 2014-10-02T20:44:35.

is_public boolean Whether the signature is public or private (including belonging to a

trusted circle).
False—if the signature is private or belongs to a Trusted Circle
True—if the signature is public
Default: False

modified_ts datetime Time stamp of when the signature was last updated on
For example, 2014-10-02T20:44:35.


Reference Guide
Threat Model
name string Name of the signature.
Signature name is associated with your organization. Therefore,

the name must be unique within your organization. However, two
signatures with the same name can exist on ThreatStream as
long as they belong to different organizations.
notes string Free-form text description and any other significant information
about the signature.
publication_ string A signature can be in new, pending_review, review_requested,

status reviewed, published statuses.
Note: A signature must be in published status for it to be


ThreatStream
OnPrem only)
s_type string Signature type such as Snort, YARA, OpenIOC, Suricata.
When creating a signature, specify the ID of the signature type. To

obtain a list of signature type IDs, make an API call to
/api/v1/signature_type/.

associations are returned with GET requests for details of a Threat Model entity
on ThreatStream OnPrem. When a Threat Model entity has a
(On
large number of associations, association retrieval can take a long
ThreatStream
time and impact performance. Therefore, Anomali recommends
OnPrem only)
setting the skip_associations parameter to true. This
parameter is only applicable to ThreatStream OnPrem.
For example,
GET /api/v1/signature/{id}/?skip_associations=true

Reference Guide
Threat Model

are returned with GET requests for details of a Threat Model entity
(On
ThreatStream
OnPrem only)
setting the skip_intelligence parameter to true. This
For example,
GET /api/v1/signature/{id}/?skip_intelligence=true
source_created datetime Time stamp of when the signature was created by its original
source.
source_modified datetime Time stamp of when the signature was last updated by its original
source.
tags list Tags assigned to the signature.

tlp string Traffic Light Protocol designation for the signature—red, amber,
green, white.

lower case.
Examples
1. To create a private signature whose s_type ID is 3 (for CybOX):
curl --request POST --data '{"name": "dummy test signature", "tlp": "red",
"s_type": 3, "tags": ["big signature", "dummy tag"], "intelligence":
[165546], "publication_status": "published", "notes": "the definition of
this CybOX signature"}' "https://api.threatstream.com/api/v1/signature/" -H
"Content-Type:application/json" -H 'Authorization: apikey <username>:<api_
key>'
2. To update an existing signature whose ID is 10:
curl --request PATCH --data '{"name": "another dummy test signature", "tlp":
"orange"}' "https://api.threatstream.com/api/v1/signature/10/" -H

Reference Guide
Threat Model
3. To get the detail of an existing signature whose ID is 10:
curl "https://api.threatstream.com/api/v1/signature/10/" -H 'Authorization:

4. To get the first 10 signatures from ThreatStream:
curl "https://api.threatstream.com/api/v1/signature/?limit=10" -H
5. (Only on ThreatStream OnPrem) To get the detail of a remote signature whose ID is 11:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/signature/11/?remote_

signature with ID 234678:
FQDN>/api/v1/signature/234678/?skip_associations=true" -H 'Authorization:
Tipreport
To create, update or retrieve threat bulletins from the ThreatStream platform.
Request
/api/v1/tipreport/
HTTP Methods: GET, PATCH, POST
Create a new threat bulletin POST /api/v1/tipreport/
Get a list of threat bulletins Anomali recommends to use the

/api/v1/threat_model_search
endpoint to retrieve the list of actors. See
"Threat Model Search" on page 89 for
details.
For example,
GET /api/v1/threat_model_
search/?model_type=tipreport

Reference Guide
Threat Model
Get a list of a specified entity type (such as malware, GET /api/v1/tipreport/

actor, campaign, and so on) that is associated with the {id}/<entity_type>/
specified threat bulletin
For example,
GET
/api/v1/tipreport/234673/actor/
returns all actors associated with the
specified threat bulletin.
Get a list of observables associated with the specified GET /api/v1/tipreport/

threat bulletin {id}/intelligence/
Get a list of comments associated with the threat GET /api/v1/tipreport/

bulletin, as shown in the Comments section in the user {id}/comment
interface
Get all revision history values associated with a threat GET /api/v1/tipreport/
bulletin, as shown in the History table in the user {id}/history
interface
Modify an existing threat bulletin PATCH /api/v1/tipreport/
Note: For information creating and removing associations between threat bulletins and other
threat model entities through the API, see "Managing Threat Model Associations " on page 154
Response
Format: JSON
Notes
Attributes
assignee_org_id integer ID of the organization to which the threat bulletin is

assigned.
assignee_user_id integer ID of the user to which the threat bulletin is

assigned.

Reference Guide
Threat Model
attachments related (see item All files—whitepapers, reports, news—attached to

1 in "Notes" on the threat bulletin.
the previous
page)
body_content_type string Format used for the body text of the threat bulletin:
markdown or richtext
Default: markdown
Note: Once specified, body_content_type

cannot be modified.
body string Full text of the threat bulletin. Body text must be in
the format specified for body_content_type.
Use your favorite search engine to search for

information on markdown and rich text formats.
circles related (see item IDs of the trusted circles with which the threat
1 in "Notes" on bulletin is shared.
the previous
page)
comments related (see item Deprecated. Use the GET request to view
1 in "Notes" on comments associated with the threat bulletin.
the previous
page)
created_ts datetime Timestamp when the investigation was created.
history related (see item Deprecated. Use the GET request to view history
1 in "Notes" on of the threat bulletin.
the previous
page)
id string Unique ID for the threat bulletin.
The identifier is assigned to the threat bulletin

when it is first created on ThreatStream.
import_sessions related(see item Import sessions associated with the threat bulletin.
1 in "Notes" on
Use this attribute if you need to associate a batch
the previous
of imported indicators. Provide Import Job ID from
page)
the Import UI page or use the import API to obtain
the job ID.

Reference Guide
Threat Model
intelligence related (see item Observables associated with the threat bulletin.
1 in "Notes" on
Use this attribute to associate intelligence
page 139)
(indicators) available on ThreatStream through
means other than "import".
Note: The intelligence associated with the

"import_sessions" and "intelligence" attributes
may be mutually exclusive. That is, indicators
returned through "import_sessions" attribute may
not appear in the list of indicators available
through the "intelligence" attribute. Therefore, to
obtain a complete list of intelligence associated
with a threat bulletin, get intelligence using both
the attributes.
is_anonymous string Whether the threat bulletin user and organization

information is anonymized.
is_anonymous=1 for true (anonymous)
is_anonymous=0 for false (not anonymous)
is_public boolean Whether the threat bulletin is public or private

(including belonging to a trusted circle).
False—if the threat bulletin is private or belongs to

a Trusted Circle
True—if the threat bulletin is public
Default: False
limit numeric The limit variable controls the number of results

returned every time an API call is made; the total
number of results may be much larger than
returned in one API call.
If limit is not specified, 20 results are returned

with each API call. Specifying limit=0 will return
up to a maximum of 1000 results (if available).
modified_ts datetime Timestamp when the investigation was last

modified.
name string Threat bulletin name.
owner_org_id integer Organization ID of the owner.
In most cases, this ID is the same as the assignee

organization ID.

Reference Guide
Threat Model
owner_user_id integer User ID of the owner of the threat bulletin.
In most cases, owner of the threat bulletin is the

same as the assignee of the threat bulletin.

ThreatStream OnPrem
only)
entity is remote.
resource_uri string URI for the threat bulletin on ThreatStream.
sandbox_reports related (see item Sandbox reports associated with the threat
1 in "Notes" on bulletin.
page 139)
Obtain ID of the Sandbox report from the Sandbox
UI page.
skip_associations boolean By default, up to 1000 Threat Model and

(On ThreatStream
OnPrem only)
recommends setting the skip_associations
For example,
GET /api/v1/tipreport/{id}/?skip_
associations=true
skip_intelligence boolean By default, up to 1000 Threat Model and

(On ThreatStream
OnPrem only)
recommends setting the skip_intelligence
For example,
GET /api/v1/tipreport/{id}/?skip_
intelligence=true

Reference Guide
Threat Model
source string Source of the intelligence.
For example, USCERT, Anomali.
source_created datetime Time stamp of when the threat bulletin was

created by its original source.
source_modified datetime Time stamp of when the threat bulletin was last
updated by its original source.
status string Provides the status of the threat bulletin

(equivalent of Stage in the user interface).
Default: new
Other possible values—published, reviewed,

review_requested, pending_review
tags_v2 string Tag assigned to the threat bulletin.
A tag is a meaningful name or any other string

value assigned to identify the information.
threat_actor string Deprecated. Returns null in responses.
tlp string Traffic Light Protocol designation for the threat

bulletin—Red, Amber, Green, White.
ttp string Deprecated. Returns null in responses.
vulnerability string Deprecated. Returns null in responses.
Examples
1. To retrieve the first 10 threat bulletins:
curl "https://api.threatstream.com/api/v1/tipreport/?limit=10"
2. To retrieve threat bulletins that were created since a specified date and time:
curl "https://api.threatstream.com/api/v1/tipreport/?created_ts__gte=2014-
10-02T20:44:35"
3. To create a new threat bulletin:
curl --request POST --data '{"body":"this is a new threat

bulletin","name":"New Threat Bulletin"}'
"https://api.threatstream.com/api/v1/tipreport/" -H 'Authorization: apikey
<username>:<api_key>' -H "Content-Type:application/json" -v

Reference Guide
Threat Model
4. To create a new threat bulletin that includes private tags:
curl --request POST --data '{"name":"New Threat Bulletin with

Associations","tags_v2": [{"name":"my_private_tag","tlp":"red"}]}'
"https://api.threatstream.com/api/v1/tipreport/" -H 'Authorization: apikey
5. To modify an existing threat bulletin whose ID is 11:
curl --request PATCH --data '{"name":"Updated Threat Bulletin Name"}'

"https://api.threatstream.com/api/v1/tipreport/11/" -H 'Authorization:
6. To add an attachment to an existing threat bulletin:
curl --request POST -F"attachment=@<file_directory>/<file_name>" -F

"filename=<file_name>"
"https://api.threatstream.com/api/v1/tipreport/<threat_bulletin_
ID>/attachment/" -H 'Authorization: apikey <username>:<api_key>' -v
where <file_directory> is the directory of the file which you want to attach
<file_name> is the name of the file which you want to attach
7. (Only on ThreatStream OnPrem) To get the details of a remote threat bulletin whose ID is 12:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/tipreport/12/?remote_
8. (Only on ThreatStream OnPrem) To skip associations when retrieving details of a local threat
bulletin with ID 234678:
9. curl "https://<ThreatStream_OnPrem_IP_or_
FQDN>/api/v1/tipreport/234678/?skip_associations=true" -H 'Authorization:
TTPs (Tactics, Techniques, and Procedures)

To create, update or retrieve TTPs from the ThreatStream platform.
Request
/api/v1/ttp/
Create a new TTP POST /api/v1/ttp/

Reference Guide
Threat Model
Get a list of TTPs Anomali recommends to use the /api/v1/threat_

For example,
type=ttp
Update the specified TTP PATCH /api/v1/ttp/{id}/
Get the specified TTP GET /api/v1/ttp/{id}/
Get a list of TTPs associated with the GET /api/v1/ttp/associated_with_

GET /api/v1/ttp/associated_with_
intelligence/?ids={comma_separated_id_
list}
For example,
GET /api/v1/ttp/associated_with_
TTPs that are associated with google.com.
Get all TTPs created by the user's GET /api/v1/my_organization/

organization
Get a list of a specified entity type (such GET /api/v1/ttp/{id}/<entity_type>/

as malware, actor, campaign, and so on)
For example,
that is associated with the specified TTP
GET /api/v1/ttp/234673/actor/ returns all actors
associated with the specified TTP.
Get a list of observables associated with GET /api/v1/ttp/{id}/intelligence/

the specified TTP
Response
Format: JSON
Notes

Reference Guide
Threat Model
Attributes
actors related Actor names associated with the TTP.

(see item 1
When creating a TTP, specify the Actor ID. See "Actors " on
in "Notes"
page 97.
on the
previous
page)
circles related All Trusted Circles to which the TTP belongs.

(see item 1
in "Notes"
on the
previous
page)
created_ts datetime Time stamp of when the TTP was created on ThreatStream, in
UTC format.
For example, 2014-10-02T20:44:35.

description string The free-form text associated with the TTP (as specified in the
Description field in the UI).
intelligence related Indicators associated with the TTP on the ThreatStream platform.
(see item 1
When creating a TTP, specify the indicator ID. See "Intelligence"
in "Notes"
on page 40.
on the
previous
page)
is_public boolean Whether the TTP is public or private (including belonging to a

trusted circle).
False—if the TTP is private or belongs to a Trusted Circle
True—if the TTP is public
Default: False

Reference Guide
Threat Model

modified_ts datetime Time stamp of when the TTP was last updated on ThreatStream,
in UTC format.
For example, 2014-10-02T20:44:35.

name string Name of the TTP.
TTP name is associated with your organization. Therefore, the

name must be unique within your organization. However, two
TTPs with the same name can exist on ThreatStream as long as
they belong to different organizations.
publication_ string A TTP can be in new, pending_review, review_requested,

Note: A TTP must be in published status for it to be visible to

other users outside your organization.

ThreatStream
OnPrem only)
signatures related Signatures associated with the TTP.

(see item 1
When creating a TTP, specify the Signature ID. See "Signatures"
in "Notes"
on page 133.
on
page 145)

Reference Guide
Threat Model

associations are returned with GET requests for details of a Threat Model
(On
ThreatStream
OnPrem only)
recommends setting the skip_associations parameter to
OnPrem.
For example,
GET /api/v1/ttp/{id}/?skip_associations=true

are returned with GET requests for details of a Threat Model
(On
ThreatStream
OnPrem only)
recommends setting the skip_intelligence parameter to
OnPrem.
For example,
GET /api/v1/ttp/{id}/?skip_intelligence=true
source_created datetime Time stamp of when the TTP was created by its original source.
source_modified datetime Time stamp of when the TTP was last updated by its original
source.
tags list Tags assigned to the TTP.

tlp string Traffic Light Protocol designation for the TTP—red, amber,
green, white.

lower case.
Examples
1. To create a private TTP associated with an Indicator whose ID is 165546 and Signature whose
ID is 10:

Reference Guide
Threat Model
curl --request POST --data '{"name": "dummy test ttp", "tlp": "red", "tags":
["big ttp", "dummy tag"], "intelligence": [165546], "signatures": [10],
"publication_status": "published"}'
"https://api.threatstream.com/api/v1/ttp/" -H 'Authorization: apikey
2. To update an existing TTP whose ID is 1774:
curl --request PATCH --data '{"name": "another dummy test ttp", "tlp":
"orange"}' "https://api.threatstream.com/api/v1/ttp/1774/" -H
3. To get the detail of an existing TTP whose ID is 1774:
curl "https://api.threatstream.com/api/v1/ttp/1774/?skip_
associations=true&skip_intelligence=true" -H 'Authorization: apikey
4. To get the first 10 TTPs from ThreatStream:
curl "https://api.threatstream.com/api/v1/ttp/?limit=10&skip_
associations=true&skip_intelligence=true" -H 'Authorization: apikey
5. (Only on ThreatStream OnPrem) To get the detail of a remote TTP whose ID is 1775:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/ttp/1775/?remote_
6. (Only on ThreatStream OnPrem) To skip associations when retrieving details of a local TTP with
ID 234678:
curl "https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/ttp/234678/?skip_
Vulnerabilities
To create, update, or retrieve vulnerabilities from the ThreatStream platform.
Request
/api/v1/vulnerability/
Create a new vulnerability POST /api/v1/vulnerability/
Update the specified vulnerability PATCH /api/v1/vulnerability/{id}/

Reference Guide
Threat Model
Get the specified vulnerability GET /api/v1/vulnerability/{id}/
Get a list of vulnerabilities Anomali recommends to use the

/api/v1/threat_model_search endpoint to
retrieve the list of actors. See "Threat Model
Search" on page 89 for details.
For example,
type=vulnerability
Get a list of vulnerabilities associated with GET /api/v1/vulnerability/associated_

the specified indicator value or indicator ID with_intelligence/?value={value}
GET /api/v1/vulnerability/associated_
with_intelligence/?ids={comma_separated_
id_list}
For example,
GET /api/v1/vulnerability/associated_
with_intelligence/?value=google.com
returns all vulnerabilites that are associated with
google.com.
Get a list of a specified entity type (such as GET /api/v1/vulnerability/{id}/<entity_

threat bulletin, actor, campaign, and so on) type>/
that is associated with the specified
For example,
vulnerability
GET
/api/v1/vulnerability/234673/tipreport/
returns all threat bulletins associated with the
specified vulnerability.
Get a list of observables associated with the GET /api/v1/vulnerability/

specified vulnerability {id}/intelligence/
Response
Format: JSON
Notes

Reference Guide
Threat Model
Attributes
circles related All Trusted Circles to which the vulnerability belongs.

(see item
1 in
"Notes" on
the
previous
page)
created_ts datetime Time stamp of when the vulnerability was created on

For example, 2014-10-02T20:44:35.

description string Free-form text associated with the vulnerability (as specified in the
Description field in the UI).
is_public boolean Whether the vulnerability is public or private (including belonging

False—if the vulnerability is private or belongs to a Trusted Circle
True—if the vulnerability is public
Default: False
is_system boolean Whether the vulnerability was imported by ThreatStream.
True—if the vulnerability was imported by ThreatStream
False—if the vulnerability was added by a ThreatStream user


Reference Guide
Threat Model
modified_ts datetime Time stamp of when the vulnerability was last updated on
For example, 2014-10-02T20:44:35.

name string Name of the vulnerability.
Vulnerability name is associated with your organization.

Therefore, the name must be unique within your organization.
However, two vulnerabilities with the same name can exist on
ThreatStream as long as they belong to different organizations.
publication_ string A vulnerability can be in new, pending_review, review_requested,

Note: A vulnerability must be in published status for it to be


ThreatStream
OnPrem only)

associations are returned with GET requests for details of a Threat Model entity
(On
ThreatStream
OnPrem only)
setting the skip_associations parameter to true. This
For example,
GET /api/v1/vulnerability/{id}/?skip_
associations=true

are returned with GET requests for details of a Threat Model entity
(On

Reference Guide
Threat Model
ThreatStream on ThreatStream OnPrem. When a Threat Model entity has a

OnPrem only) large number of associations, association retrieval can take a long
setting the skip_intelligence parameter to true. This
For example,
GET /api/v1/vulnerability/{id}/?skip_
intelligence=true
source string Where the vulnerability was imported from.
source_created datetime Time stamp of when the vulnerability was created by its original
source.
source_modified datetime Time stamp of when the vulnerability was last updated by its
original source.
tags list Tags assigned to the vulnerability.

tlp string Traffic Light Protocol designation for the vulnerability—red,


lower case.
Examples
1. To create a private vulnerability:
curl --request POST --data '{"name": "dummy test vulnerability", "tlp":

"red", "tags": ["big vulnerability", "dummy tag"], "publication_status":
"published", "definition": "the definition of this vulnerability"}'
"https://api.threatstream.com/api/v1/vulnerability/" -H "Content-
2. To update an existing vulnerability whose ID is 15:
curl --request PATCH --data '{"name": "another dummy test vulnerability",

"tags": ["December"]}'
"https://api.threatstream.com/api/v1/vulnerability/15/" -H 'Authorization:
apikey <username>:<api_key>' -H "Content-Type:application/json"

Reference Guide
Threat Model
3. To get the details of an existing vulnerability whose ID is 15:
curl "https://api.threatstream.com/api/v1/vulnerability/15/" -H
4. To get the first 10 vulnerabilities from ThreatStream:
curl "https://api.threatstream.com/api/v1/vulnerability/?limit=10" -H
5. (Only on ThreatStream OnPrem) To get the details of a remote vulnerability whose ID is 16:
FQDN>/api/v1/vulnerability/16/?remote_api=true" -H 'Authorization: apikey

vulnerability with ID 12345:
FQDN>/api/v1/vulnerability/12345/?skip_associations=true" -H 'Authorization:
Managing Threat Model Associations

ThreatStream enables you to create bidirectional associations between Threat Model entities, which
are displayed in the Associations tab on Threat Model entity details pages.
You can use the information in this section to add and remove Threat Model entity associations
through the API.
Bulk Add
To create associations between Threat Model entities on the ThreatStream platform.
Request
/api/v1/<entity_type>/<entity_id>/<associated_entity_type>/bulk_add/
where <entity_type> is the type of Threat Model entity on which you are adding the association
(actor, attackpattern, campaign, courseofaction, identity, infrastructure,
intrusionset, incident, malware, signature, tipreport (Threat Bulletin), tool, ttp,
vulnerability)
<entity_id> is the ID of the Threat Model entity on which you are adding the association
<associated_entity_type> is the type of Threat Model entity with which you are associating the
initial entity (actor, attackpattern, campaign, courseofaction, identity, infrastructure,
vulnerability)
HTTP Method: POST

Reference Guide
Threat Model
Attribute
ids Unique IDs of the Threat Model entities or observables with which you are
associating the initial entity.
Example
To associate a threat bulletin whose ID is 744 with observables whose IDs are 54 and 67:
curl --request POST --data '{"ids":[54,67]}'

"https://api.threatstream.com/api/v1/tipreport/744/intelligence/bulk_add/" -H
'Authorization: apikey <username>:<api_key>' -H "Content-Type:application/json"
-v
Bulk Remove
To remove associations between Threat Model entities on the ThreatStream platform.
Request
/api/v1/<entity_type>/<entity_id>/<associated_entity_type>/bulk_remove/
where <entity_type> is the type of Threat Model entity on which you are adding the association
(actor, attackpattern, campaign, courseofaction, identity, infrastructure,
vulnerability)
<entity_id> is the ID of the Threat Model entity on which you are adding the association
<associated_entity_type> is the type of Threat Model entity with which you are associating the
initial entity (actor, attackpattern, campaign, courseofaction, identity, infrastructure,
vulnerability)
HTTP Method: POST
Attribute
ids Unique IDs of the Threat Model entities or observables with which you are
associating the initial entity.
Example
To remove an association between a TTP whose ID is 67 with a signature whose ID is 123:
curl --request POST --data '{"ids":[123]}'

"https://api.threatstream.com/api/v1/ttp/67/signature/bulk_remove/" -H "Content-
Type:application/json" -H 'Authorization: apikey <username>:<api_key>' -v

Threat Model Entity and Observable Tags
ThreatStream enables you to add tags to intelligence for purposes of filtering for related entities.
Tags can be made visible to your organization only or to all ThreatStream users with access to the
data. You can add tags to observables and threat model entities.
Additionally, you can manage observable and threat model entity tags in bulk. See "Observable Tags
in Bulk" on the next page and "Threat Model Entity Tags in Bulk" on page 162 for more information.
Request
/api/v1/<entity_type>/<entity_id>/tag/
where <entity_type> is the type of threat model entity on which you are adding the tag (actor,
attackpattern, campaign, incident, intelligence (observables), malware, signature,
tipreport, ttp, or vulnerability)
<entity_id> is the ID of the threat model entity or tag on which you are adding the association
HTTP Method: POST
Attributes
ids Unique IDs of the threat model entities or observables to which you are adding tags.
tags Tags applied to the specified threat model entities or observables.
Tag Attributes:
n white—public, or visible to all ThreatStream users with access to the data.
Default: white
Note: Adding public tags may be restricted by your Org Admin.
In the example above, my_tag is private and my_tag2 and my_tag3 are public.

Reference Guide
Examples
1. To add a private tag to an observable whose ID is 4744:
curl --request POST --data '{"tags": [{"name": "test", "tlp": "red"}]}'

"https://api.threatstream.com/api/v2/intelligence/4744/tag/" -H "Content-
2. To add a public tag and a private tag to an actor whose ID is 35:
curl --request POST --data '{"tags": [{"name": "january_attack", "tlp":

"white"},{"name": "PHI", "tlp": "red"}]}'
"https://api.threatstream.com/api/v1/actor/35/tag/" -H "Content-
Observable Tags in Bulk

ThreatStream enables you to add and remove observable tags in bulk. You can use the information
in this section to manage tags associated with sets of observables through the API.
Adding Observable Tags in Bulk

Request
/api/v2/intelligence/bulk_tagging/

HTTP Method: POST
Attributes
ids Unique IDs of the observables to which you are adding tags.
tags Tags that will be applied to the specified observables.
Tag Attributes:

Reference Guide
Default: white
By default, you can manage up to 250 tags in bulk. If you need to manage up more
than 250 tags in bulk, see "Managing up to 10,000 Tags in Bulk" on the next page for
more information.
Example
To add a private tag to a set of observables whose IDs are 61, 52, 8, 50, 34:
curl --X POST --data '{"tags": [{"name": "test", "tlp": "red"}], "ids":[61, 52,
8, 50, 34]}' "https://api.threatstream.com/api/v2/intelligence/bulk_tagging/" --
H "Content-Type:application/json" -H 'Authorization: apikey <username>:<api_
key>'
Removing Observable Tags in Bulk

Request
/api/v2/intelligence/bulk_remove_tags/

HTTP Method: PATCH
Attributes
ids Unique IDs of the observables from which you are removing tags.
tags Tags that will be removed from the specified observables.
Tag Attributes:

Reference Guide
Default: white
By default, you can manage up to 250 tags in bulk. If you need to manage up more
than 250 tags in bulk, see "Managing up to 10,000 Tags in Bulk" below for more
information.
Example
To remove two tags from a set of observables whose IDs are 776 and 349:
curl --X PATCH --data '{"tags": [{"name": ["test", "tagB"]}], "ids":[776, 349]}'
"https://api.threatstream.com/api/v2/intelligence/bulk_remove_tags/" -H
'Authorization: apikey <username>:<api_key>' -H "Content-Type:application/json"
Managing up to 10,000 Tags in Bulk

By default, you can add and delete up to 250 tags in bulk. If you need to manage up to 10,000 tags,
you can do so by specifying a dataset to which tags will be applied or from which tags will be
removed.
When you add or remove up to 10,000 tags in bulk, a job is created. Once the job is completed
successfully, you must get the results of the job to finish the procedure. You can create one job at a
time. Otherwise, making this API call will result in an error.
Request
1. /api/v2/intelligence/bulk_tagging/?async_result=true
HTTP Method: POST
This request requires that you specify payload in JSON format. Payload consists of the query
object that creates a dataset, and the list of tags to be added and/or removed from observables
in the dataset.
2. /api/v1/generic_async_result/<id>/
HTTP Method: GET

Reference Guide
Payload Parameters
Parameter Type Description
query object Payload object that specifies the dataset and has the
following parameters: q, limit, and order_by. The
parameters are described in this table below.
For example, query: {q: "(status = "active") and

(created_ts >= 2022-10~01T23:00:00)", limit:
10000, order_by: "-created_ts"}
q string Parameter in the query object that filters out the observables
to which tags will be added or from which the tags will be
removed.
For example, q: "(status = "active") and (created_

ts >= 2022-10~01T23:00:00)" will create a dataset of
active observables created at the specified time.
limit integer Parameter in the query object, maximum number of

observables to which tags will be added or from which tags
will be removed.
For example, limit: 10000
You can manage up to 10,000 observables in bulk.
order_by string Parameter in the query object, an observable attribute by

which the observables in the dataset will be ordered.
For example, order_by: "-created_ts"
tags array of strings Tags that will be added to the selected observables.
For example, tags: [{name: "my_tag", tlp: "red"}]
remove_tags array of strings Tags that will be removed from the selected observables.
For example, remove_tags: [{name: "my_tag2", tlp:

"red"}]
Example
1. To add a private my_tag to and remove a private my_tag2 from the active observables created
on a specific date and ordered by date of creation:
curl --X POST "https://api.threatstream.com/api/v2/intelligence/bulk_

tagging/?async_result=true" --H "Content-Type:application/json" -H

Reference Guide
query: {q: "(status = "active") and (created_ts >= 2022-10~01T23:00:00)", limit:

10000, order_by: "-created_ts"}
remove_tags: [{name: "my_tag2", tip: "red"}]
tags: [{name: "my_tag", tlp: "red"}]
Results are returned similar to the following:
created_ts: "2022-11-01T21:10:56.008462"
id: <id>
modified_ts: "2022-11-01T21:10:56.008475"
path: "/api/v2/intelligence/bulk_tagging/"
resource_uri: "/api/vl/generic_async_result/<id>/"
response_status: null
status: "inprogress"
where <id> is the unique ID of the job. You will use this value to check the status of the job and
return the results after its completion.
2. To check the status of the job using the command listed for resource_uri:
curl --X GET "https://api.threatstream.com/api/v1/generic_async_

result/<id>/" --H "Content-Type:application/json" -H 'Authorization: apikey
where <id> is the unique ID of the job.
created_ts: "2022-11-01T21:10:56.008462"
id: <id>
modified_ts: "2022-11-01T21:10:56.008475"
path: "/api/v2/intelligence/bulk_tagging/"
resource_uri: "/api/vl/generic_async_result/<id>/"
Repeat this call until you see the following values:
response_status: 200
status: "done"
This indicates that the job is complete and ready to return the results.
3. Return the results of the completed job:
curl "https://api.threatstream.com/api/v1/generic_async_result/<id>/get_
result/" -H 'Authorization: apikey <username>:<api_key>'

Reference Guide
Threat Model Entity Tags in Bulk

ThreatStream enables you to manage tags of Threat Model entities in bulk. You can use the
information in this section to add and delete tags associated with sets of the following entities: Actors,
Attack Patterns, Campaigns, Incidents, Malware, Signatures, Threat Bulletins, TTPs, and
Vulnerabilities.
Request
/api/v1/<entity_type>/bulk_tagging/
where <entity_type> is the type of threat model entity on which you are adding the tag (actor,
attackpattern, campaign, incident, malware, signature, tipreport, ttp, or vulnerability.)
HTTP Method: POST
Attributes
ids Unique IDs of the Threat Model entities to which you are adding tags.
remove_ Tags must be specified as follows:

tags
remove_tags=[{“name”:"my_tag"},{"name":"my_tag2"},{"name":"my_
tag3"}]
By default, you can delete up to 25 tags in bulk from a threat model entity.
tags Tags that will be applied to the specified Threat Model entities.
Tag Attributes:
Default: white
By default, you can add up to 25 tags in bulk to a threat model entity.

Reference Guide
Example
To add tags private_tag1, private_tag2, and public_tag to a set of actors whose IDs are 655,
2784, 2785 and to remove tag4 from these actors:
curl -XPOST 'https://api.threatstream.com/api/v1/actor/bulk_tagging/' -d '

{"ids": [655, 2784, 2785], "tags": [{"name":"private_tag1", "tlp":"red"},
{"name":"public_tag", "tlp":"white"}, {"name":"private_tag3", "tlp":"red"}],
"remove_tags": [{"name":"tag4"}]}' -H 'content-type: application/json' -H
'Authorization:apikey <username>:<apikey>'

User Administration
To add, edit, or delete users in your organization on ThreatStream.
Request
/api/v1/orgadmin/
Create a new user POST /api/v1/orgadmin/
Get a list of users GET /api/v1/orgadmin/
Get a specifc user GET /api/v1/orgadmin/<user_id>
Modify an existing user PATCH /api/v1/orgadmin/<user_id>
Unlock the account of an existing user PATCH /api/v1/orgadmin/<user_id>/unlock
Delete a user DELETE /api/v1/orgadmin/<user_id>
Attributes
can_approve_ boolean Whether the user can approve imported intelligence.

intel
can_import_ boolean Whether the user can push data from TAXII clients to your
to_taxii_inbox ThreatStream TAXII server.
can_see_api_ boolean Whether the user can access their dedicated ThreatStream API key
key on the My Profile tab within ThreatStream settings.
can_share_ boolean Whether the user can create intelligence shared with the Anomali
intelligence Community. This includes importing observables, creating Sandbox
Reports, as well as modifying tags and commenting on observables
and Sandbox Reports shared with the Anomali Community.
can_use_chat boolean Whether the user can use ThreatStream Chat.
Note: To grant users this privilege, ThreatStream Chat must be

enabled for your organization from the Organization within
settings.
email string Email address of the user you want to add to your organization.
is_org_admin boolean Whether the user is an Org Admin.

Reference Guide
User Administration
is_readonly boolean Whether the user should be restricted to Read Only status.
Note: You cannot set is_readonly to true when any of the

following attributes are also set to true: can_share_intelligence,
can_import_to_taxii_inbox, can_approve_intel, or is_org_
admin.
is_tfa_exempt boolean Whether the user is excluded from having to use multi-factor
authentication.
must_ boolean Force existing users to change their password the next time they
change_ login.
password
user_id string ID of the user you want to edit or delete.
Execute a GET request to retrieve IDs of users in your organization.
Response
The response contains all request attributes (except must_change_password) in addition to the
following attributes.
avatar_s3_url URL for the avatar image associated with the user.
date_joined Timestamp when the user was added to ThreatStream.
date_password_ Timestamp when the user last changed their password.

changed
is_active Whether the user is active.
is_locked Whether the user is currently locked.
last_access_ts Timestamp when the user last accessed ThreatStream.
last_login Timestamp when the user was last authenticated to ThreatStream.
must_change_ Whether the user will be forced to change their password the next time they
password login.
name Name entered by the user on the My Profile tab within ThreatStream
Settings.
next_password_ Future timestamp when the user will be forced to change their password.
change_ts
nickname Nickname entered by the user on the Profile screen, accessible through the
ThreatStream menu.

Reference Guide
User Administration
resource_uri Resource URI of the user.
user_id ID of the user.
Examples
Note: The user whose username and API key is used in requests must have Org Admin
privileges.
1. To get a list of users in your organization:
curl 'https://api.threatstream.com/api/v1/orgadmin/' -H 'Authorization:

2. To create a non-Read Only user with all available privileges:
curl --request POST --data '{"email": "newuser@company.com","is_org_admin":

true,"can_approve_intel": true,"can_share_intelligence": true,"can_see_api_
key": true,"can_import_to_taxii_inbox": true}'
"https://api.threatstream.com/api/v1/orgadmin/" -H 'Authorization: apikey
3. To give Org Admin privileges to an existing user whose ID is 145:
curl --request PATCH --data '{"is_org_admin": true}'

"https://api.threatstream.com/api/v1/orgadmin/145/" -H 'Authorization:
4. To give Read Only privileges to an existing user whose ID is 123:
curl --request PATCH --data '{"is_readonly": true}'

If the user had any of the following privileges, they are automatically removed: can_share_
intelligence, can_import_to_taxii_inbox, can_approve_intel, or is_org_admin.
5. To delete a user whose ID is 348:
curl --request DELETE "https://api.threatstream.com/api/v1/orgadmin/348/" -H

'Authorization: apikey <username>:<api_key>’ -v
6. To force a user whose ID is 145 to change their password:
curl --request PATCH --data '{"must_change_password": true}'


Reference Guide
User Administration
7. To unlock a user whose account has been locked due to successive failed login attempts and
whose ID is 123:
curl --request PATCH

"https://api.threatstream.com/api/v1/orgadmin/123/unlock/" -H
'Authorization: apikey <username>:<api_key>' -v

User Audit
To generate activity reports in CSV or JSON format for users in your organization. Reports include
login history, Threat Model, investigation, and import activity.
There are two types of user activity reports: UI activity reports (including actions taken from the
ThreatStream user interface) and API activity reports (including API requests made by users).
Returning user activity reports is a three part process. It involves generating a user activity report,
checking the status of the report, and returning the report after completion. See "Examples" on the
next page for more information on this multi-step process.
Request
Generate a user UI activity report GET /api/v1/useraction/
Generate a user API activity report GET /api/v1/apiuseraction/
Check the status of the report GET /api/v1/generic_async_result/<id>/
Return results of the report. GET /generic_async_result/<id>/get_result/
Attributes
async_ Boolean Whether results are fetched asynchronously.

result
Anomali recommends setting async_result to true when returning
results for more than five users or a week of data.
created_ Date Beginning of the time range for which you want to generate the report.
ts__gte
where T denotes the start of the value for time, in UTC time.
For example, 2014-10-02T20:44:35
created_ Date End of the time range for which you want to generate the report
ts__lte
where T denotes the start of the value for time, in UTC time.
For example, 2014-10-02T20:44:35

Reference Guide
User Audit
format String File format of the generated report.
Specify csv or json
limit Numeric Maximum number of records included in report.
Default: 20
user_id__ Numeric IDs of the users which you want to include in the report.
in
If you do not specify a user ID, results are returned for all organization
users.
Response
Format: CSV, JSON
Examples
Request:
1. To generate a user UI activity report for a single user, whose user ID is 56:
a. curl "https://optic.threatstream.com/api/v1/useraction/?async_
result=true&created_ts__gte=2019-10-09T00:00:00.000Z&created_ts__
lte=2019-10-10T23:59:59.999Z&format=csv&limit=1000&order_by=-created_
ts&user_id__in=56" -H 'Authorization: apikey <username>:<api_key>'
created_ts: "2020-08-07T21:05:11.501490",
id: <id>,
modified_ts: "2020-08-07T21:05:11.501505",
path: "/api/v1/useraction/",
resource_uri: "/api/v1/generic_async_result/<id>/",
response_status: null,
where <id> is the unique ID of the export. You will use this value to check the status of the
export job and return the results after completion.
b. To check the status of the export using the command listed for resource_uri:
curl "https://optic.threatstream.com/api/v1/generic_async_result/<id>/"
where <id> is the unique ID of the export.

Reference Guide
User Audit
Results are returned similar to the following when the export job is in progress:
created_ts: "2020-08-07T22:31:21.358172"
id: <id>
modified_ts: "2020-08-07T22:31:21.597286"
path: "/api/v1/useraction/"
resource_uri: "/api/v1/generic_async_result/<id>/"
status: "done"
This indicates that the export job is complete and ready to return.
c. Return the completed export job:
curl "https://optic.threatstream.com/api/v1/generic_async_
result/<id>/get_result/" -H 'Authorization: apikey <username>:<api_key>'
2. To generate a user API activity report for a single user, whose user ID is 56:
a. curl "https://optic.threatstream.com/api/v1/apiuseraction/?async_
ts&user_id__in=56" -H 'Authorization: apikey <username>:<api_key>'
created_ts: "2020-08-07T21:05:11.501490",
id: <id>,
modified_ts: "2020-08-07T21:05:11.501505",
path: "/api/v1/apiuseraction/",
b. Check the status of the export using the command listed for resource_uri:

Reference Guide
User Audit
created_ts: "2020-08-07T22:31:21.358172"
id: <id>
modified_ts: "2020-08-07T22:31:21.597286"
path: "/api/v1/apiuseraction/"
status: "done"
3. To generate an activity report that includes all organization users:
a. curl "https://optic.threatstream.com/api/v1/useraction/?async_
ts" -H 'Authorization: apikey <username>:<api_key>'
created_ts: "2020-08-07T21:05:11.501490",
id: <id>,
modified_ts: "2020-08-07T21:05:11.501505",
path: "/api/v1/apiuseraction/",
b. Check the status of the export using the command listed for resource_uri:

Reference Guide
User Audit
created_ts: "2020-08-07T22:31:21.358172"
id: <id>
modified_ts: "2020-08-07T22:31:21.597286"
path: "/api/v1/useraction/"
status: "done"

Whitelist
To create, modify, delete, or retrieve import whitelist entries from the ThreatStream platform.
Request
/api/v1/orgwhitelist/
HTTP Methods:
Create a new whitelist entry POST /api/v1/orgwhitelist/
Get a list of whitelist entries GET /api/v1/orgwhitelist/
Modify contextual notes associated with existing whitelist PATCH

entries /api/v1/orgwhitelist/
Delete a whitelist entry DELETE

/api/v1/orgwhitelist/
Request Attributes
Attribute Definition
file Path to the CSV file containing the whitelist entries you want to add.
format Format of whitelist exports.
Specify csv or json
limit The limit variable controls the number of results returned every time an API call is
made; the total number of results may be much larger than returned in one API call.
If limit is not specified, 10 results are returned with each API call. Specifying
limit=0 will return up to a maximum of 1000 results (if available).
remove_ Whether you want to replace existing whitelist entries with the entries specified in
existing the request.
true—remove existing whitelist entries and replace with specified entries.
false—do not remove existing whitelist entries.
Default: false

Reference Guide
Whitelist
showNote Whether contextual notes are included in the response.
true—notes are included.
false—notes are not included.
Default: true
whitelist Whitelist entries can be specified in a list, as in the following example:
{"whitelist": [{value_type: "domain", value: "example.com", notes:

"example domain"}]}
Whitelist Attributes
l value_type—cidr, domain, email, ip, md5 url, user-agent
l value—value of the entry you want to add
l notes—contextual note associated with the entry
You can also specify whitelist entries in a CSV file.
The CSV file must adhere to the following requirements:
l The entries must be contained in a valid CSV file with the following header line:
value_type,value,notes.
l value_type must be specified for each entry. Possible types include domain,
email, ip, md5, url, user-agent, and cidr.
l value must be specified for each entry. Values must be valid entries based on
the specified type. For example, if you specify ip for type, the corresponding
value must be a valid IP address.
l notes is optional for each entry.
l All text in the CSV file must be lower-cased.
The following is an example of a valid CSV file:
value_type,value,notes
domain,*wildcard-example.com,this is a valid domain
email,account@example.com,example note
ip,1.2.3.4,
md5,fe01ce2a7fbac8fafaed7c982a04e229,
url,http://example.com,
user-agent,myagent1,
cidr,192.0.2.0/24,

Reference Guide
Whitelist
Response
Format: JSON
Response Attributes
created_ts Timestamp of when the entry was created.
id Unique ID associated with the whitelist entry.
modified_ts Timestamp of when the entry was most recently modified.
notes Contextual note associated with the entry
value Value of the entry.
value_type Type of entry—cidr, domain, email, ip, md5 url, user-agent
Examples
1. To return a list of your 10 most recently added whitelist entries:
curl -X GET 'https://api.threatstream.com/api/v1/orgwhitelist/?format=json'

-H "Content-Type:application/json" -H 'Authorization: apikey
2. To add an entry to your import whitelist:
curl -X POST 'https://api.threatstream.com/api/v1/orgwhitelist/bulk/' -d '

{"whitelist":[{"value_type": "domain", "value": "example44.org", "notes":
"example domain"}]}' -H "Content-Type:application/json" -H 'Authorization:
3. To add entries to your import whitelist from a CSV file:
curl -X POST
'https://api.threatstream.com/api/v1/orgwhitelist/upload/?remove_
existing=false' -F "file=@whitelist.csv" -H 'Authorization: apikey
where the whitelist.csv file contains the following data:
value_type,value,notes
domain,*foo.wildcarddomain.com,some notes on foo
domain,*wildcarddomain.com,
email,test@email.com,
ip,8.8.8.8,notes on ip address

Reference Guide
Whitelist
md5,fe01ce2a7fbac8fafaed7c982a04e229,this is a test md5 hash

url,http://gooddomain.com/,
4. To replace your existing import whitelist with entries from a CSV file:
curl -X POST
'https://api.threatstream.com/api/v1/orgwhitelist/upload/?remove_
existing=true' -F "file=@whitelist.csv" -H 'Authorization: apikey
5. To export your import whitelist in CSV format:
curl -X GET
'https://api.threatstream.com/api/v1/orgwhitelist/?showNote=True&format=csv'
-H "Content-Type:application/json" -H 'Authorization: apikey
6. To export your import whitelist in JSON format:
curl -X GET
'https://api.threatstream.com/api/v1/orgwhitelist/?showNote=True&format=jso
n' -H "Content-Type:application/json" -H 'Authorization: apikey
7. To remove an entry from your import whitelist:
curl -X DELETE 'https://api.threatstream.com/api/v1/orgwhitelist/<Entry_

ID>/' -H 'Authorization: apikey <username>:<api_key>'
where <Entry_ID> is the ID associated with the whitelist entry you want to delete. To determine
the entry ID, execute return a list of your current whitelist entries and note the ID value
associated with the entry of interest.
8. To edit the note associated with an import whitelist entry:
curl -X PATCH 'https://api.threatstream.com/api/v1/orgwhitelist/<Entry_ID>/'

-d '{"notes":"updated note text"}' -H "Content-Type:application/json" -H
where <Entry_ID> is the ID associated with the whitelist entry you want to modify. To determine
the entry ID, return a list of your current whitelist entries and note the ID value associated with
the entry of interest.

Appendix A: Intelligence Fields in
ThreatStream API
This section lists the intelligence fields available in ThreatStream that can be used for filtering and
advanced searching.
Field Name Type Description
asn String The Autonomous System Number (ASN) for the

IP associated with the observable.
classification String Indicates the confidentiality level of an observable.
Possible values: private, public
Notes:
- Private also includes Trusted Circles.
- classification is displayed as Visibility on the
ThreatStream user interface.
confidence Numeric Risk score from 0 to 100, assigned by ThreatStream's

predictive analytics technology to observables.
country String Two-letter ISO country code for the IP associated with the
observable. For example, US, CN, DE, and so on.
created_by String Email address of the user who submitted the import job
containing the observable.
created_ts Date UTC time stamp of when the observable was first created
in ThreatStream.
Date can be specified as follows:
l In this format: YYYY-MM-DDThh:mm:ss, where T

denotes the start of the value for time. For example,
2014-10-02T20:44:35.
l As a relative time unit, in this format: -<n><unit>, where

n is a whole number and unit is w, d, h, m, s (for week,
days, hour, minutes, and seconds, respectively). For
example, -2w denotes two weeks, starting NOW.
detail String Additional comments and context associated with the

observable.

Reference Guide
Appendix A: Intelligence Fields in ThreatStream API
feed_group String Name of the group or industry associated with the

observable. For example, healthcare, government,
financial.
Possible values: behavioral, education, financial,

government, energy, healthcare, spam, hitech, retail.
file_name String File name associated with the observable.
file_size String Size of the file associated with the observable.
file_type String File type associated with the observable.
import_session_id Numeric ID of the import session that created the observable on

ThreatStream.
import_source String Original source of the observable. Values are only

displayed for observables manually imported through the
ThreatStream user interface by your organization. Import
source for observables owned by other organizations is not
visible.
ip String IP associated with the observable.
is_osint Boolean Whether the observable is from an open source

intelligence feed.
itype String Indicator type. For example, c2_ip, compromised_email,

apt_md5, and so on.
See "Indicator Types" on page 1 for a complete list.
lat Numeric Latitude associated with the Geo location of the IP.
lon Numeric Longitude associated with the Geo location of the IP.
maltype String Information regarding a malware family, a CVE ID, or

another attack or threat, associated with the observable.
modified_ts Date UTC time stamp of when the observable was last updated
in ThreatStream.
Date can be specified as follows:
l In this format: YYYY-MM-DDThh:mm:ss, where T

denotes the start of the value for time. For example,
modified_ts > 2014-10-02T20:44:35.
l As a relative time unit, in this format: -<n><unit>, where

n is a whole number and unit is w, d, h, m, s (for week,
days, hour, minutes, and seconds, respectively). For
example, -2w denotes two weeks, starting NOW. The

Reference Guide
following example shows how you will use this field in a

filter: modified_ts > -14d.
org String Name of the business that owns the IP address associated
with the observable. For example, Comcast, Amazon, and
so on.
owner_id Numeric ID of the organization (in ThreatStream) that imported the

observable.
rdns String Domain name (obtained through reverse domain name

lookup) associated with the IP address that is associated
with the observable.
registrant_email String Email address of the person who registered the domain.
This information is obtained from WHOIS.
registrant_name String Name of the person who registered the domain.
registrant_org String Name of the organization that registered the domain.
registrant_phone String Phone number associated with the domain registration.
registrant_address String Street address associated with the domain registration.
registration_ Date Time stamp of when the domain was registered.

created_ts
registration_ Date Time stamp of when the domain registration was last
modified_ts updated.
severity String Criticality associated with the threat feed that supplied the
observable.
source_created Date UTC time stamp of when the entity was created by its
original source.
Date can be specified as follows: YYYY-MM-

DDThh:mm:ss, where T denotes the start of the value for
time. For example, 2014-10-02T20:44:35. T must be
capitalized.
source_modified Date UTC time stamp of when the entity was created by its
original source.
Date can be specified as follows: YYYY-MM-

DDThh:mm:ss, where T denotes the start of the value for
time. For example, 2014-10-02T20:44:35. T must be
capitalized.

Reference Guide
source_reported_ Numeric A risk score from 0 to 100, provided by the source of the
confidence observable.
stream_id Numeric ID of the threat feed that created the observable on

ThreatStream.
status String Current state of the observable in ThreatStream.
Possible values: active, inactive, falsepos
subtype String For hash observables—those with type=md5—subtype

provides additional metadata on the type of hash
associated with the observable.
Possible values: MD5, SHA1, SHA256, SHA512
tags String Additional comments and context associated with the

observable when it was imported from its original threat
feed.
Note: Because this field can contain multiple values, when

specifying this field in a filter, make sure you either specify
all of those values, separated by commas, in the order they
appear in the ThreatStream UI, or use the startswith
operator to specify the beginning of a value you are looking
for. For example, to look for "phish-target,victim-hi-tech",
specify detail ="phish-target,victim-hi-tech", or detail
startswith phish, or detail startswith victim.
threat_type String Summarized threat type of the observable. For example,

malware, compromised, apt, c2, and so on.
tlp String Traffic Light Protocol designation for the observable—red,

trusted_circle_id String ID of the trusted circle with which the observable is shared.
type String Data type of the observable.
Possible values: ip, domain, url, email, md5
value String Specifies the value of an observable, whose type is

specified by the "type" field.

Appendix B: Indicator Types in
ThreatStream API
The following table lists all available indicator types in ThreatStream.
The severity values listed in the table below represent the default severity values that Anomali
assigns to observables of a given indicator types. However, default values are not displayed in the
following cases:
1. When severity value assigned to observable by the source are used
2. When users modify the assigned value while editing observables that belong to their
organizations on ThreatStream
Notes:
- Observables assigned indicator types which display String in the Type column below are not
consumed by downstream integrations such as Anomali Match or those which receive
intelligence through ThreatStream Integrator. Additionally, string-type observables cannot be
cloned in ThreatStream.
- MD5 observables ingested from feeds are never made inactive by ThreatStream API.
However, MD5 observables imported through other means, such as the import assistant, adhere
to the expiration dates you set.
Indicator Type Name Type Severity Description
actor_ip Actor IP IP Low IP address associated with a

system involved in malicious
activity.
Example: itype="actor_ip"
actor_ipv6 Actor IPv6 IP Low IPv6 address associated with a

system involved in malicious
activity.
Example: itype="actor_ipv6"
actor_subject Actor Subject String High Subject from an email associated

Line with a threat actor.
Example: itype="actor_subject"

Reference Guide
Appendix B: Indicator Types in ThreatStream API
adware_domain Adware Domain Domain Low Domain name associated with

adware or other Potentially
Unwanted Applications (PUA).
Example: itype="adware_
domain"
adware_ Adware Registry String Low Registry key associated with

registry_key Key adware or other Potentially
Unwanted Applications (PUA).
Example: itype="adware_
registry_key"
anon_proxy Anonymous IP Low IP address of the system on

Proxy IP which anonymous proxy software
is hosted.
Example: itype="anon_proxy"
anon_proxy_ Anonymous IP Low IPv6 address of the system on

ipv6 Proxy IPv6 which anonymous proxy software
is hosted.
Example: itype="anon_proxy_
ipv6"
anon_vpn Anonymous IP Low IP address associated with

VPN IP commercial or free Virtual Private
Networks (VPN).
Example: itype="anon_vpn"
anon_vpn_ipv6 Anonymous IP Low IPv6 address associated with

commercial or free Virtual Private
Networks (VPN).
Example: itype:"anon_vpn_ipv6"
apt_domain APT Domain Domain Very-High Domain name associated with a

known Advanced Persistent
Threat (APT) actor used for
command and control, launching
exploits, or data exfiltration.
Example: itype=" apt_domain"

Reference Guide
apt_email APT Email Email High Email address used by a known

Advanced Persistent Threat
(APT) actor for sending targeted,
spear phishing emails.
Example: itype="apt_email"
apt_email_ APT Email String High Subject from an email associated

subject_line Subject Line with an Advanced Persistent
Threat (APT) actor.
Example: itype="apt_email_
subject_line"
apt_file_name APT File Name String Very-High Name of a file used by a known
(APT) actor.
Example: itype="apt_file_name"
apt_file_path APT File Path String Very-High File path used by a known

(APT) actor.
Example: itype="apt_file_path"
apt_ip APT IP IP Very-High IP address associated with

Threat (APT) actor for command
and control, data exfiltration, or
targeted exploitation.
Example: itype="apt_ip"
apt_ipv6 APT IPv6 IP Very-High IPv6 address associated with

Threat (APT) actor for command
and control, data exfiltration, or
targeted exploitation.
Example: itype="apt_ipv6"
apt_md5 APT File Hash Hash Very-High MD5 or SHA hash of a malware
sample used by a known
(APT) actor.
Example: itype="apt_md5"

Reference Guide
apt_mta APT Mail String Very-High Mail transfer agent used by a

Transfer Agent known Advanced Persistent
Threat (APT) actor.
Example: itype="apt_mta"
apt_mutex APT Mutex String Very-High Mutex used by a known

(APT) actor.
Example: itype="apt_mutex"
apt_registry_key APT Registry String Very-High Registry key used by a known

Key Advanced Persistent Threat
(APT) actor.
Example: itype="apt_registry_
key"
apt_service_ APT Service String Very-High Description used by a known

description Description Advanced Persistent Threat
(APT) actor.
Example: itype="apt_service_
description"
apt_service_ APT Service String Very-High Service display name used by a

displayname Display Name known Advanced Persistent
Threat (APT) actor.
displayname"
apt_service_ APT Service String Very-High Service name used by a known

name Name Advanced Persistent Threat
(APT) actor.
name"
apt_ssdeep APT SSDeep String Very-High SSDeep Hash used by a known

Hash Advanced Persistent Threat
(APT) actor.
Example: itype="apt_ssdeep"
apt_subject APT Subject Line String High Email subject line used by a
Threat (APT) actor.
Example: itype="apt_subject"

Reference Guide
apt_ua APT User Agent String High User agent string used by a
Threat (APT) actor.
Example: itype="apt_ua"
apt_url APT URL URL Very-High URL used by a known Advanced

Persistent Threat (APT) actor for
command and control, launching
web based exploits, or data
exfiltration.
Example: itype=" apt_url"
bot_domain Infected Bot Domain Low Domain name of an infected

Domain Name machine acting as an
autonomous bot.
Example: itype="bot_domain"
bot_ip Infected Bot IP IP Low IP address of an infected

machine acting as an
autonomous bot.
Example: itype="bot_ip"
bot_ipv6 Infected Bot IPv6 IP Low IPv6 address of an infected

machine acting as an
autonomous bot.
Example: itype="bot_ipv6"
bot_md5 Infected Bot Hash Low Hash related to a file used by an

Hash infected machine acting as an
autonomous bot.
Example: itype="bot_md5"
bot_url Infected Bot URL URL Low URL of an infected machine

acting as an autonomous bot.
Example: itype="bot_url"
browser_ Browser String High Unique ID given to each browser

extension_id Extension ID extension, which is available in
the Extension store of such
browsers as Firefox, Chrome,
and so on.
Example: itype="browser_
extension_id"

Reference Guide
brute_ip Brute Force IP IP Low IP address associated with

password brute force activity.
Example: itype="brute_ip"
brute_ipv6 Brute Force IPv6 IP Low IPv6 address associated with

password brute force activity.
Example: itype="brute_ipv6"
c2_domain Malware C&C Domain High Domain name used by malware

Domain Name for command and control
communication.
Example: itype="c2_domain"
c2_ip Malware C&C IP IP High IP address used by malware for

Address command and control
communication.
Example: itype="c2_ip"
c2_ipv6 Malware C&C IP High IPv6 address used by malware

IPv6 Address for command and control
communication.
Example: itype="c2_ipv6"
c2_url Malware C&C URL High URL used by malware for

URL command and control
communication.
Example: itype="c2_url"
comm_proxy_ Commercial Domain Low Domain of the system on which

domain Webproxy commercial proxy software is
Domain hosted.
Example: itype="comm_proxy_
domain"
comm_proxy_ip Commercial IP Low IP address of the system on

Webproxy IP which commercial proxy software
is hosted.
Example: itype="comm_proxy_
ip"

Reference Guide
compromised_ Compromised Domain Low Domain name of website or

domain Domain server that has been
compromised.
Example: itype="compromised_
domain"
compromised_ Compromised Email Low Email address that has been

email Account Email compromised and/or taken over
by a threat actor.
email"
compromised_ Compromised String Low Email subject from a known

email_subject Email Subject compromised email address.
email_subject"
compromised_ip Compromised IP IP Low IP address of website or server

that has been compromised.
ip"
compromised_ Compromised IP Low IPv6 address of website or server

ipv6 IPv6 that has been compromised.
ipv6"
compromised_ Compromised String Low Account information associated

serv_account Service Account with a service account that has
been compromised and/or taken
over by a threat actor.
serv_account"
compromised_ Compromised URL Medium URL of the website or server that

url URL has been compromised.
url"

Reference Guide
compromised_ Compromised String Medium Username that has been

username Username compromised and/or taken over
by a threat actor. Must have a
length of 128 characters or less.
username"
crypto_hash Cryptocurrency Hash High File hash for cryptocurrency

Mining Software mining software.
Example: itype="crypto_hash"
crypto_ip Cryptocurrency IP High IP address associated with

IP cryptocurrency mining software.
Example: itype="crypto_ip"
crypto_pool Cryptocurrency Domain High Domain for cryptocurrency pool.

Pool Domain
Example: itype="crypto_pool"
crypto_url Cryptocurrency URL High URL where cryptocurrency

URL mining software is hosted.
Example: itype="crypto_url"
crypto_wallet Cryptocurrency String Very-High Public or private cryptocurrency

Wallet Address wallet key.
Example: itype="crypto_wallet"
ddos_ip DDOS IP IP Low IP address associated with

Distributed Denial of Service
(DDoS) attacks.
Example: itype="ddos_ip"
ddos_ipv6 DDOS IPv6 IP Low IPv6 address associated with

Distributed Denial of Service
(DDoS) attacks.
Example: itype="ddos_ipv6"
disposable_ Disposable Email Domain Low Domain associated with

email_domain Domain disposable email activity.
Example: itype="disposable_
email_domain"

Reference Guide
downloader_ Downloader Domain Domain associated with a

domain Domain downloader, which is a type of
malware that downloads and runs
other malware.
Example: itype="downloader_
domain"
downloader_ Downloader File Hash High Hash of a malicious file

hash Hash associated with a downloader,
which is a type of malware that
downloads and runs other
malware.
hash"
downloader_ip Downloader IP IP High IP address associated with a

downloader, which is a type of
other malware.
Example: itype="downloader_ip"
downloader_ Downloader IPv6 IP High IPv6 address associated with a

ipv6 downloader, which is a type of
other malware.
ipv6"
downloader_url Downloader URL URL High URL associated with a

downloader, which is a type of
other malware.
Example: itype="downloader_url"
dyn_dns Dynamic DNS Domain Low Domain name used for hosting
Dynamic DNS services.
Example: itype="dyn_dns"
email_ Email String Low Email subject from a known

attachment_ Attachment compromised email attachment.
subject Subject
Example: itype="email_
attachment_subject"

Reference Guide
exfil_domain Data Exfiltration Domain High Domain name associated with

Domain the infrastructure used for data
exfiltration.
Example: itype="exfil_domain"
exfil_ip Data Exfiltration IP High IP address used for data

IP exfiltration.
Example: itype="exfil_ip"
exfil_ipv6 Data Exfiltration IP High IPv6 address used for data

IP exfiltration.
Example: itype="exfil_ipv6"
exfil_url Data Exfiltration URL High URL used for data exfiltration.
URL
Example: itype="exfil_url"
exploit_domain Exploit Kit Domain Very-High Domain name associated with

Domain the web server hosting an exploit
kit or launching web-based
exploits.
Example: itype="exploit_domain"
exploit_ip Exploit Kit IP IP High IP address associated with the

web server hosting an exploit kit
or launching web-based exploits.
Example: itype="exploit_ip"
exploit_ipv6 Exploit Kit IPv6 IP High IPv6 address associated with the
web server hosting an exploit kit
or launching web-based exploits.
Example: itype="exploit_ipv6"
exploit_md5 Exploit Hash Hash Low Hash related to a file used to

exploit a known vulnerability.
Example: itype="exploit_md5"
exploit_url Exploit Kit URL URL Very-High URL used for launching web-
based exploits.
Example: itype="exploit_url"
fraud_domain Fraud Domain Domain High Domain associated with

fraudulent activity.
Example: itype="fraud_domain"

Reference Guide
fraud_email Fraud Email Email Low Email address associated with

Example: itype="fraud_email"
fraud_email_ Fraud Email String Medium Subject from an email associated

subject Subject with fraud activity.
Example: itype="fraud_ip"
fraud_ip Fraud IP Address IP High IP address associated with

Example: itype="fraud_email_
subject"
fraud_ipv6 Fraud IPv6 IP High An IPv6 address associated with

Example: itype="fraud_ipv6"
fraud_md5 Fraud Hash Hash Very-High Hash associated with fraudulent

activity.
Example: itype="fraud_md5"
fraud_url Fraud URL URL Medium URL associated with fraudulent

activity.
Example: itype="fraud_url"
free_email_ Free Email Domain Low Domain associated with free

domain Domain email service activity.
Example: itype="free_email_
domain"
geolocation_url IP Geolocation URL Low URL that can be used to provide

URL IP Geo location services.
Example: itype="geolocation_url"
hack_tool Hacking Tool String High Name of general hacking

software tools used by threat
actors.
Example: itype="hack_tool"
hack_tool_md5 Hack Tool File Hash Very-High MD5 or SHA hash of general
Hash hacking software tools used by
threat actors.
Example: itype="hack_tool_md5"

Reference Guide
i2p_ip I2P IP Address IP Low IP address observed to be

connecting to the I2P (Invisible
Internet Project) network.
Example: itype="i2p_ip"
i2p_ipv6 I2P IPv6 Address IP Low IPv6 address observed to be

connecting to the I2P (Invisible
Internet Project) network.
Example: itype="i2p_ipv6"
image_hash Image Hash String Low Cryptographic hash of the image

used for comparing two different
images. It differs from typical
MD5, SHA1, SHA2 hashes.
Example: itype="image_hash"
infostealer_ Information Domain Very High Domain associated with an

domain Stealer Domain information stealer.
Example: itype="infostealer_
domain"
infostealer_hash Information Hash Very High Hash of a malicious file

Stealer File Hash associated with an information
stealer.
hash"
infostealer_ip Information IP Very High IP address associated with an

Stealer IP information stealer.
Example: itype="infostealer_ip"
infostealer_ipv6 Information IP Very High IPv6 address associated with an

Stealer IPv6 information stealer.
ipv6"
infostealer_url Information URL Very High URL associated with an

Stealer URL information stealer.
Example: itype="infostealer_url"

Reference Guide
iot_domain Internet of Things Domain Medium Domain associated with malware

Malicious targeting Internet of Things
Domain devices.
Example: itype="iot_domain"
iot_hash Internet of Things Hash High Hash of a malicious sample

Malicious File targeting Internet of Things
Hash devices.
Example: itype="iot_hash"
iot_ip Internet of Things IP Medium IP address associated with

Malicious IP malware targeting Internet of
Things devices.
Example: itype="iot_ip"
iot_ipv6 Internet of Things IP Medium IPv6 associated with malware

Malicious IPv6 targeting Internet of Things
devices.
Example: itype="iot_ipv6"
iot_url Internet of Things URL Medium URL associated with malware

Malicious URL targeting Internet of Things
devices and services.
Example: itype="iot_url"
ipcheck_url IP Check URL URL Low URL that can be used to provide
IP checking services, such as
echoing the Internet facing IP
address of the client.
Example: itype="ipcheck_url"
mal_domain Malware Domain Domain Very-High Domain contacted by malware

sample; could be for command
and control commands, or to
check if the client is online.
Example: itype="mal_domain"
mal_email Malware Email Email Low Email address used to send

malware through malicious links
or attachments.
Example: itype="mal_email"
mal_email_ Malware Email String Medium Subject from an email associated

subject Subject with malware activity.

Reference Guide
mal_file_name Malware File String Very-High File name of malware sample.

Name
Example: itype="mal_file_name"
mal_file_path Malware File String Very-High File path of malware sample.

Path
Example: itype="mal_file_path"
mal_ip Malware IP IP Very-High IP address contacted by malware

sample; could be for command
and control commands, or to
check if the client is online.
Example: itype="mal_ip"
mal_ipv6 Malware IPv6 IP Very-High IPv6 address contacted by

malware sample; could be for
command and control
commands, or to check if the
client is online.
Example: itype="mal_ipv6"
mal_md5 Malware File Hash Very-High MD5 or SHA hash of malware

Hash sample.
Example: itype="mal_md5"
mal_mutex Malware Mutex String Very-High Mutex of malware sample.
Example: itype="mal_mutex"
mal_registry_ Malware Registry String High Registry key of malware sample.

key Key
Example: itype="mal_registry_
key"
mal_service_ Malware Service String Very-High Service description associated

description Description with the malware sample.
Example: itype="mal_service_
description"
mal_service_ Malware Service String Very-High Service display name associated

displayname Display Name with the malware sample.
displayname"

Reference Guide
mal_service_ Malware Service String Very-High Service name associated with the
name Name malware sample.
name"
mal_ssdeep Malware String Very-High SSDeep Hash associated with

SSDeep Hash the malware sample.
Example: itype="mal_ssdeep"
mal_sslcert_ SSL Certificate Hash High MD5 or SHA hash of SSL

sha1 Hash certificate associated with
malware or botnet activities.
Example: itype="mal_sslcert_
sha1"
mal_ua Malware User String Low User agent string used by

Agent malware sample when
communicating via HTTP.
Example: itype="mal_ua"
mal_url Malware URL URL Very-High URL contacted by malware

sample when run on an infected
host.
Example: itype="mal_url"
p2pcnc Peer-to-Peer IP Medium IP addressed associated with a

C&C IP Address peer-to-peer command and
control infrastructure.
Example: itype="p2pcnc"
p2pcnc_ipv6 Peer-to-Peer IP Medium IPv6 addressed associated with a

C&C IPv6 peer-to-peer command and
Address control infrastructure.
Example: itype="p2pcnc_ipv6"
parked_domain Parked Domain Domain Low Domain name of a website which

is currently parked.
Example: itype="parked_domain"
parked_ip Domain Parking IP Low IP addressed used for parking

IP newly registered or inactive
domain names.
Example: itype="parked_ip"

Reference Guide
parked_ipv6 Domain Parking IP Low IPv6 addressed used for parking

IPv6 newly registered or inactive
domain names.
Example: itype="parked_ipv6"
parked_url Parked URL URL Low URL of a website that is currently

parked.
Example: itype="parked_url"
pastesite_url Paste Site URL URL Low URL that can be used for sharing
pastes or text content
anonymously.
Example: itype="pastesite_url"
phish_domain Phishing Domain Domain Very-High Domain used to perform phishing

or spear phishing attacks or
contained in a phishing email.
Example: itype="phish_domain"
phish_email Phishing Email Email Very-High Email address associated with

Address sending phishing or spear
phishing emails to victims.
Example: itype="phish_email"
phish_email_ Phishing Email String High Subject from an email associated

subject Subject with phishing activity.
Example: itype="phish_email_
subject"
phish_ip Phishing IP Very-High IP address that has been used to

IP Address perform phishing or spear
phishing or is contained in a
phishing email.
Example: itype="phish_ip"
phish_ipv6 Phishing IP Very-High IPv6 address that has been used

IPv6 Address to perform phishing or spear
phishing or is contained in a
phishing email.
Example: itype="phish_ipv6"

Reference Guide
phish_md5 Phishing File Hash Very-High Hash related to a file used to

Hash perform phishing or spear
phishing attacks or contained in a
phishing email.
Example: itype="phish_md5"
phish_url Phishing URL URL Very-High URL used to perform phishing or

spear phishing attacks or
contained in a phishing email.
Example: itype="phish_url"
pos_domain Point of Sale Domain Medium Domain associated with malware

Malicious targeting Point of Sales systems.
Domain
Example: itype="pos_domain"
pos_hash Point of Sale Hash High Malicious file hash targeting Point
Malicious File of Sales systems.
Hash
Example: itype="pos_hash"
pos_ip Point of Sale IP Medium IP address associated with

Malicious IP malware targeting Point of Sale
systems.
Example: itype="pos_ip"
pos_ipv6 Point of Sale IP Medium IPv6 address associated with

Malicious IPv6 malware targeting Point of Sales
systems.
Example: itype="pos_ipv6"
pos_url Point of Sale URL Medium URL associated with malware

Malicious URL targeting Point of Sales systems.
Example: itype="pos_url"
proxy_ip Open Proxy IP IP Low IP address hosting open or

anonymous proxy software.
Allows user to hide their IP
address from target.
Example: itype="proxy_ip"

Reference Guide
proxy_ipv6 Open Proxy IPv6 IP Low IPv6 address hosting open or

anonymous proxy software.
Allows user to hide their IP
address from target.
Example: itype="proxy_ipv6"
ransomware_ Ransomware Domain Very High Domain associated with

domain Domain ransomware.
Example: itype="ransomware_
domain"
ransomware_ Ransomware Hash Very high File hash of a malicious

hash File Hash ransomware sample.
hash"
ransomware_ip Ransomware IP IP Very High IP address associated with

ransomware.
Example: itype="ransomware_ip"
ransomware_ Ransomware IP Very High IPv6 address associated with

ipv6 IPv6 ransomware.
ipv6"
ransomware_url Ransomware URL Very High URL associated with

URL ransomware.
url"
rootkit_hash Rootkit File Hash Hash Very High File hash of rootkit malware that
provides root-level access to an
attacker.
Example: itype="rootkit_hash"
scan_ip Scanning IP IP Medium IP address observed to perform

port scanning and vulnerability
scanning activities.
Example: itype="scan_ip"

Reference Guide
scan_ipv6 Scanning IPv6 IP Medium IPv6 address observed to

perform port scanning and
vulnerability scanning activities.
Example: itype="scan_ipv6"
sinkhole_ Sinkhole Domain Domain Low Domain name that researchers or

domain security companies typically
sinkhole.
Example: itype="sinkhole_
domain"
sinkhole_ip Sinkhole IP IP Low IP address that is known to be

used to sinkhole malicious
domain names.
Example: itype="sinkhole_ip"
sinkhole_ipv6 Sinkhole IPv6 IP Low IPv6 address that is known to be

used to sinkhole malicious
domain names.
Example: itype="sinkhole_ipv6"
social_media_ Social Media URL Medium URL related to social media

url URL activity. This indicator type is
provided by select feeds and
cannot be imported through the
ThreatStream user interface.
Example: itype="social_media_
url"
spam_domain Spam Domain Domain Low Malicious domain name

contained in the SPAM email
messages.
Example: itype="spam_domain"
spam_email Spammer Email Email Low Email address that has been
Address observed sending SPAM emails.
Example: itype="spam_email"
spam_email_ Spam Email String Low Subject from an email associated

subject Subject with spam activity.
Example: itype="spam_email_
subject"

Reference Guide
spam_ip Spammer IP IP Low IP address that is known to send

SPAM emails.
Example: itype="spam_ip"
spam_ipv6 Spammer IPv6 IP Low IPv6 address that is known to

send SPAM emails.
Example: itype="spam_ipv6"
spam_mta Spam Mail String Low Mail transfer agent known to be

Transfer Agent associated with SPAM emails.
Example: itype="spam_mta"
spam_url Spam URL URL Low Malicious URL contained in the

SPAM email messages.
Example: itype="spam_url"
speedtest_url Speed Test URL URL Low URL that can be used to run
internet speed tests or bandwidth
measurements of the client's
network connection.
Example: itype="speedtest_url"
ssh_ip SSH Brute Force IP Low IP addresses associated with

IP SSH brute force attempts.
Example: itype="ssh_ip"
ssh_ipv6 SSH Brute Force IP Low IPv6 addresses associated with

IPv6 SSH brute force attempts.
Example: itype="ssh_ipv6"
ssl_cert_serial_ SSL Certificate String Low Serial number unique to the TLS
number Serial Number certificate issuer that identifies
the entity being signed.
Example: itype="ssl_cert_serial_
number"
suppress Suppress n/a n/a Not a true indicator type. Used by

Arcsight for suppressing false
positives.
Default Severity: n/a
Example: itype="suppress"

Reference Guide
suspicious_ Suspicious Domain Medium Domain name that appears to be

domain Domain registered for suspect reasons,
but may not be associated with
known malicious activity yet.
Example: itype="suspicious_
domain"
suspicious_ Suspicious Email Email Low Email address that appears to be

email used for suspect reasons, but
may not be associated with
Example: itype="suspicious_
email"
suspicious_ Suspicious Email String Low Email subject from a suspicious

email_subject Subject email address.
Example: itype="suspicious-
email_subject"
suspicious_ip Suspicious IP IP Medium IP address that appears to be

registered for suspect reasons,
Example: itype="suspicious_ip"
suspicious_reg_ Suspicious Email Low Registrant email address that

email Registrant Email appears to be used for suspect
reasons, but may not be
associated with known malicious
activity yet.
Example: itype="suspicious_reg_
email"
suspicious_url Suspicious URL URL Medium URL that appears to be

registered for suspect reasons,
Example: itype="suspicious_url"
tor_ip TOR Node IP IP Low IP address operating as part of

The Onion Router (TOR)
Network, also know as a TOR exit
node.
Example: itype="tor_ip"

Reference Guide
tor_ipv6 TOR Node IPv6 IP Low IPv6 address operating as part of

The Onion Router (TOR)
Network, also know as a TOR exit
node.
Example: itype="tor_ipv6"
torrent_tracker_ Torrent Tracker URL Low URL used for tracking bittorrent
url URL file transfer activity.
Example: itype="torrent_tracker_
url"
trojan_domain Trojan Domain Domain High Domain associated with Trojan

malware that disguises as a
legitimate code or software.
Example: itype="trojan_domain"
trojan_hash Trojan File Hash Hash High File hash associated with Trojan
Example: itype="trojan_hash"
trojan_ip Trojan IP High IP address associated with

IP Address Trojan malware that disguises as
a legitimate code or software.
Example: itype="trojan_ip"
trojan_ipv6 Trojan IPv6 IP High IPv6 address associated with a

Address Trojan malware that disguises as
a legitimate code of software.
Example: itype="trojan_ipv6"
trojan_url Trojan URL URL High URL associated with a Trojan

Example: itype="trojan_url"
vpn_domain Anonymous Domain Low Domain name associated with

VPN Domain commercial or free Virtual Private
Networks (VPN).
Example: itype="vpn_domain"

Reference Guide
vps_ip Cloud Server IP IP Low IP address that is used for

hosting Virtual Private Servers
(VPS) or other server rentals.
Example: itype="vps_ip"
vps_ipv6 Cloud Server IP Low IPv6 address that is used for

IPv6 hosting Virtual Private Servers
(VPS) or other server rentals.
Example: itype="vps_ipv6"
whois_bulk_ Whois Bulk Email Low Registrant email address

reg_email Registrant Email associated with privacy domain
purchased from Whois.
Example: itype="whois_bulk_
reg_email"
whois_privacy_ Whois Privacy Domain Low Privacy domain purchased from

domain Email Domain Whois.
Example: itype="whois_privacy_
domain"
whois_privacy_ Whois Privacy Email Low Email address associated with a

email Email privacy domain purchased from
Whois.
Example: itype="whois_privacy_
email"

Appendix C: Fraud Indicator Types for
ThreatStream OnPrem
This appendix lists the fraud indicator types available for use on ThreatStream OnPrem. These
indicator types cannot be used with ThreatStream Cloud.
Fraud
Indicator Data
Type Type Description
bitcoin_ String Bitcoin wallet address

wallet
fraud_aba_ Numeric ABA number, also known as the routing number or routing transfer
num number
fraud_ Numeric Account number

acct_num
fraud_actor String Name (includes first and last name)
fraud_ String Company name

company
fraud_ String Email address

email
Note: The specified email address must adhere to the email address
syntax such as name@company.com. If the email address does not
follow this syntax, it will not be imported.
fraud_ String Phone number representing fraudulent activity

phone_
num
fraud_ Numeric SWIFT code

swift_code
fraud_tax_ Numeric Tax ID

id

Appendix D: Threat Types in
ThreatStream
During the import process, ThreatStream uses machine learning to assign indicator types to imported
observables based on the threat type you select. The following table lists all available threat types in
ThreatStream, in addition to the indicator types with which they are associated. For more on indicator
types, see "Indicator Types in ThreatStream API" on page 181.
Associated
Threat Type Name Example Indicator Types
adware Adware threat_type="adware" adware_domain
anomalous Anomalous threat_ geolocation_url,

type="anomalous" ipcheck_url,
speedtest_url
anonymization Anonymization threat_ anon_proxy, anon_

type="anonymization" proxy_ipv6, anon_
vpn, anon_vpn_ipv6,
proxy_ip, proxy_ipv6,
vpn_domain
apt APT threat_type="apt" apt_domain, apt_

email, apt_email_
subject, apt_file_
name, apt_file_path,
apt_ip, apt_ipv6, apt_
md5, apt_mta, apt_
mutex, apt_registry_
key, apt_service_
description, apt_
service_
displayname, apt_
service_name, apt_
ssdeep, apt_subject,
apt_ua apt_url
bot Bot threat_type="bot" bot_domain, bot_ip,

bot_ipv6, bot_md5,
bot_url
brute Brute threat_type="brute" brute_ip, brute_ipv6,

ssh_ip, ssh_ipv6

Reference Guide
Appendix D: Threat Types in ThreatStream
Associated
c2 C2 threat_type="c2" c2_domain, c2_ip,

c2_ipv6, c2_url
compromised Compromised threat_ compromised_

type="compromised" domain,
compromised_email,
compromised_email_
subject,
compromised_ip,
compromised_ipv6,
compromised_url,
compromised_
username
crypto Crypto threat_type="crypto" crypto_hash, crypto_

ip, crypto_pool,
crypto_url, crypto_
wallet
data_leakage Data Leakage threat_type="data_ pastesite_url

leakage"
ddos DDOS threat_type="ddos" ddos_ip, ddos_ipv6
dyn_dns Dynamic DNS threat_type="dyn_dns" dyn_dns
exfil Exfil threat_type="exfil" exfil_domain, exfil_ip,

exfil_ipv6, exfil_url
exploit Exploit threat_type="exploit" exploit_domain,

exploit_ip, exploit_
ipv6, exploit_md5,
exploit_url
fraud Fraud threat_type="fraud" fraud_domain, fraud_

email, fraud_email_
subject, fraud_ip,
fraud_md5, fraud_url
hack_tool Hacking Tool threat_type="hack_ hack_tool, hack_

tool" tool_md5
i2p I2P threat_type="i2p" i2p_ip, i2p_ipv6

Reference Guide
Associated
informational Informational threat_ comm_proxy_

type="informational" domain, comm_
proxy_ip,
disposable_email_
domain, free_email_
domain, passphrase,
ssl_cert_serial_
number, whois_bulk_
reg_email, whois_
privacy_domain,
whois_privacy_email
malware Malware threat_type="malware" mal_domain, mal_

email, mal_email_
subject, email_
attachment_subject,
mal_file_name, mal_
file_path, mal_ip,
mal_ipv6, mal_md5,
mal_mutex, mal_
registry_key, mal_
service_description,
mal_service_
displayname, mal_
service_name, mal_
ssdeep, mal_sslcert_
sha1, mal_ua, mal_
url
p2p P2P threat_type="p2p" actor_ip actor_ipv6,

actor_subject,
p2pcnc, p2pcnc_
ipv6, torrent_tracker_
url
parked Parked threat_type="parked" parked_domain,

parked_ip, parked_
ipv6, parked_url
phish Phish threat_type="phish" phish_domain,

phish_email, phish_
email_subject,
phish_ip, phish_ipv6,
phish_url
scan Scan threat_type="scan" scan_ip, scan_ipv6

Reference Guide
Associated
sinkhole Sinkhole threat_type="sinkhole" sinkhole_domain,

sinkhole_ip,
sinkhole_ipv6
spam Spam threat_type="spam" adware_registry_key,

spam_domain,
spam_email, spam_
email_subject,
spam_ip, spam_ipv6,
spam_mta spam_url
suppress Suppress threat_type="suppress" suppress
suspicious Suspicious threat_ suspicious_domain,

type="suspicious" suspicious_email,
suspicious_email_
subject, suspicious_
ip, suspicious_reg_
email, suspicious_url
tor TOR threat_type="tor" tor_ip, tor_ipv6
vps VPS threat_type="vps" vps_ip, vps_ipv6

Send Documentation Feedback
If you have comments about this document, you can contact the documentation in these ways:
l Click contact the documentation team to send an email. If you have an email client configured on
this system, an email window will open with the following information in the subject line:
Feedback on (ThreatStream API)
l Send your feedback to support@anomali.com.
Thank you for your feedback!

ThreatStream API Reference Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

ThreatStream API Reference Guide

Uploaded by

Copyright:

Available Formats

Anomali ThreatStream API

March 29, 2023

2/2/2023 Updated the description of the search_filter attribute in "Intelligence" on page 40.

1/12/2023 Updated "Investigation" on page 59.

9/14/2022 Updated "Tipreport" on page 138.

Anomali ThreatStream API Page 2 of 209

Anomali ThreatStream API Page 3 of 209

Threat Model Entity and Observable Tags 156

User Administration 164

User Audit 168

Appendix A: Intelligence Fields in ThreatStream API 177

Appendix B: Indicator Types in ThreatStream API 181

Anomali ThreatStream API Page 4 of 209

Appendix C: Fraud Indicator Types for ThreatStream OnPrem 204

Appendix D: Threat Types in ThreatStream 205

Send Documentation Feedback 209

Anomali ThreatStream API Page 5 of 209

Accessing the API

<resource> is API endpoint; for example, import, intelligence, tipreport

Anomali ThreatStream API Page 6 of 209

Anomali ThreatStream API Page 7 of 209

l took—time in milliseconds ThreatStream took to retrieve the data.

Using “next” to Iteratively Retrieve Datasets

Anomali ThreatStream API Page 8 of 209

The above API call yields the following metadata:

where <link_to_next_page> is the value specified by the metadata in your results.

Using API to Access ThreatStream OnPrem

Anomali ThreatStream API Page 9 of 209

<OnPrem_IP_or_FQDN> is the IP address or FQDN you use to access your ThreatStream OnPrem,

<OnPrem_IP_or_FQDN> is the IP address or FQDN you use to access your ThreatStream OnPrem,

<username> is the username you use to access ThreatStream OnPrem.

Anomali ThreatStream API Page 10 of 209

Bulk HTTP Method: GET

Number of rows returned (by default): 20

Attributes: See table below.

edit_type APP Store activity type. Possible types include:

l Accepted Paid—a user in your organization activated an APP Store service on

l Accepted Trial—a user in your organization activated an APP Store service

l Activation—a user in your organization activated an APP Store service.

l Approved—a vendor approved your request for access to an APP Store

l Credential Change—a user in your organization updated the credentials

l Declined—trial access request declined by the vendor.

l Ejection—a vendor removed access from your organization to an APP Store

l Invite—a vendor invited your organization to activate an APP Store service.

l Leave/Deactivation—a user in your organization deactivated an APP Store

Anomali ThreatStream API Page 11 of 209

l Request—a user in your organization requested trial access to an APP Store

l Request Unauthorized—a user made an unauthorized request for access to

l Unauthorized—a vendor sent an unauthorized invite to your organization.

id Unique ID of the APP store activity on the activity log.

name Name of the APP Store service.

timestamp Timestamp when the action was taken.

Anomali ThreatStream API Page 12 of 209

Bulk HTTP Method: GET

Attributes: See table below.

type Type of intelligence details. Default: confidence

value Value of an observable for which confidence will be returned.

Number of rows returned (by default): 20

Attributes: See table below.

min_confidence Lowest ThreatStream calculated confidence score for the observable.

average_confidence Average ThreatStream calculated confidence score for the observable.

max_confidence Highest ThreatStream calculated confidence score for the observable.

Anomali ThreatStream API Page 13 of 209

Anomali ThreatStream API Page 14 of 209