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.