Submitting Connections Between Data

ThreatExchange supports creating connections (also known as edges or relations) between ThreatIndicator objects to express relationships. Examples of when this can be useful are for describing URL redirect chains or domain-to-IP-address relationships.

Notes:

  • These indicator-to-indicator connections will soon be deprecated in favor of a new descriptor-to-descriptor relation -- which will also feature a user-selectable enumeration for the type of relation.
  • This feature is not currently supported for Malware or MalwareFamily objects, but may be in the future.

Using the UI

When you connect one descriptor to another, you must own one or the other.

Within the view/edit popup for a given descriptor, you'll need the IDs of the descriptor(s) to connect it to. So we need to first get the IDs to be connected to. Let's start with any search results -- in this case, testing-relation-editing. Let's go ahead and connect the first one to the next two.


Let's select the IDs of the next two descriptors and poke the copy-IDs-to-clipboard button:


Next let's poke the View/Edit button on the first descriptor, paste in the IDs, and then Add Relation:


The results are saved:

Using the UI for bulk relations

Just like the above, we can say that multiple descriptors are related to another one.

Here we do a query -- in this case, for a particular tag -- but this could be any set of descriptors. Then we select the "Bulk relate" button.

Then we supply the ID of the related-to indicator and select OK.

Using the UI for bulk upload

Please also see the Submitting Data page. There are optional columns you can use to bulk-relate:

  • The descriptors you want to relate your new one to must already exist.
  • You can specify the relate-to descriptors by ID using the td_related_ids_for_upload column.
  • Alternatively, you can specify the relate-to descriptors using the td_related_triples_for_upload column -- please provide the owner-app ID, indicator type, and indicator text which will uniquely identify the linked-to descriptors.

CSV example (written vertically for convenience):

td_description                Testing bulk upload
td_status                     NON_MALICIOUS
td_confidence                 100
td_severity                   INFO
td_share_level                AMBER
td_indicator_type             HASH_MD5
td_raw_indicator              e8b19da37825a3056e84c522f05eb000
td_visibility                 HAS_WHITELIST
td_subjective_tags            testing
td_whitelist_apps             494491891138576:Media Hash Sharing RF Test
td_privacy_groups             
td_review_status              REVIEWED_MANUALLY
td_related_ids_for_upload     2515798535123892,2376386079125415
td_related_triples_for_upload 

td_description                Testing bulk upload
td_status                     NON_MALICIOUS
td_confidence                 100
td_severity                   INFO
td_share_level                AMBER
td_indicator_type             HASH_MD5
td_raw_indicator              e8b19da37825a3056e84c522f05eb001
td_visibility                 HAS_WHITELIST
td_subjective_tags            pwny;testing
td_whitelist_apps             494491891138576:Media Hash Sharing RF Test
td_privacy_groups             
td_review_status              REVIEWED_MANUALLY
td_related_ids_for_upload     
td_related_triples_for_upload 494491891138576:HASH_MD5:e8b19da37825a3056e84c522f05eb000,494491891138576:HASH_MD5:e8b19da37825a3056e84c522f05eb002

JSON example:

[
  {
    "td_description": "Testing bulk upload/relate",
    "td_status": "NON_MALICIOUS",
    "td_confidence": 100,
    "td_severity": "INFO",
    "td_share_level": "AMBER",
    "td_indicator_type": "HASH_MD5",
    "td_raw_indicator": "e8b19da37825a3056e84c522f05eb000",
    "td_visibility": "HAS_WHITELIST",
    "td_subjective_tags": ["testing"],
    "td_whitelist_apps": [
      {
        "id": "494491891138576",
        "name": "Media Hash Sharing RF Test"
      }
    ],
    "td_privacy_groups": [],
    "td_review_status": "REVIEWED_MANUALLY",
    "td_related_ids_for_upload": ["2515798535123892","2376386079125415"]
  },
  {
    "td_description": "Testing bulk upload/relate",
    "td_status": "NON_MALICIOUS",
    "td_confidence": 100,
    "td_severity": "INFO",
    "td_share_level": "AMBER",
    "td_indicator_type": "HASH_MD5",
    "td_raw_indicator": "e8b19da37825a3056e84c522f05eb001",
    "td_visibility": "HAS_WHITELIST",
    "td_subjective_tags": ["pwny", "testing"],
    "td_whitelist_apps": [
      {
        "id": "494491891138576",
        "name": "Media Hash Sharing RF Test"
      }
    ],
    "td_privacy_groups": [],
    "td_review_status": "REVIEWED_MANUALLY",
    "td_related_triples_for_upload": [
      {
        "owner_app_id": "494491891138576",
        "td_indicator_type": "HASH_MD5",
        "td_raw_indicator": "e8b19da37825a3056e84c522f05eb000"
      },
      {
        "owner_app_id": "494491891138576",
        "td_indicator_type": "HASH_MD5",
        "td_raw_indicator": "e8b19da37825a3056e84c522f05eb002"
      }
    ]
  }
]
      

Using the API

Using the API, connections are created via an HTTP POST request to the /related URI for a specific object:

https://graph.facebook.com/v2.8/<object_id>/related

In the example below we will create a connection between between the facebook.com domain object (788497497903212) and the 173.252.120.6 IP address object (1061383593887032), which facebook.com can resolve to via DNS.

https://graph.facebook.com/v2.8/788497497903212/related

POST DATA:
related_id=1061383593887032
&amp;access_token=<access_token>

Data returned:

{
"success": true
}