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 ThreatStream OnPrem only)	GET /api/v1/rule/?remote_api=true

Attributes: See the Attributes table below

Attributes

Attribute	Type	Description
actors	array of integers or strings	IDs of the Actors with which you want to associate matched entities.
campaigns	array of integers or strings	IDs of the Campaigns with which you want to associate matched entities.
create_investigation	boolean	Whether you want to create a dedicated investigation the first 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 strings	Indicator types you want to exclude from rule matches. 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_org_whitelisted	boolean	Whether you want to exclude the rule from matching 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_owner_org	boolean	Whether you want to exclude keyword matches on Observables imported by your organization from Keyword Match or Hourly Digest email notifications.
incidents	array of integers or strings	IDs of the Incidents with which you want to associate matched entities.
keywords	array of strings	Keywords for which you want the rule to match. Keywords added to rules must adhere to the following requirements: IP addresses must be expressed as regular expressions. Example: 192\.168\. IP subnets should be expressed using CIDR notation and not as regular expressions. Example: 10.20.100.0/26 Do not start or end keywords with .* Keywords must contain at least three characters.
malware	array of integers or strings	IDs of the Malware with which you want to associate matched entities.
match_impacts	array of strings	Indicator types in which you want to look for rule matches at 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_observables	boolean	Whether the rule should match keywords in newly created Observables. True—if you want to match Observables False—if you do not want to match Observables Default: False
match_reportedfiles	boolean	Whether the rule should match keywords in newly created 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
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
match_vulnerabilities	boolean	Whether the rule should match keywords in newly created 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 ThreatStream OnPrem only)	boolean	Whether the rule is remote (stored on Cloud). This attribute does not need to be set to retrieve local rules. Only use this attribute when retrieving remote rules from ThreatStream Cloud. Set this attribute to true in this case. Do not set this attribute to false for retrieving local rules. Doing so will generate errors.
signatures	array of integers or strings	IDs of the Signatures with which you want to associate matched entities.
tags	array of strings	Tags applied to the matched entities. Tags must be specified as follows: tags: [{"name": "my_tag","tlp": "red"},{"name": "my_tag2","tlp": "clear"},{"name": "my_tag3"}] Tag Attributes: name—name of the tag that you want to add. tlp—the visibility setting for the tag. Possible values: red, amber, amber+strict, green, clear. red—private, or visible to your organization only. white—public, or visible to all ThreatStream users with access to the data. Default: white. Note: Adding public tags may be restricted by your Organization Administrator. In the example above, my_tag is private and my_tag2 and my_tag3 are public.
tips	array of integers or strings	IDs of the Threat Bulletins with which you want to associate matched entities.
ttps	array of integers or strings	IDs of the TTPs with which you want to associate matched entities.
vulnerabilities	array of integers or strings	IDs of the Vulnerabilities with which you want to associate matched entities.

Response

Format: JSON

Attributes: See the table below

Attributes

Attribute	Description
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_whitelisted	Whether Observables whitelisted by your organization are excluded from rule matches.
exclude_notify_owner_org	Whether keyword matches on Observables imported by your organization 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.
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 ThreatStream OnPrem only)	Whether the rule is remote (stored on Cloud). Value returned for this attribute is true when the rule is remote.
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:

   Copy

   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"}'

2. To get a list of the 20 most recently configured rules:

   Copy

   curl 'https://api.threatstream.com/api/v1/rule/' -H 'Authorization: apikey <username>:<api_key>'

3. To update an existing rule whose ID is 56:

   Copy

   curl -X PATCH 'https://api.threatstream.com/api/v1/rule/56/' -F tags: "[{"name":"new_tag","tlp":"white"}]" -H 'Authorization: apikey <username>:<api_key>'

4. To delete a rule whose ID is 210:

   Copy

   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:

   Copy

   curl 'https://api.threatstream.com/api/v1/rule/?remote_ api=true&order_by=-created_ts'-H 'Authorization: apikey <username>:<api_ key>'