Skip to main content

API V2 User Guide

Emily Makroy
  • Updated

The goal of this article is to describe the features and functionality of the ProcessUnity GRX API V2, as well as provide a guide for customers wishing to leverage the API for integration or reporting purposes.

As additional functionality is released, information in this article will be updated along with updates to the OpenAPI Spec. Please see the API V2 Change Log article for information regarding delivered and planned releases. 

For members using our API V1 functionality, we encourage you to begin the migration to API V2 as soon as possible. The API V1 End-of-Life is planned for August 31, 2024.

 

Table of Contents

API Getting Started

API Access & Information

API Features & Functionality

 

API Getting Started

The ProcessUnity GRX V2 APIs allow customers to create and automate workflows to support your Third Party Risk Management program.

Here are the high-level quick start steps for using the GRX API:

  1. Explore the technical documentation for information about what endpoints and fields are available on our OpenAPI Spec
  2. Contact your GRX representative to provision credentials for you in the Demo or Production environments
  3. Verify your credentials with the built in OpenAPI auth GET TOKEN
  4. Experience the data available with OpenAPI’s “TRY” functionality
  5. Review your current TPRM process and decide what level of integration and automation is best for your business
  6. Need more info? Keep reading below to get answers to all your API related questions

 

API Access & Information

OpenAPI Spec

ProcessUnity GRX uses OpenAPI Specification (fka Swagger RESTful API Documentation Specification) to document our REST APIs.

 

View the OpenAPI Spec for the production GRX API.

View the OpenAPI Spec for the demo / test GRX API.

 

API Authentication

At ProcessUnity GRX, we are all about keeping your data secure. You must have a GRX account and credentials with the appropriate permissions to access the GRX APIs.

 

API Credentials

Contact your ProcessUnity GRX representative to generate API V2 credentials in either Demo or Production. A client id and client secret associated with your company account will be created and shared with you via an encrypted email.

If you are interested in "end to end" integration functionality and do not currently have access to an account in the Demo environment, one will be created for you at this time. While you can experience production-like functionality in demo, we do not have real company and assessment information in demo. It has been seeded with “fake” company records and completed assessments to enable end to end testing.

If you are primarily interested in "reporting" functionality, Demo environment access is not needed as it will be better for you to leverage the real data in Production. 

 

NOTE: Currently, there is not a way to self-serve the creation of API V2 credentials from the GRX Portal. That functionality is planned to be delivered at a future time.

Your API credentials carry many privileges, so be sure to keep them secure. Do not share your secret API credentials in publicly accessible areas such as GitHub, client-side code, and so on.

 

API Tokens

To make a call to the GRX REST API, you need an API token. We setup the OAuth 2.0 API authentication mechanism to provision API tokens for you. Once you have received your API credentials, verify them with the built in OpenAPI auth GET TOKEN

API V2 Auth.png

 

Tokens are valid for 10 hours and should be reused by the same application during that time window. Token end times are encoded into the token and can be checked prior to using the token so a new one can be generated. Decoding the token can be done with a standard library to view the “issued at” (iat) and the “expiration” (exp) timestamps.

Otherwise, once a token expires the call to the endpoint will fail authentication. If you generate a new token before the expiration has passed, the previous token will still work through its expiration timestamp.

 

API Scopes

All scopes assigned to the account will be enabled when provisioning a token. When you decide what level of integration you want, we can update your account to have only the necessary scopes to limit data access. Data that is not within one of the selected scopes will not be accessible to the API token.

We use Auth0 for our authentication provider. Here is their high-level documentation. More specifically, this link has an example about how to pass in the client id and secret to retrieve the token and an example is provided below.

 

curl -s --request POST \
--url https://cybergrx-production.us.auth0.com/oauth/token \
--header 'content-type: application/json' \
--data '{"client_id":"$client_id","client_secret":"$client_secret","audience":https://api.cybergrx.com,"grant_type":"client_credentials"}'

In order to see which scopes are required to call an endpoint, refer to the below table:

 

API Endpoint Required Scope
   
Company Endpoints  
   
GET /v2/company/companies read:company
GET /v2/company/companies/{company_id} read:company
   
Portfolio Endpoints  
   
GET /v2/portfolio/third-parties read:portfolio
POST /v2/portfolio/third-parties write:portfolio
GET /v2/portfolio/third-parties/{company_id} read:portfolio
PUT /v2/portfolio/third-parties/{company_id} write:portfolio
DELETE /v2/portfolio/third-parties/{company_id} write:portfolio
PATCH /v2/portfolio/third-parties/{company_id} write:portfolio/tags
POST /v2/portfolio/third-parties/{company_id}/requests write:portfolio
GET /v2/portfolio/tags read:portfolio/tags
   
Collection Endpoints  
   
GET /v2/portfolio/third-parties/{company_id}/impact-questionnaire read:questionnaire/impact
PUT /v2/portfolio/third-parties/{company_id}/impact-questionnaire write:questionnaire/impact
GET /v2/collection/impact-questionnaire read:questionnaire/impact
   
Reporting Endpoints  
   
GET /v2/portfolio/third-parties/{company_id}/risk-profile read:portfolio
GET /v2/portfolio/third-parties/{company_id}/risk-navigator/{framework_id}/summary read:portfolio-findings
GET /v2/portfolio/third-parties/{company_id}/risk-navigator/{framework_id} read:portfolio-findings
GET /v2/reporting/frameworks read:frameworks
GET /v2/reporting/frameworks/{framework_id} read:frameworks
GET /v2/reporting/framework-controls/{framework_id} read:frameworks
GET /v2/reporting/priority-third-parties/{framework_id} read:portfolio-findings
POST /v2/reporting/exports write:exports
GET /v2/reporting/exports/{export_id} read:exports
GET /v2/reporting/exports/{export_id}/download read:exports

 

Release Versions

Beta Release

Endpoints tagged as Beta are available for customer use and testing. Please feel free to try them out and provide feedback for future enhancements! These endpoints have been vetted and should be final. Depending on the specific endpoint(s) complexity, they may stay in Beta mode for varying lengths of time to ensure they are stable before moving them to the Generally Available areas.

Once an endpoint is released to Beta, changes to the schema that would be “breaking” – field renames, field type changes, schema reorganizations, etc – are highly unlikely. However, we still reserve the right to do those, if necessary, with notice via our release notes process.

 

Alpha Release

Endpoints tagged as Alpha are not available for customer access at this time. You can review the schema and the planned functionality to get a sneak peek at future functionality, but these endpoints are still undergoing review and it is likely that we may introduce breaking changes to these endpoints as they undergo our review process. Please feel free to submit suggestions or feedback on these endpoints as they are undergoing active development!

We do not recommend doing any development against these endpoints while they are in Alpha.

 

Base URL

The GRX REST API base URL is as follows:

The GRX authentication base URL is different since we leverage AuthO 2.0 to manage authentication, token create and scope permissions.

All requests to the GRX API must use TLS protocol version 1.2 in order for the request to be successfully sent.

 

Time Zone

All dates and time zones available via the API are presented in Coordinated Universal Time (UTC). You may notice a difference in the day or timestamp in the GRX UI because that display is localized based on your set time zone. 

If you want to convert the UTC dates to local time prior to presenting to your users, there are standard libraries available.

 

Pagination

We have one style of pagination you will see in the endpoint to get the list of companies in your third party portfolio.

In the response, you will see “total” which represents the total number of results available, even if they are not all returned in the response.

You can control how many records are returned in the response by setting the “limit” parameter. There is a max set by ProcessUnity GRX.

If you turn the “limit” up and the “total” is still showing a number higher than the limit, you can iterate through the result set by calling the endpoint again and incrementing the “offset”.

 

Filtering

Several of the endpoints for the GRX API allow for filtering. Filtering is optional.

For multiple values of the same filter type, append the filter name and selected values with “&” separating them. Do not use comma delimited lists or new line for multiple values

Example: Tags=123&Tags=345&Tags=XXX

 

Rate Limits

The ProcessUnity GRX API is rate limited. Users can make up to 5 requests a second. Information about rate limits will be returned in the response headers.

 

 

API Features & Functionality

API Overview

The ProcessUnity GRX V2 APIs allows members to automate reporting and workflows to support your Third Party Risk Management program.

 

Interact with the Exchange

 

Search for companies in the ProcessUnity Global Risk Exchange (GRX)

GET /v2/company/companies

 

Search for companies in the GRX Exchange by name or domain. Optionally filter the results by Country Code. Provides public company firmographics, third party relationship flag, and available assessment information to identify a company on the exchange.

The main data point to save is the company_id – that is the GRX ID for a company and is used in all the subsequent API calls as the identifier for that company.

The domain is the best way to search. If you search by name and domain the system is actually doing 2 separate searches and presenting the mixed results back to you ranked on match strength. If you want to completely automate adding a new company to your third party portfolio, pass in both name and domain and take the top result by setting the limit to 1.

Want to know more about using Company Search? Check out this article for more information.

 

View a company in the ProcessUnity Global Risk Exchange

GET /v2/company/companies/{company_id}

 

If you already have a GRX company_id stored, you can fetch that company to view public level company firmographics, third party relationship flag, and available assessment information for a company on the exchange.

Use this endpoint if any other endpoint gives you an error on the company_id to ensure you have a correct GRX ID saved. Also use this to pull back address information on a company if needed since the GET TP endpoint does not return the company’s address.

 

Manage Your Third-Party Portfolio

 

Add a company in the ProcessUnity Global Risk Exchange to your third party portfolio

 PUT /v2/portfolio/third-parties/{company_id}

 

You have found your vendor on the ProcessUnity Global Risk Exchange. (And maybe they might already have a completed attested assessment, awesome!) Now it is a simple step to use the company_id returned in the company search to add that company to your third party portfolio in order to unlock additional risk information.

 

Add a company to the ProcessUnity Global Risk Exchange and to your third party portfolio

 POST /v2/portfolio/third-parties

 

If you have searched for a company on the GRX Exchange and have not been successful in finding the vendor you are looking for, you can request to add a new company to the GRX Exchange and also to your third party portfolio with this endpoint. Requires company name, domain and country ISO2 code. The remaining address elements are strongly encouraged to be provided if known as it feeds into our company deduplication and enrichment efforts and will help ensure the correct company you are looking for is added to the Exchange.

 

Remove a company from your third party portfolio

DELETE /v2/portfolio/third-parties/{company_id}

 

Added the wrong company? No longer doing business with a vendor? Declutter your third party portfolio by removing that company; simply pass in the company_id to this endpoint and that company will no longer be in your third party portfolio.

If you tried to call the GET /v2/portfolio/third-parties/{company_id} again with the same company_id, it would now return an error. If you used that company_id to do the more general GET /v2/company/companies/{company_id}, you should see the “in_third_party_portfolio” set to false.

NOTE: If you have any requests for data currently in progress, those requests will be cancelled when a third party is removed. You will lose access to data from previously completed requests and authorized assessments as well. Even if you add the company back to your third party portfolio, you will need to re-request access to view attested information.

 

View the companies in your third party portfolio

GET /v2/portfolio/third-parties

 

Now that you are done with all the searching, adding and removing of companies, let’s see who is currently in your third party portfolio. View the companies in your third party portfolio, filterable by several elements such as Tags, Inherent Risk, and Custom ID. Provides third party relationship metadata, request and authorization status, available questionnaires and dates, and high level risk information for analysis and prioritization.

 

To understand how to interpret the data provided on a third party, read the Access Your Third Party Risk Information section below.

 

View the tags associated with companies in your third party portfolio

GET /v2/portfolio/tags

 

View the tags currently associated with companies in your third party portfolio. Use this information to filter and find third parties via GET /v2/portfolio/third-parties

 

View a company in your third party portfolio

GET /v2/portfolio/third-parties/{company_id}

 

View a company in your third party portfolio by its GRX Company ID. Provides third party relationship metadata, request and authorization status, available questionnaires and dates, and high level risk information for analysis and prioritization.

To understand how to interpret the data provided on a third party, read the Access Your Third Party Risk Information section below.

 

Update information on a company in your third party portfolio

PATCH /v2/portfolio/third-parties/{company_id}

 

Update information on a company in your third party portfolio by GRX ID. Manage tags associated with a third party. Set or update the custom id associated with a third party. Use this information to filter and find third parties via GET /v2/portfolio/third-parties

 

Request a third party complete and authorize a GRX questionnaire

POST /v2/portfolio/third-parties/{company_id}/requests

 

Request a third party complete and authorize access to the specified GRX questionnaire with the option for validation. A third party contact must also be provided.

Prior to placing a request for an assessment, check if that vendor already has an attested assessment on the Exchange. If you order that tier or lower, the vendor only has to authorize the release of the completed assessment and results to you. If you order a higher tier or if the vendor does not have any assessment on the Exchange yet, that vendor must first completed the assessment in order to authorize the release of the results to you.

 

NOTE: It is possible that the contact you provided will not be the one returned in the GET TP call. The contact provided at this time is the “Assessment Owner” if possible, or the "Account Admin". This is the user determined by ProcessUnity GRX to be the contact most likely to be able to action on your request.

 

Want to know more about the assessment tiers? Check out this article for more information.

 

Check to see if a request has been fulfilled

 

Once a request for an assessment has been placed on a company in your Third Party portfolio, you can use either the GET /v2/portfolio/third-parties/{company_id} or GET /v2/portfolio/third-parties to check if that request has been fulfilled.

 

There are two milestones that must be completed for a request to be fulfilled. The company must authorize you to view their data and the company must complete and attest the questionnaire tier. If you requested validation, then a third activity also needs to be completed where the company uploads their evidence documents and ProcessUnity GRX Assessors reviews the evidence to makes determinations if it substantiates the vendor’s claims.

 

At a higher level, the field “available_in_portfolio” will show you when you have access to an Attested questionnaire or a Validated questionnaire and a request has been fulfilled.

 

For more detailed information, the section “request_status” provides information about that status and the authorization for access to the data while the section “data_available_in_exchange” provides information about the state of completed and validated questionnaires. While sometimes the "latest_questionnaire" data may match the "data_available_in_exchange", when they do not match the "latest_questionnaire" section is displaying the status of In Progress assessments.

 

Request_access_status

  • Requested: The company has not yet responded to your request.
  • Approved: The company has authorized you to view their attested data for the questionnaire tier and validation requested. This field and status alone does not signify that the request has been fulfilled yet as the company may still need to finish the questionnaire and validation may need to be completed.
  • Denied: The company has rejected your request to view their attested data for the questionnaire tier and validation requested.

Request_progress

  • the request progress field is associated with the "latest_questionnaire" section and will show you the status of your first request for an assessment as well as ongoing refreshes by the third party

Data_available_in_exchange

  • If the questionnaire_name and validation are at the same level or a lower tier as the “request_status” questionnaire_name and validation, you know that the vendor already has a completed assessment on the exchange and you are only waiting for “request_access_status” to be updated to Approved
  • If the questionnaire_name and validation are at a higher than the “request_status” section questionnaire_name and validation, then the vendor must complete the additional questions and validation process (if requested). Once that is done you will see the new tier and dates reflected here since this section always shows the highest available tier on the exchange.  
  • If this section is null, then the vendor has no questionnaire completed on the exchange and must finish answering all the questions for the requested tier and attest for that information to populate for this section.
  • If you requested a validated questionnaire, it is possible that you will see a questionnaire with an attestation date prior to the validation being completed.

 

 

Access Your Third Party Risk Information

 

Third Party Risk Profile

Once a company has been added to your Third Party portfolio, you can use either the GET /v2/portfolio/third-parties/{company_id} or GET /v2/portfolio/third-parties/{company_id}/risk-profile to understand the risk profile for a company.

The “available_in_portfolio” field indicates at a glance what risk data is available to you at your third party portfolio level.

 

Inherent_Profile | Predictive Profile | Attested Profile | Validated Profile

  • An Inherent Profile is set when predictive data is not available for the company and when there is no request for an assessment, or when there is a request that is not yet approved and completed.
  • A Predictive Profile is set when predictive data is available for the company and when there is no request for an assessment, or when there is a request that is not yet approved and completed.
  • An Attested Profile is set when the third party approves the request and attests the associated assessment. For non-validated assessments, the request is considered complete at this point.  For assessments with validation pending, this status is displayed when the request is in the validation process but validation has not yet been completed.
  • A Validated Profile is set when the third party has approved the request and attested the assessment associated with that request and an assessor has completed the validation process and is only applicable to assessments with validation

 

Inherent Risk Profile

 

As soon as a company is added to your third party portfolio, you will have access to Inherent Risk data, powered by the GRX “Auto Inherent Risk” feature. You can use the GET /v2/portfolio/third-parties/{company_id}/risk-profile to understand the Inherent Risk profile for a company.

 

Inherent Risk describes risk when all cybersecurity controls fail or are missing. It provides a worst-case scenario view for engaging with a third party.

 

There is a section of the company response “inherent_risk” that has the following fields:

inherent_risk_score

  • Returns a number from 0.00 to 100.00
  • This score is not static and is subject to change daily based on a variety of inputs
  • The score is provided to allow custom thresholds for classification if you would prefer to calculate your own bands

inherent_risk_rating

  • Returns a string to provide the GRX interpretation of the inherent_risk_score
  • The rating provided is the GRX standard classification - GRX is currently using a 5 band of Critical, High, Medium, Low and Nominal

impact_status

  • Returns “CONFIRMED” if you have completed the Impact Questionnaire for the third party
  • Returns “UNCONFIRMED” if you have not yet completed the Impact Questionnaire for the third party and are instead seeing the score and rating based on our “Auto Inherent Risk” feature

What to do next?

If “available_in_portfolio” = Inherent_Profile

 

You can complete the Impact Questionnaire to fine tune the Inherent Risk and ensure it is reflecting how you do business with and rely on that vendor.

 

You can wait for Predictive to be generated for that company. Predictive results are typically available within 2 weeks. See the section “Predictive Risk Profile” for more info.

 

Depending on the inherent risk of the vendor and your business process, you can request an assessment and wait for it to be completed and authorized to get access to Attested information from the vendor. See the section “Request a third party complete and authorize a GRX questionnaire” for more info.

 

Want to know more about inherent risk? Check out this article for more information.

 

Predictive Risk Profile

 

As soon as an existing company on the GRX Exchange is added to your third party portfolio, you will have access to Predictive Residual Risk data, powered by the GRX Predictive Model. You can use the GET /v2/portfolio/third-parties/{company_id}/risk-profile to understand the Predictive Risk profile for a company.

 

If you added a new company to the GRX Exchange and to your third party portfolio, the Predictive data may take a while to be generated. Predictive results are typically available within 2 weeks.

 

Residual Risk describes risk when cybersecurity controls are in place and is what remains of Inherent Risk after the controls assessment answers predict what is mitigated. The score is provided to allow custom thresholds for classification.

 

There is a section of the response “residual_risk” that has the following fields:

predictive_residual_risk_score

  • Returns a number from 0.00 to 100.00
  • This score is not static and is subject to change daily based on a variety of inputs

predictive_risk_reduction_percentage

  • Returns a number from 0.00 to 100.00 and is the percentage reduction between the Inherent Risk and the Predictive Residual Risk
  • This score is not static and is subject to change daily based on a variety of inputs

predictive_risk_reduction_rating

  • The rating of how well the residual risk reduced inherent risk
  • Values: EXCELLENT, VERY_GOOD, GOOD, FAIR, POOR, VERY_POOR, INSUFFICIENT_INHERENT_RISK

What to do next?

If “available_in_portfolio” = Predictive_Profile

 

You can review the summary of the Predictive Assessment results that support the higher level Predictive Residual Risk score.  See the section “Assessment Results” for instructions on how to pull and understand the summary Predictive Results.

 

You can dig deeper into the details of the Predictive Assessment results that support the higher level Predictive Residual Risk score.  See the section “Assessment Results” for instructions on how to pull and understand the detailed Predictive Results.

 

Depending on the inherent risk of the vendor and your business process, you can request an assessment and wait for it to be completed and authorized to get access to Attested information from the vendor. See the section “Request a third party complete and authorize a ProcessUnity GRX questionnaire” for more info.

 

Want to know more about residual risk? Check out this article for more information.

 

Attested Risk Profile

 

After you have requested an assessment and that vendor has completed and authorized you to view the assessment, you will have access to Attested Residual Risk data. You can use the GET /v2/portfolio/third-parties/{company_id}/risk-profile to understand the Attested Risk profile for a company.

 

Residual Risk describes risk when cybersecurity controls are in place and is what remains of Inherent Risk after the controls assessment answers tell us what is mitigated. The score is provided to allow custom thresholds for classification.

 

There is a section of the response “residual_risk” that has the following fields:

attested_residual_risk_score

  • Returns a number from 0.00 to 100.00
  • This score is not static and is subject to change daily based on a variety of inputs

attested_risk_reduction_percentage

  • Returns a number from 0.00 to 100.00 and is the percentage reduction between the Inherent Risk and the Attested Residual Risk
  • This score is not static and is subject to change daily based on a variety of inputs

attested_risk_reduction_rating

  • The rating of how well the residual risk reduced inherent risk
  • Values: EXCELLENT, VERY_GOOD, GOOD, FAIR, POOR, VERY_POOR, INSUFFICIENT_INHERENT_RISK

What to do next?

If “available_in_portfolio” = Attested_Profile

 

You can review the summary of the Attested Assessment results that support the higher-level Attested Residual Risk score.  See the section “Assessment Results” for instructions on how to pull and understand the summary Attested Results.

 

You can dig deeper into the details of the Attested Assessment results that support the higher-level Attested Residual Risk score.  See the section “Assessment Results” for instructions on how to pull and understand the detailed Attested Results.

 

Want to know more about residual risk? Check out this article for more information.

 

Validated Risk Profile

 

A validated profile will only ever be available if you had requested a validated assessment for that vendor. This profile will be available after the company has completed and attested the assessment, submitted evidence documentation, and the GRX Assessors reviewed the documentation and made determinations if the evidence validates the critical controls.

 

NOTE: Validation results do not influence the Attested Residual Risk data. 

 

What to do next?

If “available_in_portfolio” = Validated_Profile

 

At this time you can pull the detailed “Assessment Results” again and additional fields will be populated. See the section “Assessment Results” for instructions on how to pull and understand the detailed Validation Results.

 

Assessment Results

 

Assessment Results - Data Available

GET /v2/portfolio/third-parties/{company_id}/risk-profile

 

View the attestation dates for the assessment and validation data that is visible to you for a company in your third party portfolio. These dates are associated with the assessment data pulled via the Summary or Detailed Assessment Results.

 

Assessment Results - Summary

GET /v2/portfolio/third-parties/{company_id}/risk-navigator/{framework_id}/summary

 

View summary assessment and risk information for a company in your third party portfolio for a specified framework. Review predictive or attested assessment results at the overall and group levels, depending on what data is authorized and available in portfolio. This endpoint will return the highest level of data available to be viewed as the default.

 

If “available_in_portfolio” = Inherent_Profile: Assessment data does not yet exist to be pulled via this API.

 

If “available_in_portfolio” = Predictive_Profile: Predictive assessment data exists and can be pulled via this API. Predictive data is the default response when it is the highest level of data available. 

 

If “available_in_portfolio” = Attested_Profile: Attested assessment data exists and can be pulled via this API. Attested data is the default response when it is the highest level of data available. 

 

If “available_in_portfolio” = Validated_Profile: Validated and Attested assessment data exists and can be pulled via this API. Validated data is the default response when it is the highest level of data available. 

 

After deciding what framework to use, you will get the following assessment results information:

 

 

Assessment Results - Details

GET /v2/portfolio/third-parties/{company_id}/risk-navigator/{framework_id}

 

View detailed assessment and risk information for a company in your third party portfolio for a specified framework. Review predictive or attested assessment results in detail at the question level, depending on what data is authorized and available in portfolio, in order to analyze and prioritize gaps for risk mitigation. This endpoint will return the highest level of data available to be viewed as the default.

 

If “available_in_portfolio” = Inherent_Profile: Assessment data does not yet exist to be pulled via this API.

 

If “available_in_portfolio” = Predictive_Profile: Predictive assessment data exists and can be pulled via this API. Predictive data is the default response when it is the highest level of data available. 

 

If “available_in_portfolio” = Attested_Profile: Attested assessment data exists and can be pulled via this API. Attested data is the default response when it is the highest level of data available. 

 

If “available_in_portfolio” = Validated_Profile: Validated and Attested assessment data exists and can be pulled via this API. Validated data is the default response when it is the highest level of data available. 

 

After deciding what framework to use, you will get the following assessment results information:

 

Every framework selected has one or more framework controls. The results are organized by the framework controls first with information about each one along with their score. Each framework control is supported with information on the list of GRX controls, and associated information, mapped to the framework control.

 

framework_control_name

  • The framework specific control name, label or identifier

framework_control_description

  • The framework specific control description to elaborate on what is being considered and evaluated

framework_control_group

  • The framework specific group that the framework control is associated with for organization and filtering purposes

framework_control_score

  • Weighted average score that is derived from the mapped GRX question(s) score(s) and represents how well a framework control is covered

framework_control_rank

  • Rank that is associated with the framework control score and represents how well a framework control is covered
  • values: VERY_POOR, POOR, FAIR, GOOD, VERY_GOOD

 

cybergrx_controls

  • This section shows the list of GRX controls that were mapped to the framework control
  • There could be 0, 1 or many GRX controls mapped depending on the context of the framework control

question_number

  • This is the unique identifier for the GRX question on the assessment

question_name

  • This is the high-level name / topic for the GRX question on the assessment

question_prompt

  • This is the full question text that was displayed to the third party as they were answering the GRX assessment

question_type

  • Shows the relationship of the GRX question to the associated framework control
  • Primary  – indicates one to one matching of the GRX question to the Framework control
  • Supporting – indicates that the GRX question will typically cover an aspect of the Framework control but not the control in its entirety

question_score_basis

  • Describes the means by which the scores were derived for each control. Values may be any of the following:
  • Attested Metrics – the control score is based on Tier 1 answers and includes strength, coverage, and timeliness fidelity
  • Attested Control –  the control score is based on Tier 2 answers at a Yes/No fidelity
  • Attested NA – the control was answered with a 'Not Applicable' response
  • Predictive Control – the control score is a predicted value
  • Unavailable – neither predictive or attested results are available for this control

question_score

  • The attested or predicted effectiveness of the GRX control

  • Tier 1 assessments range from 0-100

  • Tier 2 assessments are credited with 0 for "No" answers and 85 for "Yes" answers

  • Predictive outcomes range from 0-85

  • The score will be null if the control answer is "NA" or Unavailable

answer_state

  • Answer states for the GRX question presented to the vendor
  • Yes – the company confirmed they do have the GRX control in place
  • No – the company confirmed they do not have the GRX control in place
  • NA (Not Applicable) – the company confirmed that the GRX control was not applicable to them
  • Unavailable – The company did not have this control in the version of the questionnaire they answered
  • Empty / Null – If calculation_basis = Predictive_Profile this field will be null since Predictive assessments do not include an answer state from the company

question_comment

  • Third Party comments on the GRX Control if provided
  • If the answer_state = NA, then comments are required to be provided by the company
  • If calculation_basis = Predictive_Profile, this field will be null since Predictive assessments do not include comments from the company

finding_severity

  • Finding severity refers to the identification of a security, policy, or management weakness at the control level. The determination severity is based on a combination of the control’s effectiveness and classification, with those deemed Critical or instrumental in preventing MITRE ATT&CK scenarios given extra scrutiny
  • High, Medium or Low
  • Empty /null – no finding severity for the given control

maximum_impact

  • Maximum impact refers to the highest level of impact that a failed control would have on your business, based on how you answered the Impact Questions. If the Impact Questions are Unconfirmed, then the Auto Impact Responses will be used.

mitigation

  • Provides suggested approaches, technologies, or standards that help improve the control, establish best practices, and reduce the risk of compromise

validation_status

  • Describes the validation state for each mapped GRX Control
  • Not Applicable – control is not a GRX 60 Critical Control; or validation was not included with your request; or if calculation_basis = Predictive_Profile
  • Pending Review – GRX Analysts are in the process of evaluating evidence provided by the Third Party; will only show if “available_in_portfolio” = Attested_Profile and validation was included with your request
  • Not Validated – evidence provided was inadequate to determine if the control was in place; will only be an option if “available_in_portfolio” = Validated_Profile
  • Validated – all of the validation criteria has been met for this control; will only be an option if “available_in_portfolio” = Validated_Profile
  • Not Selected – GRX 60 Critical Control that the third party stated they do not perform (i.e. 'No' answer state), therefore validation is not required; will only be an option if “available_in_portfolio” = Validated_Profile

evidence_type

  • Describes the type of evidence that was provided by the third party to validate a control
  • Written – evidence in a narrative documentation format. Examples include policies, procedures, emails, etc.
  • Demonstrated – any type of primary, technical evidence. Examples include actual live demonstrations, screenshots, exports, etc.
  • Verbal – any evidence which is self-attested. Examples include discussions, written notes or explanations, previously completed self-assessments, etc.
  • No Evidence – evidence was not provided by the third party
  • Not Applicable – control is not a GRX 60 Critical Control; or validation was not included with your request

 

Want to know more about assessment results? Check out this article for more information.

 

Get the list of available frameworks

GET /v2/reporting/frameworks

 

Get the list of available GRX Frameworks, Standard Frameworks, Threat Profiles, and Industry Profiles. If applicable, Licensed Content and Custom Frameworks will also be returned. Store the framework_id to be used as the input parameter for the Risk Navigator or the Portfolio Risk Findings.

 

Don’t know where to start? We recommend using our “GRX Assessment – Risk Domains” framework as it returns the entire GRX Assessment organized by Risk Domains.

 

Want to know more about frameworks? Check out this article for more information.

 

Download a Third Party Risk Information Report

 

If your risk analysts prefer to review the risk information on a third party in report format, endpoints are available to retrieve the spreadsheet report for a company’s predictive or attested assessment.

 

Request the Report

POST /v2/reporting/exports

Use the company_id and selected framework_id to request the export of the spreadsheet version of the Assessment Report. This report can be downloaded for either a “PREDICTIVE_PROFILE” or an “ATTESTED_PROFILE”. 

 

The report provided is the same file from the Third Party -> Risk Profile tab -> Risk Navigator "Download". This report includes Third Party meta data, Inherent and Residual Risk data, and detailed Assessment data with scoring and findings.

 

Check if the Report is Ready

GET /v2/reporting/exports/{export_id}

Use the export_id to check the status of the report until it is "Ready". At that time, you will also get the uri for the download.

 

Retrieve the Report

GET /v2/reporting/exports/{export_id}/download

Use the export_id to download the report. The download will work only once. If not retrieved, the download link will expire after 30 days.

Was this article helpful?
0 out of 0 found this helpful
Return to top

Related articles

Comments

0 comments

Article is closed for comments.