Press CTRL+K to open search

Custom Fields

  • 3 minute(s) read
Prev Next

Overview

Early Access

Custom Fields is currently in early access, please refer to your success team to get access to the Early Access Program

Custom Fields let you extend the Nucleus finding data model with your own organization-specific data — for example, an internal risk category, a remediation owner, or a compliance mapping that doesn't exist as a standard Nucleus field.


Once a custom field is created, you can populate it on findings, then use it the same way you'd use any built-in finding field: as a column on the All Findings page, as a filter or sorting in NQL, as criteria or an action in an automation rule, and through the API.


Supported field types

We currently support the following field types:

  • Text

  • Integer

  • Date

  • Boolean


Creating and managing custom fields

Custom fields are created and managed at the project/org admin level:


  1. Navigate to the Project Admin folder for your project.

  1. Open the Custom Fields management screen.

  1. Click Add Field and set:

    1. Name — how the field will appear as a column and in NQL

    2. Type — Text, Integer, Date, or Boolean

    3. Description (optional) — helps other users understand what the field is for

Custom Field Restrictions

  1. Field names cannot contain spaces

  2. The field type cannot be changed after it has been created, but available values can be edited

  3. Description must be 250 characters or less

Click the Add button to make it available on findings.

Existing custom fields can be  deleted from the same screen. Deleting a custom field removes its values from all findings

Each custom field name must be unique within your organization.


Using custom fields on the All Findings page

Once created, a custom field behaves like any other finding field on the All Findings page:


  • Columns — use the column selector to add the custom field as a visible column.

  • Filtering — filter findings by the custom field's value using the standard filter builder.

  • Sorting — click the column header to sort by the custom field's value.

  • [Future] Grouping — group findings by a custom field's value to see rollups by category.

Column Selector

NQL fields + filtering

Using custom fields in NQL

Custom fields are queryable in the Nucleus Query Language (NQL) via finding_field.* field references. You can:


  • Add a custom field as a returned column

  • Filter with a WHERE clause on the custom field

Example — filter on a custom field:


SELECT * FROM findings WHERE finding_field.`remediation_owner` = 'Platform Team'

For a full list of fields available in NQL, please refer to the Available Datasets (NQL) document.

Notes about Field Types in NQL

Field type matters because these will be available in NQL queries, which means you can enable advanced use cases and dynamic filtering.

E.G. If using a date field you can use a dynamic date search on a NQL search to see anything coming up within the next 7 days: WHERE custom_date_field <= TODAY +7d

Using NQL in Dashboards

Because NQL can be used in Dashboards, that means that all new Custom Fields are available in the Dashboarding module, where you can embed Saved Searches or Ad hoc searches on the dashboards.

Bulk updating findings using custom fields

You can set a custom field's value across many findings at once using Bulk Modify from either the All Findings page or the Active Vulnerabilities page:


  1. Select the findings you want to update (or select all matching your current filter).

  2. Click Bulk Modify.

  3. Choose the custom field and enter the value to apply.

  4. Confirm to apply the change to all selected findings.

Modify from All Findings page

Set finding field action

Set the finding field value

Custom fields in automation rules

Custom fields can be used in Automation rules two ways:


  • As rule criteria — trigger a rule based on a custom field's current value.

  • As a rule action — set a custom field's value automatically when a rule fires (for example, tagging findings from a specific scanner with a risk category).

See the Automation documentation for general rule-building steps; custom fields appear alongside standard finding fields in the criteria and action pickers.

Use finding field as a match criteria


Custom fields via the API

Custom fields are fully manageable through the Nucleus API:

  • Create and delete custom field definitions

  • Set a custom field's value on a finding

  • Read a custom field's value from a finding

You can see the API endpoints for managing fields within your API docs

See the API reference (Swagger) for the specific endpoints and payload schemas.


What's next

Future releases will build on Custom Fields to support custom risk scoring, and to group and aggregate vulnerability data by custom field in All Findings and on dashboards. This article will be updated as those capabilities ship.


FAQ

What field types are supported? Text, Integer, Date, and Boolean. Dropdown/picklist fields are not yet available.


How do I get access? Custom Fields for Findings is in Early Access. Contact your Nucleus success manager to have it enabled for your organization.


Can I use custom fields in reports and dashboards? Custom fields work today in All Findings and NQL. Dashboard-level grouping and aggregation is planned for a future release.