Data Posture API Tutorial
- How to retrieve security issues from the Data Posture API.
- How to export relevant issues to a third-party system.
- How to use the Apply Action API to update multiple issues at once.
- How to mark issues as resolved after export to keep BigID in sync.
In this tutorial, we'll use SAMPLE as our session token. This is unique to the training sandbox and will not work in other environments. See BigID API/Tutorial for information on authenticating with BigID.
To view the complete code for all steps, see the section labelled Code Samples.
For more information on the API capabilities used in this tutorial, check out the Data Posture API Docs.
1. Authenticate Using Your API Key
All API requests require authentication using a valid API key. Refer to BigID Documentation to obtain your token. Then, define the Authorization header using the format Authorization: Bearer YOUR_API_KEY. This header must be included in every request to ensure proper authentication and access to BigID’s API endpoints. Throughout the tutorial, we will be using SAMPLE as our token.
2. Retrieve Security Issues
There are multiple endpoints available for fetching security cases, but because our goal is to export these issues to a third party system, we want to use the GET /api/v1/actionable-insights/all-cases. This will allow us to fetch all existing security issues, as well as limit the selection based on various parameters if necessary.
In the case that you do not want to fetch all cases, you can filter the response based on several parameters, all of which are outlined in the following table:
| Parameter | Type | Description |
|---|---|---|
| skip | integer | Number of records to skip (for pagination) |
| limit | integer | Number of records to return |
| filter | string | BigID Query Language filter to narrow results |
| fields | string | Comma-separated list of fields to return |
| sort | string | Field to sort by, plus optional ASC/DESC |
| requireTotalCount | boolean | Whether to include totalCount in response |
Once you have fetched the details for all of the security cases you are interested in, you can proceed to the next step.
3. Export Issues to Your Third-Party System
Once you retrieve the list of open security issues, the next step is to export them to your third-party system for remediation. This could be a ticketing platform like Jira, ServiceNow, or a SOAR tool for automated workflows.
For each issue, map the relevant fields to your third-party system’s API. Common mappings might include:
| BigID Field | Third-Party Field |
|---|---|
| caseLabel | Ticket title |
| policyName | Category or label |
| severityLevel | Priority |
| assignee | Assigned owner |
| dataSourceName | Affected resource |
4. Mark Issues as Resolved
After successfully exporting the issues, you’ll want to mark them as resolved in BigID to avoid duplicate work and keep the backlog clean. You have two options for marking issues as resolved using the API.
First, you can do so in bulk using the PATCH /api/v1/actionable-insights/cases:{actionType} endpoint. In order to use this endpoint, you should:
- In the request, tell BigID which field to update (in this case, caseStatus) and what the new value should be (set it to resolved).
- Add filters to select the cases you want to update, like policyName or caseStatus:open.
- Run the request. BigID will return the list of case IDs that were successfully updated.
For example, your request may be structured like the following:
{
"type": "CasesDB",
"subType": "updateCases",
"additionalProperties": {
"field": "assignee",
"newValue": "[email protected]",
"casesFilters": [
{
"filterField": "policyName",
"filterValues": [
"policy1234"
]
},
{
"filterField": "caseStatus",
"filterValues": [
"remediated"
]
}
]
}
}
The following request uses the example request body above. To actually test this endpoint, replace the fields with real values based on the previous steps.
If you only need to update the status of specific cases, this can be done using the PATCH /api/v1/actionable-insights/case-status/{caseId} endpoint. To do so:
- Replace {caseId} with the actual ID of the case you want to update.
- In the request body, set caseStatus to resolved.
- Add an auditReason so your team knows why the change was made (for example, “Exported to Jira on July 14th”).
For example, your request may be structured like the following:
{
"caseStatus": "resolved",
"auditReason": "Exported to Jira on July 14th"
}
In the request below, the {caseId} is currently represented by a fake ID, 123abc. In order to test the endpoint, replace it with a case ID you have addressed in the previous steps.
5. Troubleshooting
If your request fails, here’s what the server might tell you, and how to fix it:
| Status Code | Example Response | What It Means | How to Fix It |
|---|---|---|---|
| 200 | Successful response with scan data | Everything’s looking good! | Keep cruising. |
| 400 | { "error": "Scan ID is invalid" } |
Bad or malformed scan ID provided | Double-check the scan ID you’re using. |
| 404 | { "error": "Scan 1234 was not found" } |
Scan ID doesn’t exist | Make sure the ID is valid and fetched from the parent scans endpoint. |
| 401 | Unauthorized | API key missing or invalid | Verify your API key and authorization header. |
| 500 | { "status": "error", "message": "Server error", "errors": [{}] } |
BigID server hit a snag (internal error) | Wait a moment and retry. If it persists, reach out to support. |
Code Samples
Summary
Congratulations! In this tutorial, you have learned how to retrieve open security issues from BigID, export those issues to a third-party system for remediation, and mark the issues as resolved in BigID to keep your backlog clean and accurate. By following these steps, you can streamline your remediation process, reduce manual effort, and maintain a clear, up-to-date view of your organization’s security posture.