This article will illustrate how to automate the configuration of roles and permissions for your CloudGuard account using the CloudGuard API.
Resources used:
- Role - this is used to add and update a new role to the CloudGuard account (see Role)
- CloudAccount - this is used to obtain the CloudGuard account id (see CloudAccounts)
- OrganizationalUnit - this is used to obtain the CloudGuard id for an Org Unit (see OrganizationalUnit)
Prerequisites
- you will need the API Key and Secret for your CloudGuard account. These are used as the username & password to access your account with the API, using Basic Authentication.
Get all the roles in your account
Request
GET https://api.dome9.com/v2/Role
Response
The response gives all the roles currently defined for the account, with their permissions.
[
{
"id":76721,
"name":"admin",
"description":"admin",
"permissions":{
"access":[
"1"
],
"manage":[
"1"
],
"create":[
"2"
],
"view":[
""
],
"crossAccountAccess":[ ]
}
},
{
"id":76641,
"name":"Auditor",
"description":"Auditor Role, Views all system resources",
"permissions":{
"access":[ ],
"manage":[ ],
"create":[ ],
"view":[
""
],
"crossAccountAccess":[ ]
}
},
{
"id":76642,
"name":"Super User",
"description":"Super User Role, Manages all system resources",
"permissions":{
"access":[ ],
"manage":[
""
],
"create":[
"0",
"2"
],
"view":[ ],
"crossAccountAccess":[ ]
}
}
]
Code sample
curl -X GET https://api.dome9.com/v2/Role/ \
--basic -u <key-id>:<key-secret> \
-H 'Accept: application/json'
Create a new role
Creating a new role is a 2 step process:
- first we create (
post) a new role with empty permissions
- then we update (
put) this role with the desired permissions
This is the JSON request block for the POST method:
{
"name":"new-name",
"description":"my-role-desc",
"permissions": {
"access": [],
"manage": [],
"create": [],
"view": [],
"crossAccountAccess": []
}
}
Create a new role without permissions
Request
POST https://api.dome9.com/v2/Role
{
"name":"new-role",
"description":"my-role-desc",
"permissions":{
"access":[ ],
"manage":[ ],
"create":[ ],
"view":[ ],
"crossAccountAccess":[ ]
}
}
Response
The response shows the new role. The id, 94761, will be used to add permissions to the role.
{
"id":94761,
"name":"new-role",
"description":"my-role-desc",
"permissions":{
"access":[ ],
"manage":[ ],
"create":[ ],
"view":[ ],
"crossAccountAccess":[ ]
}
}
Code sample
curl -X POST https://api.dome9.com/v2/Role \
--basic -u <key-id>:<key-secret> \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
-d '{
"name":"new-name",
"description":"my-role-desc",
"permissions": {
"access": [],
"manage": [],
"create": [],
"view": [],
"crossAccountAccess": []
}
}'
Add permissions to the role
Construct the correct permissions object
The most relevant permissions are manage and view. Note that manage also includes the view permission so there is no need to add duplicates.
The resolution for our use-case will be either all accounts or a specific AWS account(s). You can also assign permissions to an Organizational Unit (a group of cloud accounts).
Permission for specific AWS accounts
In the (manage/view) property we'll construct an array of the form: 1|<CloudGuard Cloud Account Id>
Example - permissions object for managing 2 AWS accounts:
"permissions": {
"access": [],
"manage": [
"1|aaaaaaaaa-48b8-4f64-baa5-b70901fe56db",
"1|bbbbbbbbb-48b8-4f64-baa5-b70901fe56db"
],
"create": [],
"view": [],
"crossAccountAccess": []
}
Note: "1" is the code for AWS. For Azure, use "7", and for GCP, "8". For Organizational Units (groups of accounts), use "12". The value after "|" is the CloudGuard id for the account (or Org Unit, see below, for details how to obtain this).
Permission for ALL resources (AWS account, Azure ,GCP and any other asset/policy)
In the (manage/view) property we'll add an entry with an empty string, which represents a 'catch all' filter.
Example - permissions object for viewing ALL AWSaccounts:
"permissions": {
"access": [],
"manage": [],
"create": [],
"view": [
""
],
"crossAccountAccess": []
}
``
Determine the CloudGuard account id from the AWS account number
The permissions array in the request block for updating (post) roles requires the internal CloudGuard account id. To obtain this, we will use the cloudaccounts resource to resolve the AWS account number to the CloudGuard ID.
Request
GET https://api.dome9.com/v2/CloudAccounts
Response
The response shows details for the CloudGuard account. The id field in the response is the internal CloudGuard account ID.
[
{
"id":"6*******-a***-4***-b***-c**********a",
"vendor":"aws",
"name":"AWS-1",
"externalAccountNumber":"***********9",
"error":null,
"creationDate":"2018-08-27T12:58:25.443Z",
"credentials":{ ... },
"iamSafe":null,
"netSec":{ ...
},
"magellan":false,
"fullProtection":false,
"allowReadOnly":false
}
]
Code sample
curl -X GET https://api.dome9.com/v2/CloudAccounts/ \
--basic -u <key-id>:<key-secret> \
-H 'Accept: application/json'
In a similar way, you can use GET https://api.dome9.com/v2/OrganizationalUnit to obtain a list of all Org Units,
and their ids.
Update a role with permissions
To add permissions to a role, we will put into the right resource id the new role object.
In this example we'll add a permission to manage a single AWS account, but we could make any permissions modification, such as removing old permissions or adding new permissions.
Notes:
- This will overwrite the entire entity, so, if you wish to perform a partial update, make sure to
get it first, apply your modification to the entire list, and then put the new state
- Please review the resource URL that we are putting into (containing the role ID)
Request
PUT https://api.dome9.com/v2/Role/94761
{
"id": 94761,
"name":"new-role",
"description":"auto-desc",
"permissions": {
"access": [],
"manage": [
"1|6*******-a***-4***-b***-c**********a"
],
"create": [],
"view": [],
"crossAccountAccess": []
}
}
Response
The response confirms the addition of the 'manage' permission to the role.
{
"id":94761,
"name":"new-role",
"description":"auto-desc",
"permissions":{
"access":[ ],
"manage":[
"1|6*******-a***-4***-b***-c**********a"
],
"create":[ ],
"view":[ ],
"crossAccountAccess":[ ]
}
}
Code sample
curl -X GET https://api.dome9.com/v2/CloudAccounts/94761 \
--basic -u <key-id>:<key-secret> \
-H 'Accept: application/json'
-d '{
"id":94761,
"name":"new-role",
"description":"auto-desc",
"permissions":{
"access":[ ],
"manage":[
"1|6*******-a***-4***-b***-c**********a"
],
"create":[ ],
"view":[ ],
"crossAccountAccess":[ ]
}
}'
Delete a role
Delete a role by sending the delete http request to the relevant resource id.
Request
DELETE https://api.dome9.com/v2/Role/94761
Response
204
