Tenable Security Center API: Role

/role

/tes/role

/tes/role is only available in Tenable Enclave Security

Methods

GET

Gets the list of Roles

Fields Parameter

The fields not under * or ** can be used only by Admin or users with manageRole permission enabled.
Logged in user can use these fields to view details for self role only.
Org users cannot view Admin role itself but can view any other roles created by admin.

Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,...

Allowed Fields

*id
**name
**description
creator
createdTime
modifiedTime
permManageApp
permManageGroups
permManageRoles
permManageImages
permManageGroupRelationships
permManageBlackoutWindows
permManageAttributeSets
permCreateTickets
permCreateAlerts
permCreateAuditFiles
permCreateLDAPAssets
permCreatePolicies
permPurgeTickets
permPurgeScanResults
permPurgeReportResults
permScan
permAgentsScan
permAgentsSync
permShareObjects
permUpdateFeeds
permUploadNessusResults
permViewOrgLogs
permManageAcceptRiskRules
permManageRecastRiskRules
permManageACR
permViewDomainInventoryAssets
permManageAttackSurfaceDomains
permManageVulnRoutingRules
permViewHostAssets
permManageRiskRules
organizationCounts

Legend

* = always comes back

** = comes back if fields list not specified on GET all

Request Parameters

None

Filter Parameters

subset - Removes subset roles from the return response.

Example Response

Expand

{
	"type" : "regular",
	"response" : [
		{
			"id" : "0",
			"name" : "No Role",
			"description" : "This role is available as a catch-all role if a role gets deleted. It has virtually no permissions."
		},
		{
			"id" : "2",
			"name" : "Security Manager",
			"description" : "The Security Manager role has full access to all actions at the organization level. A Security Manager has the ability to create new groups and manage existing ones. A Security Manager can also define how users interact with other groups.\n\nThe ability to manage other users and their objects can be configured using group permissions on the Access tab of User add/edit. This includes viewing and stopping running scans and reports."
		},
		{
			"id" : "3",
			"name" : "Security Analyst",
			"description" : "The Security Analyst role has the permission to perform all actions at the organizational level except managing groups and users. A Security Analyst is most likely an advanced user who can be trusted with some system related tasks such as setting blackout windows or updating plugins."
		},
		{
			"id" : "4",
			"name" : "Vulnerability Analyst",
			"description" : "The Vulnerability Analyst role can perform basic tasks within the application. A Vulnerability Analyst is allowed to look at security data, perform scans, share objects, view logs and work with tickets."
		},
		{
			"id" : "5",
			"name" : "Executive",
			"description" : "The Executive role is intended for users who are interested in a high level overview of their security posture and risk profile. Executives would most likely be browsing dashboards and reviewing reports but would not be concerned with monitoring running scans or managing users. Executives would also be able to assign tasks to other users using the Ticketing interface."
		},
		{
			"id" : "6",
			"name" : "Credential Manager",
			"description" : "The Credential Manager role can be used specifically for handling credentials. A Credential Manager can create and share credentials without revealing the contents of the credential. This can be used by someone outside the security team to keep scanning credentials up to date."
		},
		{
			"id" : "7",
			"name" : "Auditor",
			"description" : "The Auditor role can access summary information to perform 3rd party audits. An Auditor can view dashboards, reports, and logs but cannot perform scans or create tickets. Restricting access to vulnerability and event data can be achieved by placing the user in an appropriately configured group."
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1445013119
}

POST

Adds a Role

Request Parameters

Expand

Note: Roles cannot be created with permManageApp privilege.

{
	"name" : <string>,
	"description" : <string> DEFAULT "",
	"permManageGroups" : <string> "false" | "true" DEFAULT "false",
	"permManageRoles" : <string> "false" | "true" DEFAULT "false",
	"permManageImages" : <string> "false" | "true" DEFAULT "false",
	"permManageGroupRelationships" : <string> "false" | "true" DEFAULT "false",
	"permManageBlackoutWindows" : <string> "false" | "true" DEFAULT "false",
	"permManageAttributeSets" : <string> "false" | "true" DEFAULT "false",
	"permCreateTickets" : <string> "false" | "true" DEFAULT "false",
	"permCreateAlerts" : <string> "false" | "true" DEFAULT "false",
	"permCreateAuditFiles" : <string> "false" | "true" DEFAULT "false",
	"permCreateLDAPAssets" : <string> "false" | "true" DEFAULT "false",
	"permCreatePolicies" : <string> "false" | "true" DEFAULT "false",
	"permPurgeTickets" : <string> "false" | "true" DEFAULT "false",
	"permPurgeScanResults" : <string> "false" | "true" DEFAULT "false",
	"permPurgeReportResults" : <string> "false" | "true" DEFAULT "false",
	"permScan" : <string> "full" | "none" DEFAULT "none",
	"permAgentsScan" : <string> "false" | "true" DEFAULT "false",
	"permAgentsSync" : <string> "false" | "true" DEFAULT "false",
	"permShareObjects" : <string> "false" | "true" DEFAULT "false",
	"permUpdateFeeds" : <string> "false" | "true" DEFAULT "false",
	"permUploadNessusResults" : <string> "false" | "true" DEFAULT "false",
	"permViewOrgLogs" : <string> "false" | "true" DEFAULT "false",
	"permManageAcceptRiskRules" : <string> "false" | "true" DEFAULT "false",
	"permManageRecastRiskRules" <string> "false" | "true" DEFAULT "false",
	"permManageACR" <string> "false" | "true" DEFAULT "false",
	"permViewDomainInventoryAssets" <string> "false" | "true" DEFAULT "false",
	"permManageAttackSurfaceDomains" <string> "false" | "true" DEFAULT "false",
	"permManageVulnRoutingRules" <string> "false" | "true" DEFAULT "false",
	"permViewHostAssets" <string> "false" | "true" DEFAULT "false",
	"permManageRiskRules" <string> "false" | "true" DEFAULT "false"
}

Example Response

Expand

{
	"type" : "regular",
	"response" : {
		"id" : "1",
		"name" : "Administrator",
		"description" : "Role defining an administrator of the application",
		"createdTime" : "0",
		"modifiedTime" : "0",
		"permManageApp" : "true",
		"permManageGroups" : "false",
		"permManageRoles" : "true",
		"permManageImages" : "false",
		"permManageGroupRelationships" : "false",
		"permManageBlackoutWindows" : "false",
		"permManageAttributeSets" : "false",
		"permCreateTickets" : "false",
		"permCreateAlerts" : "false",
		"permCreateAuditFiles" : "true",
		"permCreateLDAPAssets" : "false",
		"permCreatePolicies" : "true",
		"permPurgeTickets" : "false",
		"permPurgeScanResults" : "false",
		"permPurgeReportResults" : "false",
		"permScan" : "none",
		"permAgentsScan" : "false",
		"permAgentsSync": "false",
		"permShareObjects" : "false",
		"permUpdateFeeds" : "true",
		"permUploadNessusResults" : "false",
		"permViewOrgLogs" : "true",
		"permManageAcceptRiskRules" : "true",
		"permManageRecastRiskRules" : "true",
		"permManageACR": "false",
		"permViewDomainInventoryAssets": "false",
		"permManageAttackSurfaceDomains": "false",
		"permManageVulnRoutingRules": "false",
		"permViewHostAssets": "false",
		"permManageRiskRules": "false",
		"organizationCounts" : [
			{
				"id" : "0",
				"userCount" : "1"
			},
			{
				"id" : "12",
				"userCount" : "0"
			}
		],
		"creator" : {
			"id" : "1",
			"username" : "admin",
			"firstname" : "Admin",
			"lastname" : "User",
			"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1445013361
}

/role/{id}

/tes/role/{id}

/tes/role/{id} is only available in Tenable Enclave Security

Methods

GET

Gets the Role associated with {id}.

Fields Parameter

Expand

The fields parameter should be specified along the query string, and it takes the syntax

    ?fields=<field>,...

Allowed Fields

*id
**name
**description
creator
createdTime
modifiedTime
permManageApp
permManageGroups
permManageRoles
permManageImages
permManageGroupRelationships
permManageBlackoutWindows
permManageAttributeSets
permCreateTickets
permCreateAlerts
permCreateAuditFiles
permCreateLDAPAssets
permCreatePolicies
permPurgeTickets
permPurgeScanResults
permPurgeReportResults
permScan
permAgentsScan
permAgentsSync
permShareObjects
permUpdateFeeds
permUploadNessusResults
permViewOrgLogs
permManageAcceptRiskRules
permManageRecastRiskRules
permManageACR
permViewDomainInventoryAssets
permManageAttackSurfaceDomains
permManageVulnRoutingRules
permViewHostAssets
permManageRiskRules
organizationCounts

Legend

* = always comes back

** = comes back if fields list not specified on GET all

The fields not under * or ** can be used only by Admin or users with manageRole permission enabled.
Logged in user can use these fields to view details for self role only.
Org users cannot view Admin role itself but can view any other roles created by admin.

Request Parameters

None

Example Response

Admin user

Expand

{
	"type" : "regular",
	"response" : {
		"id" : "1",
		"name" : "Administrator",
		"description" : "Role defining an administrator of the application",
		"createdTime" : "0",
		"modifiedTime" : "0",
		"permManageApp" : "true",
		"permManageGroups" : "false",
		"permManageRoles" : "true",
		"permManageImages" : "false",
		"permManageGroupRelationships" : "false",
		"permManageBlackoutWindows" : "false",
		"permManageAttributeSets" : "false",
		"permCreateTickets" : "false",
		"permCreateAlerts" : "false",
		"permCreateAuditFiles" : "true",
		"permCreateLDAPAssets" : "false",
		"permCreatePolicies" : "true",
		"permPurgeTickets" : "false",
		"permPurgeScanResults" : "false",
		"permPurgeReportResults" : "false",
		"permScan" : "none",
		"permAgentsScan" : "false",
		"permAgentsSync" : "false",
		"permShareObjects" : "false",
		"permUpdateFeeds" : "true",
		"permUploadNessusResults" : "false",
		"permViewOrgLogs" : "true",
		"permManageAcceptRiskRules" : "true",
		"permManageRecastRiskRules" : "true",
		"permManageACR": "false",
		"permViewDomainInventoryAssets": "false",
		"permManageAttackSurfaceDomains": "false",
		"permManageVulnRoutingRules": "false",
		"permViewHostAssets": "false",
		"permManageRiskRules": "false",
		"organizationCounts" : [
			{
				"id" : "0",
				"userCount" : "1"
			},
			{
				"id" : "12",
				"userCount" : "0"
			}
		],
		"creator" : {
			"id" : "1",
			"username" : "admin",
			"firstname" : "Admin",
			"lastname" : "User",
			"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1445013361
}

Any user with manageRole permission enabled

Expand

{
	"type" : "regular",
	"response" : {
		"id" : "2",
		"name" : "Security Manager",
		"description" : "The Security Manager role has full access to all actions at the organization level. A Security Manager has the ability to create new groups and manage existing ones. A Security Manager can also define how users interact with other groups.\n\nThe ability to manage other users and their objects can be configured using group permissions on the Access tab of User add/edit. This includes viewing and stopping running scans and reports.",
		"createdTime" : "0",
		"modifiedTime" : "0",
		"permManageApp" : "false",
		"permManageGroups" : "true",
		"permManageRoles" : "true",
		"permManageImages" : "true",
		"permManageGroupRelationships" : "true",
		"permManageBlackoutWindows" : "true",
		"permManageAttributeSets" : "true",
		"permCreateTickets" : "true",
		"permCreateAlerts" : "true",
		"permCreateAuditFiles" : "true",
		"permCreateLDAPAssets" : "true",
		"permCreatePolicies" : "true",
		"permPurgeTickets" : "true",
		"permPurgeScanResults" : "true",
		"permPurgeReportResults" : "true",
		"permScan" : "full",
		"permAgentsScan" : "true",
		"permAgentsSync" : "false",
		"permShareObjects" : "true",
		"permUpdateFeeds" : "true",
		"permUploadNessusResults" : "true",
		"permViewOrgLogs" : "true",
		"permManageAcceptRiskRules" : "true",
		"permManageRecastRiskRules" : "true",
		"permManageACR": "false",
		"permViewDomainInventoryAssets": "false",
		"permManageAttackSurfaceDomains": "false",
		"permManageVulnRoutingRules": "false",
		"permViewHostAssets": "false",
		"permManageRiskRules": "false",
		"organizationCounts" : [
			{
				"id" : "12",
				"userCount" : "1"
			}
		],
		"creator" : {
			"id" : "1",
			"username" : "head",
			"firstname" : "",
			"lastname" : "",
			"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1445013361
}

Any user with manageRole permission disabled

Expand

{
	"type" : "regular",
	"response" : {
		"id" : "2",
		"name" : "Security Manager",
		"description" : "The Security Manager role has full access to all actions at the organization level. A Security Manager has the ability to create new groups and manage existing ones. A Security Manager can also define how users interact with other groups.\n\nThe ability to manage other users and their objects can be configured using group permissions on the Access tab of User add/edit. This includes viewing and stopping running scans and reports."
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1445013361
}

Any user fetching self role

Expand

{
	"type" : "regular",
	"response" : {
		"id" : "8",
		"name" : "Self role",
		"description" : "Any role with manageRole permission disabled",
		"createdTime" : "0",
		"modifiedTime" : "0",
		"permManageApp" : "false",
		"permManageGroups" : "true",
		"permManageRoles" : "false",
		"permManageImages" : "true",
		"permManageGroupRelationships" : "true",
		"permManageBlackoutWindows" : "true",
		"permManageAttributeSets" : "true",
		"permCreateTickets" : "true",
		"permCreateAlerts" : "true",
		"permCreateAuditFiles" : "true",
		"permCreateLDAPAssets" : "true",
		"permCreatePolicies" : "true",
		"permPurgeTickets" : "true",
		"permPurgeScanResults" : "true",
		"permPurgeReportResults" : "true",
		"permScan" : "full",
		"permAgentsScan" : "true",
		"permAgentsSync" : "false",
		"permShareObjects" : "true",
		"permUpdateFeeds" : "true",
		"permUploadNessusResults" : "true",
		"permViewOrgLogs" : "true",
		"permManageAcceptRiskRules" : "true",
		"permManageRecastRiskRules" : "true",
		"permManageACR": "false",
		"permViewDomainInventoryAssets": "false",
		"permManageAttackSurfaceDomains": "false",
		"permManageVulnRoutingRules": "false",
		"permViewHostAssets": "false",
		"permManageRiskRules": "false",
		"organizationCounts" : [
			{
				"id" : "12",
				"userCount" : "1"
			}
		],
		"creator" : {
			"id" : "1",
			"username" : "head",
			"firstname" : "",
			"lastname" : "",
			"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
		}
	},
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1445013361
}

PATCH

Edits the Role associated with {id}, changing only the passed in fields.

Request Parameters

(All fields are optional)

See /role::POST for parameters.

Example Response

See /role/{id}::GET

DELETE

Deletes the Role associated with {id}, depending on access and permissions.

Request Parameters

None

Example Response

Expand

{
    "type" : "regular",
    "response" : "",
    "error_code" : 0,
    "error_msg" : "",
    "warnings" : [],
    "timestamp" : 1403100582
}