Tenable.sc API: Role

 

/role

Methods
GET

Gets the list of Roles

Fields Parameter
Expand

NOTE: Currently, all fields come back on GET all, but the ** indicates fields which will be listed in a future release

 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
permShareObjects
permUpdateFeeds
permUploadNessusResults
permViewOrgLogs
permManageAcceptRiskRules
permManageRecastRiskRules
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.",
			"createdTime" : "0",
			"modifiedTime" : "0",
			"permManageApp" : "false",
			"permManageGroups" : "false",
			"permManageRoles" : "false",
			"permManageImages" : "false",
			"permManageGroupRelationships" : "false",
			"permManageBlackoutWindows" : "false",
			"permManageAttributeSets" : "false",
			"permCreateTickets" : "false",
			"permCreateAlerts" : "false",
			"permCreateAuditFiles" : "false",
			"permCreateLDAPAssets" : "false",
			"permCreatePolicies" : "false",
			"permPurgeTickets" : "false",
			"permPurgeScanResults" : "false",
			"permPurgeReportResults" : "false",
			"permScan" : "none",
			"permAgentsScan" : "false",
			"permShareObjects" : "false",
			"permUpdateFeeds" : "false",
			"permUploadNessusResults" : "false",
			"permViewOrgLogs" : "false",
			"permManageAcceptRiskRules" : "false",
			"permManageRecastRiskRules" : "false",
			"organizationCounts" : [
				{
					"id" : "12",
					"userCount" : "0"
				}
			],
			"creator" : {
				"id" : "1",
				"username" : "head",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
			}
		},
		{
			"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",
			"permShareObjects" : "true",
			"permUpdateFeeds" : "true",
			"permUploadNessusResults" : "true",
			"permViewOrgLogs" : "true",
			"permManageAcceptRiskRules" : "true",
			"permManageRecastRiskRules" : "true",
			"organizationCounts" : [
				{
					"id" : "12",
					"userCount" : "1"
				}
			],
			"creator" : {
				"id" : "1",
				"username" : "head",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
			}
		},
		{
			"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.",
			"createdTime" : "0",
			"modifiedTime" : "0",
			"permManageApp" : "false",
			"permManageGroups" : "false",
			"permManageRoles" : "false",
			"permManageImages" : "true",
			"permManageGroupRelationships" : "false",
			"permManageBlackoutWindows" : "true",
			"permManageAttributeSets" : "true",
			"permCreateTickets" : "true",
			"permCreateAlerts" : "true",
			"permCreateAuditFiles" : "true",
			"permCreateLDAPAssets" : "true",
			"permCreatePolicies" : "true",
			"permPurgeTickets" : "true",
			"permPurgeScanResults" : "true",
			"permPurgeReportResults" : "true",
			"permScan" : "full",
			"permAgentsScan" : "true",
			"permShareObjects" : "true",
			"permUpdateFeeds" : "true",
			"permUploadNessusResults" : "true",
			"permViewOrgLogs" : "true",
			"permManageAcceptRiskRules" : "true",
			"permManageRecastRiskRules" : "true",
			"organizationCounts" : [
				{
					"id" : "12",
					"userCount" : "0"
				}
			],
			"creator" : {
				"id" : "1",
				"username" : "head",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
			}
		},
		{
			"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.",
			"createdTime" : "0",
			"modifiedTime" : "0",
			"permManageApp" : "false",
			"permManageGroups" : "false",
			"permManageRoles" : "false",
			"permManageImages" : "false",
			"permManageGroupRelationships" : "false",
			"permManageBlackoutWindows" : "false",
			"permManageAttributeSets" : "false",
			"permCreateTickets" : "true",
			"permCreateAlerts" : "true",
			"permCreateAuditFiles" : "true",
			"permCreateLDAPAssets" : "true",
			"permCreatePolicies" : "true",
			"permPurgeTickets" : "false",
			"permPurgeScanResults" : "false",
			"permPurgeReportResults" : "false",
			"permScan" : "full",
			"permAgentsScan" : "true",
			"permShareObjects" : "true",
			"permUpdateFeeds" : "true",
			"permUploadNessusResults" : "true",
			"permViewOrgLogs" : "true",
			"permManageAcceptRiskRules" : "false",
			"permManageRecastRiskRules" : "false",
			"organizationCounts" : [
				{
					"id" : "12",
					"userCount" : "0"
				}
			],
			"creator" : {
				"id" : "1",
				"username" : "head",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
			}
		},
		{
			"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.",
			"createdTime" : "0",
			"modifiedTime" : "0",
			"permManageApp" : "false",
			"permManageGroups" : "false",
			"permManageRoles" : "false",
			"permManageImages" : "false",
			"permManageGroupRelationships" : "false",
			"permManageBlackoutWindows" : "false",
			"permManageAttributeSets" : "false",
			"permCreateTickets" : "true",
			"permCreateAlerts" : "false",
			"permCreateAuditFiles" : "false",
			"permCreateLDAPAssets" : "false",
			"permCreatePolicies" : "false",
			"permPurgeTickets" : "false",
			"permPurgeScanResults" : "false",
			"permPurgeReportResults" : "false",
			"permScan" : "none",
			"permAgentsScan" : "false",
			"permShareObjects" : "false",
			"permUpdateFeeds" : "false",
			"permUploadNessusResults" : "false",
			"permViewOrgLogs" : "false",
			"permManageAcceptRiskRules" : "false",
			"permManageRecastRiskRules" : "false",
			"organizationCounts" : [
				{
					"id" : "12",
					"userCount" : "0"
				}
			],
			"creator" : {
				"id" : "1",
				"username" : "head",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
			}
		},
		{
			"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.",
			"createdTime" : "0",
			"modifiedTime" : "0",
			"permManageApp" : "false",
			"permManageGroups" : "false",
			"permManageRoles" : "false",
			"permManageImages" : "false",
			"permManageGroupRelationships" : "false",
			"permManageBlackoutWindows" : "false",
			"permManageAttributeSets" : "false",
			"permCreateTickets" : "false",
			"permCreateAlerts" : "false",
			"permCreateAuditFiles" : "false",
			"permCreateLDAPAssets" : "false",
			"permCreatePolicies" : "false",
			"permPurgeTickets" : "false",
			"permPurgeScanResults" : "false",
			"permPurgeReportResults" : "false",
			"permScan" : "none",
			"permAgentsScan" : "false",
			"permShareObjects" : "true",
			"permUpdateFeeds" : "false",
			"permUploadNessusResults" : "false",
			"permViewOrgLogs" : "false",
			"permManageAcceptRiskRules" : "false",
			"permManageRecastRiskRules" : "false",
			"organizationCounts" : [
				{
					"id" : "12",
					"userCount" : "0"
				}
			],
			"creator" : {
				"id" : "1",
				"username" : "head",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
			}
		},
		{
			"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.",
			"createdTime" : "0",
			"modifiedTime" : "0",
			"permManageApp" : "false",
			"permManageGroups" : "false",
			"permManageRoles" : "false",
			"permManageImages" : "false",
			"permManageGroupRelationships" : "false",
			"permManageBlackoutWindows" : "false",
			"permManageAttributeSets" : "false",
			"permCreateTickets" : "false",
			"permCreateAlerts" : "false",
			"permCreateAuditFiles" : "false",
			"permCreateLDAPAssets" : "false",
			"permCreatePolicies" : "false",
			"permPurgeTickets" : "false",
			"permPurgeScanResults" : "false",
			"permPurgeReportResults" : "false",
			"permScan" : "none",
			"permAgentsScan" : "false",
			"permShareObjects" : "false",
			"permUpdateFeeds" : "false",
			"permUploadNessusResults" : "false",
			"permViewOrgLogs" : "true",
			"permManageAcceptRiskRules" : "false",
			"permManageRecastRiskRules" : "false",
			"organizationCounts" : [
				{
					"id" : "12",
					"userCount" : "0"
				}
			],
			"creator" : {
				"id" : "1",
				"username" : "head",
				"firstname" : "",
				"lastname" : "",
				"uuid" : "96F2AD1B-1B83-462E-908A-84E6054F6B64"
			}
		}
	],
	"error_code" : 0,
	"error_msg" : "",
	"warnings" : [],
	"timestamp" : 1445013119
}

POST

Adds an 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",
	"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"
}
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",
		"permShareObjects" : "false",
		"permUpdateFeeds" : "true",
		"permUploadNessusResults" : "false",
		"permViewOrgLogs" : "true",
		"permManageAcceptRiskRules" : "true",
		"permManageRecastRiskRules" : "true",
		"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}

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

permShareObjects
permUpdateFeeds
permUploadNessusResults
permViewOrgLogs
permManageAcceptRiskRules
permManageRecastRiskRules
organizationCounts

Legend

* = always comes back

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

None

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",
		"permShareObjects" : "false",
		"permUpdateFeeds" : "true",
		"permUploadNessusResults" : "false",
		"permViewOrgLogs" : "true",
		"permManageAcceptRiskRules" : "true",
		"permManageRecastRiskRules" : "true",
		"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
}

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
}