Suggested Workflows

This section provides a suggested workflow for automatically exporting Data Theorem issues to an external bug tracking system, such as Jira. The workflow leverages the target’s external_id field to store the ID of the target’s corresponding ticket in the bug tracking system.

Exporting New Issues to a Bug Tracker

The following process should be run regularly (for example once a day) in order to keep all the issues found by Data Theorem in sync with the external bug tracking system. The process can be implemented as follows:

1. Query the list apps endpoint and filter it by the results_since query parameter to find the list of apps that have recent results (for example within the last 4 days). requests_since should be a date/timestamp in RFC-3339‘s profile of the ISO8601 time format. i.e. '%Y-%m-%dT%H:%M:%S.%f'

    GET https://api.securetheorem.com/apis/mobile_security/results/v2/mobile_apps?results_since=2017-11-02T19:25:16.664990-00:00
   

2. For each app in the response of the previous query:

   1. Query the List Security Finding Targets endpoint and filter the results by both mobile_app_id and results_since query parameters to find security finding targets within the given app that have recently changed. GET https://api.securetheorem.com/apis/mobile_security/results/v2/security_finding_targets?mobile_app_id=13&results_since=2016-11-02T19:25:16.664990-00:00
   2. For each target in the response of the previous query:
      1. Check the target’s external_id field; if the field is already set, it means that the target has already been exported to the external bug tracking system.
      2. If the target does not have a corresponding ticket, create a new ticket in the external bug tracking system. Then, use the newly created ticket id to set the external_id field on the target using a PATCH request.
      3. If the target does have a ticket, then update the status of the ticket (for example in Jira, by adding a comment) regarding the changed status or transitioning the ticket to resolved if the target is closed.

Notes:

• If a target transitions to closed but the ticket is already closed, it should be gracefully handled.
• If a ticket already exists for an issue, it should not be recreated.
• Always store the newly-created ticket’s ID in the external_id field of its corresponding target.
• If you would like to group multiple targets into one ticket, then the best thing to do is to set all the related targets external_id to the same Jira ticket ID.

Exporting a Target

Metadata for each new target such as the parent finding and the mobile app the issue relates to can be retrieved under the links section of the API response, and could be added to the ticket in the external bug tracking system, in order to provide a complete picture as to what the target relates to.

1. To retrieve the metadata on the mobile app the target relates to, use the GET /mobile_apps:id entry provided in the links section.
2. To retrieve the metadata (such as the description and the recommendation) on the parent finding of the target, use the GET /security_findings/:security_finding_id entry provided in the links section.
3. A link to the target as displayed in the Data Theorem portal can be retrieved under the portal_url field of the target.
4. After creating the ticket in the external bug tracking system, make sure to set the external_id field of the corresponding target to the newly-created ticket ID. This id can be used for future reference for relating the target to the corresponding ticket, and to also keep track of which targets have already been exported.