Provisioning and Reporting API Guide
CYRISMA’s Provisioning and Reporting API offers organizations using the CYRISMA risk management platform an enhanced way to automate the setup of new instances and collect scan data for reporting. This API enables organizations to manage partner relationships, monitor usage, and retrieve detailed scan results, all while supporting secure access through token-based authentication.
Written by Liam Downward
Updated at November 22nd, 2024
Table of Contents
Obtain Initial Credentials:
- Contact CYRISMA Support to obtain the API Key (also called “Username”) and API Secret (also called “Password”) to start communication with the API.
Change the API Secret:
- Update the API Secret to ensure only authorized applications can access the API.
Request a Session Token:
- Use the API credentials to request a session token.
- The CYRISMA platform is cloud-based, and the initial session token can be distributed among the cloud servers supporting risk management across organizations and instances.
Session Token Use:
- Once the session token is established, subsequent transactions must present the token as evidence of authorization.
- Tokens last for a few minutes and can be renewed as needed using the credentials.
Provision Partner Organization or Instance:
- Request to provision a partner organization or an instance under a partner.
- Processing is automated and typically takes less than 5 minutes.
Assign Users for Web Platform Access:
- Request to assign at least one user to the partner account.
- Users can sign on at the organization level to access and inspect all organizations under management.
- Users can set up a password via the self-service password reset feature.
Set Up Multiple Organizations and Users:
- Set up multiple organizations, each with its own set of users.
- Multi-Factor Authentication (via email code or authenticator apps) can be enabled during the initial organization provisioning request.
Partner Login and Instance Setup:
- Partners can log in to their organization and set up instances for their customer base.
Retrieve Usage and Utilization Details:
- Use the API to retrieve usage and utilization data at any time.
Retrieve Scan Result Data:
- Use the API to get scan result data (including Vulnerability, Baseline Configurations, or Data Scans).
Manage Partners:
- Manage partner accounts (convert, suspend, or reactivate) as needed.
API Endpoints Overview:
- A graphic is available that identifies the various API Endpoints described throughout this document.
CYRISMA API Credentials
Obtain API Credentials:
- Contact CYRISMA Support to obtain your API Key and TEMPORARY Secret.
Example API Key and Secret:
- API Key: 407cc078-46c7-11ed-8e42-000d3a3ba598
- API Secret: ZjNkMjg4MTdlOTA2Y2UyYzcyNDAzYzk5ZWNlMTFkOGQ
Important Security Note:
- Always connect to the API service using SSL. Any connection type other than SSL will be ignored or rejected.
Login and Obtain Access Token
Use API Credentials to Log In:
- With your API Key and Secret, access the API to receive the initial access token.
Data Submission:
- Since the interaction with the API is in plaintext, use x-www-form-urlencoded data type when submitting data elements.
API Response:
- The API will respond with plaintext formatted as JSON.
api.cyrisma.com/app/partner/login/
cURL Example: Obtaining an Access Token
Use the following cURL command to log in and obtain an access token from the CYRISMA API.
cURL Command:
curl --location 'https://api.cyrisma.com/app/partner/login/' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=efbe0212-7828-11ee-8431-000d3a9ba78c' \
--data-urlencode 'password=NjQ1N2RkOGY2YjgxMzE3NWQ1NTZhNzFkYjlmZTUwNzI'
Encoded Message Body:
-
Key:
username-
Value:
407cc078-46c7-11ed-8e42-000d3a3ba598
-
Value:
-
Key:
password-
Value:
ZjNkMjg4MTdlOTA2Y2UyYzcyNDAzYzk5ZWNlMTFkOGQ
-
Value:
-
Key:
grant_type-
Value:
password
-
Value:
API Response:
{
"access_token": "YdxKmK3ZHG8220231101000426",
"token_type": "access",
"expires_in": 600,
"refresh_token": "vdqddetOPeAg20231101000426",
"client_id": ""
}
Explanation:
- grant_type: This key indicates that the request is using a password grant type, as per OAuth 2.0 principles.
- access_token: The token returned by the API, which is required for future interactions with the API.
- expires_in: The access token typically expires in 600 seconds (10 minutes).
- refresh_token: The optional token used to refresh the access token's expiration time. If your API setup doesn't handle refresh tokens, you can request a new access token by re-issuing the login call with valid credentials.
Provisioning Endpoints
Once a session token is obtained, it is used as authorization to access all API capabilities. Below are the endpoints for accessing and managing the provisioning process.
Primary URL:https://api.cyrisma.com/app
Provisioning Endpoints and Their Functions:
| Function | Verb | Endpoint |
|---|---|---|
| Reset Password | POST | /partner/login/regen-pass |
| Get All Structure | GET | /partner/instances/info/ |
| Get Single Partner | GET | /partner/instances/info/[instanceID] |
| Provision New | POST | /partner/instances/create |
| Create User | POST | /partner/instances/users/create |
| Convert to Managed | PATCH | /partner/instances/convert |
| Suspend Partner | PATCH | /partner/instances/suspend |
| Reactivate Partner | PATCH | /partner/instances/info |
| Get All Users | GET | /partner/users/info |
| Get Specific User | GET | /partner/users/info/[UserRef] |
| Disable User | PATCH | /partner/users/disable |
| Set MFA Method | PATCH | /partner/instances/mfa |
Reset Password
First-time API use should always begin with a password reset to ensure that only authorized applications have access to the API.
Password Reset Endpoint:POST https://api.cyrisma.com/app/partner/login/regen-pass
Example Request:
Form-Data Message Body:
| Key | Value |
|---|---|
| username | 407cc078-46c7-11ed-8e42-000d3a3ba598 |
| password | ZjNkMjg4MTdlOTA2Y2UyYzcyNDAzYzk5ZWNlMTFkOGQ |
Example Response:
{
"success": "1",
"message": "",
"newPass": "YTBjNzc3N2QtZmE0Ni0xMWVkLTlhYWMtMDAwZDNhOWJhNzhj"
}
Important Notes:
- The
newPassvalue is your API secret password and is only returned once. - Cyrisma stores an encrypted hash of the password for future login validation. The password itself cannot be recovered once it is returned.
- Keep a record of the secret password (or string) in a secure location to prevent loss.
- The new password, along with your username, will be used to generate new session tokens as needed.
Retrieve Existing Provisioned Structure
This endpoint retrieves the entire provisioned structure of organizations and instances within the CYRISMA platform.
Endpoint:GET https://api.cyrisma.com/app/partner/instances/info/
Authorization:
Include the API Key access_token [Token Value] in the header.
cURL Example:
curl --location 'https://api.cyrisma.com/app/partner/instances/info/' \
--header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Note:
- No form data is required in this example other than the token itself.
Example Response:
[
{
"instance_id": "7BD9226DA1AE0FC1EDDFFEF756342E54",
"name": "East Side Stories",
"short_name": "East Side Stories",
"parent_id": "D9A7AB1C9A3EA47693C4CC9987D10FA8",
"heirarchy": "/MyCo/Security Metrics/East Side Stories",
"instance_type": "mssp",
"is_consulting": true,
"number_of_endpoints": 18,
"tenant_id": "",
"url": "cc2d78ea.cyrisma.com",
"mfa": "email"
},
{
"instance_id": "4D3596F48BE76EE68E309D6A1C38EBE4",
"name": "Cyber Security Solutions",
"short_name": "Cyber Security Solutions",
"parent_id": "F8E6AA6015A6EFC5EAF67DCF8287E94D",
"heirarchy": "/MyCo/Cyber Security Solutions",
"instance_type": "msp",
"is_consulting": false,
"number_of_endpoints": 0,
"tenant_id": "",
"url": "cc7e6744.cyrisma.com",
"mfa": "none"
}
]
Key Information:
- instance_type: Indicates whether the instance is an organization (typically "msp" or "mssp") or an end instance ("standard").
- is_consulting: Indicates whether the instance is a trial (used during consulting engagements) or a month-to-month instance.
Retrieve Single Partner
This endpoint retrieves the provisioned details for a single specified partner instance.
Endpoint:GET https://api.cyrisma.com/app/partner/instances/info/[instanceID]
Authorization:
Include the API Key access_token [Token Value] in the header.
cURL Example:
curl --location 'https://api.cyrisma.com/app/partner/instances/info/AD7F0D15EC7CA8662C07F6E3D2AB4171' \
--header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Form-data Message Body:
| Key | Value |
|---|---|
| instance_id | ID of the organization for this user |
Example Response:
[
{
"instance_id": "AD7F0D15EC7CA8662C07F6E3D2AB4171",
"name": "BCSS_Evans Consulting",
"short_name": "Evans Consulting",
"parent_id": "4D3596F48BE76EE68E309D6A1C38EBC2",
"heirarchy": "/MyCo/Cyber Security Solutions/Foundation Consulting",
"instance_type": "standard",
"is_consulting": false,
"number_of_endpoints": 96,
"tenant_id": "4586734786",
"url": "cc415f0e.cyrisma.com",
"mfa": "email"
}
]
New Provisioning
It is important to understand the hierarchy of organizations set up within the CYRISMA platform. New instances can be created under existing organizations or sub-organizations, or new sub-organizations can be created.
Endpoint:POST https://api.cyrisma.com/app/partner/instances/create
Authorization:
Include the API Key access_token [Token Value] in the header.
cURL Example – Creating a New Organization:
curl --location 'https://api.cyrisma.com/app/partner/instances/create' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token StjOiIfz9kXn20231101235306' \
--data-urlencode 'instance_type=msp' \
--data-urlencode 'is_consulting=false' \
--data-urlencode 'parent_instance_id=97E6AA6015A6EFC5EAF67DCF8287E95E' \
--data-urlencode 'name=API Auto Test' \
--data-urlencode 'short_name=API Auto' \
--data-urlencode 'country=US' \
--data-urlencode 'email=mike.l@myco.com'
Form-Data Message Body:
| Key | Value |
|---|---|
| name | String: Name of Organization or Instance |
| country | String: Two-letter country code |
| String: Associated email address | |
| parent_instance_id | ID of the Parent in the Hierarchy |
| is_consulting | Boolean: false for organizations, true for consulting instances |
| short_name | String: Name as it appears within the instance |
| instance_type | String: "MSP" or "MSSP" for organizations, "standard" for instances |
| mfa_type | Optional Int: 0 = None, 1 = Email, 2 = Authenticator TOTP |
| tenant_id | Optional String: Matching tenant ID of existing MDR/XDR |
| state | Optional String: State or province abbreviation |
| city | Optional String: Town or City |
| postal | Optional String: Postal code |
| street | Optional String: Street Address |
Example Response:
{
"instance_id": "BC0CB7373EE6249A2059DB24D2A9A7C0"
}
Important Notes:
- Instance creation generally takes less than 5 minutes to complete.
-
Check the completion of your order by using the
provision-statusAPI call along with the returned instance ID. - parent_instance_id: This is the immediate parent under which this new instance or sub-organization will appear in the hierarchy.
-
is_consulting: For new sub-organizations, the value must be
false. You cannot create a sub-organization that is marked as "Trial" or "Consulting."- If creating a new instance, set is_consulting to
trueto indicate that the instance is in temporary consulting mode, which will eventually be converted to "standard."
- If creating a new instance, set is_consulting to
- short_name: This is the name displayed at the top left of the browser window when logged into the instance. It is also the name of the browser tab, so it should be kept short for easy identification.
- country: This value determines the geographic location where the instance will reside, which is critical for compliance with data sovereignty restrictions.
- mfa_type: Defaults to 0 (none) but can be set to 1 (Email) or 2 (Authenticator) for added security when submitting the provisioning request.
- tenant_id: This is an optional string parameter that can be used to associate the provisioning with a pre-existing tenant in an MDR/XDR suite.
Create User under Partner
This endpoint allows you to create a new user under an organization in the CYRISMA platform.
Endpoint:POST https://api.cyrisma.com/app/partner/instances/users/create
Authorization:
Include the API Key X-API-Key: [Token Value] in the header.
cURL Example – Create New User under Organization:
curl --location 'https://api.cyrisma.com/app/partner/instances/users/create' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-API-Key: 0mzRSbzWJI7R20231031155938' \
--data-urlencode 'instance_id=36E6AA6015A6EFC5EAF67DCF8287E9D2' \
--data-urlencode 'username=donnyduck@emailemail.com' \
--data-urlencode 'first_name=Donny' \
--data-urlencode 'last_name=Duck'
Form-Data Message Body:
| Key | Value |
|---|---|
| instance_id | ID of the organization for this user |
| username | String: Email address used for login |
| first_name | String: User's first name |
| last_name | String: User's last name |
Example Response:
{
"id": "1302",
"username": "donnyduck@email.com",
"first_name": "Donny",
"last_name": "Duck",
"enabled": "true",
"instance_id": "36E6AA6015A6EFC5EAF67DCF8287E9D2"
}
Important Notes:
- Users must be added to organization instances: You can only add users to instance IDs associated with organizations. You cannot add users to "standard," "trial," or "consulting" instances.
Convert Consulting to Managed
This endpoint allows you to convert a consulting instance to a managed (standard) instance in the CYRISMA platform.
Endpoint:PATCH https://api.cyrisma.com/app/partner/instances/convert
Authorization:
Include the API Key in the header with Authorization: access_token [Token Value].
cURL Example:
curl --location --request PATCH \
'https://api.cyrisma.com/app/partner/instances/convert' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token tl2KlbXCUiHv20231102012040' \
--data-urlencode 'instance_id=322048E99EB5A84AD6492081D32B2A45'
Form-Data Message Body:
| Key | Value |
|---|---|
| instance_id | ID of the organization under conversion |
Example Response:
{
"instance_id": "322048E99EB5A84AD6492081D32B2A45",
"name": "Stella Blow Dryers",
"consulting_status": "Converted from Consulting to Standard"
}
Important Notes:
-
One-Way Operation:
Conversion from consulting to managed is a one-way operation. Once an instance is converted to a managed instance, it cannot be reverted back to a consulting instance.
Suspend a Partner or Instance
This endpoint allows you to suspend a partner or instance, blocking access to it while keeping it operational in the backend.
Endpoint:PATCH https://api.cyrisma.com/app/partner/instances/suspend
Authorization:
Include the API Key in the header with Authorization: access_token [Token Value].
cURL Example:
curl --location --request PATCH \
'https://api.cyrisma.com/app/partner/instances/suspend' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token tl2KlbXCUiHv20231102012040' \
--data-urlencode 'instance_id=3677DBCDDB8E6A7A9DD6F58CA4DCFA6E'
Form-Data Message Body:
| Key | Value |
|---|---|
| instance_id | ID of the organization to suspend |
Example Response:
{
"instanceID": "3677DBCDDB8E6A7A9DD6F58CA4DCFA6E",
"name": "Strategic Sunset Company",
"enabled": "0"
}
Important Notes:
Visibility:
Suspended instances are not visible in the MSP web interface.
API Requests:
Suspended instances are also not shown in the "Get All" request via the API.
Restoration:
To restore a suspended instance or organization, the instanceID is required. It's important to document the instanceID for future restoration.
Functionality:
While access is blocked, suspended instances still work in the backend. Only access to the suspended instance is restricted.
Impact on Sub-Organizations:
If an organization is suspended, access to all instances and sub-organizations within that organization is also blocked.
Reactivate a Partner or Instance
This endpoint allows you to reactivate a previously suspended partner or instance, restoring access.
Endpoint:PATCH https://api.cyrisma.com/app/partner/instances/reactivate
Authorization:
Include the API Key in the header with Authorization: access_token [Token Value].
cURL Example:
curl --location --request PATCH \
'https://api.cyrisma.com/app/partner/instances/reactivate' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token tl2KlbXCUiHv20231102012040' \
--data-urlencode 'instance_id=3677DBCDDB8E6A7A9DD6F58CA4DCFA6E'
Form-Data Message Body:
| Key | Value |
|---|---|
| instance_id | ID of the organization to be reactivated |
Example Response:
{
"instanceID": "3677DBCDDB8E6A7A9DD6F58CA4DCFA6E",
"name": "Strategic Sunset Company",
"enabled": "1"
}
Notes:
Reactivation:
Reactivating an instance restores its access. The enabled field will change to 1 to indicate that the instance is active again.
Visibility:
Once reactivated, the instance will become visible and accessible both in the MSP web interface and through the API.
Get All Users
This endpoint retrieves information about all users within a specific organization or instance.
Endpoint:GET https://api.cyrisma.com/app/partner/users/info
Authorization:
Include the API Key in the header with Authorization: access_token [Token Value].
cURL Example:
curl --location 'https://api.cyrisma.com/app/partner/users/info/' --header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Example Response:
[
{
"User_reference": "25d9de68a3edbdbdb54ae7a6a0a9ba2d",
"First_Name": "Frank",
"Last_Name": "Stein",
"Login_ID": "fstein@cyrisma.com",
"instanceid": "D361408273C2D3522713ECD20C9C55F0",
"Organization": "CYRISMA"
},
{
"User_reference": "735455d9b065da527f17ae6701b579b6",
"First_Name": "Sandhya",
"Last_Name": "Shadangi",
"Login_ID": "sandhya.s@cyrisma.com",
"instanceid": "D361408273C2D3522713ECD20C9C55F0",
"Organization": "CYRISMA"
}
]
Notes:
- The response will contain a list of users with their respective details, including:
- User_reference: Unique identifier for the user.
- First_Name and Last_Name: User's full name.
- Login_ID: User's login email address.
- instanceid: The instance or organization to which the user belongs.
- Organization: The organization to which the user is assigned.
Get Specific User
This endpoint retrieves details for a specific user by their User_reference.
Endpoint:GET https://api.cyrisma.com/app/partner/users/info/[UserRef]
Authorization:
Include the API Key in the header with Authorization: access_token [Token Value].
cURL Example:
curl --location 'https://api.cyrisma.com/app/partner/users/info/25d9de68a3edbdbdb54ae7a6a0a9ba2d' --header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Example Response:
{
"User_reference": "25d9de68a3edbdbdb54ae7a6a0a9ba2d",
"First_Name": "Frank",
"Last_Name": "Stein",
"Login_ID": "fstein@cyrisma.com",
"instanceid": "D361408273C2D3522713ECD20C9C55F0",
"Organization": "CYRISMA"
}
Notes:
- Replace
[UserRef]with the actual User_reference (e.g.,25d9de68a3edbdbdb54ae7a6a0a9ba2d). - The response will contain the user's detailed information:
- User_reference: Unique identifier for the user.
- First_Name and Last_Name: The user's full name.
- Login_ID: The user's email address.
- instanceid: The instance or organization to which the user belongs.
- Organization: The organization the user is associated with.
Disable User
This endpoint disables a user account by marking it as "disabled."
Endpoint:PATCH https://api.cyrisma.com/app/partner/users/disable
Authorization:
Include the API Key in the header with Authorization: access_token [Token Value].
cURL Example:
curl --location 'https://api.cyrisma.com/app/partner/users/disable' --header 'Content-Type: application/x-www-form-urlencoded' --header 'Authorization: access_token 807liEf4p8Sf20231031232416' --data-urlencode 'user_id=25d9de68a3edbdbdb54ae7a6a0a9ba2d'
Request Body:
- user_id: The unique ID reference of the user to be disabled.
Example Response:
{
"Email": "fstein@cyrisma.com",
"Status": "Disabled"
}
Notes:
- Replace
[user_id]with the actual user_id of the user you want to disable. - The response will indicate the user's Email and their Status (e.g.,
"Status": "Disabled"), confirming that the user has been successfully disabled.
Modify MFA Method
This endpoint allows you to modify the Multi-Factor Authentication (MFA) method for a given organization instance.
Endpoint:PATCH https://api.cyrisma.com/app/partner/instances/mfa
Authorization:
Include the API Key in the header with Authorization: access_token [Token Value].
cURL Example:
curl --location 'https://api.cyrisma.com/app/partner/instances/mfa' --header 'Content-Type: application/x-www-form-urlencoded' --header 'Authorization: access_token 807liEf4p8Sf20231031232416' --data-urlencode 'mfa_type=2' --data-urlencode 'instance_id=36E6AA6015A6EFC5EAF67DCF8287E9D2'
Request Body:
-
mfa_type: The MFA method to set for the instance:
-
0= None -
1= Email -
2= Authenticator (TOTP)
-
- instance_id: The ID of the organization instance to modify.
Example Response:
{
"ID": "986",
"Name": "Save Me",
"Country": "US",
"State": "New York",
"City": "",
"Address": "",
"Zip": "",
"Notification_Email": "",
"MFA_Status": "Code"
}
Notes:
-
MFA modification is only allowed for organization instances (
instance_idthat are not "standard", "trial", or "consulting"). - The
mfa_typeparameter allows you to set different MFA methods:- 0: No MFA
- 1: Email-based MFA
- 2: Authenticator (TOTP) MFA
Make sure to replace the instance_id with the correct ID of the organization instance for which you wish to modify MFA settings.
INSTANCE REPORTING OPERATIONS
This section covers API usage for retrieving scan data for the purpose of reporting. Since thousands of CYRISMA cloud instances are hosted in an elastic infrastructure of cloud based servers, the individual instances must also be authenticated and authorized to grant access to the scan data through the API.
Before scan results can be fetched from any CYRISMA cloud instance, authorization must be established first. Authorization is granted via session token delivery using an encrypted channel. Each CYRISMA cloud instance is represented by its own unique URL. Session tokens can be applied per specific instance URL or session tokens can be delivered to all available URLs at once.
Instance Authentication
This endpoint is used to authenticate a CYRISMA instance, enabling access to subsequent reporting endpoints. Authentication is required whenever a new session token is generated or when the current token expires.
Endpoint:POST https://api.cyrisma.com/app/partner/instances/login/[optional instance_id]
Authorization:
Include the API Key in the header with Authorization: access_token [Token Value].
cURL Example:
curl --location 'https://api.cyrisma.com/app/partner/instances/login/' --header 'Content-Type: application/x-www-form-urlencoded' --header 'Authorization: access_token 807liEf4p8Sf20231031232416'
You can also specify an optional instance_id to authenticate a specific instance, or leave it out to authenticate all available instances.
Example Response:
{
"failed_token_inserts": [],
"success_token_inserts": [
{
"instance_id": "9A1B19GHG389XA4V1493GRW1C8A95E",
"instance_url": "bag94c12.cyrisma.com"
}
]
}
Notes:
- Authentication Requirement: This step is essential before using any reporting or instance-related endpoints.
- Token Expiration: When the session token expires, all instances must be re-authenticated using the latest session token.
-
Optional
instance_id: If you provide aninstance_id, only that specific instance will be authenticated. If noinstance_idis provided, all available instances will be authenticated at once. - After successful authentication, you can interact with various endpoints related to the authenticated instance using the full instance URL (e.g.,
https://bag94c12.cyrisma.com/...).
Make sure to use the latest session token for all subsequent requests following the initial authentication.
Available Reporting Endpoints and Their Functions:
| Function | Verb | Endpoint |
|---|---|---|
| Data Scan Summary | GET | /partner/scans/data |
| Baseline Scan Summary | GET | /partner/scans/baseline |
| Vulnerability Scan Summary | GET | /partner/scans/vulnerability |
| Overall Dashboard Results | GET | /partner/dashboards/overall |
| Data Dashboard | GET | /partner/dashboards/data |
| Baseline Dashboard | GET | /partner/dashboards/baseline |
| Vulnerability Dashboard | GET | /partner/dashboards/vulnerability |
| Vulnerability CVE Detail | GET | /partner/dashboards/vulnerability/cve |
Get Data Scan Summary
Endpoint:
GET https://ccnnnnnn.cyrisma.com/app/partner/scans/data
cURL Example:
curl --location 'https://ccnnnnnn.cyrisma.com/app/partner/scans/data' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Response:
{
"header": {
"data_scan_items": 856350,
"data_scan_folders": 81525,
"data_scan_sensitive_items": 19112,
"average_data_scan_grade": 4.37,
"average_data_scan_grade_alpha": "D",
"times_data_category_scanned": {}
},
"data_scans": [
{
"scan_id": "13798",
"scan_name": "Internal File Scan",
"scan_type": "file",
"scanned_items": 102414,
"scanned_folders": 57503,
"total_sensitive_items": 2933,
"percent_sensitive_items": 2.6,
"scan_started": "1/5/2024 1:08:51 AM",
"scan_finished": "1/8/2024 7:31:56 AM",
"grade": 4.67,
"grade_alpha": "D-",
"issuing_user": "user1",
"categories": "Social Security Numbers, Credit Cards, Passport Numbers, Bank Accounts, Passwords, Drivers License"
}
]
}
Key Information:
- Data Scan Summary includes details like the number of items, folders, and sensitive items scanned, along with average grades.
- Individual scan details provide insights into each specific scan (e.g., scan name, items scanned, percentage of sensitive data, etc.).
Make sure to substitute "nnnnnn" with your actual instance URL when making the request.
Get Secure Baseline Scan Information
Endpoint:
GET https://ccnnnnnn.cyrisma.com/app/partner/scans/baseline
cURL Example:
curl --location 'https://ccnnnnnn.cyrisma.com/app/partner/scans/baseline' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Response:
{
"header": {
"average_secure_baseline_grade": 5.0,
"average_secure_baseline_grade_alpha": "F"
},
"secure_baseline_scans": [
{
"scan_id": "46217",
"scan_name": "Secure Baseline Scan",
"scan_type": "secure_baseline",
"failed_tests": 243,
"score": 25.00,
"scan_started": "11/6/2023 10:00:04 AM",
"scan_finished": "11/6/2023 10:27:59 AM",
"grade": 5.0,
"grade_alpha": "F",
"issuing_user": "user1",
"target_details": "target1 | 243/333 Tests Failed | 25.00% Pass Rate. ||"
}
]
}
Key Information:
- Secure Baseline Scan Summary includes details like the average scan grade, number of failed tests, score, and pass rate.
- Individual scan details provide insights into each baseline scan, including the scan start and finish times, grade, user issuing the scan, and target test results.
Make sure to substitute "nnnnnn" with your actual instance URL when making the request.
Get Vulnerability Scan Information
Endpoint:
GET https://ccnnnnnn.cyrisma.com/app/partner/scans/vulnerability
cURL Example:
curl --location 'https://ccnnnnnn.cyrisma.com/app/partner/scans/vulnerability' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Response:
{
"header": {
"total_vulnerabilities": 2842,
"total_critical_vulnerabilities": 141,
"total_high_vulnerabilities": 2096,
"total_medium_vulnerabilities": 561,
"total_low_vulnerabilities": 44,
"average_vulnerability_grade": 4.5,
"average_vulnerability_grade_alpha": "D-"
},
"vulnerability_scans": [
{
"scan_id": "89292",
"scan_name": "Internal Authenticated Vulnerability Scan",
"scan_type": "vulnerability",
"vulnerabilities": 2842,
"critical_vulnerabilities": 141,
"high_vulnerabilities": 2096,
"medium_vulnerabilities": 561,
"low_vulnerabilities": 44,
"scan_started": "10/31/2023 12:01:12 AM",
"scan_finished": "11/2/2023 12:10:00 AM",
"grade": 7.0,
"grade_alpha": "D-",
"issuing_user": "user1"
}
]
}
Key Information:
- Vulnerability Scan Summary provides an overview of total vulnerabilities, broken down into critical, high, medium, and low categories, along with the overall vulnerability grade.
- Individual scan details include the number of vulnerabilities, the start and finish times, the grade, and the user issuing the scan.
Make sure to replace "nnnnnn" with your actual instance URL when making the request.
Get Overall Risk Dashboard
Endpoint:
GET https://ccnnnnnn.cyrisma.com/app/partner/dashboards/overall
cURL Example:
curl --location 'https://ccnnnnnn.cyrisma.com/app/partner/dashboards/overall' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Response:
{
"previous_or_grade": "D-",
"current_or_grade": "D",
"previous_ds_grade": "D",
"current_ds_grade": "D",
"previous_vn_grade": "D",
"current_vn_grade": "D",
"previous_sb_grade": "F",
"current_sb_grade": "F",
"previous_cmpl_grade": "F",
"current_cmpl_grade": "C-"
}
Key Information:
-
Overall Risk Dashboard provides the current and previous grades for various scan types, indicating the overall risk of an organization.
- Or - Overall Risk
- Ds - Data Scans
- Vn - Vulnerability Scans
- Sb - Secure Baseline Scans
- Cmpl - Compliance Grade
- The grades represent the current and previous assessments over either a monthly or quarterly period, depending on the system's configuration.
Example Grades:
- Current and Previous Grades for Overall Risk (Or), Data Scans (Ds), Vulnerability Scans (Vn), Secure Baseline Scans (Sb), and Compliance Grade (Cmpl).
Make sure to replace "nnnnnn" with your actual instance URL when making the request.
Get Data Dashboard
Endpoint:
GET https://ccnnnnnn.cyrisma.com/app/partner/dashboards/data
cURL Example:
curl --location 'https://ccnnnnnn.cyrisma.com/app/partner/dashboards/data' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Response:
{
"current_grade": "D",
"previous_grade": "D-",
"top_5_categories": [
{
"name": "Bank Accounts",
"times_searched": 34
},
{
"name": "Social Security Numbers",
"times_searched": 34
},
{
"name": "Passwords",
"times_searched": 25
},
{
"name": "Credit Cards",
"times_searched": 20
},
{
"name": "Drivers License",
"times_searched": 8
}
],
"top_10_most_sensitive": [
{
"name": "Cloud_Agent",
"ip_address": "x.x.x.x",
"last_scanned": "2023-09-27",
"total_scans": 10,
"total_sensitive_items": 15453,
"percent_sensitive": 3.9,
"risk_grade": "D"
},
{
"name": "ABC",
"ip_address": "x.x.x.x",
"last_scanned": "2023-09-27",
"total_scans": 4,
"total_sensitive_items": 10960,
"percent_sensitive": 4.6,
"risk_grade": "C"
},
{
"name": "LT-BShackelford_d_20230112",
"ip_address": "192.168.86.70",
"last_scanned": "2022-04-15",
"total_scans": 3,
"total_sensitive_items": 1615,
"percent_sensitive": 38.6,
"risk_grade": "F"
},
{
"name": "PBS-2550",
"ip_address": "172.28.80.1",
"last_scanned": "2024-01-19",
"total_scans": 1,
"total_sensitive_items": 420,
"percent_sensitive": 6.8,
"risk_grade": "D-"
}
]
}
Key Information:
Current Grade and Previous Grade represent the data security score, showing the overall data security grade for the instance.
Top 5 Categories: Lists the most frequently searched categories related to sensitive data.
- For example, categories like Bank Accounts and Social Security Numbers.
Top 10 Most Sensitive Items: Displays the most sensitive items found in scans, including:
- Name of the item
- IP Address associated with the item
- Last Scanned date
- Total Scans conducted
- Total Sensitive Items found
- Percent Sensitive: The percentage of sensitive data found
- Risk Grade: The overall risk grade for the item
Make sure to replace "nnnnnn" with your actual instance URL when making the request.
Get Secure Baseline Dashboard
Endpoint:
GET https://ccnnnnnn.cyrisma.com/app/partner/dashboards/baseline
cURL Example:
curl --location 'https://ccnnnnnn.cyrisma.com/app/partner/dashboards/baseline' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Response:
{
"current_grade": "F",
"previous_grade": "F",
"top_5_baselines": [],
"lowest_pass_targets_domain": [
{
"name": "PBS2144",
"ip": "192.168.108.11",
"scan_date": "1/1/2024 12:00:00 AM",
"pass_rate": 0.0,
"grade": "N/A",
"profile_name": "[CIS Security] MS Windows 10",
"profile_type": "Level1"
},
{
"name": "pbs-cyr-w10PC",
"ip": "10.10.2.110",
"scan_date": "1/1/2024 12:00:00 AM",
"pass_rate": 0.0,
"grade": "N/A",
"profile_name": "[CIS Security] MS Windows 10",
"profile_type": "Level1"
},
{
"name": "PBS-2560",
"ip": "172.22.96.1",
"scan_date": "1/1/2024 12:00:00 AM",
"pass_rate": 0.0,
"grade": "N/A",
"profile_name": "[CIS Security] MS Windows 11",
"profile_type": "Level1"
},
{
"name": "pbs-ts",
"ip": "192.168.100.101",
"scan_date": "5/10/2023 12:00:00 AM",
"pass_rate": 0.0,
"grade": "F",
"profile_name": "[CIS Security] MS Windows Server 2012 R2",
"profile_type": "Level 1 Member Server"
}
],
"lowest_pass_targets_nondomain": []
}
Key Information:
Current Grade and Previous Grade: The baseline security grade showing the overall state of secure baseline configurations. In this example, the grade is F for both current and previous.
Top 5 Baselines: This array is empty in the response, meaning there are no baseline configurations with notable performance.
Lowest Pass Targets Domain: This section lists the domain targets with the lowest pass rates. Each entry includes:
- Name: The name of the target (e.g., "PBS2144")
- IP: The IP address of the target
- Scan Date: When the scan was performed
- Pass Rate: The percentage of successful baseline compliance checks
- Grade: The grade assigned to the baseline target (e.g., "N/A" or "F")
- Profile Name: The security profile applied (e.g., "[CIS Security] MS Windows 10")
- Profile Type: The level or type of the profile (e.g., "Level1")
Lowest Pass Targets Non-Domain: This array is empty in the response, indicating there are no non-domain targets with low pass rates.
Make sure to replace "nnnnnn" with your actual instance URL when making the request.
Get Vulnerability Dashboard
Endpoint:
GET https://ccnnnnnn.cyrisma.com/app/partner/dashboards/vulnerability
cURL Example:
curl --location 'https://ccnnnnnn.cyrisma.com/app/partner/dashboards/vulnerability' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Response:
{
"current_grade": "D",
"previous_grade": "D",
"top_5_profiles": [
{
"name": "MS Windows 10",
"times_used": 1579,
"machines": 65
},
{
"name": "MS Windows Server 2016",
"times_used": 204,
"machines": 28
},
{
"name": "MS Windows Server 2019",
"times_used": 331,
"machines": 16
},
{
"name": "MS Windows 11",
"times_used": 266,
"machines": 15
},
{
"name": "MS Windows Server 2012 R2",
"times_used": 142,
"machines": 8
}
],
"top_10_most_sensitive": [
{
"name": "365sc (SRV)",
"ip_address": "192.168.100.27",
"os": "MS Windows Server 2019",
"last_scanned": "1/18/2024 12:00:00 AM",
"vuln_count_critical": 30,
"vuln_count_high": 388,
"vuln_count_medium": 140,
"vuln_count_low": 1
},
{
"name": "embs-d (SRV)",
"ip_address": "192.168.100.37",
"os": "MS Windows Server 2022",
"last_scanned": "1/16/2024 12:00:00 AM",
"vuln_count_critical": 17,
"vuln_count_high": 92,
"vuln_count_medium": 104,
"vuln_count_low": 12
}
]
}
Key Information:
Current Grade and Previous Grade: These represent the security grade for vulnerabilities. In this example, the grade is D for both the current and previous periods.
Top 5 Profiles: Lists the most commonly used security profiles. Each entry includes:
- Name: The name of the profile (e.g., "MS Windows 10")
- Times Used: The number of times the profile was used
- Machines: The number of machines using the profile
Top 10 Most Sensitive: Lists the most sensitive machines based on their vulnerability counts. Each entry includes:
- Name: The name of the machine (e.g., "365sc (SRV)")
- IP Address: The machine's IP address
- OS: The operating system of the machine (e.g., "MS Windows Server 2019")
- Last Scanned: The last date the machine was scanned
- Vulnerability Counts: The count of vulnerabilities broken down by severity (critical, high, medium, and low)
Make sure to replace "nnnnnn" with your actual instance URL when making the request.
Get CVE Details
Endpoint:
GET https://ccnnnnnn.cyrisma.com/app/partner/dashboards/vulnerability/cve
cURL Example:
curl --location 'https://ccnnnnnn.cyrisma.com/app/partner/dashboards/vulnerability/cve' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: access_token 807liEf4p8Sf20231031232416'
Response:
{
"cve_items": [
{
"id": "CVE-2023-24895",
"title": ".NET Framework Remote code execution Vulnerability. This type of exploit is sometimes referred to as Arbitrary Code Execution (ACE). The attack itself is carried out locally. In order to exploit this vulnerability, an attacker convinces a victim to download and open a specially crafted file from a website which leads to a local attack on their computer.",
"cve_score": 7.8,
"cve_risk": "High",
"published_date": "2023-06-14",
"affected_targets": "Target01 (WS)",
"num_affected_targets": 1
}
]
}
Key Information:
- CVE ID: A unique identifier for the vulnerability (e.g., "CVE-2023-24895").
- Title: A detailed description of the vulnerability, including how it works and potential exploitation methods.
- CVE Score: The CVSS score assigned to the vulnerability, indicating its severity (e.g., 7.8 which is considered high).
- CVE Risk: The risk level associated with the CVE (e.g., High).
- Published Date: The date when the CVE was published (e.g., 2023-06-14).
- Affected Targets: The targets that are impacted by the vulnerability (e.g., "Target01 (WS)").
- Number of Affected Targets: The total number of affected targets (e.g., 1).
Notes:
- Optionally, you can pass a specific
cve_idinto the request body (e.g.,{'cve_id': 'cve-2023-24895'}) to retrieve details for an individual CVE.
Make sure to replace "nnnnnn" with your actual instance URL when making the request.
API Documentation
For comprehensive endpoint details, usage examples, and additional setup instructions, please refer to the full CYRISMA API Guide: