Security Labels¶
Security Labels included in the ThreatConnect platform provide a means to designate information stored within ThreatConnect as sensitive. When sharing data with partners or when copying data to/from Communities, Security Labels provide control over what is shared and allow the sharer to redact information based on Security Labels. Security Labels can be applied to Indicators, Attributes, Groups, Tasks, and Victims in ThreatConnect.
Retrieve Security Labels¶
Filtering Security Labels¶
When retrieving Security Labels from ThreatConnect, it is possible to filter the results on the following data points:
Filter | Data Type | Operator(s) |
---|---|---|
name | string | = , ^ |
Hint
The “^” character means “starts with”. For example, this character would be used to find all URL Indicators that start with http://xn--
or all Groups whose name starts with APT
.
Note
The =
, <
, >
, and ^
operators in any filters must URL encoded as follows:
Character | URL Encoded Form |
---|---|
= | %3D |
< | %3C |
> | %3E |
^ | %5E |
The following query will return all Security Labels that start with “TLP” (name^TLP
):
GET /v2/securityLabels/?filters=name%5ETLP
The following query will return the Security Label with the name “TLP:Green” (name=TLP:Green
):
GET /v2/securityLabels/?filters=name%3DTLP%3AGreen
Retrieve All Security Labels¶
To retrieve all Security Labels, use the following query:
GET /v2/securityLabels/
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 2,
"securityLabel": [
{
"name": "TLP:Amber",
"description": "TLP:Amber information requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved.",
"dateAdded": "2017-07-13T17:50:17"
},
{
"name": "TLP:Green",
"description": "TLP:Green information is useful for the awareness of all participating organizations as well as with peers within the broader community or sector.",
"dateAdded": "2017-07-13T17:50:17"
}
]
}
}
Retrieve a Single Security Label¶
To retrieve a specific Security Label, use a query in the following format:
GET /v2/securityLabels/{securityLabel}
For example, the following query will return information about the TLP:Amber
Security Label:
GET /v2/securityLabels/TLP:Amber
JSON Response:
{
"status": "Success",
"data": {
"securityLabel": {
"name": "TLP:Amber",
"description": "TLP:Amber information requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved.",
"dateAdded": "2017-07-13T17:50:17"
}
}
}
Retrieve Items Labeled with Security Labels¶
Retrieve Labeled Groups¶
To view Groups labeled with a given Security Label, use a query in the following format:
GET /v2/securityLabels/{securityLabel}/groups
For example, the query below will retrieve all of the Groups labeled with the TLP:Amber
Security Label:
GET /v2/securityLabels/TLP:Amber/groups
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 1,
"group": [
{
"id": "54321",
"name": "IOCs_report_2017.doc",
"type": "Document",
"ownerName": "Example Organization",
"dateAdded": "2017-07-13T17:50:17",
"webLink": "https://app.threatconnect.com/auth/document/document.xhtml?document=54321"
}
]
}
}
You can also find associated Groups of a given type using the following format:
GET /v2/securityLabels/{securityLabel}/groups/{associatedGroupType}
Replace {associatedGroupType}
with one of the following Group types:
adversaries
campaigns
documents
emails
events
incidents
intrusionSets
reports
signatures
threats
For example, we could use the following query to find all Incidents labeled with the TLP:Amber
Security Label:
GET /v2/securityLabels/TLP:Amber/groups/incidents
We can also drill down even further by adding the ID of an associated Group to the end of the query such as:
GET /v2/securityLabels/TLP:Amber/groups/incidents/54321
Where 54321
is the ID of an Incident labeled with the TLP:Amber
Security Label.
Retrieve Labeled Indicators¶
To view Indicators labeled with a given Security Label, use a query in the following format:
GET /v2/securityLabels/{securityLabel}/indicators
For example, the query below will retrieve all of the Indicators labeled with the TLP:Amber
Security Label:
GET /v2/securityLabels/TLP:Amber/indicators
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 1,
"indicator": [
{
"id": "54321",
"ownerName": "Example Organization",
"type": "Address",
"dateAdded": "2017-07-13T17:50:17",
"lastModified": "2017-07-20T15:43:09Z",
"threatAssessRating": 3,
"threatAssessConfidence": 50,
"webLink": "https://app.threatconnect.com/auth/indicators/details/address.xhtml?address=0.0.0.0&owner=Example+Organization",
"summary": "0.0.0.0"
}
]
}
}
You can also find associated Indicators of a given type using the following format:
GET /v2/securityLabels/{securityLabel}/indicators/{associatedIndicatorType}
For example, we could use the following query to find all Address Indicators labeled with the TLP:Amber
Security Label:
GET /v2/securityLabels/TLP:Amber/indicators/addresses
We can also drill down even further by adding an associated Indicator to the end of the query like:
GET /v2/securityLabels/TLP:Amber/indicators/addresses/0.0.0.0
Retrieve Labeled Tasks¶
To view Tasks labeled with a given Security Label, use a query in the following format:
GET /v2/securityLabels/{securityLabel}/tasks
For example, the query below will retrieve all of the Tasks labeled with the TLP:Amber
Security Label:
GET /v2/securityLabels/TLP:Amber/tasks
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 1,
"task": [
{
"id": 12345,
"name": "Send Related Updates to IR Team",
"ownerName": "Example Organization",
"dateAdded": "2017-06-12T19:12:14Z",
"webLink": "https://app.threatconnect.com/auth/workflow/task.xhtml?task=12345",
"status": "Completed",
"escalated": true,
"reminded": true,
"overdue": false,
"dueDate": "2017-06-15T00:00:00Z",
"reminderDate": "2017-06-16T05:07:00Z",
"escalationDate": "2017-06-17T06:07:00Z"
}
]
}
}
We can also drill down even further by adding the ID of an associated Task to the end of the query such as:
GET /v2/securityLabels/TLP:Amber/tasks/12345
Where 12345
is the ID of a Task labeled with the TLP:Amber
Security Label.
Retrieve Labeled Victims¶
To view Victims labeled with a given Security Label, use a query in the following format:
GET /v2/securityLabels/{securityLabel}/victims
For example, the query below will retrieve all of the Victims labeled with the TLP:Amber
Security Label:
GET /v2/securityLabels/TLP:Amber/victims
JSON Response:
{
"status": "Success",
"data": {
"resultCount": 1,
"victim": [
{
"id": "54321",
"name": "Bad Guy",
"org": "Example Organization",
"webLink": "https://app.threatconnect.com/auth/victim/victim.xhtml?victim=54321"
}
]
}
}
We can also drill down even further by adding the ID of an associated Victim to the end of the query like:
GET /v2/securityLabels/TLP:Amber/victims/54321
Where 54321
is the ID of a Victim labeled with the TLP:Amber
Security Label.
Add Security Labels to Data Imported Via Batch API¶
The platform supports adding Security Labels via Batch API.
Users can specify this JSON Response inside their Indicator or Group:
"securityLabel": [{
"name": "TLP:GREEN",
}],
The name can be any Security Label that already exists in the user’s system. Users who wish to create a new Security Label (and have permission to do so), can provide the entire label definition as follows:
"securityLabel": [{
"name": "MyCustomLabel",
"description": "A security label I just made up.",
"color": "33FF00"
}],
Delete Security Labels¶
To delete a Security Label, use the query format below:
DELETE /v2/securityLabels/{securityLabel}
For example, the following query will delete the TLP:Amber
Security Label:
DELETE /v2/securityLabels/TLP:Amber
JSON Response:
{
"apiCalls": 1,
"resultCount": 0,
"status": "Success"
}
As you would likely expect, deleting a Security Label via the API removes that Security Label from all Groups, Indicators, and Victims which had the deleted Security Label.
Additional Links¶
Note
If you’re working with Security Labels and Groups, you may find the following links helpful:
Note
If you’re working with Security Labels and Indicators, you may find the following links helpful:
Note
If you’re working with Security Labels and Tasks, you may find the following links helpful:
Note
If you’re working with Security Labels and Victims, you may find the following links helpful: