PiRogue Tool Suite

REST API

Threatr propagates user’s requests to the different configured services and returns the aggregated entities along with the knowledge graph linking the different entities with the requested one. Threatr stores the results in its internal database and will always return the data already stored unless the attribute force is set to true. By forcing the refresh of the data, Threatr will propagate the user’s request to all external services.

The retrieval of the data from the 3rd-party is done asynchronously. That means it’s necessary to replay the same request until the status is no longer ENQUEUED.

Danger

Do not forget to reset the attribute force to false or Threatr will constantly request the same information.

Once Threatr has retrieved the data from the different 3rd-party, it returns a JSON document following this structure:

  • root_entity: the requested entity
  • entities: the list of all retrieved entities (DNS records, etc.)
  • events: the list of all retrieved events (Passive DNS, etc.)
  • relations: the knowledge graph linking the entities all together, root_entity included
  • graph: the Mermaid definition of the knowledge graph

Users can ask Threatr for threat intelligence by sending POST HTTP requests. In the following example, we ask Threatr to get threat intelligence about a SHA256.

Authentication

Open Threatr administration panel.

  1. Create Threatr User:

    • Navigate to Threatr administration panel
    • Go to Users menu
    • Create a new regular user

  2. Generate API Key:

    • Stay in Threatr administration panel
    • Go to Tokens menu
    • Generate a new API key for the created user

Administration panel URLs

Note that the administration panels are accessible at random URLs:

  • Threatr: https://${threatr_base_url}/${threatr_django_admin_url} with the variables set in your configuration vault

Request with curl

Request Threatr with curl
curl -X POST --location "[threat URL]" \
  -H "Content-Type: application/json" \
  -H "Authorization: Token [api-key]" \
  -d "{\"super_type\": \"observable\",
    \"type\": \"sha256\", \   # we provide a SHA256 observable
    \"value\": \"854774a198db490a1ae9f06d5da5fe6a1f683bf3d7186e56776516f982d41ad3\", \   # the SHA256
    \"force\": false}"

Request in Python

threatr.py
import requests

def send_request(data):
    """
    Send the request to Threatr. If Threatr returns a status code equals to 201,
    this means the client has to come back later.

    If the status code is equal to 200, we are ready to return the result to the client.

    The data sent to Threatr must follow this structure:
    {
        "super_type": the entity super type such as observable or device,
        "type": the entity type such as IPv4 or server,
        "value": the actual subject of the search such as 1.1.1.1,
        "force": indicated to update Threatr cache by querying all vendors
    }

    :param data: the data to be sent
    :return: the query results and a boolean telling if the client has to wait and come back later, False otherwise
    """
    headers = {'Authorization': f'Token API_KEY'}
    response = requests.post(
        'http://127.0.0.1:9080/api/request/',
        headers=headers,
        json=data
    )
    if response.status_code == 201:
        return [], True
    elif response.status_code == 200:
        return response.json(), False
    else:
        return [], False


data = {
    "super_type": "observable",
    "type": "domain",
    "value": "google.com",
    "force": False
}
d, come_back_later = send_request(data)
Example of result returned by Threatr
{
  "root_entity": {
    "id": "7c208f04-54f6-441c-8823-a125ee8d9151",
    "super_type": {
      "name": "Observable",
      "short_name": "OBSERVABLE",
      "description": null,
      "nf_icon": null
    },
    "type": {
      "name": "SHA256",
      "short_name": "SHA256",
      "description": null,
      "nf_icon": "nf-fa-hashtag"
    },
    "name": "854774a198db490a1ae9f06d5da5fe6a1f683bf3d7186e56776516f982d41ad3",
    "description": null,
    "source_url": null,
    "created_at": "2023-03-18T20:36:38.377497Z",
    "updated_at": "2023-03-20T15:06:31.046058Z",
    "tlp": "WHITE",
    "pap": "WHITE",
    "attributes": {
      "md5": "79ba96848428337e685e10b06ccc1c89",
      "sha1": "51b31827c1d961ced142a3c5f3efa2b389f9c5ad",
      "size": "3007920",
      "tlsh": "T18AD5338F15B14C4A94A719F7A1B6F2480D6D6BE1740C6342A32C6107B9D2F31AF6FC9B",
      "vhash": "32b92707c2fd75aba00c39dde6dc91f9",
      "sha256": "854774a198db490a1ae9f06d5da5fe6a1f683bf3d7186e56776516f982d41ad3",
      "ssdeep": "49152:rlaYuMuLPV74she6ZMKqvoWY9KqUoHLUfgP8csv5oJewBktwFcBVOhOUfFW:r0YhiqshtJqQWY9GEUoP8zv5f0kuFczJ",
      "filesize": "3007920",
      "vt_score": "39/76",
      "file_type": "Zip archive data, at least v2.0 to extract",
      "ZIP:ZipCRC": "0x2eb041f1",
      "file_class": "APK",
      "is_malicious": "True",
      "source_vendor": "OTX Alien Vault",
      "ZIP:ZipBitFlag": "0x0808",
      "ZIP:ZipFileName": "META-INF/MANIFEST.MF",
      "ZIP:ZipModifyDate": "2019:10:23 10:54:58",
      "ZIP:ZipCompression": "Deflated",
      "ZIP:ZipCompressedSize": "505",
      "ZIP:ZipRequiredVersion": "20",
      "ZIP:ZipUncompressedSize": "956"
    }
  },
  "entities": [
    {
      "id": "01ee1c48-8670-4535-b90f-b99070fd02e4",
      "super_type": {
        "name": "External documentation",
        "short_name": "EXT_DOC",
        "description": null,
        "nf_icon": null
      },
      "type": {
        "name": "Analysis report",
        "short_name": "REPORT",
        "description": null,
        "nf_icon": "nf-fa-file-lines"
      },
      "name": "FinSpy spyware found in Egypt, and Mac and Linux versions revealed",
      "description": "\"FinSpy is a commercial spyware suite produced by the Munich-based company FinFisher Gmbh. Since 2011 researchers have documented numerous cases of targeting of Human Rights Defenders (HRDs) - including activists, journalists, and dissidents with the use of FinSpy in many countries, including Bahrain, Ethiopia, UAE, and more.\"",
      "source_url": "https://www.amnesty.org/en/latest/research/2020/09/german-made-finspy-spyware-found-in-egypt-and-mac-and-linux-versions-revealed/",
      "created_at": "2023-03-18T20:36:40.807646Z",
      "updated_at": "2023-03-20T15:06:31.012557Z",
      "tlp": "WHITE",
      "pap": "WHITE",
      "attributes": {
        "tags": "linux,osx,finspy,android,backdoor,cobalt strike,spyware",
        "created": "2020-09-25 18:20:44.470000+00:00",
        "modified": "2020-10-25 00:02:49.937000+00:00",
        "source_vendor": "OTX Alien Vault"
      }
    },
    {
      "id": "be2a862c-30d6-468f-91c0-583c00286f83",
      "super_type": {
        "name": "Threat",
        "short_name": "THREAT",
        "description": null,
        "nf_icon": null
      },
      "type": {
        "name": "Trojan",
        "short_name": "TROJAN",
        "description": null,
        "nf_icon": "nf-fa-bug"
      },
      "name": "trojan.finspy/techfu",
      "description": null,
      "source_url": null,
      "created_at": "2023-03-20T11:52:05.535519Z",
      "updated_at": "2023-03-20T15:06:27.658068Z",
      "tlp": "WHITE",
      "pap": "WHITE",
      "attributes": {
        "tags": "apk,checks-gps,sudo,android,contains-elf",
        "source_vendor": "VirusTotal"
      }
    },
    {
      "id": "bbc19a6b-8b56-4efd-96d5-c56bb1128d59",
      "super_type": {
        "name": "External documentation",
        "short_name": "EXT_DOC",
        "description": null,
        "nf_icon": null
      },
      "type": {
        "name": "Analysis report",
        "short_name": "REPORT",
        "description": null,
        "nf_icon": "nf-fa-file-lines"
      },
      "name": "German-made FinSpy spyware found in Egypt, and Mac and Linux versions revealed",
      "description": "",
      "source_url": "https://github.com/AmnestyTech/investigations/blob/master/2020-09-25_finfisher/android_tlv_list.csv",
      "created_at": "2023-03-18T20:36:40.825174Z",
      "updated_at": "2023-03-20T15:06:31.025317Z",
      "tlp": "WHITE",
      "pap": "WHITE",
      "attributes": {
        "tags": "android finspy,backdoored,older linux,macos installer,linux finspy,older mac os",
        "created": "2020-09-25 16:28:05.448000+00:00",
        "modified": "2020-10-25 00:02:49.937000+00:00",
        "source_vendor": "OTX Alien Vault"
      }
    }
  ],
  "events": [
    {
      "id": "ba3180c7-6bb0-46c0-8d2b-ac2b853dec9c",
      "type": {
        "name": "AntiVirus detection",
        "short_name": "AV_DETECTION",
        "description": null,
        "nf_icon": "nf-oct-alert"
      },
      "first_seen": "2022-11-23T13:30:52Z",
      "last_seen": "2022-11-23T13:30:52Z",
      "count": 1,
      "name": "Latest analysis on VT",
      "created_at": "2023-03-20T15:58:23.694985Z",
      "updated_at": "2023-03-20T15:58:23.704958Z",
      "description": null,
      "attributes": {
        "source_vendor": "VirusTotal"
      },
      "involved_entity": "7c208f04-54f6-441c-8823-a125ee8d9151"
    },
    {
      "id": "ba7e49bb-bf7b-4c00-a9c9-0eced24890e2",
      "type": {
        "name": "Hit",
        "short_name": "HIT",
        "description": null,
        "nf_icon": "nf-mdi-white_balance_sunny"
      },
      "first_seen": "2019-11-27T03:50:05Z",
      "last_seen": "2023-01-11T09:34:41Z",
      "count": 11,
      "name": "Submission on VT",
      "created_at": "2023-03-20T15:58:23.694985Z",
      "updated_at": "2023-03-20T15:58:23.704958Z",
      "description": null,
      "attributes": {
        "source_vendor": "VirusTotal"
      },
      "involved_entity": "7c208f04-54f6-441c-8823-a125ee8d9151"
    }
  ],
  "relations": [
    {
      "id": "27f61e7e-0b3a-44fc-842c-2933c160105e",
      "name": "documents",
      "description": null,
      "created_at": "2023-03-18T20:36:40.821695Z",
      "attributes": {
        "source_vendor": "OTX Alien Vault"
      },
      "obj_from": "729c6a82-9fc7-4411-abcf-ebfb30d54e24",
      "obj_to": "7c208f04-54f6-441c-8823-a125ee8d9151"
    },
    {
      "id": "55d2bdac-41d9-4cb2-8a4e-acb101166bb7",
      "name": "documents",
      "description": null,
      "created_at": "2023-03-18T20:36:40.837011Z",
      "attributes": {
        "source_vendor": "OTX Alien Vault"
      },
      "obj_from": "1b994b04-870f-458a-8cb3-a3e3502e514d",
      "obj_to": "7c208f04-54f6-441c-8823-a125ee8d9151"
    },
    [redacted]
  ],
  "graph": "flowchart [redacted Mermaid diagram]"
}
Edit this page on GitHub
Prev
Integrations
Next
REST API