X-Analytics Public API 1.0 provides access to the X-Analytics cyber condition report’s data, including information about a control framework’s level of implementation. It gives Users the ability to pull data from X-Analytics application to their own applications or 3rd party services. The X-Analytics Public API 1.0 was created with the best API practices in mind. The following guide provides the main information about using the X-Analytics API, best practices used and recommendations for Users to keep their data safe.
To test configuration and output of API integration see: How to Test and Configure X-Analytics Public API 1.0
The above resource refers to developer documentation for how to fetch X-Analytics data from the API.
Understanding API Integrations
Before learning how the X-Analytics API works, it's essential to understand the API integrations terminology:
API: An Application Programming Interface (API) is a set of rules and protocols that allows different software applications to communicate with each other.
Client ID and Client Secret: These are unique credentials issued to authenticate and authorize your application when making requests to an API.
OAuth: Often used for authentication and authorization in API integrations, OAuth is a secure protocol that protects sensitive information during communication. OAuth is a secure protocol underneath the OpenID authentication protocol.
X-Analytics Public API 1.0 gives access to a certain Business Unit/Profile’s report data:
Business Unit Cyber Exposure: overall exposure value per category for each severity (Low, Medium, High, Worst Case).
Business Unit CIS CSC: macro score, function score, score by control, exposure benefit by control.
Business Unit NIST CSF: macro score, tier score, function score, score by control, exposure benefit by control.
Prioritized mitigation: ranking for best CIS CSC controls, ranking for best NIST CSF controls.
Only registered X-Analytics application users can create an integration. All user types can create an integration (Organization Admin, User with editor or viewer permissions). For now, it’s possible to create only 1 integration per User. Users can see only their own integrations on the list of Integrations. Organization Admin can see all Integrations in the organization. Information about an integration contains integration name, author and creation date.
Creating an integration
Step 1: Creating an integration
The first step in integrating with X-Analytics API is to create an integration. In order to do this, User needs to log into the application and go to the Integrations tab in the menu on the left-hand side. Then, User needs to click on “Add new integration” button, and provide
● name of integration,
● scope – choose list of Business Units.
Step 2: Client ID and Client Secret
Once integration is created, Users will see a modal with Client Id and Client Secret. It will be presented to the user only once, please copy these credentials as it won’t be possible to see the credentials after you move past Step 2. Client IDs and Client secrets are the keys to application's access to the API, so it’s important to store them in a safe location.
Step 3: API Requests
Having stored credentials, read the following documentation in order to create an API request:
Step 3.1: Editing an integration
Currently, it’s not possible to edit an integration. Users need to delete and create a new integration in order to change integration details.
Step 3.2: Viewing integration details
To see details of an integration, User needs to click on the specific integration on the list of integrations. The page with information about integration name, author, creation date and list of Business Units will open.
Step 3.3: Deleting an Integration
In order to delete an integration, User should click on the Actions > Delete in Integrations list page, and confirm the action.
Security Best Practices
To enhance security during API integrations, the following best practices were used:
Authorization: Fine-grained access controls implementation to restrict access to specific API endpoints or actions based on the user's role or permissions (user role, business units access, limited data scope).
Keeping Client ID and Client Secret Confidential: Both the Client ID and Client Secret are treated as sensitive information and presented to the User just once – after creating an integration. They are stored securely on the server side and not visible on the client-side.
API Rate Limiting: API rate limits are used in order to avoid overloading the API server.
Audit and Monitoring: Audit logs are implemented. It’s possible to see the information about each action on integrations done by each user. The data can be used for further analysis of any suspicious behavior. NOTE: In order to receive the data for your organization, please contact the X-Analytics Support Team at firstname.lastname@example.org.
Updated Documentation: API integration documentation is up-to-date and accessible to authorized team members.
Error Handling: Providing generic error messages to users and logging errors on the server side in order to avoid leaking sensitive information in error messages.
Recommendations for Users
Keep Client ID and Client Secret in a secure location, so no one can use the credentials to get access to your organization’s sensitive data.
Use HTTPS: When exchanging Client ID and Client Secret, or when making requests that involve sensitive information, always use HTTPS to encrypt the data in transit and prevent eavesdropping.
If you have any difficulties or questions, please, contact the support team for assistance at email@example.com.