Custom Threat Intelligence

Overview

Within Nucleus, we allow customers to populate their own threat intelligence in real time to the Nucleus platform as an enrichment layer on top of the vulnerability, asset, and software inventory that is contained in Nucleus. This gives customers the flexibility to integrate any of their own commercially-obtained, or proprietary, datasets and use them as indicators for vulnerability management and exposure management workflows.

How to Use
Custom Threat Intel is only available through the Nucleus API. This encourages automated systems to update and refresh the data consistently.

How it works

You create feeds, configure them, and then add data to them using CVEs as a unique identifier. This means that your threat intel data will show up alongside the rest of the Nucleus Enrichment Layer, and your fields can be used in various parts of the Nucleus console. This includes:

Automation Workflows
Vulnerability Analysis/Details pages
Custom Risk Score
and more

Add Threat Feed

The first step to using custom threat intel is to create a feed. A feed is a collection of fields that Nucleus will expect to see populated.

You create the feed by using the POST {{nucleusURL}}/api/intel/configure endpoint. Authenticate like normal, and then send a JSON body in the response that looks like the following:

{
  "custom_threat_intel_name": "string",
  "custom_threat_intel_description": "string",
  "custom_threat_intel_display": "string",
  "custom_threat_intel_fields": [
    {
      "intel_key": "string",
      "intel_type": "text"
    }
  ],
  "custom_threat_intel_project_ids": [
    0
  ],
  "org_id": 0
}

Field Definitions

Field/Object	Details	Required	Example Values
custom_threat_intel_name	A string field. The name of the feed you are creating.	Yes	“My Internal Feed”
custom_threat_intel_description	Optional: A string field. A description for the threat feed that will show up in the console and API.	No	“Here is a description of my feed. It’s really awesome and all-knowing.”
custom_threat_intel_display	Optional: A string field. This allows you to style your intel feed in the console using basic html. This field leverages standard html, in-line css, and single bracket {} templating to build a front end view for your intel feed. If nothing defined, you will see all the key-value pairs by default in a list.	No	`"<h1 style='text-align:center;'>Field name</h1><p style='text-align:center;'>{field name}</p>"`
custom_threat_intel_fields	An array of objects. These are the fields you want this feed to expect.	No	N/A
custom_threat_intel_project_ids		Yes	[ 1, 2, 3 ]
org_id	Optional: If you are an MSSP and want to publish this feed to your end customers, you can add a separate Org to the feed. Default to your user’s org.	No	100000

`custom_threat_intel_fields` Definition Array

Here is a list of the fields required for every “field definition” for your feed that you want to create. All of these values should be embedded as an array of objects.

Field/Object	Details	Required	Example Values
custom_threat_intel_fields	An array of objects. These are the fields you want this feed to expect.		N/A
intel_key	This is the name of the field. This is what will show up in the console and automation rules as your field name.	Yes	“exploited_internally” “ciso_priority” “our_risk_score”
intel_type	This is the `field type`. You define what type of field the feed supports, as well as choice values. Fields supported: text dropdown boolean number	Yes	text dropdown boolean number
options	A list of string values that define which field options are available in the dropdown.	Required for `dropdown` field type.	Only required for dropdown. [ “option 1”, “option 2” ]

Example custom_threat_intel_fields object with all supported field types defined:

  "custom_threat_intel_fields": [
    {
      "intel_key": "field1",
      "intel_type": "text",
    },
    {
      "intel_key": "field2 - number",
      "intel_type": "number",
    },
    {
      "intel_key": "field1 - with options",
      "intel_type": "dropdown",
      "options": [
        "Option 1",
        "Option 2"
      ]
    },
    {
      "intel_key": "field3 - Boolean",
      "intel_type": "boolean",
    }
  ]

Tip: Save your json objects as config files somewhere
Rather than building the json object directly into your scripts or when testing, we recommend saving config files, so if you need to make adjustments to the feed (such as adding a new project_id), then you can add it to the config file and decrease the risk of accidentally removing fields from the feed configuration.

Configure/Update Feed

If you want to update a defined custom threat feed, you do so by using the PUT {{nucleusURL}}/api/intel/configure/{{custom_threat_intel_id}} endpoint.

Step 1 - Get your threat intel ID

Use the GET {{nucleusURL}}/api/intel/configure API to get the custom_threat_intel_id

A successful response should result in a list of your configured threat feeds, and the associated field definitions

[
  {
    "custom_threat_intel_id": 1000000,
    "custom_threat_intel_name": "Example Threat Feed 1",
    "custom_threat_intel_description": "This is a description for the feed of sufficient length.",
    "custom_threat_intel_display": "This is the display field.",
    "custom_threat_intel_fields": [
      {
        "intel_key": "field1",
        "intel_type": "text"
      },
      {
        "intel_key": "field2 - number",
        "intel_type": "number"
      },
      {
        "intel_key": "field1 - with options",
        "intel_type": "dropdown",
        "options": [
          "Option 1",
          "Option 2"
        ]
      },
      {
        "intel_key": "field3 - Boolean",
        "intel_type": "boolean"
      }
    ],
    "custom_threat_intel_project_ids": [
      10
    ],
    "org_id": 1
  },
  {
    "custom_threat_intel_id": 1000002,
    "custom_threat_intel_name": "Configured Feed 2",
    "custom_threat_intel_description": "This feed represents the kill list for our CISO.",
    "custom_threat_intel_display": "CISO List",
    "custom_threat_intel_fields": [
      {
        "intel_key": "field1",
        "intel_type": "text"
      },
      {
        "intel_key": "field2 - number",
        "intel_type": "number"
      },
      {
        "intel_key": "field1 - with options",
        "intel_type": "dropdown",
        "options": [
          "Option 1",
          "Option 2"
        ]
      },
      {
        "intel_key": "field3 - Boolean",
        "intel_type": "boolean"
      }
    ],
    "custom_threat_intel_project_ids": [],
    "org_id": 1
  }
]

Grab the custom_threat_intel_id field and use it for Step 2.

Step 2 - Update Threat Intel Feed

To update a feed, you will use the PUT {{nucleusURL}}/intel/configure/{{custom_threat_intel_id}} API. This API works similar to the POST version of this API call, except it will update existing fields. You must include all fields every time you use the PUT request to avoid accidentally removing field definitions.

Note: If you have data in a dropdown field and then remove an “Option” from that field definition, then CVE data in Nucleus that had that field value will need to be re-applied.

Example 1: I have a Boolean field for “Fix Now”. CVE1 is set to True. I remove that Boolean field from the feed. The data on the CVE will no longer exist on the CVE because I removed the field.
Example 2: I have a dropdown field called “Risk Level” with 2 options: “Critical” & “High”. I update the field definition to not include the Option for “High”. All CVEs who have the “High” risk level would have that value removed and I will need to ensure I re-upload the threat feed data with updated information for each CVE.

Add data

This is how you add the information to the fields themselves. For example, let’s say you want to add an “exploitable = True” to a CVE. Then this API call is where you would update the field value from “False” to “True”.

Nucleus will automatically handle overwriting of the data. If you pass in new data to a field on a CVE, Nucleus will assume this is the most recent and will overwrite the existing value in the field. You access this through the POST {{nucleusURL}}/api/intel/data/{custom_threat_intel_id} endpoint.

{
  "CVE-1": {
    "key1": "val1",
    "key2": null
  },
  "CVE-2": {
    "key1": "val3"
  }
}

Update Data

Nucleus will automatically handle overwriting of the data. If you pass in new data to a field on a CVE, Nucleus will assume this is the most recent and will overwrite the existing value in the field. You access this through the PUT {{nucleusURL}}/api/intel/data/{custom_threat_intel_id} endpoint.

{
  "CVE-1": {
    "key1": "val1",
    "key2": null
  },
  "CVE-2": {
    "key1": "val3"
  }
}

Use Data in the Console

Once data is uploaded to Nucleus via the API, you now have access to the Nucleus Enrichment Layer. Custom Threat Intel data can be used in the following Nucleus product features:

Vulnerability Details

Custom Threat Intel is available in active vulnerabilities > vulnerability details > vulnerability intelligence. You can make very visually appealing UI’s using this API, to control visibility for your end users:

Automation > Finding Processing

Custom Threat Intel can be used as finding matching conditions in Finding Processing Rules. See below for an example of these fields showing up as match criteria in finding processing rules

Custom Risk Score

All of the fields added via the custom threat intel upload can be leveraged as part of the Custom Risk Score module, so that users can utilize any of their custom threat intel fields as decision criteria in the curation of risk scoring in their environment.

For more information on how to use custom threat intel, please give us a shout at [email protected].