Get Indicator Metadata¶

POST /1.3/indicators/metadata

Warning

This endpoint has replaced GET /1.3/indicators/{value}/metadata and GET /1.3/indicators/metadata, which have been deprecated.

Description¶

Provide metadata associated with an indicator, including: indicatorType, value, priorityLevel, noteCount, sightings, firstSeen, lastSeen, enclaveIds, tags (each tag contains guid, name, and enclaveId attributes), source, notes, and guid. The metadata is determined based on the enclaves the user making the request has READ access to. The source attribute will only be returned if the indicator was submitted to Station through the “Submit Indicators” endpoint (POST /1.3/indicators) (docs here: https://docs.trustar.co/api/v13/indicators/submit_indicators.html ). If the indicator was extracted from a report that the user submitted to Station, it will not have a source attribute.

The request method must be POST because a JSON body is required for the request.

Parameters¶

Query String Parameters¶

Parameter	Required	Default	Description
enclaveIds		all of the user’s enclaves	A list of enclave IDs to restrict to. All information returned will pertain only to these enclaves.

Request Body Parameters¶

The request JSON body must be a well-formed JSON list, where each entry is an object with the following values.

Parameter	Required	Default	Description
value	X		The indicator value to query.
indicatorType			The indicator type. This parameter is only necessary in rare cases where an indicator value has been associated with multiple types due to context.

Note

If the indicatorType field is used, it must be present for all entries in the list.

Warning

If you experience repeated failures when querying this endpoint for the metadata for hundreds / thousands of indicators, try breaking your list into smaller lists of 500 indicators or less each.

Warning

Some IOCs just do not work with this endpoint and their presence in the list of indicators submitted to this endpoint will cause the entire endpoint call to fail and return an error. You may need to repeatedly split your list until you isolated those culprits. If you find them, send an email to support@trustar.co describing the situation and the measures you took, and a member of the customer success team will reach out to you to resolve it.

Response (200)¶

An indicator metadata object containing the metadata for the requested indicator.

Example Usage¶

“indicatorType” not specified:

curl -k -H "Content-Type: application/json" -X POST -d '[{"value":"1.2.3.4"}, {"value":"www.example.com"}]' -H "Authorization: Bearer {token}" "https://api.trustar.co/api/1.3/indicators/metadata"

“indicatorType” specified:

curl -k -H "Content-Type: application/json" -X POST -d '[{"value":"1.2.3.4", "indicatorType":"IP"}, {"value":"www.example.com", "indicatorType":"URL"]' -H "Authorization: Bearer {token}" "https://api.trustar.co/api/1.3/indicators/metadata"

Request Body¶

[
    {
        "value": "1.2.3.4"
    },
    {
        "value": "www.example.com"
    }
]

Response¶

 [
     {
         "indicatorType": "IP",
         "value": "1.2.3.4",
         "priorityLevel": "LOW",
         "noteCount": 3,
         "sightings": 6,
         "firstSeen": 1532495940000,
         "lastSeen": 1532495940000,
         "enclaveIds": [
             "4dfb66f8-1dfc-406d-a0ed-b517ff043053"
         ],
         "tags": [
             {
                 "guid": "c05436cf-db96-41a9-b4bc-d182befcf961",
                 "name": "tag_2",
                 "enclaveId": "4dfb66f8-1dfc-406d-a0ed-b517ff043053"
             },
             {
                 "guid": "aaa4968c-39c9-4c2f-9591-5fa140fa388c",
                 "name": "tag_1",
                 "enclaveId": "4dfb66f8-1dfc-406d-a0ed-b517ff043053"
             }
         ],
         "source": "Somewhere",
         "notes": [
             "First note.", "Second note.", "Third note."
         ],
         "guid": "IP|1.2.3.4"
     },
     {
         "indicatorType": "URL",
         "value": "www.example.com",
         "priorityLevel": "LOW"
         "noteCount": 3,
         "sightings": 8,
         "lastSeen": 1532495940000,
         "enclaveIds": [
             "4dfb66f8-1dfc-406d-a0ed-b517ff043053"
         ],
         "tags": [
             {
                 "guid": "7cf538a8-f8d5-469d-9dbb-9b3762ea7dbb",
                 "name": "a_different_tag",
                 "enclaveId": "4dfb66f8-1dfc-406d-a0ed-b517ff043053"
             },
             {
                 "guid": "c05436cf-db96-41a9-b4bc-d182befcf961",
                 "name": "tag_2",
                 "enclaveId": "4dfb66f8-1dfc-406d-a0ed-b517ff043053"
             },
             {
                 "guid": "aaa4968c-39c9-4c2f-9591-5fa140fa388c",
                 "name": "tag_1",
                 "enclaveId": "4dfb66f8-1dfc-406d-a0ed-b517ff043053"
             }
         ],
         "source": "Somewhere else",
         "notes": [
             "This is a note.", "This is a second note.", "This is third note."
         ],
         "guid": "URL|www.example.com"
     }
]