Manage Scans

You can use the Britive API methods for managing scans and retrieving scan history of accounts, permissions, or groups.

1. Run Organization Scan

Important Note:

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/orgScanOnly=true

Note:

orgScanOnly (Optional): If this parameter is true, only organization scan runs for Azure and GCP (Environment scan is not triggered.) The default value when this query parameter is not passed is false.

Request Example

An example of a POST request for running an organization scan for applications is shown here.

curl --location --request POST '{{url}}/api/apps/{{appID}}/scanorgScanOnly=true' \
--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

Important Note:

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."
}