Graph API Version

ThreatTag

A label which groups Malware, ThreatDescriptor, and/or MalwareFamily objects. Once objects are tagged, you can use tags to narrow your search queries in TE.

Fields

ParameterDescriptionType

id

Unique identifier of the threat tag

number

text

The text for this tag

string

The text of tags is case insensitive, restricted to letters, numbers, underscores, and colons, and must be UTF-8 friendly. So "שלום" is a valid text, but "#example-tag" is not.

Sample Usage

Example query for a specific ThreatTag: 908180082612873

Data returned:

{
  "id": "908180082612873",
  "text": "evilevil"
}

Example of searching for a tag by text 'evilevil'. Note that partial tag search is supported.

https://graph.facebook.com/v2.7/threat_tags/?access_token=555|aSdF123GhK&text=evilevil

Data returned:

{
  "data": [
    {
      "id": "908180082612873",
      "text": "evilevil"
    }
    ...
  ]
}

Connections

NameDescriptionType

tagged_objects

The objects tagged with this text

Malware, ThreatDescriptor, MalwareFamily

Sample Usage

Example of tagged objects for a specific ThreatTag: 908180082612873

https://graph.facebook.com/v2.7/908180082612873/tagged_objects/?access_token=555|aSdF123GhK

Data returned:

{
  "data": [
    {
      "id": "1039423046092869",
      "type": "THREAT_DESCRIPTOR",
      "name": "test1464195852.evilevillabs.com"
    },
    ...
  ]
}

Example of tagged objects for a ThreatTag with the text 'ducks'

https://graph.facebook.com/v2.7/threat_tags/?access_token=555|aSdF123GhK&text=ducks&fields=id,text,tagged_objects

Data returned:

{
  "data": [
    {
      "id": "501159930008561",
      "text": "ducks"
      "tagged_objects": {
        "data": [
          {
            "id": "1162586023812794",
            "type": "THREAT_DESCRIPTOR",
            "name": "test1469481750.evilevillabs.com"
          },
          ...
        ]
      },
    }
  ]
}

Creating a New Tag

You can create a ThreatTag on-the-fly while creating a ThreatDescriptor. If the ThreatTag does not exist, a new one will be created and applied to the new ThreatDescriptor.

https://graph.facebook.com/v2.7/threat_descriptors?access_token=555|aSdF123GhK

POST DATA:
  tags=cows,bar
  &type=DOMAIN
  &indicator=test1466722733.evilevillabs.com
  &description=this is an example with tags
  &privacy_type=VISIBLE
  &share_level=GREEN
  &status=UKNOWN

Data returned:

{
  "success": true,
  "id": "1162586023812794"
}

To create a ThreatTag without labeling any objects, you can post to the /threat_tags endpoint explicitly:

https://graph.facebook.com/v2.7/threat_tags?access_token=555|aSdF123GhK

POST DATA:
  text=superlongtagfortestingcreation
  &objects=973966502652751,898684593584287

Data returned:

{
  "success": true,
  "id": "1373232162693002"
}

Example of updating a ThreatDescriptor with more tags. If the tag does not exist, a new one will be created and applied to this ThreatDescriptor.

https://graph.facebook.com/v2.7/1162586023812794?access_token=555|aSdF123GhK

POST DATA:
  tags=ducks,chicken

Data returned:

{
  "success": true
}

Here is a list of the most popular tags categorizing data related to attacks:

NameDescription

access_token_theft

Theft of an OAuth style or similar access token

bogon

A bogus IP address

bot

A bot

brute_force

Repeated attempts to access an authenticated resource

clickjacking

Any UI redressing or similar type of attack redirecting a person's clicks

compromised

The associated party has been compromised

creeper

A party which stalks another online

drugs

Associated with drugs

email_spam

Sending of unsolicited email

explicit_content

Pornographic or otherwise explicit content

exploit_kit

A set of tools used to take advantage of vulnerabilities

fake_account

An account associated with no real entity, often used for abuse

financial

Associated with financials, perhaps fraud

ip_infringement

Infringement on the rights of an intellectual property holder

malicious_app

A malicious web app

malicious_nameserver

A malicious name server

malicious_webserver

A malicious web server

malvertising

The use of online advertising to spread malware

malware

A malware-based attack

passive_dns

Interserver DNS messages are being captured, recorded, and potentially exfiltrated

phishing

An attempt to obtain credentials via a deceptive lure

piracy

Illegal replication of protected property

prox

A proxy host

scam

A generic type of scam

scanning

Port scanning to map a network

scraping

Systematic traversal of a network and recording of data

self_xss

Attack where a person is social engineered into pasting malicious code into their brower's address bar or developer console

share_baiting

A person is convinced to share spammy content in exchange for a fictitious product or content

targeted

An attack conducted by a sophisticated actor and directed at a specific target

terrorism

Associated with terrorist attacks or groups

weapons

Related to the illegal trade of arms

web_app

A malicious web app

Here is a list of the most popular tags categorizing data by type:

NameDescription

bad_actor

Details on a presumed bad actor (e.g. botherder, spammer)

compromised_credential

The credential compromised by an attack (must be already publicly accessible)

ht_victim

For high-value victim targeting

malicious_ad

A malicious advertisement

malicious_api_key

An API key which is being abused

malicious_content

A malicious post, image, or document

malicious_domain

A malicious Internet domain

malicious_inject

A malicious piece of code that injected into a another file, process, or DOM

malicious_ip

A malicious IP address

malicious_subnet

A malicious IP address range

malicious_ssl_cert

A malicious SSL certificate

malware_sample

A specific piece of Malware

malware_victim

A victim of Malware

proxy_ip

An IP address known to be a proxy or VPN

signature

Represents some means or pattern for detecting a threat

web_request

A full web request, optionally with GET query parameters

whitelist_domain

An Internet domain that should be treated as non-malicious

whitelist_ip

An IP address that should be treated as non-malicious

whitelist_url

An URI that should be treated as non-malicious