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 and from Communities, Security Labels provide control over what is shared and allow the sharer to redact information based on the 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 be 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": 6,
        "securityLabel": [
            {
                "name": "TLP:AMBER",
                "description": "This security label is used for information that requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved. Information with this label can be shared with members of an organization and its clients.",
                "dateAdded": "2016-08-31T00:00:00Z"
            },
            {
                "name": "TLP:AMBER+STRICT",
                "description": "This security label is used for information that requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved and the source of the information wants to restrict sharing of the information to only the organizations involved. Information with this label can only be shared with members of an organization.",
                "dateAdded": "2022-08-31T00:00:00Z"
            },
            {
                "name": "TLP:CLEAR",
                "description": "This security label is used for information that carries minimal or no foreseeable risk of misuse, in accordance with applicable rules and procedures for public release.",
                "dateAdded": "2022-08-31T00:00:00Z"
            },
            {
                "name": "TLP:GREEN",
                "description": "This security label is used for information that is useful for the awareness of all participating organizations as well as with peers within the broader community or sector.",
                "dateAdded": "2016-08-31T00:00:00Z"
            },
            {
                "name": "TLP:RED",
                "description": "This security label is used for information that cannot be effectively acted upon by additional parties, and could lead to impacts on a party's privacy, reputation, or operations if misused.",
                "dateAdded": "2016-08-31T00:00:00Z"
            },
            {
                "name": "TLP:WHITE",
                "description": "This security label is used for information that carries minimal or no foreseeable risk of misuse, in accordance with applicable rules and procedures for public release.",
                "dateAdded": "2016-08-31T00:00:00Z"
            }
        ]
    }
}

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%3AAMBER

JSON Response:

{
    "status": "Success",
    "data": {
        "securityLabel": {
            "name": "TLP:AMBER",
            "description": "This security label is used for information that requires support to be effectively acted upon, yet carries risks to privacy, reputation, or operations if shared outside of the organizations involved. Information with this label can be shared with members of an organization and its clients.",
            "dateAdded": "2016-08-31T00:00:00Z"
        }
    }
}

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%3AAMBER/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",
        "lastModified": "2017-07-13T17:51: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
attackPatterns
campaigns
coursesOfAction
documents
emails
events
incidents
intrusionSets
malware
reports
signatures
tactics
threats
tools
vulnerabilities

For example, we could use the following query to find all Incidents labeled with the TLP:AMBER Security Label:

GET /v2/securityLabels/TLP%3AAMBER/groups/incidents

You can delve further by adding the ID of an associated Group to the end of the query:

GET /v2/securityLabels/TLP%3AAMBER/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%3AAMBER/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,
        "threatAssessScore": 833,
        "calIndicatorStatus": 1,
        "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, you could use the following query to find all Address Indicators labeled with the TLP:AMBER Security Label:

GET /v2/securityLabels/TLP%3AAMBER/indicators/addresses

You can delve further by adding an associated Indicator to the end of the query like:

GET /v2/securityLabels/TLP%3AAMBER/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%3AAMBER/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"
      }
    ]
  }
}

You can delve further by adding the ID of an associated Task to the end of the query:

GET /v2/securityLabels/TLP%3AAMBER/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%3AAMBER/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"
      }
    ]
  }
}

You can delve further by adding the ID of an associated Victim to the end of the query:

GET /v2/securityLabels/TLP%3AAMBER/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 MyCustomLabel custom Security Label:

DELETE /v2/securityLabels/MyCustomLabel

JSON Response:

{
  "status": "Success"
}

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 are working with Security Labels and Groups, you may find the following links helpful:

Note

If you are working with Security Labels and Indicators, you may find the following links helpful:

Note

If you are working with Security Labels and Tasks, you may find the following links helpful:

Note

If you are working with Security Labels and Victims, you may find the following links helpful: