Rulesets & Rules

A ruleset is comprised of rules which are assigned to an Agent. You can have multiple rulesets assigned to an Agent, such as AIP's Base Ruleset or Threat Intelligence Ruleset.

AIP fires an alert after evaluating incoming events against the rules you created and enabled within your organization. A rule fires 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 AIP, 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

A 400 error means the agentId is invalid.

A 404 error 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

Unauthorized response

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 rulesets in your environment.

Sample Query

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 ruleset was unable to be created.

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

409: The ruleset name duplicates an existing ruleset name. The ruleset 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

OK

400

Invalid keys

401

Unauthorized response

404

ruleIds not found

409

Resource already exists

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 Query

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

Unauthorized response

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 Query

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 ruleset 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 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 new and existing rule in the ruleset.

WARNING: If a rule that belongs in the ruleset in AIP is not included in this API ruleset, then it will be removed from the ruleset, permanently deleted, and irrecoverable from AIP.

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

OK

400

Invalid keys

401

Unauthorized response

404

Ruleset or ruleIds not found

409

Resource already exists

429

Rate limit hit

500

An internal error has occurred

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 AIP.
  • All rules included in the ruleset are permanently deleted from AIP.

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 Query

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 to delete was not found.

Request
path Parameters
rulesetId
required
string

ID of the ruleset.

Responses
200

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

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 Query

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 from which you want to get rules

Responses
200

Successful operation

400

Bad parameters

401

Unauthorized response

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 Query

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.
Request
path Parameters
rulesetId
required
string

ID of the ruleset from which you want to get rules

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

Name of the rule

type
string

Type of the rule. This field is case insensitive

Enum: "host" "cloudtrail" "threatintel" "file" "kubernetesAudit" "kubernetesConfig"
createdAt
string <date-time>

The date and time the rule was created

updatedAt
string <date-time>

The data and time the rule was last updated

severityOfAlerts
integer

Severity level of alerts this rule generates

Enum: 1 2 3
alertDescription
string [ 0 .. 300 ] characters

Description of the alert that the rule generates

filter
string

Defines the conditions under which a rule generates an alert Important: Filters must pass validation specified by the AIP filter query language

window
integer

The time period that must see at least the threshold value of events before the rule generates an alert

Enum: 3600 7200 14400 28800 57600 86400
threshold
integer

The minimum number of events matching a rule in the assigning window before the rule generates an alert

Enum: 1 5 10 20 40 60
suppressions
Array of strings

List of alert suppressions for the rule Important: Suppressions must pass validation specified by AIP filter query language

enabled
boolean

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

Array of objects (ClassificationAttachment)

Optional list of classifiers to attach to this rule

aggregatedFields
Array of strings

List of fields to aggregate for the alert the file rule generates NOTE: Alerts fire once per unique aggregate

Responses
200

OK

400

Validation error

401

Unauthorized response

404

Ruleset ID not found

429

Rate limit hit

500

An internal error has occurred

post/rulesets/{rulesetId}/rules
Request samples
application/json
{
  • "name": "string",
  • "type": "host",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "severityOfAlerts": 1,
  • "alertDescription": "string",
  • "filter": "string",
  • "window": 3600,
  • "threshold": 1,
  • "suppressions": [
    ],
  • "enabled": true,
  • "classificationLabels": [
    ],
  • "aggregatedFields": [
    ]
}
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 ruleset by the rulesetId and ruleId.

NOTE

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

Sample Query

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

Unauthorized response

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": "host",
  • "severityOfAlerts": 1,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 3600,
  • "threshold": 1,
  • "suppressions": [
    ],
  • "fileIntegrityPaths": [
    ],
  • "ignoreFiles": [
    ],
  • "eventsToMonitor": [
    ],
  • "enabled": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "rulesetId": "2f23ed23-d3ba-42fd-898b-b2ccad407a6e",
  • "classificationLabels": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}

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 ruleset:

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

Error Handling Tips

  • 400: Invalid value(s) in the rule syntax.
  • 404: Either the selected ruleset cannot be found, or 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
string [ 1 .. 200 ] characters

Name of the rule

type
string

Type of the rule. This field is case insensitive

Enum: "host" "cloudtrail" "threatintel" "file" "kubernetesAudit" "kubernetesConfig"
createdAt
string <date-time>

The date and time the rule was created

updatedAt
string <date-time>

The data and time the rule was last updated

severityOfAlerts
integer

Severity level of alerts this rule generates

Enum: 1 2 3
alertDescription
string [ 0 .. 300 ] characters

Description of the alert that the rule generates

filter
string

Defines the conditions under which a rule generates an alert Important: Filters must pass validation specified by the AIP filter query language

window
integer

The time period that must see at least the threshold value of events before the rule generates an alert

Enum: 3600 7200 14400 28800 57600 86400
threshold
integer

The minimum number of events matching a rule in the assigning window before the rule generates an alert

Enum: 1 5 10 20 40 60
suppressions
Array of strings

List of alert suppressions for the rule Important: Suppressions must pass validation specified by AIP filter query language

enabled
boolean

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

Array of objects (ClassificationAttachment)

Optional list of classifiers to attach to this rule

aggregatedFields
Array of strings

List of fields to aggregate for the alert the file rule generates NOTE: Alerts fire once per unique aggregate

Responses
200

OK

400

Validation error

401

Unauthorized response

404

Ruleset or rule ID not found

409

Resource already exists

429

Rate limit hit

500

An internal error has occurred

put/rulesets/{rulesetId}/rules/{ruleId}
Request samples
application/json
{
  • "name": "string",
  • "type": "host",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "severityOfAlerts": 1,
  • "alertDescription": "string",
  • "filter": "string",
  • "window": 3600,
  • "threshold": 1,
  • "suppressions": [
    ],
  • "enabled": true,
  • "classificationLabels": [
    ],
  • "aggregatedFields": [
    ]
}
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 ruleset.

Sample Queries

Delete a rule from a specific ruleset

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

Error Handling Tips

404: Either the selected ruleset cannot be found, or 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.

401

Unauthorized response

404

Ruleset cannot be found

429

Rate limit hit

500

An internal error has occurred

delete/rulesets/{rulesetId}/rules/{ruleId}
Response samples
application/json
{
  • "message": "string"
}

List Active Agents for Ruleset

Overview

This method enables you to get the list of AIP 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 Query

Find the list of AIP 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

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

429

Rate limit hit

500

An internal error has occurred

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.

NOTE

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

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

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.

NOTE

You can only pass one ruleId at a #docTextSection:zR4WHD8nqEMdNENHa. 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 AIP Agent. Any AIP 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 AIP Agent. Any AIP Agent associated with that server will not have this rule applied to it.

Responses
200

OK

400

Bad parameters

401

Unauthorized response

404

The resource was not found

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

OK

400

Bad Request

401

Unauthorized response

404

ruleId not found

429

Rate limit hit

500

An internal error has occurred

put/rules/{ruleId}/suppressions
Request samples
application/json
{
  • "suppressions": [
    ]
}
Response samples
application/json
{
  • "name": "string",
  • "title": "string",
  • "type": "host",
  • "severityOfAlerts": 1,
  • "alertDescription": "string",
  • "aggregateFields": [
    ],
  • "filter": "string",
  • "window": 3600,
  • "threshold": 1,
  • "suppressions": [
    ],
  • "enabled": true,
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "rulesetId": "2f23ed23-d3ba-42fd-898b-b2ccad407a6e",
  • "classificationLabels": [
    ],
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z"
}