ThreatQ Module

The ThreatQ module enables you to synchronize your DocIntel instance with your ThreatQ threat intelligence platform. All the reports with their associated tags and structured data will be exported for you to use.

Please note that this module is not part of the open-source version and is installed as an external module. If you are interested in this module, please contact antoine@docintel.org.

Installation

To install the module, follow these steps:

Copy the received public key to $DOCINTEL_DATA/modules/public.pem.
Download the archive and extract its contents.
Copy the contents of the archive to $DOCINTEL_DATA/modules/threatq.
Copy the licence file to $DOCINTEL_DATA/modules/threatq/licence.txt.
Restart the application.

Configuration

You can map tags used in DocIntel to malware, identity, vulnerability, tool, attack pattern, adversary, and campaign relationships, as well as to TLP taxonomies used in ThreatQ. The mapping is fully customizable.

To map tags, follow these steps:

Check the inbox “Export to ThreatQ relationship?” in the facet settings.
Select the appropriate relationship that you want to map to.

With this mapping, DocIntel will export the label of the tag as the value for the relationship. If you want to customize the value for the relationship, go to the settings page for the tag and specify a value for the mapping.

To map classifications to specific TLP markings, go to the edit page for the classification and select the appropriate TLP mapping.

You can exclude specific sources from the exports. None of the documents with a source that is excluded will show in the export.

Usage

Configure your ThreatQ platform to consume the following endpoints:

https://your-instance/API/Export/threatq/exporter/Document
https://your-instance/API/Export/threatq/exporter/Document/$DOCUMENT_ID

Note that the connector needs to authenticate first and obtain a token, as explained in the API guide.

To test the authentication, use the following command:

curl --request POST \
  --url http://your-instance/API/Authentication/Login \
  --header 'Content-Type: application/json' \
  --data '{
  "username": "my_user",
  "api_key": "my_api_key_"
}'

This command returns data similar to the following:

{"token":"eyJhbGciOiJI..."}

To test the endpoint /API/Export/threatq/exporter/Document, use the following command:

curl --request GET \
  --url 'http://your-instance/API/Export/threatq/exporter/Document?PageSize=5' \
  --header 'Authorization: Bearer my_token'

The available options are

DateFrom specifying the date from which the documents are to be exported
DateTo specifying the date up to which the documents are to be exported
PageSize specifying the number of documents to return
Page specifying the page to return

This command returns data similar to the following:

{
  "data": [
    {
      "tlp": "TLP-Green",
      "attributes": {
        "docintel_url": "https://your-instance/Document/Details/my-document-9",
        "classification": "Unclassified"
      },
      "published_at": "2023-04-24T22:00:00Z",
      "adversary": [
        {
          "type": "adversary",
          "value": " Kimsuky",
          "description": "",
          "id": "37849a05-72a4-456a-be4b-af68dc0c608a",
          "created_at": "2022-09-26T15:09:30Z",
          "updated_at": "2022-11-23T20:42:44Z"
        }
      ],
      "attack_pattern": [],
      "campaign": [],
      "identity": [],
      "indicator": [
        {
          "type": "MD5",
          "value": null,
          "id": "a12f65c53ccf4baa9f0e7fd09f7007fa464bb3ee70268a6f2384419978120510",
          "created_at": "0001-01-02T22:44:10Z",
          "updated_at": "0001-01-02T22:44:10Z"
        }
      ],
      "malware": [],
      "vulnerability": [],
      "type": "Report",
      "value": "My document",
      "id": "329d98fd-76da-433b-b589-5793c1bee459",
      "created_at": "2023-04-26T09:07:09Z",
      "updated_at": "2023-04-27T16:39:41Z"
    },
    {
      "type": "adversary",
      "value": " Kimsuky",
      "description": "",
      "id": "37849a05-72a4-456a-be4b-af68dc0c608a",
      "created_at": "2022-09-26T15:09:30Z",
      "updated_at": "2022-11-23T20:42:44Z"
    }
    ...
  ]
}

To test the endpoint /API/Export/threatq/exporter/Document/$DOCUMENT_ID, use the following command:

curl --request GET \
  --url https://your-instance/API/Export/threatq/exporter/Document/$DOCUMENT_ID \
  --header 'Authorization: Bearer my_token'

This command returns data similar to the following:

[
  {
    "tlp": "TLP-Green",
    "attributes": {
      "docintel_url": "https://your-instance/Document/Details/my-document-9",
      "classification": "Unclassified"
    },
    "published_at": "2023-04-24T22:00:00Z",
    "adversary": [
      {
        "type": "adversary",
        "value": " Kimsuky",
        "description": "",
        "id": "37849a05-72a4-456a-be4b-af68dc0c608a",
        "created_at": "2022-09-26T15:09:30Z",
        "updated_at": "2022-11-23T20:42:44Z"
      }
    ],
    "attack_pattern": [],
    "campaign": [],
    "identity": [],
    "indicator": [
      {
        "type": "MD5",
        "value": null,
        "id": "a12f65c53ccf4baa9f0e7fd09f7007fa464bb3ee70268a6f2384419978120510",
        "created_at": "0001-01-02T22:44:10Z",
        "updated_at": "0001-01-02T22:44:10Z"
      }
    ],
    "malware": [],
    "vulnerability": [],
    "type": "Report",
    "value": "My document",
    "id": "329d98fd-76da-433b-b589-5793c1bee459",
    "created_at": "2023-04-26T09:07:09Z",
    "updated_at": "2023-04-27T16:39:41Z"
  },
  {
    "type": "adversary",
    "value": " Kimsuky",
    "description": "",
    "id": "37849a05-72a4-456a-be4b-af68dc0c608a",
    "created_at": "2022-09-26T15:09:30Z",
    "updated_at": "2022-11-23T20:42:44Z"
  }
]