Getting Started
This documentation is currently outdated and in the process of being updated. This documentation is provided as a temporary reference to various API endpoints and output. This warning will be at the top of each outdated page. As the documentation is updated, this warning will be removed.
You will need to obtain several items in order to start using the Ivanti Neurons for RBVM/ASOC API. This guide will help you complete the following tasks.
Using This Guide
This guide provides clients with useful information about each API call and endpoint. This section will help you better understand the documentation presented on this website.
Organization
This guide is sorted by API endpoint. In each endpoint, there are individual API calls grouped under each endpoint. Each API call has its own section that provides useful information about each call.
Required Permissions
The Ivanti Neurons for RBVM/ASOC platform supports a privilege-based permissions structure. When the requesting user doesn't have permission to access an endpoint, the API will return a 419 error code with a payload that looks like this:
{ "timestamp": "2021-03-30T16:47:30.648", "status": 419, "error": "InsufficientPrivileges", "clientsMissingPrivileges": [ 656 ], "missingPrivilege": "Assessment Control", "method": "PUT", "path": "/api/v1/client/656/assessment/12" }
In the above example, the requesting user was denied access because they lacked the Assessment Control privilege. To overcome this, the requesting user needs to be assigned a role that grants the Assessment Control privilege. One way to do this is login to the platform UI and go to the IAM Roles page. Type in "Assessment Control" in the search input and select different roles on the left side panel. As you click through the various roles, look for ones that display a green checkmark for the Assessment Control card. Once you've found a suitable role, assign it yourself or have another user with User Role Disposition Control do it for you.
If you don't want to assign one of the Ivanti Neurons for RBVM/ASOC provided roles to grant the Assessment Control privilege, you can create a custom role that only has the privileges needed. Note, if any role negates the Assessment Control privilege, you will need to un-assign that role regardless of any other roles that grant the privilege because negation always take precedence.
Another option is to manually perform the action in the UI first. If your user doesn't have the necessary privileges, mouse over the button and a tooltip will display which roles need to be assigned (and unassigned in some cases because of negation). So for the above example, go to the Assessments page, select an assessment, and the Edit Assessment option should be disabled. Hover over it and the tooltip will show the pertinent roles.
Code Samples
In order to help clients gain a better grasp on how to use Ivanti Neurons for RBVM/ASOC's APIs, we have provided code samples in cURL to get you started.
Parameters
Parameters are fields that require user input. If a specific API call requires information from another section (e.g., Client ID, Network ID, etc.), we provide links to that section for your convenience.
Endpoint URL Structure
All URLs start with the root platform.risksense.com/api/v1.
The platform instance where your client is located determines the endpoint URL structure. Use the following table to determine what URL to use.
| If you are on... | ...your URL will look like... |
|---|---|
| Platform 1 | platform.risksense.com/api/v1
|
| Platform 2 | platform2.risksense.com/api/v1
|
| Platform 3 | platform3.risksense.com/api/v1
|
| Platform 4 | platform4.risksense.com/api/v1
|
Generating an API Token
In order to use the Ivanti Neurons for RBVM/ASOC API, you will need an API authorization token. Authorization tokens are generated in the Ivanti Neurons for RBVM/ASOC platform. Permissions to access Ivanti Neurons for RBVM/ASOC platform data are based on the permissions of the Ivanti Neurons for RBVM/ASOC user that generates the token.
The following steps will show you how to generate and manage Ivanti Neurons for RBVM/ASOC API tokens.
Navigate to your Ivanti Neurons for RBVM/ASOC platform and log in. Once logged into the Ivanti Neurons for RBVM/ASOC platform, click your initials in the top-right corner of the screen and select User Settings.
Once on the User Settings page, scroll down to the API Tokens section. This is where you can generate new tokens to use the Ivanti Neurons for RBVM/ASOC.
If you have already created API tokens in the past, their names are displayed here. You can rename or delete existing API tokens here, as well.
To generate a new token, click the blue Generate button in the API Tokens section.
When you click the Generate button, the following dialog box appears.
Token names may not contain spaces but may contain all alphanumeric characters and the following special characters:
- ^
- \
- -
- ,
- +
- $
After entering your token name, click Generate. Ivanti Neurons for RBVM/ASOC displays the following dialog box showing the newly generated API token.
This token will only be displayed once. Select and copy the API token to a secure location, so you can retrieve it later. Clicking the Clipboard icon to the right of the API token also copies the token to the clipboard, as well.
After copying the new token, click OK to return to the User Settings page. This token can now be used to interact with the Ivanti Neurons for RBVM/ASOC REST API.