Exclusion Lists

Indicator Exclusion Lists prevent the import of Indicators that may be deemed legitimate or non-hostile to an organization. ThreatConnect is prepopulated with default Indicator Exclusion Lists, but you can create custom Indicator Exclusion Lists at the System and owner (i.e., Organization, Community, and Source) levels.

Endpoint: {baseUrl}/api/v3/security/exclusionLists

Endpoint Options

Available Request Body Fields

Send the following request to retrieve a list of available request body fields, including each field’s name, description, and accepted data type, that you can use in a POST or PUT request to the /v3/security/exclusionLists endpoint:

Request

OPTIONS /v3/security/exclusionLists

Hint

To include read-only fields in the API response, use the show query parameter and assign it a value of readonly.

Filter Results With TQL

When retrieving data, you can use the tql query parameter to filter results with ThreatConnect Query Language (TQL).

Send the following request to retrieve a list of valid TQL parameters you can assign to the tql query parameter when using it in a request to the /v3/security/exclusionLists endpoint:

Request

OPTIONS /v3/security/exclusionLists/tql

Schemas

Request Body (POST)

The following is the request body schema for a POST request to the /v3/security/exclusionLists endpoint:

• name: <String> REQUIRED The Indicator Exclusion List’s name. The name must be of the format Indicator-{exclusionListType}, where {exclusionListType} is the type of Exclusion List you are creating. For owner-level Exclusion Lists, you can obtain a list of Exclusion List types by navigating to Indicator Exclusions tab on the Organization Config (for Organization-level Exclusion Lists), Community Config (for Community-level Exclusion Lists), or Source Config (for Source-level Exclusion Lists) screen in the ThreatConnect UI. For System-level Exclusion Lists, you can obtain a list of Exclusion List types by navigating to the Indicators tab on the System Settings screen in the ThreatConnect UI and selecting Exclusion Rules in the menu on this tab.

• fixedValues: <Object> REQUIRED The fixed Indicator values to add to the Indicator Exclusion List.

  • data: <Array of Objects> An array of fixed Indicator value objects.

    • value: <String> The fixed Indicator value (e.g., badguy@bad.com ).

• variableValues: <Object> REQUIRED The variable Indicator values to add to the Indicator Exclusion List.

  • data: <Array of Objects> An array of variable Indicator value objects.

    • value: <String> The variable Indicator value (e.g., *@bad.com).

• ownerId: <Integer> The ID number of the owner to which the Indicator Exclusion List. If creating a System-level Indicator Exclusion List, do not include this field in the request body.

Note

Include both the fixedValues and variableValues fields in the request body, regardless of whether each one contains Indicator values. Otherwise, the API may return a 500 - Internal Server Error status code.

Example

{
    "name": "<string>",
    "fixedValues": {
        "data": [
            {
                "value": "<string>"
            }
        ]
    },
    "variableValues": {
        "data": [
            {
                "value": "<string>"
            }
        ]
    },
    "ownerId": 0,
}

Request Body (PUT)

The following is the request body schema for a PUT request to the /v3/security/exclusionLists endpoint:

• fixedValues: <Object> REQUIRED The fixed Indicator values to add to or remove from the Indicator Exclusion List.

  • data: <Array of Objects> An array of fixed Indicator value objects.

    • value: <String> The fixed Indicator value (e.g., badguy@bad.com ).

  • mode: <String> Specifies how to update the fixed Indicator values. (Acceptable values: append, delete, replace; Default value: replace)

• variableValues: <Object> REQUIRED The variable Indicator values to add to or remove from the Indicator Exclusion List.

  • data: <Array of Objects> An array of variable Indicator value objects.

    • value: <String> The variable Indicator value (e.g., *@bad.com).

  • mode: <String> Specifies how to update the variable Indicator values. (Acceptable values: append, delete, replace; Default value: replace)

Note

Include both the fixedValues and variableValues fields in the request body, regardless of whether each one contains Indicator values. Otherwise, the API may return a 500 - Internal Server Error status code.

Example

{
    "fixedValues": {
        "data": [
            {
                "value": "<string>"
            }
        ],
        "mode": "<string>"
    },
    "variableValues": {
        "data": [
            {
                "value": "<string>"
            }
        ],
        "mode": "<string>"
    }
}

Response Body

The default response returned for successful GET, POST, and PUT requests to the /v3/security/exclusionLists endpoint may include one or more objects with the following fields:

• id: <Integer> The Indicator Exclusion List’s ID number.

• owner: <String> The name of the owner to which the Indicator Exclusion List applies. This field will be included only for owner-level Indicator Exclusion List objects.

• ownerId: <Integer> The ID number of the owner to which the Indicator Exclusion List applies. This field will be included only for owner-level Indicator Exclusion List objects.

• name: <String> The Indicator Exclusion List’s name.

• description: <String> The Indicator Exclusion List’s description.

• active: <Boolean> Specifies whether the Indicator Exclusion list is active.

• managed: <Boolean> Specifies whether the Indicator Exclusion List is a non-custom, default Exclusion List managed at the System level.

Example

{
    "id": 0,
    "owner": "<string>",
    "ownerId": 0,
    "name": "<string>",
    "description": "<string>",
    "active": true,
    "managed": true
}

Retrieve Indicator Exclusion Lists

Requirements

• To view Indicator Exclusion Lists in an Organization, your API user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer.

• To view Indicator Exclusion Lists in a Community or Source, your API user account must have a Community role of Editor or Director for that Community or Source.

Query Parameters

The following table outlines optional query parameter(s) that may be used when sending a GET request to the /v3/security/exclusionLists endpoint.

Parameter	Description	Data Type	Default Value
fields	Returns additional fields in the API response based on the specified value(s).	String	N/A
owner	Filters custom Indicator Exclusion Lists by owner. Note that default Indicator Exclusion Lists managed at the System-level will still be included in the response.	String	N/A
resultLimit	The maximum number of objects to include each result set within the API response.	Integer	100
resultStart	The starting index of the result set within the API response.	Integer	0
sorting	The order and field by which to sort results in the API response.	String	N/A
tql	Filters results based on the provided ThreatConnect Query Language (TQL) query.	String	N/A

Retrieve All Indicator Exclusion Lists

GET /v3/security/exclusionLists

Retrieve details about all Indicator Exclusion Lists in your owners and at the System level.

Example Request

Note

You must include the required authentication headers for the method you are using to authenticate your API request.

Request

GET /v3/security/exclusionLists

Response

{
    "data": [
        {
            "id": 1,
            "name": "Indicator-ASN-AS Number",
            "description": "1058 fixed",
            "active": true,
            "managed": true
        },
        {
            "id": 2,
            "name": "Indicator-Address-IPv4",
            "description": "106 fixed, 42 variable",
            "active": true,
            "managed": true
        },
        ...
        {
            "id": 32,
            "owner": "CAL Automated Threat Library",
            "ownerId": 22,
            "name": "Indicator-Host",
            "description": "1 fixed",
            "active": true,
            "managed": false
        },
        {
            "id": 33,
            "name": "Indicator-File-SHA256",
            "description": "1 fixed",
            "active": true,
            "managed": false
        }
    ],
    "status": "Success"
}

Retrieve a Specific Indicator Exclusion List

GET /v3/security/exclusionLists/{id}

Retrieve details about a specific Indicator Exclusion List.

Example Request

Note

You must include the required authentication headers for the method you are using to authenticate your API request.

Request

GET /v3/security/exclusionLists/30

Response

{
    "data": {
        "id": 30,
        "owner": "Demo Organization",
        "ownerId": 1,
        "name": "Address-IPv6",
        "description": "1 fixed, 1 variable",
        "active": true,
        "managed": false
    },
    "status": "Success"
}

To include the Indicator values on an Indicator Exclusion List, use the fields query parameter in the request and assign it a value of values:

Request

GET /v3/security/exclusionLists/30?fields=values

Response

{
    "data": {
        "id": 30,
        "owner": "Demo Organization",
        "ownerId": 1,
        "name": "Address-IPv6",
        "description": "1 fixed, 1 variable",
        "fixedValues": {
            "data": [
                {
                    "value": "2001:500:12::d0d"
                }
            ],
            "count": 1
        },
        "variableValues": {
            "data": [
                {
                    "value": "100::/64"
                }
            ],
            "count": 1
        },
        "active": true,
        "managed": false
    },
    "status": "Success"
}

Create Indicator Exclusion Lists

POST /v3/security/exclusionLists

Create a custom Indicator Exclusion List with the specified fixed and variable Indicator values.

Requirements

• To create custom Indicator Exclusion Lists in an Organization, your API user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer.

• To create custom Indicator Exclusion Lists in a Community or Source, your API user account must have a Community role of Editor or Director for that Community or Source.

• To create custom Indicator Exclusion Lists at the System, Community, or Source level, your API user account’s ID number must be entered into the systemExclusionListApiAccess system setting on the System Settings screen in the ThreatConnect UI (must be a System Administrator to perform this action). For instruction on retrieving an API user account’s ID number, see Users Overview.

Query Parameters

The following table outlines optional query parameter(s) that may be used when sending a POST request to the /v3/security/exclusionLists endpoint.

Parameter	Description	Data Type	Default Value
fields	Returns additional fields in the API response based on the specified value(s).	String	N/A

Example Requests

Create a Custom Owner-Level Exclusion List

Note

In addition to the required Content-Type header, you must include the required authentication headers for the method you are using to authenticate your API request.

Request

POST /v3/security/exclusionLists
Content-Type: application/json

{
    "name": "Indicator-Address-IPv6",
    "ownerId": 1,
    "fixedValues": {
        "data": [
            {
                "value": "2001:500:12::d0d"
            }
        ]
    },
    "variableValues": {
        "data": [
            {
                "value": "100::/64"
            }
        ]
    }
}

Response

{
    "data": {
        "id": 30,
        "owner": "Demo Organization",
        "ownerId": 1,
        "name": "Indicator-Address-IPv6",
        "description": "1 fixed, 1 variable",
        "active": true,
        "managed": false
    },
    "message": "Created",
    "status": "Success"
}

Create a Custom System-Level Exclusion List

Note

In addition to the required Content-Type header, you must include the required authentication headers for the method you are using to authenticate your API request.

Request

POST /v3/security/exclusionLists
Content-Type: application/json

{
    "name": "Indicator-File-SHA256",
    "fixedValues": {
        "data": [
            {
                "value": "05503ABEA7B8AC0A01DB3CB35179242C0C1D43C7002C51E5982318244BDC4444"
            }
        ]
    },
    "variableValues": {
        "data": [
            {}
        ]
    }
}

Response

{
    "data": {
        "id": 31,
        "name": "Indicator-File-SHA256",
        "description": "1 fixed",
        "active": true,
        "managed": false
    },
    "message": "Created",
    "status": "Success"
}

Update Indicator Exclusion Lists

PUT /v3/security/exclusionLists/{id}

Update the contents of a specific custom Indicator Exclusion List.

Requirements

• To update custom Indicator Exclusion Lists in an Organization, your API user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer.

• To update custom Indicator Exclusion Lists in a Community or Source, your API user account must have a Community role of Editor or Director for that Community or Source.

• To update custom Indicator Exclusion Lists at the System, Community, or Source level, your API user account’s ID number must be entered into the systemExclusionListApiAccess system setting on the System Settings screen in the ThreatConnect UI (must be a System Administrator to perform this action). For instruction on retrieving an API user account’s ID number, see Users Overview.

Query Parameters

The following table outlines optional query parameter(s) that may be used when sending a PUT request to the /v3/security/exclusionLists endpoint.

Parameter	Description	Data Type	Default Value
fields	Returns additional fields in the API response based on the specified value(s).	String	N/A

Example Request

Note

In addition to the required Content-Type header, you must include the required authentication headers for the method you are using to authenticate your API request.

Request

PUT /v3/security/exclusionLists/30
Content-Type: application/json

{
    "fixedValues": {
        "data": [
            {
                "value": "2001:500:1::53"
            }
        ],
        "mode": "append"
    },
    "variableValues": {
        "data": [
            {
                "value": "100::/64"
            }
        ],
        "mode": "delete"
    }
}

Response

{
    "data": {
        "id": 30,
        "owner": "Demo Organization",
        "ownerId": 1,
        "name": "Indicator-Address-IPv6",
        "description": "2 fixed",
        "active": true,
        "managed": false
    },
    "message": "Updated",
    "status": "Success"
}

Delete Indicator Exclusion Lists

DELETE /v3/security/exclusionLists/{id}

Delete a specific custom Indicator Exclusion List.

Attention

You cannot delete default Indicator Exclusion Lists (that is, Indicator Exclusion Lists for which managed is true).

Requirements

• To delete custom Indicator Exclusion Lists in an Organization, your API user account must have an Organization role of Standard User, Sharing User, Organization Administrator, or App Developer.

• To delete custom Indicator Exclusion Lists in a Community or Source, your API user account must have a Community role of Editor or Director for that Community or Source.

• To delete custom Indicator Exclusion Lists at the System, Community, or Source level, your API user account’s ID number must be entered into the systemExclusionListApiAccess system setting on the System Settings screen in the ThreatConnect UI (must be a System Administrator to perform this action). For instruction on retrieving an API user account’s ID number, see Users Overview.

Example Request

Note

You must include the required authentication headers for the method you are using to authenticate your API request.

Request

DELETE /v3/security/exclusionLists/30

Response

{
    "message": "Deleted",
    "status": "Success"
}