Overview
Within Nucleus, customers are provided with an enhanced enrichment layer on top of all the vulnerability and finding data uploaded to the Nucleus platform. This takes the form of VIP, as well as integrations into the core Nucleus console.
We also allows clients to upload custom metadata to the CVE enrichment layer.
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:
Vulnerability Analysis
and more
.png "image(385).png")
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 | |
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 Fields supported:
| Yes | text dropdown boolean number |
options | A list of string values that define which field options are available in the dropdown. | Required for | 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/configureAPI to get thecustom_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.
Automation > Finding Processing
Custom Threat Intel can be used as finding matching conditions in Finding Processing Rules.
CVE
Custom Threat Intel is available in CVEs > CVE details > vulnerability intelligence. It is also available in the manage columns interface on the /link CVEs page and can be used to customize the CVEs table.