Submit Indicators

POST /1.3/indicators

Description

Submit indicators directly. Indicator value is required, other metadata is optional: firstSeen, lastSeen, sightings, notes, tags, and source. The submission must specify enclaves for the indicators to be submitted to, and can optionally specify tags to assign to all the indicators in the submission, and/or include individual tags in each indicator (which will take precedence over the submission tags). The tags can be existing or new, and are identified by name and enclaveId.

Accepted submissions will be processed and the user will be notified by email when the processing is complete. An accepted submission must have valid indicator content and enclave distribution.

Warning

If a submission contains more than 10,000 indicators, it will be rejected with a 413 (payload too large) error code. See here for details.

Parameters

The request JSON body must be a well-formed JSON object with the following fields:

Parameter	Required	Default	Description
content	X		Indicator content. Must be a JSON array of at least one row.
enclaveIds	X		Array of TruSTAR-generated enclave ids (available on Station under settings or through the GET /enclaves endpoint). Use the enclave ID, NOT the enclave name.
tags			Array of Tag objects to assign the submission. Tag name and enclaveId must be specified for each tag.

The indicator rows in the content field of the request body must match the following structure:

Parameter	Required	Default	Description
value	X		Indicator value.
firstSeen			First seen timestamp for indicator in milliseconds since epoch. Must be a number.
lastSeen			Last seen timestamp for indicator in milliseconds since epoch. Must be a number.
sightings			Number of sightings for indicator. Must be a number.
source			Source of indicator.
notes			Any notes to submit with indicator.
tags			Array containing Tag objects associated with the indicator. Tag name and enclaveId must be specified for each tag.

Response (200)

Valid submissions will return with a 200 status code. Acceptance means the submission is undergoing processing and the user will receive an email after the processing is complete and the submission is ready for viewing.

Example 1

This example will submit a single indicator and apply the tags “indicator-tag-1” and “indicator-tag-2” to it. The tag “api-tag” will not be applied to any indicator in this submission and could just as well have been ommitted.

Request

{
  "enclaveIds": [
    "c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"
  ],
  "content": [
    {
      "value": "55.66.77.88",
      "firstSeen": 1522370200040,
      "lastSeen": 1522370354692,
      "sightings": 32,
      "source": "internal",
      "notes": "internal IP",
      "tags": [
        {
          "name": "indicator-tag-1",
          "enclaveId": "c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"
        },
        {
          "name": "indicator-tag-2",
          "enclaveId": "c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"
        }
      ]
    }
  ],
  "tags": [
    {
      "name": "api-tag",
      "enclaveId": "c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"
    }
  ]
}

curl -k -H "Content-Type: application/json" -X POST -d \
   '{"enclaveIds":["c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"],"content":[{"value":"55.66.77.88","sightings":32,"source":"internal","notes":"internal IP","tags":[{"name":"indicator-tag-1","enclaveId":"c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"},{"name":"indicator-tag-2","enclaveId":"c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"}]}],"tags":[{"name":"api-tag","enclaveId":"c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"}]}' \
   -H "Authorization: Bearer {access_token}" "https://api.trustar.co/api/1.3/indicators"

Response

No content.

Example 2

This example will submit a 2 indicators and apply the tags “indicator-tag-1” and “indicator-tag-2” to the first one and “api-tag” to the second indicator. Request

---

{
  "enclaveIds": [
    "c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"
  ],
  "content": [
    {
      "value": "55.66.77.85",
      "firstSeen": 1522370200040,
      "lastSeen": 1522370354692,
      "sightings": 32,
      "source": "internal",
      "notes": "internal IP",
      "tags": [
        {
          "name": "indicator-tag-1",
          "enclaveId": "c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"
        },
        {
          "name": "indicator-tag-2",
          "enclaveId": "c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"
        }
      ]
    },
    {
      "value": "55.66.77.84",
      "firstSeen": 1522370200040,
      "lastSeen": 1522370354692,
      "sightings": 25,
      "source": "internal",
      "notes": "internal IP",
    }

  ],
  "tags": [
    {
      "name": "api-tag",
      "enclaveId": "c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"
    }
  ]
}

This example will submit 2 indicators, apply 2 tags to the first indicator, and apply the tag to the second indicator that will be applied to all indicators in the “content” parameter list for which tags are not specified:

curl -k -H "Content-Type: application/json" -X POST -d \
    '{"enclaveIds":["c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"],"content":[{"value":"55.66.77.85","sightings":32,"source":"internal","notes":"internal IP","tags":[{"name":"indicator-tag-1","enclaveId":"c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"},{"name":"indicator-tag-2","enclaveId":"c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"}]},{"value":"55.66.77.84","sightings":25,"source":"internal","notes":"internal IP"}],"tags":[{"name":"api-tag-1","enclaveId":"c04caa4e-4d1b-47fc-b9e2-c9ce11396b44"}]}' \
    -H "Authorization: Bearer {access_token}" "https://api.trustar.co/api/1.3/indicators"

Response

No content.