Security Finding Targets Endpoints

This endpoint gives access to the list of targets (also called “affected components”) found when scanning the apps.

See the Introduction for an overview of the API and information relevant to all API operations.

In the Data Theorem portal, each target is shown in the “Affected Components” section when looking at a specific finding:

List Security Finding Targets

This endpoint provides a JSON object with a targets and a pagination_information key. The targets key contains a summary of all target information for issues within a DataTheorem’s customer’s apps in addition to its status history while the pagination_information key provides cursor based pagination details for the JSON object response.

In addition to the targets data, the JSON object contains links to other API resources related to the current resource and a link to the issue on the customer facing portal for the linked target.

The JSON object response can be filtered based on the following query parameters:

• status_group - has the following supported values:

  • CLOSED
  • OPEN

For the JSON response, here are all possible values that are returned from the API:

• id - The ID that uniquely identifies the security finding target

• mobile_app_id - The ID of the mobile app within which this security finding target was identified

• security_finding_id - The ID of the security finding to which this security finding target belongs

• issue_type_id - The ID of the security finding target’s type of security issue

• current_status

  • OPEN
    • Found in the most recent scan as well as in the previous one
  • NEW
    • Found in the most recent scan
  • CLOSED_FIXED
    • A previously NEW or OPEN issue is now fixed (we detected a mechanism that mitigates the issue)
  • CLOSED_PARTIALLY_FIXED
    • A previously NEW or OPEN issue is now fixed (Deprecated)
  • CLOSED_WONT_FIX
    • A MANAGER or SECURITY role user (usually on our Portal) marked the issue as Won’t Fix
  • CLOSED_BY_POLICY
    • A MANAGER or SECURITY role user (usually on our Portal) marked the issue as Closed by Policy
  • CLOSED_RISK_ACCEPTED
    • A MANAGER or SECURITY role user (usually on our Portal) marked the issue as Risk Accepted
  • CLOSED_COMPENSATING_CONTROL
    • A MANAGER or SECURITY role user (usually on our Portal) marked the issue as Compensating Control
  • CLOSED_ITEM_NOT_FOUND
    • A previously NEW or OPEN issue is now not present (we did not detect the source of the issue)
  • OPEN_READY_TO_RESCAN
    • An issue is ready for rescan (Deprecated)

• current_status_date - The date the target’s current status was last updated

• statuses - A list of all the statuses that this target has historically held

• text - A string describing the affected component within the app

• links - A list of preformatted paths to other endpoints

• portal_url - A link to view the security finding target within the Data Theorem portal

• results_last_updated - The date when the security results for this app were last updated

• external_id - The ID of this target within an external bug tracker, if an integration has been set up

• external_bug_tracker_url - A link to this target within an external bug tracker, if an integration has been set up

• additional_contexts - A list of markdown texts describing additional information associated with the target. Often used to help track down where within the app an issue is located

• associated_sdk_ids - A list of SDK IDs that Data Theorem has detected are related to this target

Sample Request

1

GET https://api.securetheorem.com/apis/mobile_security/results/v2/security_finding_targets

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

{
  "security_finding_targets": [
    {
      "additional_contexts": [
        {
          "body": "This finding was identified within the following SDK:\nUnity-3D",
          "type": "ASSOCIATED_SDKS"
        },
        {
          "body": "This string is referenced by the `API_KEY` key within the `GoogleService-Info.plist` file for use in the Firebase SDK.",
          "type": "CUSTOM_FORMAT"
        }
      ],
      "associated_sdk_ids": [
        "860b2a23-ad2c-573c-b764-9abe6ebef0ca"
      ],
      "current_status": "OPEN",
      "current_status_date": "2021-08-17T13:45:25.305632+00:00",
      "date_created": "2016-11-02T19:25:16.664990-00:00",
      "external_id": "JIRA-12345",
      "id": "4651453173202944",
      "issue_type_id": "220e280c-1711-5590-9326-d505fbf0f511",
      "links": [
        {
          "href": "mobile_apps/643010001",
          "rel": "mobile_apps",
          "type": "GET"
        },
        {
          "href": "security_findings?mobile_app_id=643010001",
          "rel": "security_findings",
          "type": "GET"
        },
        {
          "href": "security_finding_targets?mobile_app_id=643010001",
          "rel": "self",
          "type": "GET"
        }
      ],
      "mobile_app_id": "643010001",
      "portal_url": "https://www.securetheorem.com/mobile/app/643010001/issues/053069/targets/4651453173202944",
      "results_last_updated": "2021-08-17T13:45:25.266423+00:00",
      "security_finding_id": "053069",
      "statuses": [
        {
          "date": "2021-08-17T13:45:25.305632+00:00",
          "status": "OPEN"
        },
        {
          "date": "2021-08-17T13:45:25.266423+00:00",
          "status": "OPEN"
        },
        {
          "date": "2021-08-17T13:43:03.963011+00:00",
          "status": "CLOSED_COMPENSATING_CONTROL"
        },
        {
          "build_version": "1.0.0",
          "date": "2020-10-29T23:19:55.819730+00:00",
          "status": "NEW"
        }
      ],
      "text": "`com.unity3d.player.UnityPlayer`"
    }
  ],
  "pagination_information": {
    "total_count": "1",
    "next_cursor": "kEgkIjrCzvdns0QISRmoRc35kaXNjby1vcmRlci03"
  }
}

Get Security Finding Targets

This endpoint provides a JSON object which contains a summary of a specific target for an issue within a DataTheorem’s customer’s app specified by a security_finding_target_id.

Sample Request

1

GET https://api.securetheorem.com/apis/mobile_security/results/v2/security_finding_targets/:security_finding_target_id

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

{
  "id": "12345",
  "portal_url": "https://securetheorem.com/app/4567/issues/8901",
  "mobile_app_id": "4567",
  "external_id": "JIRA-12345",
  "security_finding_id": "8901",
  "current_status": "CLOSED_FIXED",
  "current_status_date": "2016-11-02T19:25:16.664990-00:00",
  "date_created": "2016-11-02T19:25:16.664990-00:00",
  "text": "`https://username:password@www.datatheorem.com`",
  "statuses": [
    {
      "status": "CLOSED_RISK_ACCEPTED",
      "date": "2016-11-02T19:25:16.664990-00:00"
    },
    {
      "status": "OPEN",
      "date": "2017-13-02T19:25:16.664998-00:00"
    }
  ],
  "links": [
    {
      "href": "mobile_apps/4567",
      "rel": "mobile_app",
      "type": "GET"
    },
    {
      "href": "security_findings/8901",
      "rel": "security_finding",
      "type": "GET"
    },
    {
      "href": "security_finding_targets/12345",
      "rel": "self",
      "type": "GET"
    }
  ]
}

Patch Security Finding Target

This endpoint provides the ability to update an optional external_id field on a target. The external_id field should represent the id provided by an external bug tracking system such as Jira for tracking the issue. The endpoint does not provide the ability to edit any other fields on a target.

Sample Request

1

PATCH https://api.securetheorem.com/apis/mobile_security/results/v2/security_finding_targets/:security_finding_target_id

Sample Request Body

1

{"external_id": "JIRA-12345"}

Sample Response

The response is similar to a GET request for a Security Finding Target with the optional updated external_id field included in the response.

Update Status on Security Finding Target

This endpoint overrides the current status of an existing target. The endpoint is meant to be used by API clients to close or re-open certain targets. Upon success a 204 status code is returned with an empty response body.

The endpoint can be used in two ways:

• open targets can be closed with status "CLOSED_WONT_FIX", "CLOSED_RISK_ACCEPTED" or "CLOSED_COMPENSATING_CONTROL"
• manually closed targets can be re-opened by passing "OPEN"

If the new status is equal to the current status, the request will fail with a 409 status code.

If a reason is provided within the request payload, it will be posted as an internal note on the corresponding finding.

Expected request body format

The endpoint expects a JSON object to be passed in the request body.

Sample Request

1

POST https://api.securetheorem.com/apis/mobile_security/results/v2/security_finding_targets/:security_finding_target_id/statuses

JSON body:

1
2
3
4

{
  "status": "CLOSED_RISK_ACCEPTED",
  "reason": "Cannot be exploited"
}

Sample Response

1

HTTP/2 204 No Content

Empty body.