Manage Scans
- Print
- PDF
Manage Scans
- Print
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
You can use the Britive API methods for managing scans and retrieving scan history of accounts, permissions, or groups.
1. Run Organization Scan
This is the latest API for Run Organization Scan.
The POST method runs an organization scan for the supported applications in the Britive system.
| POST | {{url}}/api/apps/{{appID}}/scan |
Request Example
An example POST request for running an organization scan for applications is shown here.
curl --location --request POST '{{url}}/api/apps/{{appID}}/scan' \
--header 'Authorization: TOKEN {{token}}'Response Example
An example response of the POST request for running an organization scan for applications is shown here:
| Status: 200 OK |
{
"taskId": "34j65hi7a5lyalrq1cvzrh6c",
"scheduledTaskId": null,
"environmentId": null,
"timestamp": "2020-11-11T11:01:38Z",
"scannedBy": "user1",
"status": "Submitted",
"error": "",
"scanType": "Organization",
"scanDataSummary": null,
"tenantNamespace": "demo",
"totalScanTimeWatch": null,
"totalConnectorTimeWatch": null,
"message": "",
"success": false
}(Deprecated) Run Organization Scan
Important Note:
The following API for Run Org Scan is deprecated and will be removed in a future release.
The GET method runs an organization scan for the supported applications in the Britive system.
| GET | {{url}}/api/apps/{{appID}}/scan |
Request Example
An example GET request for running an organization scan for applications is shown here.
curl --location --request GET '{{url}}/api/apps/{{appID}}/scan' \
--header 'Authorization: TOKEN {{token}}'Response Example
An example response of the GET request for running an organization scan for applications is shown here:
| Status: 200 OK |
{ "success" : true,
"message" : null
}2. Check Scan Status
The GET method checks the status of currently active scans as indicated by the taskID provided in the request.
| GET | {{url}}/api/apps/tasks/{{taskID}}/status |
Request Example
An example request of the GET method for checking the scan status is shown here.
curl --location --request GET '{{url}}/api/apps/tasks/{{taskID}}/status' \
--header 'Authorization: TOKEN {{token}}'Response Example
| Status: 200 OK |
An example response of the GET request for checking the scan status is shown here.
{
"taskId": "60tapr56olqne9t48gm7duim",
"scheduledTaskId": null,
"environmentId": null,
"timestamp": "2020-10-12T10:44:57Z",
"scannedBy": "user1",
"status": "Success",
"scanType": "Organization",
"scanDataSummary": {
"appName": "Test App",
"envName": null,
"catalogAppName": "AWS",
"environmentsCollected": 6,
"environmentGroupsCollected": 5,
"environmentsAdded": [],
"environmentsDeleted": [],
"environmentsMoved": [],
"environmentsDisabled": [],
"environmentsEnabled": [],
"environmentGroupsAdded": [],
"environmentGroupsDeleted": [],
"scanType": "Organization",
"scanStatus": "Success",
"message": "Success",
"totalAccountsCollected": 0,
"newAccountsDetected": 0,
"accountsDeleted": 0,
"newPrivilegedAccountsDetected": 0,
"totalPermissionsCollected": 0,
"newPermissionsDetected": 0,
"permissionsDeleted": 0,
"newPrivilegedPermissionsDetected": 0,
"totalGroupsCollected": 0,
"newGroupsDetected": 0,
"groupsDeleted": 0,
"newPrivilegedGroupsDetected": 0,
"changesToAccounts": 0,
"changesToGroups": 0,
"changesToPermissions": 0,
"changesToPrivilegedPermissions": 0,
"changesToPrivilegedGroups": 0,
"permissionsAddedToAccounts": 0,
"permissionsRemovedFromAccounts": 0,
"permissionsAddedToGroups": 0,
"permissionsRemovedFromGroups": 0,
"groupsAddedToAccounts": 0,
"groupsRemovedFromAccounts": 0,
"groupsAddedToPermissions": 0,
"groupsRemovedFromPermissions": 0,
"groupsAddedToGroups": 0,
"groupsRemovedFromGroups": 0,
"accountsAddedToPermissions": 0,
"accountsRemovedFromPermissions": 0,
"accountsAddedToGroups": 0,
"accountsRemovedFromGroups": 0,
"permissionDefinitionsUpdated": 0,
"accountsMapped": 0,
"accountsUnresolved": 0,
"appId": "tf38381zi2ycznfyyst6",
"envId": null,
"metrics": null
},
"tenantNamespace": null,
"totalScanTimeWatch": null,
"totalConnectorTimeWatch": null,
"message": "",
"success": true
}3. Scan of Environments
The POST method submits a scan for the application and environment IDs provided in the request and returns the taskID. You can use the Check Scan Status API to find the status of the scan task.
| POST | {{url}}/api/apps/{{appID}}/environments/{{envID}}/scans |
Request Example
An example POST request for scanning an environment is shown here.
curl --location --request POST '{{url}}/api/apps/{{appID}}/environments/{{envID}}/scans' \
--header 'Authorization: TOKEN {{token}}'Response Example
An example response of the POST request for scanning an environment is shown here.
{
"taskId": "62r3kd96ti1tnxb711sh5ova",
"scheduledTaskId": null,
"environmentId": "378563640942",
"timestamp": "2020-07-28T11:07:06Z",
"scannedBy": "johnsmith",
"status": "Submitted",
"scanDataSummary": null,
"tenantNamespace": "preview",
"totalScanTimeWatch": null,
"totalConnectorTimeWatch": null,
"success": false,
"message": ""
}4. Scan History
This is the latest API for Scan History.
The GET method returns the list of all scans in the past 90 days for the application id given in the request. The data is returned in pages. Multiple API calls have to be made to return the complete list.
| GET | {{url}}/api/apps/{{appID}}/scans/env-status/history?page=0&size=100&sort=name,asc&filter=status eq "Active" |
Request Parameters
The request parameters used in this method are shown in the following table:
| Parameter | Description | Data Type | Required |
| appID | The ID of the application. | string | Mandatory |
page | The page number starting from zero. | string | Mandatory |
size | The number of records that are returned. Note: The total number of records can be used to calculate the number of pages. | string | Mandatory |
sort | The column used for sorting the records. | string | Optional |
filter | The filter that can filter the list of scans based on name, status, or integrity checks. The supported operators are 'eq' and 'co'. The format is as follows: name co "Dev Account" | string | Optional |
Request Example
An example GET request for retrieving the scan history is shown here.
curl --location -g --request GET '{{url}}/api/apps/{{appID}}/scans/env-status/history?page=0&size=100&sort=name,asc' \
--header 'Authorization: TOKEN {{token}}'Response Example
An example response of the GET request for retrieving the scan history is shown here.
| Status: 200 OK |
{
"count": 1,
"page": 0,
"size": 100,
"sort": "name: ASC",
"data": [
{
"taskId": "32vvg4b6r3s39u5c380t2nsf",
"scheduledTaskId": null,
"environmentId": null,
"timestamp": "2020-12-23T05:34:36Z",
"scannedBy": "user1",
"status": "Success",
"error": "Success",
"scanType": "Organization",
"scanDataSummary": {
"appName": "App1",
"envName": "Env1",
"catalogAppName": "App1",
"orgScanSummary": {},
"envLabel": "Env1",
"environmentsCollected": 100,
"environmentGroupsCollected": 1,
"environmentsAdded": [],
"environmentsDeleted": [],
"environmentsMoved": [],
"environmentsDisabled": [],
"environmentsEnabled": [],
"environmentGroupsAdded": [],
"environmentGroupsDeleted": [],
"scanType": "Organization",
"scanStatus": "Success",
"message": "Success",
"totalAccountsCollected": 0,
"newAccountsDetected": 0,
"accountsDeleted": 0,
"newPrivilegedAccountsDetected": 0,
"totalPermissionsCollected": 0,
"newPermissionsDetected": 0,
"permissionsDeleted": 0,
"newPrivilegedPermissionsDetected": 0,
"totalGroupsCollected": 0,
"newGroupsDetected": 0,
"groupsDeleted": 0,
"newPrivilegedGroupsDetected": 0,
"changesToAccounts": 0,
"changesToGroups": 0,
"changesToPermissions": 0,
"changesToPrivilegedPermissions": 0,
"changesToPrivilegedGroups": 0,
"permissionsAddedToAccounts": 0,
"permissionsRemovedFromAccounts": 0,
"permissionsAddedToGroups": 0,
"permissionsRemovedFromGroups": 0,
"groupsAddedToAccounts": 0,
"groupsRemovedFromAccounts": 0,
"groupsAddedToPermissions": 0,
"groupsRemovedFromPermissions": 0,
"groupsAddedToGroups": 0,
"groupsRemovedFromGroups": 0,
"accountsAddedToPermissions": 0,
"accountsRemovedFromPermissions": 0,
"accountsAddedToGroups": 0,
"accountsRemovedFromGroups": 0,
"permissionDefinitionsUpdated": 0,
"accountsMapped": 0,
"accountsUnresolved": 0,
"appId": "zj9lme7kdqs1riu5embs",
"envId": null
},
"orgScanDataSummary": {},
"tenantNamespace": null,
"metrics": null,
"name": "App1",
"startTime": "2020-12-23T05:34:41Z",
"endTime": "2020-12-23T05:34:57Z",
"totalTime": 16,
"success": true,
"message": "Success"
}
]
}When you submit the POST request to scan the environment, the status will be "In Progress" in the scan history. Once the scan gets completed, the status changes to Submitted.
(Deprecated) Scan History
Important Note:
The following API for Scan History is deprecated and will be removed in a future release.
The GET method provides the history of all scans in the past 30 days for an application.
| GET | {{url}}/api/apps/{{appID}}/scans/env-status/history |
Request Example
An example GET request for retrieving the scan history is shown here.
curl --location --request GET '{{url}}/api/apps/{{appID}}/scans/env-status/history' \ --header 'Authorization: TOKEN {{token}}'Response Example
An example response of the GET request for retrieving the scan history is shown here.
| Status: 200 OK |
[ { "taskId": "ipugpdzdusn4squtbh05lt3i", "scheduledTaskId": null, "environmentId": "378563640942", "timestamp": "2020-07-30T10:01:34Z", "scannedBy": "johnsmith", "status": "Success", "scanDataSummary": { "appName": "AWS-1009", "envName": "Sigma Corporate", "totalAccountsCollected": 9, "newAccountsDetected": 9, "accountsDeleted": 0, "newPrivilegedAccountsDetected": 7, "totalPermissionsCollected": 738, "newPermissionsDetected": 738, "permissionsDeleted": 0, "newPrivilegedPermissionsDetected": 235, "totalGroupsCollected": 7, "newGroupsDetected": 7, "groupsDeleted": 0, "newPrivilegedGroupsDetected": 4, "changesToAccounts": 8, "changesToGroups": 7, "changesToPermissions": 21, "changesToPrivilegedPermissions": 9, "changesToPrivilegedGroups": 2, "permissionsAddedToAccounts": 10, "permissionsRemovedFromAccounts": 0, "permissionsAddedToGroups": 16, "permissionsRemovedFromGroups": 0, "groupsAddedToAccounts": 4, "groupsRemovedFromAccounts": 0, "groupsAddedToPermissions": 7, "groupsRemovedFromPermissions": 0, "groupsAddedToGroups": 0, "groupsRemovedFromGroups": 0, "accountsAddedToPermissions": 8, "accountsRemovedFromPermissions": 0, "accountsAddedToGroups": 5, "accountsRemovedFromGroups": 0, "permissionDefinitionsUpdated": 0, "accountsMapped": 0, "accountsUnresolved": 9, "appId": "paiktfd4q9qtugzmqqln", "envId": "378563640942", "metrics": { "totalScanTime": 109.486, "totalConnectorTime": 104.932, ............................. ............................. ............................. } }, "tenantNamespace": null, "totalScanTimeWatch": null, "totalConnectorTimeWatch": null, "success": true, "message": "" }
]5. Last Scan Summary - Permissions
The GET method retrieves membership changes for permissions between the last two consecutive scans.
| GET | {{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions/memberships-last-scan-delta |
Request Example
An example request is shown here.
curl --location --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/permissions/memberships-last-scan-delta' \
--header 'Authorization: TOKEN {{token}}'Response Example
An example response is shown here.
| Status: 200 OK |
[
{
"name": "AmazonAppStreamReadOnlyAccess",
"nativeId": "arn:aws:iam::aws:policy/AmazonAppStreamReadOnlyAccess",
"description": null,
"permissionId": 4942,
"scanStatus": "New",
"hasMembershipsChanged": false,
"hasDefinitionsChanged": false,
"accounts": [],
"groups": [],
"permissions": [],
"scope": null,
"type": "policy"
},
{
"name": "AmazonMobileAnalyticsNon-financialReportAccess",
"nativeId": "arn:aws:iam::aws:policy/AmazonMobileAnalyticsNon-financialReportAccess",
"description": null,
"permissionId": 4943,
"scanStatus": "New",
"hasMembershipsChanged": false,
"hasDefinitionsChanged": false,
"accounts": [],
"groups": [],
"permissions": [],
"scope": null,
"type": "policy"
},
.........................
.........................
]6. Last Scan Summary - Groups
The GET method retrieves membership changes for groups between the last two consecutive scans.
| GET | {{url}}/api/apps/{{appID}}/environments/{{envID}}/groups/memberships-last-scan-delta |
Request Example
An example GET request is shown here.
curl --location --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/groups/memberships-last-scan-delta' \
--header 'Authorization: TOKEN {{token}}'Response Example
An example response of the GET request is shown here.
| Status: 200 OK |
[
{
"name": "IAMReadOnlyGroup",
"nativeId": "IAMReadOnlyGroup",
"description": null,
"permissionId": 4952,
"scanStatus": "New",
"hasMembershipsChanged": true,
"hasDefinitionsChanged": false,
"accounts": [],
"groups": [],
"permissions": [
{
"name": "IAMReadOnlyAccess",
"scanStatus": "Added",
"type": "policy",
"nativeId": "arn:aws:iam::aws:policy/IAMReadOnlyAccess",
"scope": null
}
],
"scope": null,
"type": "group"
},
{
"name": "Administrators",
"nativeId": "Administrators",
"description": null,
"permissionId": 5025,
"scanStatus": "New",
"hasMembershipsChanged": true,
"hasDefinitionsChanged": false,
"accounts": [
{
"nativeId": "agudanis",
"name": "agudanis",
"scanStatus": "Added",
"type": "user",
"scope": null
},
{
.......................
...........
{
]
"groups": [],
"permissions": [
{
"name": "AWSCodePipelineFullAccess",
"scanStatus": "Added",
"type": "policy",
"nativeId": "arn:aws:iam::aws:policy/AWSCodePipelineFullAccess",
"scope": null
},
{
.......................
...........
],
"scope": null,
"type": "group"
},
{
.......................
...........
{
]7. Last Scan Summary - Accounts
The GET method retrieves membership changes for accounts between the last two consecutive scans.
| GET | {{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/memberships-last-scan-delta |
Request Example
An example GET request is shown here.
curl --location --request GET '{{url}}/api/apps/{{appID}}/environments/{{envID}}/accounts/memberships-last-scan-delta' \
--header 'Authorization: TOKEN {{token}}'Response Example
An example response of the GET request is shown here.
| Status: 200 OK |
[
{
"name": "demoUser",
"firstName": null,
"lastName": null,
"type": "user",
"nativeId": "demoUser",
"accountId": 122,
"hasMembershipsChanged": true,
"scanStatus": "New",
"permissions": [
{
"name": "IAMUserChangePassword",
"nativeId": "arn:aws:iam::aws:policy/IAMUserChangePassword",
"scanStatus": "Added",
"type": "policy",
"scope": null
},
{
"name": "AleForBusinessFullAccess",
"nativeId": "arn:aws:iam::aws:policy/AleForBusinessFullAccess",
"scanStatus": "Added",
"type": "policy",
"scope": null
}
]
},
{
"name": "cpam-dev-ui",
"firstName": null,
"lastName": null,
"type": "user",
"nativeId": "cpam-dev-ui",
"accountId": 123,
"hasMembershipsChanged": false,
"scanStatus": "New",
"permissions": []
},
{
.....................
..............
]8. Run a scan for all environments
The POST method scans all environments for a given application.
| POST | {{url}}/api/apps/{{appID}}/full-scan |
Request Example
An example POST request for scanning all environments for an application is shown here.
curl --location --request POST '{{url}}/api/apps/{{appID}}/full-scan' /
--header 'Authorization: TOKEN {{token}}'Response Example
| Status: 200 OK |
{
"message": "A scan for all environments has been initiated."
}Was this article helpful?
