Overview
Using the Nucleus Automation Engine, you can create Finding Processing Rules programmatically using the API. The API matches the options available in the user interface and allows listing, creating, updating and deleting rules. The API can be used to clone rules across projects, standardize rules across multiple child organizations, simplify mass rule updates, and facilitate integration with external systems that push or modify finding processing rules into Nucleus.
Getting Started
The easiest way to get started with the Finding Processing Rules API is to work with a few examples created with the user interface. Once you’ve created some rules to start with, you can practice using the API to modify them to fit your needs.
Follow these steps:
Navigate to Automation → Finding Processing → Add Rule
Create a rule called “My Test Rule” that looks for the string “Log4shell” in the finding name
.png)
Under Actions configure the rule to set the severity to Critical
.png)
Now click Save & Finish. The rule should show in the UI as follows:
.png)
Listing Rules using the API
Now that we have a rule to work with, we can use the API to send a GET request to retrieve the rule details. This can be done directly from the user interface (View API Docs) using theGET /projects/{project_id}/automation/findingprocessing. This endpoint returns all finding processing rules in the project. You’ll also need the project ID. Make sure you authenticate with your API key (User Profile > Show API Key). You should see the following API response:
{
"total_count": 1,
"data": [
{
"rule_id": "27000007",
"rule_name": "My Test Rule",
"rule_disabled": 0,
"rule_type": "vulnerability",
"finding_criteria": [
{
"rule_match_condition": "finding_name",
"rule_match_qualifier": "contains",
"rule_match_value": "Log4shell"
}
],
"asset_criteria": [],
"asset_criteria_match_type": "All",
"rule_actions": [
{
"action_type": "severity",
"reason": "",
"severity": "Critical"
}
]
}
]
}Note that that this response contains an embedded total_count variable which specifies the number of rules returned (in this case 1). This count is included to facilitate integration with 3rd party applications. Both total_count and the data object wrapper MUST be removed before using the rule in a POST or PUT call.
Modifying a Rule using the API
Suppose I want to change the rule to perform an additional action, in this case setting a specific due date. Also let’s assume that I’d like to alter the rule to set the severity to High instead of Critical. To do this, I would take the response from the previous example and make three modifications:
Remove the total_count and data wrappers
Change “Critical” to “High”
Add an additional action_type object with a specific due date
After I’ve made these changes, the request would appear as follows:
{
"rule_id": "27000007",
"rule_name": "My Test Rule",
"rule_disabled": 0,
"rule_type": "vulnerability",
"finding_criteria": [
{
"rule_match_condition": "finding_name",
"rule_match_qualifier": "contains",
"rule_match_value": "Log4shell"
}
],
"asset_criteria": [],
"asset_criteria_match_type": "All",
"rule_actions": [
{
"action_type": "severity",
"reason": "",
"severity": "High"
},
{
"action_type": "due_date",
"due_date_type": "assign_specific",
"from": "now",
"offset": 0,
"qualifier": "days",
"specific_date": "2025-10-31"
}
]
}Once you’ve prepared the request, you can use PUT /projects/{project_id}/automation/findingprocessing/{rule_id} to modify the rule. You should see the following response from the API which reflects your change:
{
"rule_id": "27000007",
"rule_name": "My Test Rule",
"rule_disabled": 0,
"rule_type": "vulnerability",
"finding_criteria": [
{
"rule_match_condition": "finding_name",
"rule_match_qualifier": "contains",
"rule_match_value": "Log4shell"
}
],
"asset_criteria": [],
"asset_criteria_match_type": "All",
"rule_actions": [
{
"action_type": "severity",
"reason": "",
"severity": "High"
},
{
"action_type": "due_date",
"due_date_type": "assign_specific",
"from": "now",
"offset": 0,
"qualifier": "days",
"specific_date": "2025-10-31"
}
]
}Verifying the Update
If you navigate to Automation > Finding Processing and edit the rule, you should see the modifications reflected in the UI as follows
IMPORTANT NOTE: You must refresh the Finding Processing Rules Grid for the change to be reflected. Please ensure you are not editing the rule in the UI at the same time you are making changes with the API or you may see inconsistent results.
.png)
Adding New Rules
You can add new rules to any project using the POST /projects/{project_id}/automation/findingprocessing endpoint. This allows you to clone rules across projects or initialize a project with a predetermined set of finding processing automation rules. To add rules to a new project from an existing project, follow these steps.
Prepare a list of rules you’d like to upload to a new project using the
GET /projects/{project_id}/automation/findingprocessingendpoint. You’d call this endpoint on your existing project first.You’ll save this response as a JSON file
Be sure to remove the
total_countand the“data”:object identifierFor the POST API, be sure to enclose the objects in
“[“and“]”as the POST API takes a set of rules
Record the project ID of the new project
If the rules contain any project-specific identifiers, such as Team IDs, retrieve these from the new project (may not apply to all rules) and update the request
Team IDs will be different across projects
Call
POST /projects/{project_id}/automation/findingprocessingwith the JSON retrieved in Step 1.
Let’s walk through an example that builds on the first rule. Assume we’ve added 2 rules to our existing project follows:.png)
In addition to the original “My Test Rule” we’ve now added an “Assignment Rule” that assigns findings with CVSS scores > 8 to a team called “The Bears”. Using the GET API call, we now have the following response:
{
"total_count": 2,
"data": [
{
"rule_id": "27000007",
"rule_name": "My Test Rule",
"rule_disabled": 0,
"rule_type": "vulnerability",
"finding_criteria": [
{
"rule_match_condition": "finding_name",
"rule_match_qualifier": "contains",
"rule_match_value": "Log4shell"
}
],
"asset_criteria": [],
"asset_criteria_match_type": "All",
"rule_actions": [
{
"action_type": "severity",
"reason": "",
"severity": "High"
},
{
"action_type": "due_date",
"due_date_type": "assign_specific",
"from": "now",
"offset": 0,
"qualifier": "days",
"specific_date": "2025-10-31"
}
]
},
{
"rule_id": "27000008",
"rule_name": "Assignment Rule",
"rule_disabled": 0,
"rule_type": "vulnerability",
"finding_criteria": [
{
"rule_match_condition": "cvss_score",
"rule_match_qualifier": "greater than",
"rule_match_value": "8"
}
],
"asset_criteria": [],
"asset_criteria_match_type": "All",
"rule_actions": [
{
"action_type": "assign",
"assign_team": true,
"assign_team_dynamic": "",
"assign_team_specific": 25000006,
"assign_team_type": {
"assign_team_type": "specific"
},
"assign_user": false,
"assign_user_dynamic": "",
"assign_user_specific": "",
"assign_user_type": {
"assign_user_type": "specific"
},
"overwrite_team_auto": true,
"overwrite_team_manual": true
}
]
}
]
}In the previous response we can now see 2 rules are returned with two ID values: 27000007 and 27000008. In order to upload these rules to a new project we’ll remove the total_count property and data object wrapper. We’ll also have to update assign_team_specific from 25000006 to a valid value in our new project because teams are specific to projects. Here is the same request with those modifications.
[
{
"rule_id": "27000007",
"rule_name": "My Test Rule",
"rule_disabled": 0,
"rule_type": "vulnerability",
"finding_criteria": [
{
"rule_match_condition": "finding_name",
"rule_match_qualifier": "contains",
"rule_match_value": "Log4shell"
}
],
"asset_criteria": [],
"asset_criteria_match_type": "All",
"rule_actions": [
{
"action_type": "severity",
"reason": "",
"severity": "High"
},
{
"action_type": "due_date",
"due_date_type": "assign_specific",
"from": "now",
"offset": 0,
"qualifier": "days",
"specific_date": "2025-10-31"
}
]
},
{
"rule_id": "27000008",
"rule_name": "Assignment Rule",
"rule_disabled": 0,
"rule_type": "vulnerability",
"finding_criteria": [
{
"rule_match_condition": "cvss_score",
"rule_match_qualifier": "greater than",
"rule_match_value": "8"
}
],
"asset_criteria": [],
"asset_criteria_match_type": "All",
"rule_actions": [
{
"action_type": "assign",
"assign_team": true,
"assign_team_dynamic": "",
"assign_team_specific": 25000009,
"assign_team_type": {
"assign_team_type": "specific"
},
"assign_user": false,
"assign_user_dynamic": "",
"assign_user_specific": "",
"assign_user_type": {
"assign_user_type": "specific"
},
"overwrite_team_auto": true,
"overwrite_team_manual": true
}
]
}
]To upload these rules to a new project use POST /projects/{project_id}/automation/findingprocessing provide the project ID and ensure the Team ID exists in the new project. In this case, the Team ID for the assignment is 25000009. After executing the POST API call you should see the API response with "success": true and return rule IDs for the newly added rules.
{
"success": true,
"data": [
{
"rule_id": "27000011",
"rule_name": "My Test Rule",
"rule_disabled": 0,
"rule_type": "vulnerability",
"finding_criteria": [
{
"rule_match_condition": "finding_name",
"rule_match_qualifier": "contains",
"rule_match_value": "Log4shell"
}
],
"asset_criteria": [],
"asset_criteria_match_type": "All",
"rule_actions": [
{
"action_type": "severity",
"reason": "",
"severity": "High"
},
{
"action_type": "due_date",
"due_date_type": "assign_specific",
"from": "now",
"offset": 0,
"qualifier": "days",
"specific_date": "2025-10-31"
}
]
},
{
"rule_id": "27000012",
"rule_name": "Assignment Rule",
"rule_disabled": 0,
"rule_type": "vulnerability",
"finding_criteria": [
{
"rule_match_condition": "cvss_score",
"rule_match_qualifier": "greater than",
"rule_match_value": "8"
}
],
"asset_criteria": [],
"asset_criteria_match_type": "All",
"rule_actions": [
{
"action_type": "assign",
"assign_team": true,
"assign_team_dynamic": "",
"assign_team_specific": 25000009,
"assign_team_type": {
"assign_team_type": "specific"
},
"assign_user": false,
"assign_user_dynamic": "",
"assign_user_specific": "",
"assign_user_type": {
"assign_user_type": "specific"
},
"overwrite_team_auto": true,
"overwrite_team_manual": true
}
]
}
]
}NOTE: When uploading rules from an existing project to a new project, the rules will be given new rule_id values in the new project. Any existing rule_id fields in the request will be ignored and are optional.
Deleting a Rule
To delete a rule using the API, use the DELETE /projects/{project_id}/automation/findingprocessing/{rule_id} endpoint. For example, to delete the rule we added in the previous example with the ID 27000012 you would pass in both the project ID and rule ID. You should see the following response:
{
"success": true
}IMPORTANT NOTE: Deleting a Rule is a permanent change and cannot be undone
Tips and Best Practices
When authoring new rules using the API it is useful to create the structure of the rule in the UI first and then perform a GET to determine all of the required fields.
When using API calls that modify a rule such as POST or PUT, refrain from editing the same rule from the UI to prevent unexpected results. Rules should be saved in the UI prior to modification with the API
When using the response from the GET in the PUT and POST API, remember to remove the "total_count": 2 and “data”: JSON wrappers. The PUT and POST APIs will not accept these wrappers.
Ensure your request to the POST API is a JSON array. Objects should be enclosed in
“[“and“]”characters.Project specific IDs (such as Team IDs) will not work across projects and must match the project they are in