Authorization Access or Scopes
The main authorization model is based on scopes and it is driven by the OAuth2 specification. A scope is a simple string that contains no space which is interpreted by the API to accept, reject, or modify the behavior of a call. Most root scopes relates to a specific API endpoint, please use this API guide as reference, as each API will have listed which scope is required.
The following is a list of root scopes:
| scope | description |
|---|---|
Admin |
Provide admin privileges |
Asset |
Access and modify your assets |
AO |
Manage and execute your Automation workflows |
Casebook |
Access and modify your Casebooks |
Enrich:Read |
Query your configured modules for threat intelligence |
Event:Read |
Read IROH Events - Read Only |
Feedback |
Submit Customer Feedback |
Global Intel:Read |
Access Global Intelligence - Read Only |
Inspect:Read |
Extract Observables and data from text |
Integration |
Manage your modules (including Control Center tiles) |
Investigation |
Perform threat analysis investigation |
Invite |
Invite users into your organization |
Notification |
Receive notifications from integrations |
Oauth |
Manage OAuth2 Clients |
Orbital |
Orbital Integration |
Private Intel |
Access Private Intelligence |
Profile |
Get your profile information |
Registry |
Manage registry entries |
Response |
List and execute response actions using configured modules |
SSE |
SSE Integration: manage your on-prem devices |
Telemetry:Write |
collect application data for analytics - Write Only |
Users |
Manage users of your organisation |
Webhook |
Manage your Webhooks |
Sub Scopes
Read or Write Sub Scopes
Scopes are strings, but the Cisco XDR API supports a generic format of those scopes to provide fine-grained access. The first level is to provide read-only access to a scope. For that, it uses the suffix :read.
For example:
The global-intel:read is generally the scope that all users have by default. It means that the user can only access read-only routes of Cisco XDR Global Threat Intelligence. If the user tries to access a non read-only route, the user will receive an HTTP 403 Forbidden response status.
Sometime the scopes of the user cannot return a 403, but instead change the results. For example, the Response API provides both response call and references. If the user asks for all the possible responses with a scope limited to response:read, they will only receive the response they can trigger with a read-only user. And thus, they will only receive references. In summary, they will be able to have a link to the Secure Endpoint dashboard about some hash, but they will not be able to add or remove a hash from a Secure Endpoint list.
Scopes Tree Structure
In the previous section, it was explained that appending :read to some scope limits the access to read-only routes. There is also a mechanism that provides only access to some sub-trees of some API. For that, / is used to grant access only to a sub-set of all the scopes provided by the root scope.
To only grant access to the health routes to a client or user, the full scope of enrich can be replaced with the restricted scope of enrich/health:read.