Intelligence Requirements

An Intelligence Requirement (IR) is a collection of topics or a research question reflecting an organization’s cyber threat–related priorities that guides a security or threat intelligence team’s research and analysis efforts.

Endpoint: /api/v3/intelRequirements

Endpoint Options

Available Fields

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

OPTIONS /v3/intelRequirements

Hint

To include read-only fields in the response, append ?show=readonly to the end of the request URL.

Include Additional Fields in Responses

When creating, retrieving, or updating data, you can use the fields query parameter to include additional fields in the API response that are not included by default.

Send the following request to retrieve a list of fields you can include in responses returned from the /v3/intelRequirements endpoint:

OPTIONS /v3/intelRequirements/fields

Filter Results

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 use when including the tql query parameter in a request to the /v3/intelRequirements endpoint:

OPTIONS /v3/intelRequirements/tql

Schemas

Request Body (POST)

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

  • associatedArtifacts: <Object> A list of Artifacts associated to the IR.
  • associatedCases: <Object> A list of Cases associated to the IR.
  • associatedGroups: <Object> A list of Groups associated to the IR.
  • associatedIndicators: <Object> A list of Indicators associated to the IR.
  • associatedVictimAssets: <Object> A list of Victim Assets associated to the IR.
  • category: <Object> The IR’s category. To specify the category, use its ID number, name, or both.
    • id: <Integer> The IR category’s ID number.

    • name: <String> The IR category’s name.

  • description: <String> A description of the IR.

  • keywordSections: <Array> REQUIRED The sections that the IR’s keyword query contains.
    • compareValue: <String> REQUIRED Specifies whether the section is an includes or excludes section. (Accepted values: includes, excludes)

    • keywords: <Array of Objects> REQUIRED A list of keywords that the section contains. Note that the total number of keywords added to an IR must not exceed the IR keyword limit configured by your System Administrator (the default limit is 300 keywords). Otherwise, a 400 Bad Request error will be returned.
    • sectionNumber: <Integer> REQUIRED The section number for the keyword section.

  • requirementText: <String> REQUIRED The IR’s summary (i.e., the question, topic, or statement on which the IR focuses). The summary provided cannot be the same as the summary for an existing IR on the ThreatConnect instance.

  • resetResults: <Boolean> Specifies whether to include results that have been archived or marked as false results the next time results are retrieved for the IR.

  • subtype: <Object> REQUIRED The IR’s subtype.
  • tags: <Object> A list of Tags applied to the IR.
  • uniqueId: <String> REQUIRED The IR’s unique ID. The ID provided cannot be the same as the ID for an existing IR on the ThreatConnect instance.

  • xid: <String> The IR’s unique XID. The XID provided cannot be the same as the XID for an existing IR on the ThreatConnect instance.

Example

{
    "associatedArtifacts": {
        "data": [
            {
                "<artifactsFieldName>": <artifactsFieldValue>
            }
        ]
    },
    "associatedCases": {
        "data": [
            {
                "<casesFieldName>": <casesFieldValue>
            }
        ]
    },
    "associatedGroups": {
        "data": [
            {
                "<groupsFieldName>": <groupsFieldValue>
            }
        ]
    },
    "associatedIndicators": {
        "data": [
            {
                "<indicatorsFieldName>": <indicatorsFieldValue>
            }
        ]
    },
    "associatedVictimAssets": {
        "data": [
            {
                "<victimAssetsFieldName>": <victimAssetsFieldValue>
            }
        ]
    },
    "category": {
        "id": <int>,
        "name": <string>
    },
    "description": "<string>",
    "keywordSections": [
        {
            "compareValue": "<string>",
            "keywords": [
                {
                    "value": "<string>"
                }
            ],
            "sectionNumber": <int>
        }
    ],
    "requirementText": "<string>",
    "resetResults": <boolean>,
    "subtype": {
        "id": <int>
    },
    "tags": {
        "data": [
            {
                "<tagsFieldName>": <tagsFieldValue>
            }
        ]
    },
    "uniqueId": "<string>",
    "xid": "<string>"
}

Request Body (PUT)

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

  • associatedArtifacts: <Object> A list of Artifacts associated to the IR.
    • data: <Array of Artifact Objects> The details of the Artifacts.

    • mode: <String> Specifies the action to perform with the objects defined in the data field. (Accepted values: append, delete, replace; Default value: append).

  • associatedCases: <Object> A list of Cases associated to the IR.
    • data: <Array of Case Objects> The details of the Cases.

    • mode: <String> Specifies the action to perform with the objects defined in the data field. (Accepted values: append, delete, replace; Default value: append).

  • associatedGroups: <Object> A list of Groups associated to the IR.
    • data: <Array of Group Objects> The details of the Groups.

    • mode: <String> Specifies the action to perform with the objects defined in the data field. (Accepted values: append, delete, replace; Default value: append).

  • associatedIndicators: <Object> A list of Indicators associated to the IR.
    • data: <Array of Indicator Objects> The details of the Indicators.

    • mode: <String> Specifies the action to perform with the objects defined in the data field. (Accepted values: append, delete, replace; Default value: append).

  • associatedVictimAssets: <Object> A list of Victim Assets associated to the IR.
    • data: <Array of Victim Asset Objects> The details of the Victim Assets.

    • mode: <String> Specifies the action to perform with the objects defined in the data field. (Accepted values: append, delete, replace; Default value: append).

  • category: <Object> The IR’s category. To specify the category, use its ID number, name, or both.
    • id: <Integer> The IR category’s ID number.

    • name: <String> The IR category’s name.

  • description: <String> A description of the IR.

  • keywordSections: <Array> The sections that the IR’s keyword query contains.
    • compareValue: <String> Specifies whether the section is an includes or excludes section. (Accepted values: includes, excludes)

    • keywords: <Array of Objects> A list of keywords that the section contains. Note that the total number of keywords added to an IR must not exceed the IR keyword limit configured by your System Administrator (the default limit is 300 keywords). Otherwise, a 400 Bad Request error will be returned.
    • sectionNumber: <Integer> The section number for the keyword section.

  • requirementText: <String> The IR’s summary (i.e., the question, topic, or statement on which the IR focuses). The summary provided cannot be the same as the summary for an existing IR on the ThreatConnect instance.

  • resetResults: <Boolean> Specifies whether to include results that have been archived or marked as false results the next time results are retrieved for the IR.

  • subtype: <Object> The IR’s subtype.
  • tags: <Object> A list of Tags applied to the IR.
    • data: <Array of Tag Objects> The details of the Tags.

    • mode: <String> Specifies the action to perform with the objects defined in the data field. (Accepted values: append, delete, replace; Default value: append).

  • uniqueId: <String> The IR’s unique ID. The ID provided cannot be the same as the ID for an existing IR on the ThreatConnect instance.

Example

{
    "associatedArtifacts": {
        "data": [
            {
                "<artifactsFieldName>": <artifactsFieldValue>
            }
        ],
        "mode": "<string>"
    },
    "associatedCases": {
        "data": [
            {
                "<casesFieldName>": <casesFieldValue>
            }
        ],
        "mode": "<string>"
    },
    "associatedGroups": {
        "data": [
            {
                "<groupsFieldName>": <groupsFieldValue>
            }
        ],
        "mode": "<string>"
    },
    "associatedIndicators": {
        "data": [
            {
                "<indicatorsFieldName>": <indicatorsFieldValue>
            }
        ],
        "mode": "<string>"
    },
    "associatedVictimAssets": {
        "data": [
            {
                "<victimAssetsFieldName>": <victimAssetsFieldValue>
            }
        ],
        "mode": "<string>"
    },
    "category": {
        "id": <int>,
        "name": <string>
    },
    "description": "<string>",
    "keywordSections": [
        {
            "compareValue": "<string>",
            "keywords": [
                {
                    "value": "<string>"
                }
            ],
            "sectionNumber": <int>
        }
    ],
    "requirementText": "<string>",
    "resetResults": <boolean>,
    "subtype": {
        "id": <int>
    },
    "tags": {
        "data": [
            {
                "<tagsFieldName>": <tagsFieldValue>
            }
        ],
        "mode": "<string>"
    },
    "uniqueId": "<string>"
}

Response Body

The default response returned from successful GET, POST, and PUT requests to the /v3/intelRequirements endpoint includes one or more objects with the following fields:

  • id: <Integer> The IR’s ID number. Note that this is not the same ID as the one specified for the uniqueId field when the IR was created or updated.

  • xid: <String> The IR’s XID. This field is only included in the response body when a value has been assigned to it.

  • createdBy: <Object> The details of the user who created the IR.
    • id: <Integer> The ID of the user’s account.

    • username: <String> The username of the user’s account.

    • firstName: <String> The user’s first name.

    • lastName: <String> The user’s last name.

    • pseudonym: <String> The user’s pseudonym.

    • owner: <String> The Organization to which the user’s account belongs.

  • lastModified: <DateTime> The date and time when the IR was last modified (ISO 8601 format).

  • webLink: <String> The URL for the IR’s Details screen in ThreatConnect.

  • dateAdded: <DateTime> The date and time when the IR was created (ISO 8601 format).

  • uniqueId: <String> The IR’s unique ID.

  • requirementText: <String> The IR’s summary (i.e., the question, topic, or statement on which the IR focuses).

  • subtype: <Object> The details of the IR’s subtype.
    • name: <String> The name of the IR’s subtype.

    • description: <String> A description of the IR’s subtype.

  • category: <Object> The details of the IR’s category. This field is only included in the response body when a value has been assigned to it.
    • name: <String> The value of the IR’s category.

    • description: <String> A description of the IR’s category.

  • description: <String> A description of the IR. This field is only included in the response body when a value has been assigned to it.

  • keywordSections: <Array of Objects> The details of the sections that the IR’s keyword query contains.
    • compareValue: <String> Specifies whether the section is an includes or excludes section.

    • keywords: <Array of Objects> A list of keywords that the section contains.
      • value: <String> The keyword’s value.

  • resultsLink: <String> A link to view the local and global results for the IR’s keyword query.

Example

{
    "id": <int>,
    "xid": "<string>",
    "createdBy": {
        "id": <int>,
        "userName": "<string>",
        "firstName": "<string>",
        "lastName": "<string>",
        "pseudonym": "<string>",
        "owner": "<string>"
    },
    "lastModified": "<datetime>",
    "webLink": "<string>",
    "dateAdded": "<datetime>",
    "uniqueId": "<string>",
    "requirementText": "<string>",
    "subtype": {
        "name": "<string>",
        "description": "<string>
    },
    "category": {
        "name": "<string>",
        "description": "<string>"
    },
    "description": "<string>",
    "keywordSections": [
        {
            "compareValue": "<string>",
            "keywords": [
                {
                    "value": "<string>"
                }
            ]
        }
    ],
    "resultsLink": "<string>"
}

Create Intelligence Requirements

Send a request in the following format to create an IR in your Organization. Note that the request body in this example includes only a subset of the fields that can be included.

Request

POST /v3/intelRequirements
Content-Type: application/json

{
    "category": {
        "name": "CISO Priorities"
    },
    "description": "This IR is used to track threats to medical device companies.",
    "keywordSections": [
        {
            "compareValue": "includes",
            "keywords": [
                {
                    "value": "medical device companies"
                },
                {
                    "value": "healthcare"
                },
                {
                    "value": "mangled spider"
                },
                {
                    "value": "threats to medical"
                }
            ],
            "sectionNumber": 0
        },
        {
            "compareValue": "excludes",
            "keywords": [
                {
                    "value": "mrap"
                }
            ],
            "sectionNumber": 0
        }
    ],
    "requirementText": "Threats to Medical Device Companies",
    "subtype": {
        "id": 1
    },
    "uniqueId": "IR-010"
}

Response

{
    "data": {
        "id": 10,
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2023-09-18T14:06:26Z ",
        "webLink": "https://app.threatconnect.com/#/details/intel-requirements/10/overview",
        "dateAdded": "2023-09-18T14:06:24Z",
        "uniqueId": "IR-010",
        "requirementText": "Threats to Medical Device Companies",
        "subtype": {
            "name": "Intelligence Requirement (IR)",
            "description": "Threats of overall concern to the organization (e.g., cyber, fraud, geopolitical/physical threats)"
        },
        "category": {
            "name": "CISO Priorities",
            "description": "IRs prioritized for the CISO"
        },
        "description": "This IR is used to track threats to medical device companies.",
        "keywordSections": [
            {
                "compareValue": "includes",
                "keywords": [
                    {
                        "value": "medical device companies"
                    },
                    {
                        "value": "healthcare"
                    },
                    {
                        "value": "mangled spider"
                    },
                    {
                        "value": "threats to medical"
                    }
                ]
            },
            {
                "compareValue": "excludes",
                "keywords": [
                    {
                        "value": "mrap"
                    }
                ]
            }
        ],
        "resultsLink": "https://app.threatconnect.com/v3/intelRequirements/results?tql=intelReqId=10"
    },
    "message": "Created",
    "status": "Success"
}

Retrieve Intelligence Requirements

Retrieve All Intelligence Requirements

Send the following request to retrieve data for all IRs:

Request

GET /v3/intelRequirements

Response

{
    "data": [
        {
            "id": 1,
            "createdBy": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmith",
                "owner": "Demo Organization"
            },
            "lastModified": "2023-08-29T14:58:55Z",
            "webLink": "https://app.threatconnect.com/#/details/intel-requirements/1/overview",
            "dateAdded": "2023-08-29T13:18:01Z",
            "uniqueId": "IR-001",
            "requirementText": "Double Secret Probation",
            "subtype": {
                "name": "Intelligence Requirement (IR)",
                "description": "Threats of overall concern to the organization (e.g., cyber, fraud, geopolitical/physical threats)"
            },
            "category": {
                "name": "CISO Priorities",
                "description": "IRs prioritized for the CISO"
            },
            "description": "Keeping an eye on Delta House",
            "keywordSections": [
                {
                    "compareValue": "includes",
                    "keywords": [
                        {
                            "value": "Higher Education"
                        }
                    ]
                }
            ],
            "resultsLink": "https://app.threatconnect.com/v3/intelRequirements/results?tql=intelReqId=1"
        },
        {
            "id": 2,
            "createdBy": {
                "id": 1,
                "userName": "[email protected]",
                "firstName": "John",
                "lastName": "Smith",
                "pseudonym": "jsmith",
                "owner": "Demo Organization"
            },
            "lastModified": "2023-08-29T14:54:44Z",
            "webLink": "https://app.threatconnect.com/#/details/intel-requirements/2/overview",
            "dateAdded": "2023-08-29T13:23:15Z",
            "uniqueId": "IR-002",
            "requirementText": "SHINRA",
            "subtype": {
                "name": "Priority Intelligence Requirement (PIR)",
                "description": "Focus on threat actors' motives, TTPs, targeting, impact, or attribution in association with IRs"
            },
            "description": "Intel on Shinra Electric Corp",
            "keywordSections": [
                {
                    "compareValue": "includes",
                    "keywords": [
                        {
                            "value": "Electric"
                        },
                        {
                            "value": "Electric Infrastructure"
                        },
                        {
                            "value": "Grid Infrastructure"
                        },
                        {
                            "value": "Electric Grid"
                        }
                    ]
                }
            ],
            "resultsLink": "https://app.threatconnect.com/v3/intelRequirements/results?tql=intelReqId=2"
        },
        {...}
    ],
    "status": "Success"
}

Retrieve a Specific Intelligence Requirement

Send a request in the following format to retrieve data for a specific IR. Note that {intelRequirementId} represents the value of the id field for an IR, not the value of the uniqueId field.

Example Request

GET /v3/intelRequirements/{intelRequirementId}

For example, the following request will retrieve data for the IR whose ID is 10:

Request

GET /v3/intelRequirements/10

Response

{
    "data": {
        "id": 10,
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2023-09-18T14:06:26Z",
        "webLink": "https://app.threatconnect.com/#/details/intel-requirements/10/overview",
        "dateAdded": "2023-09-18T14:06:24Z",
        "uniqueId": "IR-010",
        "requirementText": "Threats to Medical Device Companies",
        "subtype": {
            "name": "Intelligence Requirement (IR)",
            "description": "Threats of overall concern to the organization (e.g., cyber, fraud, geopolitical/physical threats)"
        },
        "category": {
            "name": "CISO Priorities",
            "description": "IRs prioritized for the CISO"
        },
        "description": "This IR is used to track threats to medical device companies.",
        "keywordSections": [
            {
                "compareValue": "includes",
                "keywords": [
                    {
                        "value": "medical device companies"
                    },
                    {
                        "value": "healthcare"
                    },
                    {
                        "value": "mangled spider"
                    },
                    {
                        "value":  "threats to medical"
                    }
                ]
            },
            {
                "compareValue": "excludes",
                "keywords": [
                    {
                        "value": "mrap"
                    }
                ]
            }
        ],
        "resultsLink": "https://app.threatconnect.com/v3/intelRequirements/results?tql=intelReqId=10"
    },
    "status": "Success"
}

Update Intelligence Requirements

Send a request in the following format to update a specific IR. Note that {intelRequirementId} represents the value of the id field for an IR, not the value of the uniqueId field.

Example Request

PUT /v3/intelRequirements/{intelRequirementId}
Content-Type: application/json

{
    "<fieldName>": <fieldValue>
}

For example, the following request will update the keywords used in the keyword query for the IR whose ID is 10 and associate the IR to the Group whose ID is 15:

Warning

When updating the keywords used in an IR’s keyword query, the keywords specified within the keywordSections field will replace all existing keywords used in the query.

Hint

To include the associatedGroups field in the response body, append ?fields=associatedGroups to the end of the request URI.

Request

PUT /v3/intelRequirements/10
Content-Type: application/json

{
    "associatedGroups": {
        "data": [
            {
                "id": 15
            }
        ]
    },
    "keywordSections": [
        {
            "compareValue": "includes",
            "keywords": [
                {
                    "value": "medical device companies"
                },
                {
                    "value": "healthcare"
                },
                {
                    "value": "mangled spider"
                },
                {
                    "value": "threats to medical"
                },
                {
                    "value": "medical device"
                }
            ],
            "sectionNumber": 0
        },
        {
            "compareValue": "excludes",
            "keywords": [
                {
                    "value": "mrap"
                }
            ],
            "sectionNumber": 0
        }

    ]
}

Response

{
    "data": {
        "id": 10,
        "createdBy": {
            "id": 3,
            "userName": "11112222333344445555",
            "firstName": "John",
            "lastName": "Smith",
            "pseudonym": "jsmithAPI",
            "owner": "Demo Organization"
        },
        "lastModified": "2023-09-18T14:24:06Z",
        "webLink": "https://app.threatconnect.com/#/details/intel-requirements/10/overview",
        "dateAdded": "2023-09-18T14:06:24Z",
        "uniqueId": "IR-010",
        "requirementText": "Threats to Medical Device Companies",
        "subtype": {
            "name": "Intelligence Requirement (IR)",
            "description": "Threats of overall concern to the organization (e.g., cyber, fraud, geopolitical/physical threats)"
        },
        "category": {
            "name": "CISO Priorities",
            "description": "IRs prioritized for the CISO"
        },
        "description": "This IR is used to track threats to medical device companies.",
        "keywordSections": [
            {
                "compareValue": "includes",
                "keywords": [
                    {
                        "value": "medical device companies"
                    },
                    {
                        "value": "healthcare"
                    },
                    {
                        "value": "mangled spider"
                    },
                    {
                        "value":  "threats to medical"
                    },
                    {
                        "value":  "medical device"
                    }
                ]
            },
            {
                "compareValue": "excludes",
                "keywords": [
                    {
                        "value": "mrap"
                    }
                ]
            }
        ],
        "resultsLink": "https://app.threatconnect.com/v3/intelRequirements/results?tql=intelReqId=10"
    },
    "message": "Updated",
    "status": "Success"
}

Delete Intelligence Requirements

Send a request in the following format to delete an IR. Note that {intelRequirementId} represents the value of the id field for an IR, not the value of the uniqueId field.

Example Request

DELETE /v3/intelRequirements/{intelRequirementId}

For example, the following request will delete the IR whose ID is 10:

Request

DELETE /v3/intelRequirements/10

Response

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

Associations

For instructions on creating and managing associations for IRs, see Create and Manage Associations.