# Spyderbat RBAC API **Canonical:** https://apis.io/apis/spyderbat/spyderbat-rbac-api/ **Provider:** Spyderbat — https://apis.io/providers/spyderbat/ **Base URL:** https://api.prod.spyderbat.com/api/v1 **Documentation:** https://docs.spyderbat.com/ Spyderbat RBAC API is one of 29 APIs that [Spyderbat](https://apis.io/providers/spyderbat/) publishes on the [APIs.io](https://apis.io/) network, described by a machine-readable OpenAPI specification. Tagged areas include RBAC. The published artifact set on APIs.io includes an OpenAPI specification, API documentation, an API reference, and a getting-started guide. # Introduction This RBAC model is based off of Amazon's model with some simplifications and generic assumptions A user has some number of roles on some number of organizations, each role defines some statements which determine determine if the user has access to some resources. These role based statements are combined with a policy which may be attached to the resource to be accessed. So essentially acccess is determined by the combination of identity based polices and resource based policies. All associated statements from both the user's roles and the resources policy are considered before access is granted. If any statement denies access then access is denied, at least one statement must explicitly grant access to the resource, and if no statement denies or grants access then access is not granted. The resulting access decision is a combination of: ``` Evaluate(Roles(User,Org),Resource) - will evaluate all possible user roles on the resource Evaluate(GlobalRoles(User),Resource) - will evaluate all possible user roles on the resource Evaluate(CrossOrgRoles(User,Org),Resource) - will evaluate all possible cross org roles on the resource Evaluate(Resource.Policy,User) - will evalute the requesting user against the resource policy ``` This means that a user role can specify what the user can access, while a specific resource policy has the ability to deny access to a single user, or a user based upon roles or tags. # Example user role ```json { "name":"CatFeeder", "version":"1.0.0", "statements":[ { "sid":"FeedCats", "effect":"allow", "actions":[ "cat:feed" ], "resources":[ "srn:cat:::*" ], "condition": { "not": { "has_tag":"obese"}} } ] } ``` This example user role defines a role called 'CatFeeder', which is allowed to perform 'cat:feed' on all resources which match 'srn\:cat\:::\*', as long as the cat the role is being used on does not have the tag 'obese'. # Global vs Organization roles A global role is a role which does not have a specific context, it is 'global' in that it applies to all resources a user might interact with. An organizational role is assigned to a specific organization, and therefore limited to the context of that organization. For example a global role is one which allows a user to change their own password, or perform other actions which do not involve an organization. An organizational role is a role which allows actions on resources owned by an organization. An example of this is a typical user: * Global Role (User) * Allows the user to modify their own settings, change their password, etc. * Org Role (OrgOwner) * Allows the user to modify an organization * Applied to specific organizations # User Roles Users may zero or more roles defined on different organizations, along with global roles , a role is defined with the following attributes * Name - Name of the policy, used to match to roles associated with users * Version - Version of the role schema * Statements - Some number of statements # Resource Policy A resource may have a single policy with multiple statements associated with it, it has the following attributes * Name - Name of the policy, used to match to roles associated with users * Version - Version of the role schema * Statements - Some number of statements # Statement Each role or policy has some statements defined with it, each statement defines what actions are allowed or dissallowed Statements have the following attributes * SID - statment ID used for debugging and identification * Effect - the result of the statement (deny, allow) * Actions - a list of actions * Resources - a list of resource queries * Condition - an optional condition that will be applied to statements to determine if they apply ## Statement Effects To determine if access may be granted the statements associated with the user roles, cross account roles, and resources are evaluated. If any statement returns a deny then all further evaluation is stopped and the result is a denial. At least one statement must allow access for access to be granted. If no statement denies or allows access then the system will not allow access. ## Actions Actions are a combination of Service:Action, and also have a few wild card patterns: ``` * - match any action service:* - match any action on this service service:action - match this explicit combination of action and service ``` ## Spyderbat Resource Names Each resource in the RBAC system is given a name like so: ``` srn:service:region:org:resource ``` The resource name is expected to expand into a path like resource name when a hierarchy is needed, for example: ``` srn:report:aws-us-west-1:org-1:agent-usage-report/download.pdf ``` These resource names are matched in policies against resource queries: ``` srn:report:::*/*.pdf ``` Is an example of resource query which would match the above resource. The following globs are supported in resource names ``` /**/ - match zero or more directories {a,b} - match a or b, no spaces * - match any non-separator char ? - match a single non-separator char **/ - match any directory, start of pattern only /** - match any this directory, end of pattern only ! - removes matches from resultset, start of pattern only ``` ``` * - match all resources srn::::* - match all resources srn:report::::* - match all report resources srn:report::org-1:* - match all resources in a specific org ``` ## Conditions The system will first evalute if the requested resource and the requested action match, if so then the system will evaluate any conditions which are specified on the statement. The following conditions are supported: ``` { not: condition } - not of the specified condition { and: [....] } - and of all contained conditions { or: [....] } - or of all contained conditions { has_tag:"tag"} - returns true if the resource has the associated tag { has_role:"role", on_org:"org-1" } - returns true if the user has a role of 'role' on 'org-1' ``` # User Roles Users are mapped to roles within an organization via a userToRole relationship, which allows for a user to have many roles on many organizations. ``` (User, Org, Role)... ``` *This means that a user can have many different roles on different organizations* For example the user David may have roles on multiple organizations: ```` David Org1: Analyat Org1: Operator Org2: Analyst ... ```` These roles are mapped by name to a specific role implementation. ## Cross Org Roles Cross org roles for use by MSSPs are supported by having the managed organization defining a special cross-org role with the following attributes: * Org - The org the cross org role applies to * Condition - The condition to evaluate * AssumeRole - The role the user may assume ## Example cross org role ```json { "org":"house-1", "assume_role":"CatPetter", "version":"1.0.1", "condition": { "has_role":"CatPetter", "on_org":"house-2" } } ``` This role will allow any user who has the role 'CatPetter' in the org 'house-2' to assume the role 'CatPetter' in 'house-1' ## Machine-readable artifacts (4) - **OpenAPI** — https://raw.githubusercontent.com/api-evangelist/spyderbat/refs/heads/main/openapi/spyderbat-rbac-api-openapi.yml - **Documentation** — https://docs.spyderbat.com/ - **APIReference** — https://api.spyderbat.com/openapi - **GettingStarted** — https://docs.spyderbat.com/tutorials/integrations/how-to-set-up-your-spyderbat-api-key-and-use-the-spyderbat-api ## Other Spyderbat APIs (12) - [Spyderbat Adhoc Search API](https://apis.io/apis/spyderbat/spyderbat-adhocsearch-api/) - [Spyderbat Agent Action API](https://apis.io/apis/spyderbat/spyderbat-agent-action-api/) - [Spyderbat Agent API](https://apis.io/apis/spyderbat/spyderbat-agent-api/) - [Spyderbat Agent Registration API](https://apis.io/apis/spyderbat/spyderbat-agent-registration-api/) - [Spyderbat Agent Work API](https://apis.io/apis/spyderbat/spyderbat-agentwork-api/) - [Spyderbat Analytics Policy API](https://apis.io/apis/spyderbat/spyderbat-analyticspolicy-api/) - [Spyderbat Analytics Ruleset API](https://apis.io/apis/spyderbat/spyderbat-analyticsruleset-api/) - [Spyderbat Archive API](https://apis.io/apis/spyderbat/spyderbat-archive-api/) - [Spyderbat Cases API](https://apis.io/apis/spyderbat/spyderbat-cases-api/) - [Spyderbat Cluster API](https://apis.io/apis/spyderbat/spyderbat-cluster-api/) - [Spyderbat Custom Flag API](https://apis.io/apis/spyderbat/spyderbat-customflag-api/) - [Spyderbat Fingerprint Data API](https://apis.io/apis/spyderbat/spyderbat-fingerprintdata-api/) ## Tags RBAC --- Profiled by [API Evangelist](https://apievangelist.com) and published on [APIs.io](https://apis.io/apis/spyderbat/spyderbat-rbac-api/). The API's provider profile, Kin Score and agent-readiness rating are at https://apis.io/providers/spyderbat/.