Get Indicator Summaries¶
POST /1.3/indicators/summaries
Description¶
Provides structured summaries about indicators, which are derived from intelligence sources on the TruSTAR Marketplace that the user has access to.
Reports from many sources on the TruSTAR Marketplace represent intelligence about specific indicators. TruSTAR extracts and normalizes important information from these reports and presents them in the form of indicator summaries.
These summaries are not created by TruSTAR analysts, they are simply normalized representations of information directly extracted from reports from third-party intelligence sources on the TruSTAR Marketplace.
Severity Level¶
The severityLevel field is a normalized representation of the score field. Intelligence sources use a wide variety of different scoring systems. TruSTAR uses machine learning to map all scores to a common, discrete scale:
| Severity Level | Description |
|---|---|
| 0 | Benign |
| 1 | Low |
| 2 | Medium |
| 3 | High |
Response¶
The response JSON is a page of Indicator Summary objects.
Indicator Summary¶
A structured summary of an indicator, derived from data provided by an intelligence source about the indicator.
| Field | Type | Description |
|---|---|---|
| value | String | The indicator’s value. |
| reportId | String | The ID of the report for this summary. |
| enclaveId | String | The ID of the report’s enclave. |
| source | IntelligenceSource | An object containing information about the source that the report came from. |
| score | IndicatorScore | The score of the report, according to the source. |
| created | Integer | The created or first seen timestamp of the indicator, according to the source. |
| updated | Integer | The updated or last seen timestamp of the indicator, according to the source. |
| description | String | The description of the indicator, according to the source. |
| attributes | List[IndicatorAttribute] | A list of attributes about the indicator, according to the source. |
| severityLevel | Integer | A normalized representation of the score, on an integer scale ranging from 0 to 3, 0 being the lowest level and 3 being the highest. |
Indicator Attribute¶
An attribute of the indicator, derived from the data provided by the intelligence source.
| Field | Type | Description |
|---|---|---|
| name | String | The name of the attribute, e.g. “Actors” or “Malware Families” |
| value | Any | The value of the attribute, e.g. “North Korea” or “Emotet” |
| logical_type | String | Describes how to interpret the value field, e.g. could be “timestamp” if value is an integer. |
| description | String | A description of how to interpret this attribute. This corresponds to the attribute name, i.e. this will be the same for all attributes in a source with the same name. |
Indicator Score¶
The indicator’s score, as provided by the intelligence source.
| Field | Type | Description |
|---|---|---|
| name | String | The name of the score type, e.g. “Risk Score” or “Malicious Confidence” |
| value | String | The value of the score, as directly extracted from the source, e.g. “HIGH” or “78” |
Intelligence Source¶
An object representing the intelligence source.
| Field | Type | Description |
|---|---|---|
| key | String | A string that uniquely identifies the source, e.g. “virustotal” |
| name | String | A human-readable name of the source, as a human-readable string, e.g. “VirusTotal” |
Parameters¶
The request JSON body must be a well-formed JSON list, where each entry is the string value of an indicator, as represented in the TruSTAR system.
Warning
The indicator values must exactly match values in the TruSTAR system. In order to perform a fuzzy match, you must first use the Search Indicators endpoint to lookup the exact indicator values, then provide them to this endpoint.
Query String Parameters¶
| Parameter | Required | Default | Description |
|---|---|---|---|
| enclaveIds | all of the user’s enclaves | The enclaves to search for indicator summaries in. These should be enclaves containing data from sources on the TruSTAR Marketplace. | |
| pageSize | 25 | Size of page to return within time range. Max allowed size is 100. | |
| pageNumber | 0 | The page to start returning results from. |
Response (200)¶
A page of IndicatorSummary objects.
Example Usage¶
curl -k -H "Content-Type: application/json" -X POST -d '["LOCKY", "23.121.54.102"]' -H "Authorization: Bearer {token}" "https://api.trustar.co/api/1.3/indicators/summaries?enclaveIds=fdb4676c-1e02-47ad-b19a-24e5867c5485"
Request Body¶
[
"LOCKY",
"23.121.54.102"
]
Response¶
{
"pageNumber": 0,
"totalPages": 1,
"pageSize": 25,
"totalElements": 2,
"items": [
{
"reportId": "5dc52e41-4d22-43cc-92b2-bcca62f02a52",
"updated": 1565074829435,
"enclaveId": "fdb4676c-1e02-47ad-b19a-24e5867c5485",
"source": {
"key": "crowdstrike_indicator",
"name": "CrowdStrike"
},
"type": "MALWARE",
"value": "LOCKY",
"score": {
"name": "Malicious Confidence",
"value": "high"
},
"attributes": [
{
"name": "Malware Families",
"value": [
"njRAT"
]
},
{
"name": "Indicator Type",
"value": "campaign_id"
},
{
"name": "Relations Count",
"value": 20
}
]
},
{
"reportId": "1af288dc-9479-44ca-8ea1-b25bcaa961e3",
"updated": 1565074288021,
"enclaveId": "fdb4676c-1e02-47ad-b19a-24e5867c5485",
"source": {
"key": "crowdstrike_indicator",
"name": "CrowdStrike"
},
"type": "IP",
"value": "23.121.54.102",
"score": {
"name": "Malicious Confidence",
"value": "low"
},
"attributes": [
{
"name": "IP Address Types",
"value": [
"TorProxy"
]
},
{
"name": "Indicator Type",
"value": "ip_address"
},
{
"name": "Relations Count",
"value": 0
}
]
}
],
"empty": false,
"hasNext": false
}