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

Each SecurityFinding may contain the following fields in its JSON response. If a given field’s value is null (if it is optional), it might be omitted from the response.

Field Type Description
id string This finding’s unique ID
aggregated_status string The combined/aggregated status of all the finding’s targets/affected components. Possible values are:
  • NEW
  • OPEN
  • CLOSED_WONT_FIX
  • CLOSED_BY_POLICY
  • CLOSED_RISK_ACCEPTED
  • CLOSED_COMPENSATING_CONTROL
  • CLOSED_FIXED
  • CLOSED_ITEM_NOT_FOUND
associated_cve_ids list(string) A list of CVEs related to the security finding
associated_cwe_ids list(string) A list of CWEs related to the security finding
category string Possible values:
  • DATA_AT_REST_EXPOSURE
  • DATA_IN_TRANSIT_EXPOSURE
  • DATA_LOSS_TO_HACKERS
  • DATA_EXPOSURE_TO_THIRD_PARTY_APPS
  • UNAUTHORIZED_DATA_COLLECTION
compliance_policy_references list(CompliancePolicyReference) See the subsequent explanation of each entry’s shape
cvss_score float A numerical cvss score for the issue
cvss_Vecotr string A CVSS vector for the issue
date_created string(datetime) The date this finding was first created/opened
description_intro optional(string) Markdown-encoded optional introductory text normally presented before the list of affected components (targets)
description string Markdown-encoded description of the issue
exploitability string Possible values:
  • DIFFICULT
  • MODERATE
  • EASY
importance_tags list(string) Non-exhaustive list of possible values. Data Theorem may add more values without notification:
  • 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_KINGDOM: 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
issue_type_id string(uuid) The UUID of the issue type, which uniquely identifies a particular issue across all apps.
is_permanently_closed bool Whether the finding has been marked permanently closed
links list(ResourceLink) References to related resources within the Results API
mobile_app_id string(int64) The ID of the mobile app that this finding belongs to
notes list(Note) A list of comments on this finding
portal_url string A link to the finding in the customer portal
priority optional(string(enum)) Possible values if present:
  • P0
  • P1
  • P2
  • P3
  • P4
recommendation string Markdown-encoded explanation of how to fix this issue
results_last_updated optional(string(datetime)) When this finding, or one of its targets, was last updated, indicating something may have changed
screenshot_url optional(string) A URL linking to an image representing or demonstrating the issue
secure_code optional(string) Markdown-encoded code example for this issue
severity string Possible values:
  • HIGH
  • MEDIUM
  • LOW
title string Markdown-encoded title for this issue

Each CompliancePolicyReference entry under compliance_policy_references has the following shape:

Field Type Description
compliance_policy string Possible values (More may be added without notice):
  • GDPR
  • PCI
  • HIPAA
  • FTC
  • OWASP
  • CALOPPA
  • COPPA
  • VPPA
  • CCPA
markdown string Markdown encoded citation for the reference
link string a URL to the compliance policy, and possibly the specific reference, if plausible

Each ResourceLink entry under links has the following shape:

Field Type Description
href string(int64) The path, under the base URL of the API, where this link resides. E.G., mobile_apps/1234
type string The HTTP method for this relationship. E.G., GET.
rel string A brief name/description of the related resource.

Each Note (comment) under notes has the following shape:

Field Type Description
author_email string The email address of the comment’s author.
date_created string(datetime) The date this comment was posted.
id string(int64) Unique identifier for this comment.
is_internal_comment bool Whether this is an internal comment, and not a question for Data Theorem.
is_question_for_datatheorem bool Whether this is a question from Data Theorem.
is_reply_from_datatheorem bool Whether this is a reply from Data Theorem, in response to a question for Data Theorem.
text string The body text of this comment.

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 Limit the returned issues to those found in the mobile app with this ID
results_since string(datetime) Limit the returned issues to those whose data may have changed since the specified date/time
status_group string Limit the returned issues whose aggregated status means that it is still OPEN issues (NEW or OPEN), or limit the results to CLOSED issues (Any CLOSED_* status)

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:

Field Required Type Description
priority string(enum) Set the issue’s priority to the specified value. If omitted or null, then the priority will not be modified. Can be any of:
  • P0
  • P1
  • P2
  • P3
  • P4

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."
}