Threat Bulletins

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/ Note: The body field of a Threat Bulletin can contain up to 100 MB of text when submitted directly in the JSON request payload.
Update the specified Threat Bulletin	PATCH /api/v1/tipreport/{id}/
Get details of the specified Threat Bulletin	GET /api/v1/tipreport/{id}/
Get a list of Threat Bulletins	Anomali recommends to use the /api/v1/threat_model_search endpoint to retrieve a list of Threat Bulletins. See Threat Model Search for details. For example, GET /api/v1/threat_model_search/?model_type=tipreport
Get a list of Threat Bulletins associated with the specified observable value or observable ID	GET /api/v1/tipreport/associated_with_intelligence/?value={value} GET /api/v1/tipreport/associated_with_intelligence/?ids={comma_separated_id_list} For example, GET /api/v1/tipreport/associated_with_intelligence/?value=google.com returns all Threat Bulletins associated with google.com.
Get a list of the specified entity type (such as Malware, Actor, Campaign, and so on) associated with the specified Threat Bulletin	GET /api/v1/tipreport/{id}/<entity_type>/ 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 Threat Bulletin	GET /api/v1/tipreport/{id}/intelligence/

Response

Format: JSON

Attributes: See the table below

Attributes

Attribute	Type	Description
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.
attachments	related (see item 1 in the Notes above)	All files—whitepapers, reports, news—attached to the Threat Bulletin. Note: Attachments added to a Threat Bulletin will be visible to all organizations that have access to this Threat Bulletin.
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 1 in the Notes above)	IDs of the trusted circles with which the Threat Bulletin is shared.
comments	related (see item 1 in the Notes above)	Deprecated. Use the GET request to view comments associated with the Threat Bulletin.
created_ts	datetime	Timestamp when the investigation was created.
history	related (see item 1 in the Notes above)	Deprecated. Use the GET request to view history of the Threat Bulletin.
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 1 in the Notes above)	Import sessions associated with the Threat Bulletin. Use this attribute if you need to associate a batch of imported observables. Provide Import Job ID from the Import UI page or use the import API to obtain the job ID.
intelligence	related (see item 1 in the Notes above)	Observables associated with the Threat Bulletin. Use this attribute to associate intelligence (observables) 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, observables returned through "import_sessions" attribute may not appear in the list of observables 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.
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.
remote_api (for ThreatStream OnPrem only)	boolean	Whether the entity is remote (stored on Cloud). Value returned for this attribute is true when the entity is remote.
resource_uri	string	URI for the Threat Bulletin on ThreatStream.
sandbox_reports	related (see item 1 in the Notes above)	Sandbox reports associated with the Threat Bulletin. Obtain ID of the Sandbox report from the Sandbox UI page.
skip_associations (On ThreatStream OnPrem only)	boolean	By default, up to 1000 threat model and observable associations are returned with GET requests for details of a threat model entity on 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/tipreport/{id}/?skip_associations=true
skip_intelligence (On ThreatStream OnPrem only)	boolean	By default, up to 1000 threat model and observable associations are returned with GET requests for details of a threat model entity on 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_intelligence parameter to true. This parameter is only applicable to ThreatStream OnPrem. For example, GET /api/v1/tipreport/{id}/?skip_intelligence=true
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. For example, spear phishing,exploitation.
threat_actor	string	Deprecated. Returns null in responses.
tlp	string	Traffic Light Protocol designation for the threat bulletin—red, amber, amber+strict, green, clear.
ttp	string	Deprecated. Returns null in responses.
vulnerability	string	Deprecated. Returns null in responses.

Examples

1. To retrieve the first 10 Threat Bulletins:

   Copy

   curl "https://api.threatstream.com/api/v1/tipreport/?limit=10"

2. To retrieve Threat Bulletins that were created since a specified date and time:

   Copy

   curl 'https://api.threatstream.com/api/v1/tipreport/?created_ts__gte=2014-10-02T20:44:35'

3. To create a new Threat Bulletin:

   Copy

   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

4. To create a new Threat Bulletin that includes private tags:

   Copy

   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 <username>:<api_key>' -H 'Content-Type:application/json' -v

5. To modify the existing Threat Bulletin whose ID is 11:

   Copy

   curl --request PATCH --data '{"name":"Updated Threat Bulletin Name"}' 'https://api.threatstream.com/api/v1/tipreport/11/' -H 'Authorization: apikey <username>:<api_key>' -H 'Content-Type:application/json' -v

6. To add an attachment to an existing Threat Bulletin:

   Copy

   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

   Note: Attachments added to a threat bulletin will be visible to all organizations that have access to this threat bulletin.

7. (Only on ThreatStream OnPrem) To get details of the remote Threat Bulletin whose ID is 12:

   Copy

   curl 'https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/tipreport/12/?remote_api=true' -H 'Authorization: apikey <username>:<api_key>'

8. (Only on ThreatStream OnPrem) To skip associations when retrieving details of the local Threat Bulletin with ID 234678:

   Copy

   curl 'https://<ThreatStream_OnPrem_IP_or_FQDN>/api/v1/tipreport/234678/?skip_associations=true' -H 'Authorization: apikey <username>:<api_key>'