Mobile Security Results API

The Mobile Security Results API provides access to the list of all mobile apps registered within your organization’s Data Theorem account, and the list of scans and security issues found during scanning of the apps.

If your organization uses Jira as its bug tracker, you should see Integrating with Jira instead.

Overview

The Mobile Security Results API provides API operations for the following resources:

  • Mobile Apps represent a particular mobile app that Data Theorem continually scans. Some are apps that are published to one of the app stores, while others represent pre-production apps or internal/enterprise apps.
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps/:id
  • Mobile App Insights represent a variety of non-security-vulnerability data about the mobile apps. Insights include SDK/API versions of the mobile platform the app was built for, permissions the app needs or requests, and other miscellaneous information about the app extracted from its binaries or from its behavior.
  • Mobile App Scans represent a particular scan of a specific mobile app. They provide details from the scan such as the status, date of scan, what mobile app was scanned along with details of the app.
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps/:mobile_app_id/scans
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps/:mobile_app_id/scans/:id
  • Mobile Apps Changes represent a change of some aspect of the application from release-to-release. These changes are automatically tracked by Data Theorem, and include categories such as the application’s bundle size and requested permissions.
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps_changes
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps_changes_stats
  • Mobile Apps Monthly Security Metrics represent metrics for mobile security issues over the past 6 months that Data Theorem has detected across the applications in your inventory.
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps_monthly_security_metrics
  • Mobile Apps Security KPIs represent a variety of Key Performance Indicators(KPIs) along with their counts as tracked by Data Theorem across the apps inventory.
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps_security_kpis
  • Mobile App Third-Party SDKs represent a particular kind of Third-Party SDK data bundled within mobile apps.
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps/:mobile_app_id/sdks
  • Security Findings represent a particular kind of issue contained in a particular mobile app. They provide a description of the issue, conversation thread about the issue (from the portal), etc.
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/security_findings
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/security_findings/:security_finding_id
  • A Security Finding always has one or more Security Finding Targets that represent specific instances of the issues in a mobile app. Each one represents a particular occurrence of an issue, so they might correspond to a location in the app’s code, a particular file, or to the whole app itself.
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/security_finding_targets
    • GET https://api.securetheorem.com/apis/mobile_security/results/v2/security_finding_targets/:security_finding_target_id
    • PATCH https://api.securetheorem.com/apis/mobile_security/results/v2/security_finding_targets/:security_finding_target_id

Additional Resources

  • The last section Suggested Workflows provides a guide on how to automate the process of exporting Data Theorem issues to an external bug tracking system (such as Jira).
  • Data Theorem’s Mobile Security API client library provides a reference client for accessing the Mobile Security Results API: https://bitbucket.org/datatheorem/dt-api-client

Versioning

As explained on API Conventions – API Versioning, Data Theorem uses semantic versioning for our APIs. We publish our APIs on a path that includes the major version number of the API.

The current version of the Mobile Security Results API is v2, and its base URL is:

1
https://api.securetheorem.com/apis/mobile_security/results/v2/

It is also available at the following base URL, but it is not recommended for new integrations:

1
https://api.securetheorem.com/resultsapi/v2/

Additionally, Data Theorem still maintains a v1 API, but it is deprecated and thus no longer publicly documented. Anyone still using the v1 API is strongly encouraged to switch to the v2 API.

Authentication and Authorization

The Mobile Security Results API requires clients to use a standard API Key in order to access data about their mobile apps.

Note that an API Key may have access to all mobile apps (and their related data), or they might be restricted to only accessing certain mobile apps. This can be configured in Data Theorem’s portal.

See API Conventions – Authentication and Authorization for more information.

Calling the API

The Mobile Security Results API follows RESTful conventions:

  • It uses the semantic meaning of HTTP’s methods (GET, POST, PATCH, DELETE, PUT) to convey the intent of a request.
  • It organizes its API operations around resources (eg, a particular mobile app), and resource collections (ie, multiple resources that are of the same type, such as all mobile apps)
  • Response data is represented with JSON. The same is true for requests that expect a body (POST, PATCH, and PUT methods)

Response Codes

In general, the Results API provides conventional HTTP response codes to indicate success or failure of an API request.

  • 2XX: Successful requests.

  • 4XX: Failed requests due to authentication issues or resources that do not exist.

  • 5XX: Failed requests due to server errors.

Cross-Origin Resource Sharing (CORS)

CORS is not supported by the Mobile Security Results API. Enabling CORS headers would allow building web applications that make cross-origin HTTP requests to the Results API. Such an application would by design leak the API Key used to all users of the web application.

Example API Call With curl

1
curl -H "Authorization: APIKey 1234567890abcdefgh" -X GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps

Pagination

API operations that return collections are paginated. If there are additional pages of results, then the next page can be retrieved by calling the same endpoint again, with the same query parameters, as well as the with the next_cursor provided by the previous page’s response (located in the response’s pagination_information). This should be repeated until the last page, which does not return a next_cursor.

For example, given a request to the “List Mobile Apps” endpoint:

1
GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps?release_type=APP_STORE

The response might look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "mobile_apps": [
    {
      "id": "123",
      "external_id": "MyApp-123-TestOrg", // optional
      "bundle_id": "com.test",
      ...
    },
    ...
  ],
  "pagination_information": {
    "total_count": "256",
    "next_cursor": "kEgkIjrCzvdns0QISRmoRc35kaXNjb"
  }
}

The pagination_information entry contains all the details concerning pagination. In this case, the total number of items is given by the total_count field showing that there are 256 apps associated with this query. If other query parameters were used to filter the mobile apps, the total_count would reflect the total number of matching apps for those queries. Additionally, the next_cursor field contains a cursor that points to the next page, provided that all the other query parameters are kept the same. The next page of results can therefore be fetched as follows:

1
GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps?release_type=APP_STORE&cursor=kEgkIjrCzvdns0QISRmoRc35kaXNjb

The second page’s response will also contain a pagination_information field, which will include a next_cursor if there are any remaining pages. To fetch all items in a paginated collection, you should repeatedly call the endpoint with each subsequent cursor until a page of results does not return a next_cursor.