Comment on page
Test roles
If you have role-based access control in your APIs and application, you would want to test for privilege escalation vulnerabilities. This typically involves checking access of all the higher-privilege APIs by a lower-privilege user. If any such API exists, then it's privilege should be fixed by the development team.
Akto enables you to do automate privilege escalation security tests. You can also use the information while creating Test YAML templates if you want to develop custom tests.
The instructions here cover the above 3 steps in detail.
You should create as many roles as are in your application. For example, if you are a B2B Saas app, you might have ADMIN, BILLING, MEMBER, GUEST etc. roles. Role creation is a one-time configuration.
- 1.In the left navigation menu, go to
Testing
and then click onRoles
tab. - 2.Click on the plus-icon to add a new role.
- 3.Give a suitable name to your role eg. ADMIN. Select the APIs that belong to the application. If you want to select from an existing API Collection, use
belongs to
operator. - 4.Select API Collection from the dropdown menu.
- 5.Select endpoints you'd want to evaluate. You can simply select all. And click on
Save
button.
During API testing, Akto will add these headers to the sample API calls to check if the role has access to the API. You can provide a hardcoded auth header or you can also automate fetching auth token automatically (next section) for the role.
- 1.Click on the
Add auth
button to add auth-token for your role. Then click on theplus
icon to add auth headers for the role - 2.Add your auth header key and its value as shown.
- 3.You can add multiple headers too. Click on the
plus
icon to add more headers for this role. Click onSave
when you are done.
If you configure automated auth token generation, Akto will run the Login-request sequence before the test starts and fetch the auth token. You should know which API (or sequence of APIs) can give you the auth token in the response. For this example, we will configure a Login-request sequence of 2 APIs. The response of the 2nd API contains the auth token.
- 1.If you want to automate auth token generation you can select
Login-request
radio button. And click onCreate
button. - 2.You will see a dialog box where you can configure the sequence to fetch auth token automatically.
- 3.You can set URL, Query params, Method, Headers and Body for your request. Click on the
edit
button on each field to set it. Once you enter the required value, click on thecheck
icon at the end of the line to save the field. - 4.Here, we have configured the first API call to create a user with a given email and password. You can choose to skip this api call in your case if you already have a user created with this role.
- 5.Click on the
Test
button to see the result of this API call. - 6.If you have configured the API call correctly, you should see the desired response. In this case, we see the API responds with success.
- 7.To add another API call to the login sequence, click on the
Add step
button. You can multiple steps for the login sequence. If you want to remove a step, click onRemove step
button on the top-right. - 8.Let's configure the 2nd API call in the login sequence. Note that the
email
andpassword
field should be the same as previous API call. In the sequence, you can substitute values from requests & responses of previous API calls. You can refer to the first API call asx1
. You can accessrequest
orresponse
. Inrequest
, you can accessurl
,method
,body
,headers
fields. Forresponse
, you can accessbody
andheaders
field. Remember to use${}
while referring to any of API variables. For example, to get email from the request body of the first API call, we can say${x1.request.body.email}
. Similarly we can access password field using${x1.request.body.password}
- 9.Click on the
Test
button to check for the response. Here, we successfully get the auth token in the response body. Click onExtract
button to start extracting token from this API response.
- 10.Under "Header value" mention how to extract the auth token from the API response. In this example we can say
${x2.response.body.authentication.token}
. Mention the "Header key" under which Auth token will be attached as part of the API request while testing. eg.Authorization
. Click onDone
button. - 11.If the auth token is supposed to be attached in the request body, you can select
Body
in the step above. - 12.Don't forget to
Save
the automated login sequence in the role.
Akto will replay the API requests which it recorded in your application server traffic. In your setup, it might be possible that there are multiple accounts being used on your staging app, hence Akto will record API calls from multiple accounts. In these cases, just 1 auth token per role might not suffice. You might want to configure 1 auth token for each account. When Akto tries to replay the recorded sample API call, it can pick up the auth token meant for the same account as the API request to check for role-access.
- 1.If account id comes as a simple header field, you can click on the
Analyze
tab to find out possible values of any header that Akto has captured. - 2.For example, we can find out how many diff values has Akto recorded with
CompanyId
header. We see only 3 "CompanyId" values. Note that the analysis comes from saved requests only. Akto doesn't save all API traffic it processes. It saves only a few requests. - 3.We should configure an "auth" token for each such company. We can use
Api Header conditions
for this. Mention "CompanyId" as header key and "1234567" as header value. Akto will use this token while testing for sample API requests whose CompanyId in the headers equals "1234567". We should configure 2 more auths for remaining 2 companies for complete coverage.
Once tokens are set up, the next step is to hit all the recorded APIs with tokens from each role. This way, Akto maintains a table for each role for each API - if the role can access that API. We call this
Access matrix
.- 1.Click on the
Access
tab - 2.Click on
Create access matrix
button - 3.Currently, access-matrix job runs once per hour. You might have to wait for an hour to see the results. You don't have to click on "Create access matrix" button for other roles one-by-one. Akto will create access matrix for all roles together. In this example of Juiceshop, ADMIN can access 52 APIs, but MEMBER can access 43. There are 9 APIs exclusive to Admin.
- 4.Akto will run this task daily.
You should periodically review the access matrix. Specially when any associations change.
You can use this information in test YAML templates too. You can filter APIs exclusive to the ADMIN role (9 APIs in this example). You can also get the auth token for any role in the template.
Say we want to create a custom YAML test that should run on the Admin-exclusive APIs using Member token. If any API returns 2XX response, we will send an alert.
This is a combination of 2 conditions - The API should accessible by ADMIN, and, the API should NOT be accessible by MEMBER.
include_roles_access
- You can use this filter to include all the APIs accessible by a particular role. eg. here we can use it as -
include_roles_access:
param: ADMIN
exclude_roles_access
- You can use this filter to exclude all the APIs accessible by a particular role. eg. here we can use it as -
exclude_roles_access:
param: MEMBER
You
api_selection_filters
section can then look like the following -api_selection_filters:
response_code:
gte: 200
lt: 300
include_roles_access:
param: ADMIN
exclude_roles_access:
param: MEMBER
You can use the auth token from any role in your test template. In our example, we would want to get the token of the MEMBER role. We can use
modify_header
rule. We can pass ${roles_access_context.MEMBER}: 1
as its value which will obtain an auth token of MEMBER role and replace in the API call while testing.Your execute section will then look like -
execute:
type: single
requests:
- req:
- modify_header:
${roles_access_context.MEMBER}: 1
You can save this test template with name & id as "PRIVILEGE_ESCALATION_TEST" and have it part of your CI/CD pipeline. Now no API goes without being tested for privilege escalation!
Last modified 2mo ago