Security Findings Endpoints

This endpoint gives access to the list of security findings found when scanning the mobile apps.

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

Security Findings Overview

There are two types of security findings in the Data Theorem portal:

  • App Issues - these are findings that represent security issues that were found while scanning the mobile apps.
  • App Protection Issues - these are findings that represent possible proactive security measures that were found while scanning the mobile apps.

The findings can be found in the following sections in the portal:

App Issue vs App Protection

App Issues findings are shown as a single card when looking at an app’s issues:

App Issue Security Finding

App Protection findings are similarly shown as a single card when looking at an app’s protection tasks:

App Protection Finding

Findings have importance tags that are used internally by our service to characterize security findings. We expose these importance tags through the Mobile Security Results API because they can provide valuable insights to end-users. For example:

  • Platform-specific store blockers can be identified with the GOOGLE_P1 and APPLE_P1 tags.
  • The presence of both the DEFENSE_IN_DEPTH and SERVER_SIDE tags can be used to identify server-side App Protection issues.

Note: new kinds of importance tags may be added at any time. Integrations that use the Results API should be able to handle newly released tags.

We also return CVSS 3.1 scores and vectors as part of the response in the cvss_score and cvss_vector fields.

Values of Security Finding fields

Certain security finding fields take on predefined values:

  • status_group

    • CLOSED
    • OPEN

  • priority

    • P0
    • P1
    • P2
    • P3
    • P4

  • severity

    • HIGH
    • MEDIUM
    • LOW

  • category

    • DATA_AT_REST_EXPOSURE
    • DATA_IN_TRANSIT_EXPOSURE
    • DATA_LOSS_TO_HACKERS
    • DATA_EXPOSURE_TO_THIRD_PARTY_APPS
    • UNAUTHORIZED_DATA_COLLECTION

  • exploitability

    • DIFFICULT
    • MODERATE
    • EASY

  • compliance_policy

    • GDPR
    • PCI
    • HIPAA
    • FTC
    • OWASP
    • CALOPPA
    • COPPA
    • VPPA
    • CCPA

Non-exhaustive list of importance_tags values, subject to revision:

  • APP_STORE_PRIVACY: Issues relevant to the App Store Answers toolkit
  • APPLE_P1: Apple App Store blockers
  • COFFEE_SHOP_COMPROMISE: Issues relevant to the Coffee Shop Compromise toolkit
  • CUSTOMER_POLICY: Configurable issues. Eg, Presence of SDKs that are on an SDK deny-list.
  • DATA_LEAKS: Issues that represent “data leaks” in the app
  • DEFENSE_IN_DEPTH: App Protection issues. Represents an available defense-in-depth protection or mitigation that has not been implemented
  • GOOGLE_P1: Google Play Store blockers
  • KEYS_TO_THE_KINGOM: Issues relevant to the Keys to the Kingdom toolkit
  • PRIVACY: Issues related to user privacy
  • SECURITY: Security issues
  • SECURITY_P1: Automatically categorized by Data Theorem as a Security P1 (user can override by changing the issue’s priority)
  • SERVER_SIDE: Issues about services used by the app

List Security Findings

This endpoint provides a JSON object with a security_findings and a pagination_information keys. The security_findings key contains a summary of all issues within a Data Theorem’s customer’s apps while the pagination_information key provides cursor based pagination details for the JSON object response.

In addition to the issues 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.

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

field type description
cursor string pagination cursor as provided by the previous page
mobile_app_id integer select issues with for the given mobile app ID
results_since string select issues with changes no less recent than the provided date, expects ISO 8601 date format
status_group string select issues with the given status group, accepts values listed above
issue_type_id UUID select issues with the given issue type ID

These fields may be included in the JSON response depending on the security finding:

field type description
associated_cve_ids list of strings A list of CVEs which are related to the security finding
associated_cwe_ids list of strings A list of CWEs which are related to the security finding

Sample Request

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

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
71
72
73
74
75
76
77
78
{
  "security_findings": [
    {
      "id": "4567",
      "category": "DATA_IN_TRANSIT_EXPOSURE",
      "date_created": "2016-11-02T19:25:16.664990-00:00",
      "description_intro": "An optional summary of the description",
      "description": "This is how it breaks",
      "exploitability": "DIFFICULT",
      "mobile_app_id": "1234",
      "priority": "P1",
      "recommendation": "Fix it asap",
      "results_last_updated": "2016-11-02T19:25:16.664990-00:00",
      "secure_code": "```if else then```",
      "severity": "MEDIUM",
      "aggregated_status": "NEW",
      "title": "Lack of Verification of Up-to-date Android Security...",
      "portal_url": "https://securetheorem.com/app/1234/issues/4567",
      "cvss_score": 5,
      "cvss_vector": "AV:N/AC:L/PR:L/UI:N/S:U/C:L/I:N/A:N",
      "screenshot_url": "https://some-screenshot-url.com",
      "importance_tags": [
        "SECURITY"
      ],
      "associated_cve_ids": [
        "CVE-2000-1909"
      ],
      "compliance_policy_references": [
        {
          "compliance_policy": "GDPR",
          "link": "https://www.owasp.org/index.php/Mobile_Top_10_2016-M3-Insecure_Communication",
          "markdown": "M3 - Insecure Communication"
        }
      ],
      "notes": [
        {
          "author_email": "Data Theorem",
          "date_created": "2016-11-02T19:25:16.664990-00:00",
          "id": "77777",
          "is_internal_comment": false,
          "is_question_for_datatheorem": false,
          "is_reply_from_datatheorem": true,
          "text": "This is a note by a DT admin."
        },
        {
          "author_email": "some@example.com",
          "date_created": "2016-11-02T19:25:16.664990-00:00",
          "id": "77777",
          "is_internal_comment": false,
          "is_question_for_datatheorem": true,
          "is_reply_from_datatheorem": false,
          "text": "I have a question about this finding. Can you help me with it?"
        }
      ],
      "links": [
        {
          "href": "security_findings/4567",
          "rel": "self",
          "type": "GET"
        },
        {
          "href": "security_finding_targets?security_finding_id=123",
          "rel": "targets",
          "type": "GET"
        },
        {
          "href": "mobile_apps/1234",
          "rel": "mobile_app",
          "type": "GET"
        }
      ]
    }
  ],
  "pagination_information": {
    "total_count": "1",
    "next_cursor": "kEgkIjrCzvdns0QISRmoRc35kaXNjby1vcmRlci03"
  }
}

Get Security Finding

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

Preconditions:

  • The API key must have access to the security finding

Sample Request

1
GET https://api.securetheorem.com/apis/mobile_security/results/v2/security_findings/:security_finding_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
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
71
{
  "id": "4567",
  "category": "DATA_IN_TRANSIT_EXPOSURE",
  "date_created": "2016-11-02T19:25:16.664990-00:00",
  "description_intro": "An optional summary of the description",
  "description": "This is how it breaks",
  "exploitability": "DIFFICULT",
  "mobile_app_id": "1234",
  "priority": "P1",
  "recommendation": "Fix it asap",
  "results_last_updated": "2016-11-02T19:25:16.664990-00:00",
  "secure_code": "```if else then```",
  "severity": "MEDIUM",
  "aggregated_status": "NEW",
  "title": "Lack of Verification of Up-to-date Android Security...",
  "portal_url": "https://securetheorem.com/app/1234/issues/4567",
  "cvss_score": 5,
  "cvss_vector": "AV:N/AC:L/PR:L/UI:N/S:U/C:L/I:N/A:N",
  "screenshot_url": "https://some-screenshot-url.com",
  "importance_tags": [
    "SECURITY"
  ],
  "associated_cwe_ids": [
    "CWE-099",
    "CWE-123"
  ],
  "compliance_policy_references": [
    {
      "compliance_policy": "GDPR",
      "link": "https://www.owasp.org/index.php/Mobile_Top_10_2016-M3-Insecure_Communication",
      "markdown": "M3 - Insecure Communication"
    }
  ],
  "notes": [
    {
      "author_email": "Data Theorem",
      "date_created": "2016-11-02T19:25:16.664990-00:00",
      "id": "77777",
      "is_internal_comment": false,
      "is_question_for_datatheorem": false,
      "is_reply_from_datatheorem": true,
      "text": "This is a note by a DT admin."
    },
    {
      "author_email": "some@example.com",
      "date_created": "2016-11-02T19:25:16.664990-00:00",
      "id": "77777",
      "is_internal_comment": false,
      "is_question_for_datatheorem": true,
      "is_reply_from_datatheorem": false,
      "text": "I have a question about this finding. Can you help me with it?"
    }
  ],
  "links": [
    {
      "href": "security_findings/4567",
      "rel": "self",
      "type": "GET"
    },
    {
      "href": "security_finding_targets?security_finding_id=123",
      "rel": "targets",
      "type": "GET"
    },
    {
      "href": "mobile_apps/1234",
      "rel": "mobile_app",
      "type": "GET"
    }
  ]
}

Patch Security Finding

This endpoint updates a security finding and provides a JSON object which contains a summary of the updated issue within the DataTheorem’s customer’s app specified by security_finding_id.

Preconditions:

  • The API key must have the permission to set issues priority when it modifies priority.

The request may update the following fields:

  • priority: The issue priority.

Sample Request

1
2
3
4
PATCH https://api.securetheorem.com/apis/mobile_security/results/v2/security_findings/:security_finding_id
{
    "priority": "P2"
}

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
71
{
  "id": "4567",
  "category": "DATA_IN_TRANSIT_EXPOSURE",
  "date_created": "2016-11-02T19:25:16.664990-00:00",
  "description_intro": "An optional summary of the description",
  "description": "This is how it breaks",
  "exploitability": "DIFFICULT",
  "mobile_app_id": "1234",
  "priority": "P2",
  "recommendation": "Fix it asap",
  "results_last_updated": "2016-11-02T19:25:16.664990-00:00",
  "secure_code": "```if else then```",
  "severity": "MEDIUM",
  "aggregated_status": "NEW",
  "title": "Lack of Verification of Up-to-date Android Security...",
  "portal_url": "https://securetheorem.com/app/1234/issues/4567",
  "cvss_score": 5,
  "cvss_vector": "AV:N/AC:L/PR:L/UI:N/S:U/C:L/I:N/A:N",
  "screenshot_url": "https://some-screenshot-url.com",
  "importance_tags": [
    "SECURITY"
  ],
  "associated_cwe_ids": [
    "CWE-099",
    "CWE-123"
  ],
  "compliance_policy_references": [
    {
      "compliance_policy": "GDPR",
      "link": "https://www.owasp.org/index.php/Mobile_Top_10_2016-M3-Insecure_Communication",
      "markdown": "M3 - Insecure Communication"
    }
  ],
  "notes": [
    {
      "author_email": "Data Theorem",
      "date_created": "2016-11-02T19:25:16.664990-00:00",
      "id": "77777",
      "is_internal_comment": false,
      "is_question_for_datatheorem": false,
      "is_reply_from_datatheorem": true,
      "text": "This is a note by a DT admin."
    },
    {
      "author_email": "some@example.com",
      "date_created": "2016-11-02T19:25:16.664990-00:00",
      "id": "77777",
      "is_internal_comment": false,
      "is_question_for_datatheorem": true,
      "is_reply_from_datatheorem": false,
      "text": "I have a question about this finding. Can you help me with it?"
    }
  ],
  "links": [
    {
      "href": "security_findings/4567",
      "rel": "self",
      "type": "GET"
    },
    {
      "href": "security_finding_targets?security_finding_id=123",
      "rel": "targets",
      "type": "GET"
    },
    {
      "href": "mobile_apps/1234",
      "rel": "mobile_app",
      "type": "GET"
    }
  ]
}

Close Security Finding

This endpoint provides a means of closing a security finding specified by security_finding_id. The given text description of the reason will be posted in a closing comment. When a security finding is closed using this API operation, all open targets in that finding will be closed and the finding’s aggregated_status field will be updated with the most appropriate CLOSED_* status value. To prevent any future scans from opening new targets, you can “permanently close” the finding by specifying "is_permanently_closed": true in the request body. Otherwise, if the issue occurs somewhere else in a new build/release of the app, a new target may be opened.

Returns a 200 status code upon success with the updated security finding in the request body.

Preconditions:

  • The API key must have access to the security finding
  • The API key must have the results_api.can_close_issues permission
  • The security finding must be open

Expected request body format

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

Field Required Type Description
aggregated_status ✔️ string Status to set on the security finding, one of "CLOSED_WONT_FIX", "CLOSED_RISK_ACCEPTED", "CLOSED_COMPENSATING_CONTROL"
is_permanently_closed boolean Whether the security should be closed permanently, defaults to false
reason ✔️ string Arbitrary text, will appear in the closing comment

Sample Request

1
2
3
4
5
6
POST https://api.securetheorem.com/apis/mobile_security/results/v2/security_findings/:security_finding_id/close
{
    "aggregated_status": "CLOSED_RISK_ACCEPTED",
    "is_permanently_closed": true,
    "reason": "Test"
}

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
71
72
73
74
75
76
77
78
79
80
81
{
  "id": "4567",
  "category": "DATA_IN_TRANSIT_EXPOSURE",
  "date_created": "2016-11-02T19:25:16.664990-00:00",
  "description_intro": "An optional summary of the description",
  "description": "This is how it breaks",
  "exploitability": "DIFFICULT",
  "mobile_app_id": "1234",
  "priority": "P1",
  "recommendation": "Fix it asap",
  "results_last_updated": "2016-11-02T19:25:16.664990-00:00",
  "secure_code": "```if else then```",
  "severity": "MEDIUM",
  "aggregated_status": "CLOSED_RISK_ACCEPTED",
  "is_permanently_closed": true,
  "title": "Lack of Verification of Up-to-date Android Security...",
  "portal_url": "https://securetheorem.com/app/1234/issues/4567",
  "cvss_score": 5,
  "cvss_vector": "AV:N/AC:L/PR:L/UI:N/S:U/C:L/I:N/A:N",
  "screenshot_url": "https://some-screenshot-url.com",
  "importance_tags": [
    "SECURITY"
  ],
  "associated_cwe_ids": [
    "CWE-099",
    "CWE-123"
  ],
  "compliance_policy_references": [
    {
      "compliance_policy": "GDPR",
      "link": "https://www.owasp.org/index.php/Mobile_Top_10_2016-M3-Insecure_Communication",
      "markdown": "M3 - Insecure Communication"
    }
  ],
  "notes": [
    {
      "author_email": "Data Theorem",
      "date_created": "2016-11-02T19:25:16.664990-00:00",
      "id": "77777",
      "is_internal_comment": false,
      "is_question_for_datatheorem": false,
      "is_reply_from_datatheorem": true,
      "text": "This is a note by a DT admin."
    },
    {
      "author_email": "some@example.com",
      "date_created": "2016-11-02T19:25:16.664990-00:00",
      "id": "88888",
      "is_internal_comment": false,
      "is_question_for_datatheorem": true,
      "is_reply_from_datatheorem": false,
      "text": "I have a question about this finding. Can you help me with it?"
    },
    {
      "author_email": "Test API key creation with new permissions",
      "date_created": "2021-03-12T03:07:51.807386+00:00",
      "id": "99999",
      "is_internal_comment": false,
      "is_question_for_datatheorem": false,
      "is_reply_from_datatheorem": true,
      "text": "Issue permanently closed using the following explanation: Test"
    }
  ],
  "links": [
    {
      "href": "security_findings/4567",
      "rel": "self",
      "type": "GET"
    },
    {
      "href": "security_finding_targets?security_finding_id=123",
      "rel": "targets",
      "type": "GET"
    },
    {
      "href": "mobile_apps/1234",
      "rel": "mobile_app",
      "type": "GET"
    }
  ]
}

Post Comment on Security Finding

This API operation can create a new comment on an existing security finding. The new comment will be from the API Key itself (the author_email field is set to the API Key’s “name” rather than to an email address), and by default the comment is considered to be an “internal comment” or internal note. If a comment is intended as a question for Data Theorem support, set is_question_for_datatheorem to true in the request body.

Upon success a 204 status code is returned with an empty response body.

Preconditions:

  • The API key must have access to the security finding
  • The API key must have the results_api.can_comment_on_issues permission

Expected request body format

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

Field Required Type Description
text ✔️ string Arbitrary text, the contents of the comment
is_question_for_datatheorem bool Set this to true if the comment is a question directed at Data Theorem support. If omitted, defaults to false, meaning that the comment is an internal comment.

Sample Request

1
POST https://api.securetheorem.com/apis/mobile_security/results/v2/security_findings/:security_finding_id/notes

JSON body:

1
2
3
4
{
  "text": "Lorem ipsum dolor sit amet.",
  "is_question_for_datatheorem": false
}

Sample Response

{
  "author_email": "some@example.com",
  "date_created": "2016-11-02T19:25:16.664990-00:00",
  "id": "1234",
  "is_internal_comment": "true",
  "is_question_for_datatheorem": "false",
  "is_reply_from_datatheorem": "false",
  "text": "Lorem ipsum dolor sit amet."
}