Rule Sets & Rules

A Ruleset is comprised of rules which are assigned to an Agent. You can have multiple rule sets assigned to an Agent, such as Threat Stack's Base Rule Set or Threat Intelligence Rule Set.

Threat Stack fires an alert after evaluating incoming events against the rules you created and enabled within your organization. A rule will fire an alert when the window and threshold requirements of the rule are met.

The Rule endpoints enable you to work with the IDS Rule model and the File Rule model. To learn more about creating rules in Threat Stack, see Rule Creation Overview.

List Rulesets

Overview

This method enables you to get a list of all the Rulesets in your environment.

Sample Queries

Find all the Rulesets in your organization:

https://api.threatstack.com/v2/rulesets

Find a Ruleset with a specific agentId (for example: 12345678-9abc-def0-1234-56789abcdef0):

https://api.threatstack.com/v2/rulesets?agentId=12345678-9abc-def0-1234-56789abcdef0

Error Handling Tips

If you see a 400 error, that means the agentId is invalid.

If you see a 404 error code, that means there is no data associated with the query for that agentId.

Request
query Parameters
agentId
string
Responses
200

successful operation

400

Bad parameters

401
403

The user is not allowed to perform this action.

429

Rate limit hit.

500

An internal error has occurred.

get/rulesets
Response samples
application/json
{
  • "rulesets": [
    ]
}

Create Ruleset

Overview

This method enables you to create Rule Sets in your environment.

Sample Queries

Create a Ruleset in your organization:

https://api.threatstack.com/v2/rulesets

Error Handling Tips

400: The syntax of the message body is incorrect and the rule set was unable to be created.

404: One of the ruleIds specified in the message body does not exist, so the rule set was unable to be created.

409: The rule set name duplicates an existing rule set name. The rule set was unable to be created.

Request
Request Body schema: application/json
name
required
string [ 1 .. 200 ] characters

The updated name of the Ruleset.

WARNING: The Ruleset name must not duplicate another Ruleset name in the organization.

description
required
string [ 1 .. 300 ] characters

The updated description of the Ruleset.

ruleIds
required
Array of strings

The ruleId for each rule to be copied into the Ruleset.

Responses
200
400
401
404
409
429

Rate limit hit.

500

An internal error has occurred.

post/rulesets
Request samples
application/json
{
  • "name": "string",
  • "description": "string",
  • "ruleIds": [
    ]
}
Response samples
application/json
{
  • "id": "string",
  • "rulesIds": [
    ],
  • "name": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "description": "string"
}

Get a Ruleset

Overview

This method enables you to get the details of a Ruleset by rulesetId.

NOTE:

You can only pass one rulesetId at a time.

Sample Queries

Find a Ruleset by rulesetId:

https://api.threatstack.com/v2/rulesets/{rulesetId}

Error Handling Tips

The 404 error code means that the rulesetId was not found.

Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

Responses
200

successful operation

400

Bad parameters

401
403

The user is not allowed to perform this action.

404

The Resource was not found.

429

Rate limit hit.

500

An internal error has occurred.

get/rulesets/{rulesetId}
Response samples
application/json
{
  • "id": "string",
  • "rulesIds": [
    ],
  • "name": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "description": "string"
}

Update Ruleset

Overview

This method enables you to update Rulesets in your environment.

Sample Queries

Update a Ruleset in your organization:

https://api.threatstack.com/v2/rulesets/{rulesetID}

Error Handling Tips

400: The syntax of the message body is incorrect and the Ruleset did not update.

404: One of the following occurred:

  • The Ruleset was not found.
  • One of the rules in the Ruleset does not exist.

409: The Ruleset name duplicates an existing rule set name.

Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

Request Body schema: application/json
name
required
string [ 1 .. 200 ] characters

The updated name of the rule set.
WARNING: The rule set name must not duplicate another rule set name in the organization.

description
required
string [ 1 .. 300 ] characters

The updated description of the rule set.

ruleIds
required
Array of strings

The ruleId for each new and existing rule in the rule set.
WARNING: If a rule that belongs in the rule set in Threat Stack is not included in this API rule set, then it will be removed from the rule set, permanently deleted, and irrecoverable from Threat Stack.
IMPORTANT: Alerts previously generated by any rule contained or omitted in this list will continue to exist in the state at which they were created.

Responses
200
400
401
404
409
429
500
put/rulesets/{rulesetId}
Request samples
application/json
{
  • "name": "string",
  • "description": "string",
  • "ruleIds": [
    ]
}
Response samples
application/json
{
  • "id": "string",
  • "rulesIds": [
    ],
  • "name": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "description": "string"
}

Delete Ruleset

Overview

This method enables you to delete a specific Ruleset from your environment.

When you delete a Ruleset, two things occur:

  • The Ruleset permanently deletes from Threat Stack.
  • All rules included in the Ruleset are permanently deleted from Threat Stack

IMPORTANT: Any alerts generated by rule in the deleted Ruleset are not deleted. These alerts continue to list the rule that triggered the alert, even though the Ruleset no longer exists.

Sample Queries

Delete a Ruleset with a specific rulesetID (for example: 00000000-aaaa-0000-aaaa-0000000000):

https://api.threatstack.com/v2/rulesets/00000000-aaaa-0000-aaaa-0000000000

Error Handling Tips

404: The Ruleset set to delete was not found.

Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

Responses
200
400
401
404
429
500
delete/rulesets/{rulesetId}
Response samples
application/json
{
  • "server_ids": [
    ]
}

List Rules for a Ruleset

Overview

This method enables you to get the list of rules assigned to a Ruleset by the rulesetId.

NOTE:

You can only pass one rulesetId at a time.

Sample Queries

Find list of rules by rulesetId:

https://api.threatstack.com/v2/rulesets/{rulesetId}/rules

Error Handling Tips

The 404 error code means that the rulesetId was not found."

Request
path Parameters
rulesetId
required
string

ID of the Ruleset you want to get rules from

Responses
200

successful operation

400

Bad parameters

401
403

The user is not allowed to perform this action.

404

The Resource was not found.

429

Rate limit hit.

500

An internal error has occurred.

get/rulesets/{rulesetId}/rules
Response samples
application/json
{
  • "rules": [
    ]
}

Create Rules

Overview

This method enables you to create a rule for a specific Ruleset.

Sample Queries

Create a rule for a specific ruleset:

https://api.threatstack.com/v2/rulesets/{rulesetId}/rules

Error Handling Tips

  • 400: Invalid value(s) in the rule syntax.
  • 404: The selected Ruleset cannot be found.
  • 409: The rule's name matches an existing rule name for the organization. Rule names must be unique within an organization.
Request
path Parameters
rulesetId
required
string

ID of the Ruleset you want to get rules from

Request Body schema: application/json
One of:
name
required
string [ 1 .. 200 ] characters

Name of the rule.

title
required
string [ 1 .. 200 ] characters

Title of the rule.

type
required
string

Type of the rule.
Note: The allowed values are case insensitive.

Enum: "Host" "CloudTrail" "ThreatIntel"
severityOfAlerts
required
integer

Severity level of alerts the rule will generate.

alertDescription
string [ 0 .. 300 ] characters

Description of the alert the rule will generate.

Array of objects

List of fields to aggregate for the alert the rule will generate. Varies based on rule type.
Note: Alerts fire once per unique aggregate.

filter
required
string

Defines the conditions under which a rule will generate an alert.
IMPORTANT: Filters must pass validation specified by Threat Stack filter query language.

window
required
integer

The time period that must see at least the threshold value of events before the rule will generate an alert.
Format: int32

threshold
required
integer

The minimum number of events matching a rule in the assigning window before the rule will generate an alert.
Format: int32

suppressions
Array of strings

List of alert suppressions for the rule.
IMPORTANT: Suppressions must pass validation specified by Threat Stack filter query language.

enabled
required
boolean

Flag that shows whether the rule is enabled (true) or disabled (false)

Responses
200
400
404
409
429
500
post/rulesets/{rulesetId}/rules
Request samples
application/json
{
  • "name": "string",
  • "title": "string",
  • "type": "Host",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true
}
Response samples
application/json
{
  • "id": "string",
  • "rulesetId": "string",
  • "name": "string",
  • "type": "Host",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "title": "string",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true
}

Get a Rule for a Ruleset

Overview

This method enables you to get the details of a specific rule assigned to a rule set by the rulesetId and ruleId.

NOTE:

You can only pass one rulesetId and one ruleId at a time.

Sample Queries

Find the details of a rule by rulesetId and ruleId:

https://api.threatstack.com/v2/rulesets/{rulesetId}/rules/{ruleId}

Error Handling Tips

The 404 error code means the rulesetId or ruleId was not found.

Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

ruleId
required
string

ID of the rule within a Ruleset.

Responses
200

successful operation

400

Bad parameters

401
404

The Resource was not found.

429

Rate limit hit.

500

An internal error has occurred.

get/rulesets/{rulesetId}/rules/{ruleId}
Response samples
application/json
{
  • "name": "string",
  • "title": "string",
  • "type": "File",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true,
  • "fileIntegrityPaths": [
    ],
  • "ignoreFiles": [
    ],
  • "eventsToMonitor": [
    ]
}

Update Rule

Overview

This method enables you to update a rule.

NOTE:

You cannot update the rule's type with this method.

Sample Queries

Update a rule in a specific Rule Set:

https://api.threatstack.com/v2/rulesets/{rulesetId}/rules/{ruleId}

Error Handling Tips

  • 400: Invalid value(s) in the rule syntax.
  • 404: One of the following situations occurred: The selected Rule Set cannot be found; The rule cannot be found.
  • 409: The rule's type cannot be updated with this method.
Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

ruleId
required
string

ID of the rule within a Ruleset.

Request Body schema: application/json
One of:
name
required
string [ 1 .. 200 ] characters

Name of the rule.

title
required
string [ 1 .. 200 ] characters

Title of the rule.

type
required
string

Type of the rule.
Note: The allowed values are case insensitive.

Enum: "Host" "CloudTrail" "ThreatIntel"
severityOfAlerts
required
integer

Severity level of alerts the rule will generate.

alertDescription
string [ 0 .. 300 ] characters

Description of the alert the rule will generate.

Array of objects

List of fields to aggregate for the alert the rule will generate. Varies based on rule type.
Note: Alerts fire once per unique aggregate.

filter
required
string

Defines the conditions under which a rule will generate an alert.
IMPORTANT: Filters must pass validation specified by Threat Stack filter query language.

window
required
integer

The time period that must see at least the threshold value of events before the rule will generate an alert.
Format: int32

threshold
required
integer

The minimum number of events matching a rule in the assigning window before the rule will generate an alert.
Format: int32

suppressions
Array of strings

List of alert suppressions for the rule.
IMPORTANT: Suppressions must pass validation specified by Threat Stack filter query language.

enabled
required
boolean

Flag that shows whether the rule is enabled (true) or disabled (false)

Responses
200
400
404
409
429
500
put/rulesets/{rulesetId}/rules/{ruleId}
Request samples
application/json
{
  • "name": "string",
  • "title": "string",
  • "type": "Host",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true
}
Response samples
application/json
{
  • "id": "string",
  • "rulesetId": "string",
  • "name": "string",
  • "type": "Host",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "title": "string",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true
}

Delete Rule

Overview

This method enables you to delete a rule from a specific Rule Set.

Sample Queries

Delete a rule from a specific Rule Set

https://api.threatstack.com/v2/rulesets/{rulesetId}/rules/{ruleId}

Errors Handling Tips

404: One of the following situations occurred: The selected Rule Set cannot be found; The rule cannot be found.

Request
path Parameters
rulesetId
required
string

ID of the Ruleset.

ruleId
required
string

ID of the rule within a Ruleset.

Responses
200

The rule was successfully deleted.

404
429
500
delete/rulesets/{rulesetId}/rules/{ruleId}
Response samples
application/json
{
  • "error": "string"
}

List Active Agents for Ruleset

Overview

This method enables you to get the list of Threat Stack Agents to which a specific Ruleset has been assigned.

NOTE:

This endpoint returns only active Agents. You can only pass one rulesetId at a time.

Sample Queries

Find the list of Threat Stack Agents assigned to a specific Ruleset:

https://api.threatstack.com/v2/rulesets/{rulesetId}/agents

Error Handling Tips

The 404 error code means rulesetId was not found.

Request
path Parameters
rulesetId
required
string
Responses
200
get/rulesets/{rulesetId}/agents
Response samples
application/json
{
  • "agents": [
    ]
}

Get Tags for a Rule

Overview

This method enables you to get a list of AWS EC2 tags for a specific rule.

Notes:

You can only pass one ruleId at a time.
You cannot get tags for AWS CloudTrail rules.

Sample Request

Find tags by ruleId

https://api.threatstack.com/v2/rules/{ruleId}/tags

Error Handling Tips

404: No tags found for the selected ruleId.

Request
path Parameters
ruleID
required
string
Responses
200
400
404
409
429

Rate limit hit.

500

An internal error has occurred.

get/rules/{ruleID}/tags
Response samples
application/json
{
  • "inclusion": [
    ],
  • "exclusion": [
    ]
}

Set Tags for a Rule

Overview

This method enables you to set inclusion and exclusion AWS EC2 tags for a specific rule.

Notes:

You can only pass one ruleId at a time.
You cannot set tags for an AWS CloudTrail rule.

Sample Request

Set tags by ruleId

https://api.threatstack.com/v2/rules/{ruleId}/tags

Error Handling Tips

404: No tags found for the selected ruleId.

Request
path Parameters
ruleID
required
string
Request Body schema: application/json
Array of objects

The AWS EC2 tags on the server associated with the Threat Stack Agent. Any Threat Stack Agent associated with that server will have this rule applied to it.

Array of objects

The AWS EC2 tags on the server associated with the Threat Stack Agent. Any Threat Stack Agent associated with that server will not have this rule applied to it.

Responses
200
400
404
409
429

Rate limit hit.

500

An internal error has occurred.

post/rules/{ruleID}/tags
Request samples
application/json
{
  • "inclusion": [
    ],
  • "exclusion": [
    ]
}
Response samples
application/json
{
  • "inclusion": [
    ],
  • "exclusion": [
    ]
}

Update Rule Suppressions

Overview

This method enables you to update a rule's suppression list.

Sample Queries

Update a rule suppression list in your organization:

https://api.threatstack.com/v2/rules/{ruleID}/suppressions

Error Handling Tips

400: The syntax of the message body is incorrect and the rule did not update. There are three possible messages:

  • Error message for an invalid value where invalid1 and invalid2 are strings coming from the suppression body that do not fit an accepted format.
  • Error message for an invalid key. Status code 400
  • Error message for an invalid value type. Status code 400
Request
path Parameters
ruleId
required
string
Request Body schema: application/json
suppressions
required
Array of strings

Each string references a suppression that will be attributed to the rule.
NOTE: Individual suppressions for the rule are separated by commas.

Responses
200
400
404
409
429
500
put/rules/{ruleId}/suppressions
Request samples
application/json
{
  • "suppressions": [
    ]
}
Response samples
application/json
{
  • "name": "string",
  • "title": "string",
  • "type": "Host",
  • "severityOfAlerts": 0,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 0,
  • "threshold": 0,
  • "suppressions": [
    ],
  • "enabled": true
}