Returning scan-related information

The following article shows how you can use the ShiftLeft API to view information about your applications, their scan results, and any vulnerabilities, secrets, or insights identified by ShiftLeft. The API is an alternative to viewing similar information in the Dashboard.

Prerequisites

Before proceeding, you should have:

  • Submitted an app to ShiftLeft for analysis
  • Have the following information available:
    • Your access token and org ID (both are available in the ShiftLeft Dashboard)
    • Your app ID (e.g., if you submitted your app via the CLI and named it HelloShiftLeft, this value would also be your app ID)

For all of these examples, you can use the command-line interface on your machine, though a tool like Postman would be helpful. You can use our Postman Collection specifically for these examples.

API authentication

The ShiftLeft API uses bearer authentication, which means that you must pass in a bearer token before you make calls to any of the endpoints. More specifically, you must provide your ShiftLeft access token in the HTTP Authorization request header before proceeding.

Example 1: List findings for the latest scan of the app

Endpoint to use: List App Findings

This endpoint requires you to pass your org ID and app ID in the URL to obtain the findings for the latest scan of your app:

curl \
--request GET 'https://app.shiftleft.io/api/v4/orgs/{orgID}/apps/{appID}/findings' \
--header 'Authorization: Bearer {yourAccessToken}'

You should receive a response whose beginning looks similar to the following:

{
"ok": true,
"response": {
"scan": {
"id": "49",
"internal_id": "sl/d64f..",
"app": "HelloShiftLeft",
"version": "1c545...7627",
"successful": true,
"started_at": "2021-10-26T14:59:54.701507Z",
"completed_at": "2021-10-26T15:01:05.206619Z",
"language": "java",
"number_of_expressions": 1243
},
"findings": [
{
"id": "699",
"app": "HelloShiftLeft",
"type": "oss_vuln",
"title": "pkg:maven/com.fasterxml.jackson.core/jackson-databind@2.8.6",
"description": "FasterXML jackson-databind 2.x before 2.9.10.4 mishandles the interaction between serialization gadgets and typing, related to br.com.anteros.dbcp.AnterosDBCPConfig (aka anteros-core).",
// ...
}

Example 2: Get details for a specific finding

Endpoint to use: Read App Finding

Once you've returned the complete list of findings for your application, you can look at specific findings. To do so, you'll need (in addition to the app ID and the org ID) the finding ID. This can be obtained from the results of the call you executed in Example 1.f

curl \
--request GET 'https://app.shiftleft.io/api/v4/orgs/{orgID}/apps/{appID}/findings/{findingID}' \
--header 'Authorization: Bearer {yourAccessToken}'

You should receive a response whose beginning looks similar to the following:

{
"ok": true,
"response": {
"id": "49",
"app": "HelloShiftLeft",
"type": "vuln",
"title": "Sensitive Data Leak: Sensitive data contained in HTTP request/response in `CustomerController.getCustomer`",
"description": "Sensitive data included in HTTP request/response. This could result in sensitive data exposure. Many web applications and APIs do not protect sensitive data, such as financial and healthcare. Attackers may steal or modify such weakly protected data to conduct credit card fraud, identity theft, or other crimes.\n\n\n## Countermeasures\n\n This vulnerability can be prevented by ensuring that sensitive data is encrypted/hashed with strong up-to-date standard algorithms.\n\n## Additional information\n\n**[CWE-200](https://cwe.mitre.org/data/definitions/200.html)**\n\n**[OWASP-A3](https://owasp.org/www-project-top-ten/OWASP_Top_Ten_2017/Top_10-2017_A3-Sensitive_Data_Exposure)**",
"internal_id": "sensitive-to-http/84c15341ed3ed3c523bace3d8c912e3b",
"severity": "info",
"owasp_category": "a3-sensitive-data-exposure",
"category": "Sensitive Data Leak",
"version_first_seen": "66359c1ae87cb912bea990776683e75390e3e6b8",
"scan_first_seen": "11",
"created_at": "2020-05-26T14:20:33.759611Z",
"details": {
"Link": "https://owasp.org/www-project-top-ten/OWASP_Top_Ten_2017/Top_10-2017_A3-Sensitive_Data_Exposure",
"dataflow": {
"list": [
{
"location": {
"line_number": 120,
"package_name": "io.shiftleft.controller",
"class_name": "io.shiftleft.controller.CustomerController",
"method_name": "io.shiftleft.controller.CustomerController.getCustomer:io.shiftleft.model.Customer(java.lang.Long)",
"short_method_name": "getCustomer",
"file_name": "io/shiftleft/controller/CustomerController.java"
},
//...
}

Example 3: Get the packages used in an application

Endpoint to use: List App Findings

When listing the findings for a specific application, you can add a (query) parameter to your API call to get the OSS packages that are used in the application: ?type=package

curl \
--request GET 'https://app.shiftleft.io/api/v4/orgs/{orgID}/apps/{appID}/findings?type=package' \
--header 'Authorization: Bearer {yourAccessToken}''

You should receive a response whose beginning looks similar to the following:

{
"ok": true,
"response": {
"scan": {
"id": "49",
"internal_id": "sl/d64f2...",
"app": "HelloShiftLeft",
"version": "1c5456538997f174d475487587a0b0ed77917627",
"successful": true,
"started_at": "2021-10-26T14:59:54.701507Z",
"completed_at": "2021-10-26T15:01:05.206619Z",
"language": "java",
"number_of_expressions": 1243
},
"findings": [
{
"id": "626",
"app": "HelloShiftLeft",
"type": "package",
"title": "org.springframework/spring-test",
"description": "",
"internal_id": "package/4b89c07bc5a7b82b05934570851f1393",
"severity": "",
"owasp_category": "",
"category": "",
"version_first_seen": "1c5456538997f174d475487587a0b0ed77917627",
"scan_first_seen": "48",
"created_at": "2021-10-26T14:55:18.926306Z",
"details": {
"package_url": "pkg:maven/org.springframework/spring-test@4.3.6.RELEASE"
},
//...
}

Example 4: Get a list of apps that your org has scanned

Endpoint to use: List Apps

In addition to detailed information like scans and their findings, you can get higher-level data points, such as the list of applications that your org has submitted to ShiftLeft for analysis.

curl \
--request GET 'https://app.shiftleft.io/api/v4/orgs/{orgID}/apps' \
--header 'Authorization: Bearer {yourAccessToken}'

You should receive a response that looks similar to the following:

{
"ok": true,
"response": [
{
"id": "shiftleft-java-demo",
"name": "shiftleft-java-demo",
"tags": [
{
"key": "group",
"value": "demo-apps"
}
]
},
// ...
}