Create access group

post deprecatedhttps://cloud.tenable.com/v2/access-groups

Creates an access group.

Caution: Access groups were deprecated in Tenable Vulnerability Management on February 4th, 2022. Tenable recommends that customers use access control instead to manage user and group access to resources in Tenable Vulnerability Management. Please update any existing integrations that your organization has. For more information about access control, see Access Control in the Tenable Vulnerability Management User Guide.

Requires the Administrator [64] user role. See Roles.

time	status	user agent
Retrieving recent requests…

Loading…

Body Params

name

string

required

The name of the access group you want to create. This name must be:

Unique within your Tenable Vulnerability Management instance.
A maximum of 255 characters.
Alphanumeric, but can include limited special characters (underscore, dash, parenthesis, brackets, colon).

Note: You can add a maximum of 5,000 access groups to an individual container.

access_group_type

string

The type of access group. It can be one of three possible types:

MANAGE_ASSETS—Users in this access group can view the asset records created during previous scans and scan the associated targets for those assets.
SCAN_TARGETS—Users in this access group can scan targets associated with the access group and view the results of those scans. Targets may be associated with existing assets.
ALL—This access group type is only applicable to the default system-generated "All Assets" access group that contains all assets in your organization. This group is referred to as the "All Assets" group in the user interface. By default, Tenable Vulnerability Management grants all users in this access group both CAN VIEW and CAN SCAN permissions.

all_users

boolean

Specifies whether assets in the access group can be viewed by all or only some users in your organization:

If true, all users in your organization have Can View access to the assets defined in the rules parameter. Tenable Vulnerability Management ignores any principal parameters in your request.
If false, only specified users have Can View access to the assets defined in the rules parameter. You define which users or user groups have access in the principals parameter of the request.

If you omit this parameter, Tenable Vulnerability Management sets the parameter to false by default.

all_assets

boolean

This parameter must always be false or omitted from create requests to specify that the access group is a user-created group. If you submit a create request with this parameter set to true, the create request fails.

principals

array of objects

An array of principals. Each principal represents a user or user group assigned to the access group. You cannot add an access group as a principal to another access group.

Tenable Vulnerability Management handles data in this array based on the all_users parameter of the request:

If all_users is true, Tenable Vulnerability Management ignores any principal data in the request. You can omit this parameter from the request.
If all_users is false, Tenable Vulnerability Management adds the principal data to the access group.

principals

rules

array of objects

An array of asset rules. Tenable Vulnerability Management uses these rules to assign assets to the access group. You can specify a maximum of 1,000 rules for an individual access group. If you specify multiple rules for an access group, Tenable Vulnerability Management assigns an asset to the access group if the asset matches any of the rules. You can only add rules to access groups if the all_assets parameter is set to false.

Note: When configuring rules for an access_group_type of SCAN_TARGETS, the asset attribute type (rules.type) must match the target format used in the related scan. For example, if a SCAN_TARGETS type access group rule filters on the FQDN/Hostname attribute, the related scan succeeds if the scan target is specified in FQDN or hostname format, but fails if the scan target is specified in IPv4 address format.

rules

Responses

Response body

object

container_uuid

string

The UUID of your Tenable Vulnerability Management instance.

created_at

string

An ISO timestamp indicating the date and time on which the access group was created.

updated_at

string

An ISO timestamp indicating the time and date on which the access group was last modified.

string

The UUID of the access group.

name

string

The name of the access group. This name must be:

Unique within your Tenable Vulnerability Management instance.
A maximum of 255 characters.
Alphanumeric, but can include limited special characters (underscore, dash, parenthesis, brackets, colon).

all_assets

boolean

Specifies whether the access group is the system-provided All Assets access group:

If true, the access group is the All Assets access group. The only change you can make to this access group is to refine user membership in the group. For more information, see descriptions of the all_users and principals parameters for the PUT /v2/access-groups/{id} endpoint.
If false, the access group is a user-defined access group, and you can change all parameters for the group. This parameter is false for all access groups you create.

version

integer

Optional, user-defined value. This value must be incremented each time an access group is updated. Set to 1 by default.

status

string

The status of the process evaluating and assigning assets to the access group. Possible values are:

PROCESSING—Tenable Vulnerability Management is currently evaluating assets against the asset rules for the access group. For an indication of evaluation progress, see the processing_percent_complete attribute for the access group.
COMPLETED—Tenable Vulnerability Management has successfully completed its evaluation of assets against the asset rules for the group.
ERROR—Tenable Vulnerability Management encountered an error while evaluating assets against asset rules for the access group. Rule validation typically prevents this status from occurring. However, if you encounter an ERROR status, Tenable recommends that you delete the existing asset rules, then recreate the rules after a short time has elapsed.

access_group_type

string

The type of access group. It can be one of three possible types:

MANAGE_ASSETS—Users in this access group can view the asset records created during previous scans and scan the associated targets for those assets.
SCAN_TARGETS—Users in this access group can scan targets associated with the access group and view the results of those scans. Targets may be associated with existing assets.
ALL—This access group type is only applicable to the default system-generated "All Assets" access group that contains all assets in your organization. This group is referred to as the "All Assets" group in the user interface. By default, Tenable Vulnerability Management grants all users in this access group both CAN VIEW and CAN SCAN permissions.

MANAGE_ASSETS SCAN_TARGETS ALL

principals

array of objects

An array of principals. Each principal represents a user or user group assigned to the access group. You cannot add an access group as a principal to another access group.

principals

object

principal_name

string

The name of the user or user group. This parameter is required if the request omits the principal_id parameter. If a request includes both principal_id and principal_name, Tenable Vulnerability Management assigns the user or user group to the access group based on the principal_id parameter, and ignores the principal_name parameter in the request.

principal_id

string

The UUID of a user or user group. This parameter is required if the request omits the principal_name parameter.

type

string

(Required) The type of principal. Valid values include:

all_users—Grants access to all users in your organization. That access includes Can View access to the assets defined in the rules parameter.
user—Grants access to the user you specify.
group—Grants access to all users assigned to the user group you specify.

all_users user group

permissions

array of strings

(Required) The permissions associated with the principal of the access group as described in Permissions.

CAN_VIEW CAN_SCAN

permissions

created_by_uuid

string

The UUID of the user who created the access group.

updated_by_uuid

string

The UUID of the user who last modified the access group.

updated_by_name

string

The name of the user who last modified the access group.

created_by_name

string

The name of the user who created the access group.

processing_percent_complete

integer

The percentage of assets that Tenable Vulnerability Management has evaluated against the asset rules for the access group.

400

Returned if Tenable Vulnerability Management encountered any of the following error conditions:

max_entries—your request exceeds the maximum number of 5,000 access groups.
duplicate—an access group with the name you specified already exists.
protected—you attempted to set the all_assets parameter to true, and you cannot create the system-provided access group, All Assets.

403

Returned if you do not have permission to create access groups.

Language

Credentials

Header

Request


xxxxxxxxxx
12
1
import requests
2
3
url = "https://cloud.tenable.com/v2/access-groups"
4
5
headers = {
6
    "accept": "application/json",
7
    "content-type": "application/json"
8
}
9
10
response = requests.post(url, headers=headers)
11
12
print(response.text)


xxxxxxxxxx
44
}
1
{
2
  "container_uuid": "5c910460-38cc-4edb-bda4-49b148a1ce93",
3
  "created_at": "2020-05-03T17:26:59.465Z",
4
  "updated_at": "2020-05-03T17:26:59.465Z",
5
  "id": "7eed61fd-3985-4d1b-8b22-dfc466b5b8da",
6
  "name": "Test Group",
7
  "all_assets": false,
8
  "version": 1,
9
  "status": "PROCESSING",
10
  "access_group_type": "MANAGE_ASSETS",
11
  "rules": [
12
    {
13
      "type": "fqdn",
14
      "operator": "eq",
15
      "terms": [
16
        "example.com"
17
      ]
18
    }
19
  ],
20
  "principals": [
21
    {
22
      "type": "all_users",
23
      "principal_id": "00000000-0000-0000-0000-000000000000",
24
      "principal_name": "All Users",
25
      "permissions": [

200Returned if Tenable Vulnerability Management successfully creates an access group.

429Returned if you attempt to send too many requests in a specific period of time. For more information, see Rate Limiting.