Customize Security Profiles

A security profile defines how Tenable Identity Exposure analyzes your Active Directory (AD). Each profile has its own customization of Indicators of Exposure (checkers) and Indicators of Attack (attack types), so that different teams can review the same AD from different angles.

A profile's customization is a set of options on its Indicators. Changes to those options do not take effect when you make them: they are staged on the profile, and stay pending until you commit the profile's changes or discard them.

Workflow

1. Create the Profile

To start from Tenable's default settings, copy the default Tenable profile. In the interface, the Tenable profile cannot be modified or deleted, and its name is reserved. To find its ID, use the List profiles endpoint.

For example, to copy the Tenable profile into a new profile named SOC Review, you could use the following cURL request:

curl --request POST \
  --url https://your-instance.tenable.ad/api/profiles/from/PROFILE_ID \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{"name": "SOC Review"}'

📘

Note

The number of security profiles is limited. When the limit is reached, the request returns a 400 response with the MAX_ENTITY_COUNT_REACHED error code.

2. Review the Current Options

Each Indicator has options identified by a code name, such as O-CRITICITY for the severity level. The list endpoints return both applied and pending options unless you set the staged query parameter: 0 returns the applied options, and 1 returns the pending ones.

For example, to list the applied options of the Indicator of Exposure with ID 3, you could use the following cURL request:

curl --request GET \
  --url 'https://your-instance.tenable.ad/api/profiles/PROFILE_ID/checkers/3/checker-options?staged=0' \
  --header 'accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

Each option has a codename, a value, and a valueType. The value is a JSON-encoded string, so an integer option holds a value such as "50", and a list option holds a value such as "[]".

3. Stage New Option Values

The create endpoints take an array of options. Set directoryId to apply an option to one domain, or to null to apply it to every domain in the profile.

For example, to stage a new severity level for the Indicator of Exposure with ID 3, you could use the following cURL request:

curl --request POST \
  --url https://your-instance.tenable.ad/api/profiles/PROFILE_ID/checkers/3/checker-options \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '[{"codename": "O-CRITICITY", "directoryId": null, "value": "75", "valueType": "integer"}]'

For an Indicator of Exposure, each request replaces its pending options in the profile, so include every option you want to stage in the same request. The system checks that each value matches its valueType, but does not validate code names or value ranges, so take code names from the list in step 2.

The staged options do not affect the profile's analysis yet. To see them, list the options with staged=1.

4. Check for Pending Changes

The profile's dirty property is true while it has pending changes. The hasEverBeenCommitted property shows whether its changes have ever been committed.

5. Commit or Discard the Changes

Committing applies every pending change on the profile at once, for Indicators of Exposure and Indicators of Attack alike. Unstaging discards every pending change instead, and leaves the applied options as they were.

🛑

Caution

Committing a profile's changes erases its analysis data and requires a complete analysis of the monitored AD, which can take some time.

For example, to commit the pending changes of a profile, you could use the following cURL request:

curl --request POST \
  --url https://your-instance.tenable.ad/api/profiles/PROFILE_ID/commit \
  --header 'accept: application/json' \
  --header 'x-api-key: YOUR_API_KEY'

For more information about customizing Indicators, see Customize an Indicator in the Tenable One Identity Exposure SaaS User Guide.