API Reference

Intelligence Requirement Results Overview

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. In ThreatConnect, you can review local and global results returned by an IR's keyword query and determine the appropriate course of action to take for each result: associate the result to the IR object, archive the result, or mark the result as a false result.

Endpoint: /api/v3/intelRequirements/results

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/results endpoint:

OPTIONS /v3/intelRequirements/results
👍

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/results endpoint:

OPTIONS /v3/intelRequirements/results/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/results endpoint:

OPTIONS /v3/intelRequirements/results/tql

Schemas

Response Body

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

  • id: <Integer> The result's ID number.
  • matchedDate: <DateTime> The date and time when the result matched the IR's keyword query (ISO 8601 format).
  • name: <String> The name/summary of the ThreatConnect object corresponding to the result.
  • ownerId: <Integer> The ID number of the owner of the ThreatConnect object corresponding to the result. This field is only included in the response body when the ThreatConnect object belongs to an owner.
  • ownerName: <String> The name of the owner of the owner of the ThreatConnect object corresponding to the result. This field is only included in the response body when the ThreatConnect object belongs to an owner.
  • itemId: <Integer> The ID number of the ThreatConnect object corresponding to the result. This field is only included in the response body when the ThreatConnect object belongs to an owner.
  • itemType: <String> The type of ThreatConnect object corresponding to the result.
  • internal: <Boolean> Specifies whether the result is a local result from your Organization or one of your Communities or Sources.
  • falsePositive: <Boolean> Specifies whether the result has been marked as a false result.
  • associated: <Boolean> Specifies whether the result has been associated to the IR.
  • archived: <Boolean> Specifies whether the result has been archived.
  • archivedDate: <DateTime> The date and time when the result was archived (ISO 8601 format). This field is only included in the response body when the result is archived.
  • score: <Integer> A weighted score generated by OpenSearch® that indicates the result's relevance, where a higher score indicates a more relevant result and a lower score indicates a less relevant result. This score is determined by an OpenSearch algorithm that looks for relevant occurrences of the Intelligence Requirement's keywords within the result. Note that this field is included only in the response body for local results.
{
    "id": <int>,
    "matchedDate": "<datetime>",
    "name": "<string>",
    "ownerId": <int>,
    "ownerName": "<string>",
    "itemId": <int>,
    "itemType": "<string>",
    "internal": <boolean>,
    "falsePositive": <boolean>,
    "associated": <boolean>,
    "archived": <boolean>,
    "archivedDate": "<datetime>",
    "score": <int>
}

Retrieve Intelligence Requirement Results

Retrieve All Intelligence Requirement Results

Send the following request to retrieve data for all results for all IRs in your Organization.

GET /v3/intelRequirements/results
{
    "next": "https://app.threatconnect.com/api/v3/intelRequirements/results?resultStart=100&resultLimit=100",
    "data": [
        {
            "id": 1,
            "matchedDate": "2023-08-29T16:46:58Z",
            "name": "CC9E6578A47182A941A478B276320E06 : CB872EDD1F532C10D0167C99530A65C4D4532A1E : 40AE43B7D6C413BECC92B07076FA128B875C8DBB4DA7C036639ECCF5A9FC784F",
            "ownerId": 83,
            "ownerName": "ThreatConnect Intelligence",
            "itemId": 100,
            "itemType": "File",
            "internal": false,
            "falsePositive": false,
            "associated": false,
            "archived": false
        },
        {
            "id": 2,
            "matchedDate": "2023-08-29T17:15:51Z",
            "name": "Stop DJVU - A ransomware family wreaking havoc among home users",
            "ownerId": 115,
            "ownerName": "Intel 471 Malware Intelligence",
            "itemId": 75,
            "itemType": "report",
            "internal": true,
            "falsePositive": false,
            "associated": false,
            "archived": false,
            "score": 1946    
        },
        {...}
    ]
}
👍

Hint

To filter results based on whether they've been archived, associated to their corresponding IR, or marked as a false positive, include the tql query parameter in the request URI and assign it a value of isArchived, isAssociated, or isFalsePositive, respectively.

Retrieve a Specific Intelligence Requirement Result

Send a request in the following format to retrieve data for a specific result.

GET /v3/intelRequirements/results/{resultId}

For example, the following request will retrieve data for the result whose ID is 2.

GET /v3/intelRequirements/result/2
{
    "data": {
        "id": 2,
        "matchedDate": "2023-08-29T17:15:51Z",
        "name": "Stop DJVU - A ransomware family wreaking havoc among home users",
        "ownerId": 115,
        "ownerName": "Intel 471 Malware Intelligence",
        "itemId": 2629735,
        "itemType": "report",
        "internal": true,
        "falsePositive": false,
        "associated": false,
        "archived": false,
        "score": 1946
    },
    "status": "Success"
}

Update Intelligence Requirement Results

There are three actions you can perform when working with results for an IR:

  • Archive (or unarchive) the result
  • Associate the result to the IR object
  • Mark the result as a false result (i.e., false positive)
🚧

Important

A result cannot have more than one of the following fields set to true at a given time: archived, associated, and falsePositive. Attempting to set more than two of these fields to true for a result will return an error.

Archive a Result

Send a request in the following format to archive a specific result.

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

{
    "archived": true
}

For example, the following request will archive the result whose ID is 10.

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

{
    "archived": true
}
{
    "data": {
        "id": 10,
        "matchedDate": "2023-09-20T15:49:56Z",
        "name": "C0010",
        "itemType": "campaign",
        "internal": false,
        "falsePositive": false,
        "associated": false,
        "archived": true,
        "archivedDate": "2023-09-20T15:56:49Z"
    },
    "message": "Updated",
    "status": "Success"
}
👍

Hint

To unarchive an archived result, assign the archived field a value of false in the request body of the PUT request.

Associate a Result

Send a request in the following format to associate a specific result to its IR.

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

{
    "associated": true
}

For example, the following request will associate the result whose ID is 11 to its IR.

PUT /v3/intelRequirements/results/11
Content-Type: application/json

{
    "associated": true
}
{
    "data": {
        "id": 11,
        "matchedDate": "2023-09-19T14:56:19Z",
        "name": "http://3.145.115.94/zambos_caldo_de_p.txt",
        "ownerId": 76,
        "ownerName": "abuse.ch URLHaus",
        "itemId": 1098,
        "itemType": "url",
        "internal": true,
        "falsePositive": false,
        "associated": true,
        "archived": false,
        "score": 1166
    },
    "message": "Updated",
    "status": "Success"
}
🚧

Important

When the associated field is set to true for a result, you cannot update the field's value to false manually. Instead, you must dissociate the result from its IR, which will update the associated field's value to false automatically.

📘

Note

When you associate a global result that does not exist in one of your ThreatConnect owners to an IR, a copy of the result will be created in your Organization and then associated to the IR.

Mark a Result as a False Result

Send a request in the following format to mark a result as a false result for the IR to which it corresponds.

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

{
    "falsePositive": true
}

For example, the following request will mark the result whose ID is 12 as a false result for the IR to which it corresponds.

PUT /v3/intelRequirements/results/12
Content-Type: application/json

{
    "falsePositive": true
}
{
    "data": {
        "id": 12,
        "matchedDate": "2023-09-19T14:56:19Z",
        "name": "UNC2021",
        "ownerId": 197,
        "ownerName": "Mandiant Advantage Threat Intelligence",
        "itemId": 4855856,
        "itemType": "intrusion set",
        "internal": true,
        "falsePositive": true,
        "associated": false,
        "archived": false,
        "score": 1157
    },
    "message": "Updated",
    "status": "Success"
}

Delete Intelligence Requirement Results

Send a request in the following format to delete a result.

DELETE /v3/intelRequirements/results/{resultId}

For example, the following request will delete the result ID is 14.

DELETE /v3/intelRequirements/results/14
{
    "message": "Deleted",
    "status": "Success"
}
📘

Note

Deleting a result does not delete the Artifact, Case, Group, Indicator, Tag, or Victim to which it corresponds.

OpenSearch® is a registered trademark of Amazon Web Services.

Updated over 1 year ago

Updated over 1 year ago