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 =, ^

Note

=, <, >, and ^ operators need to be escaped in the API query URL as: %3D, %3C, %3E, and %5E respectively.

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
  • incidents
  • 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.

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.