Cloud One – Application Security

Cloud One – Application Security provides detection and protection for modern applications and APIs built on your container, serverless, and other computing platforms The API reference docs provide information on using the Application Security API. This guide describes how to integrate Application Security with the service API.

About Application Security

Application Security provides real-time application security as a service. When Application Security is properly deployed, threats to your web applications will be detected and protected against, minimizing your risk.
Determined attackers are continuously running scanners against your site, creating malicious user accounts, fuzzing various elements, triggering exceptions, and attempting to run exploitation tools. Attackers do this in order to:

  • take over customer or administrative accounts.
  • execute code on your server.
  • steal sensitive data stored on your servers.

By embedding Application Security in your web applications, you will receive alerts as soon as attackers begin conducting scans and attacks. You can address each event manually, or you can configure Application Security to react automatically to these attackers, stopping them in their tracks before any damage is done.​

Integrate with the service API

Authenticate and authorize the API calls

Account administrators are the only users that can create an API key through the dashboard.

API calls must be authenticated by using an API key associated with your account. By specifying the API key, the API can grant access to resources associated with the groups in that account.

Obtaining an API key

An API key can be obtained through the Application Security dashboard.
To create an API key:

  1. On the Application Security dashboard, click your username in the top-right corner and go to Account Settings.
  2. Select API key and then Generate API Key.

Use the API key with API calls

Any API calls issued against Application Security are required to be authenticated and authorized. Therefore, all API calls need to include:

  • the Authorization header.
  • the type “ApiKey”.
  • the API key generated for the account.
GET /accounts/groups HTTP/1.1
Authorization: ApiKey <Your API Key>
...

If the API key is valid, the resources are granted access. If not, a 403 code is returned back.

API versioning

APIs are expected to evolve over time. When you integrate with API endpoints, the version can be specified on a per-endpoint basis. When the version is specified upon content negotiation, the endpoints honor the version specified, if it’s a valid and supported version. If the version is not specified, the endpoint processes the request using the latest version.
The version is specified with the Accept header and the version of your choice:
application/json; version=<version>
For example:
application/json; version=1

GET /accounts/groups HTTP/1.1
Authorization: ApiKey <API Key>
Accept: application/json; version=2
...

In the case where the version is not specified in the accept header, the latest API version is assumed. in the response, the Content-Type specify the version associated with the API response.

GET /accounts/groups HTTP/1.1
Authorization: ApiKey <API Key>
Accept: application/json
...
-----------------------------------
HTTP/2 200
Content-Type: application/json; version=2

Use Application Security APIs

Base URL

The base URL for connecting and using the Application Security API is:
https://api.app-protect.trendmicro.com
All endpoint calls are done using this base URL.

Groups list

All groups are created and initially set from the Application Security dashboard.
Once the groups are created, the following endpoint can be used to obtain the list of active groups in the account:

GET /accounts/groups HTTP/1.1
Authorization: ApiKey <api_key>
Accept: application/json
------------------------------------------------------
200 Ok
Content-Type: application/json; version=2
[
    {
        "account_id": "576dcc26-0c47-4d00-8b7d-a4a261d6afa5",
        "activated_on": "2019-04-10T17:38:26.880743+00:00",
        "group_id": "c24af1c0-bb76-40be-9e15-264e77d43739",
        "name": "group 1 name",
        "status": "active"
    },
    {
        "account_id": "576dcc26-0c47-4d00-8b7d-a4a261d6afa5",
        "activated_on": "2019-09-24T16:17:40.608811+00:00",
        "group_id": "e72e24da-db1c-447f-af63-01c1da2533d0",
        "name": "group 2 name",
        "status": "active"
    },
]

Get and update the protection settings

The protection settings control which protection types are enabled for a given group and whether detected policy violations are mitigated or only reported.

To get policy settings:

GET /accounts/groups/<group id:uuid>/settings HTTP/1.1
Authorization: ApiKey <api key>
Accept: application/json
<----------------------------------------------------->
200 Ok
Content-Type: application/json; version=2
{
    "rce": "report",
    "file_access": "disable",
    "malicious_payload": "mitigate",
    "malicious_file_upload": "report",
    "redirect": "report",
    "sqli": "report"
}

The protection settings for any protection type can be disable, report or mitigate. If the group with the specified ID doesn’t exist, the API call returns “404 Not Found”.
The protection settings can be updated, for example:

PUT /accounts/groups/<group id:uuid>/settings
Authorization: ApiKey <api key>
Content-Type: application/json; version=2
Content-Length: <length>
{
    "rce": "report",
    "file_access": "report",
    "malicious_file_upload": "mitigate",
    "malicious_payload": "report",
    "redirect": "report",
    "sqli": "report"
}
<----------------------------------------------->
204 No Content

If the group with the specified ID cannot be found, the API call returns “404 Not Found”.

Get and update protection policies

For each protection type, the protection policy includes:

  • the security algorithms to apply.
  • the security algorithms statuses.
  • the rules associated with the security algorithms, where applicable.

The security algorithms are specific to each protection type. The following table lists the allowed algorithm names:

Protection policyProtection policy syntaxSecurity Algorithms
SQL Injection“sqli”“always_false”
“always_true”
“bad_function”
“http_params”
“stacking_queries”
“syntax_error”
“trailing_comment”
“union_set”
Malicious Payload“malicious_payload”“malicious_pattern_match”
Illegal File Access“file_access”“read_control”
“write_control”
Open Redirect“redirect”“redirect_control”
Remote Command Execution“rce”“exec_control”
“http_params”
Malicious File Upload“malicious_file_upload”“av_scanning”
“size_check”

The security algorithm statuses can take one of the following values:

StatusDescription
“enabled”The security algorithm is active and is applied.
“disabled”The security algorithm is inactive and is not applied.

The rules and the rules syntax, associated with the security algorithms are specific to each protection type. The following table describes the format for each protection type:

Protection policyProtection policy syntaxProtection policy syntaxNotes
SQL Injection“sqli”Not applicable, the algorithms don’t require rules.
Malicious Payload“malicious_payload”“patterns”: [
{“cves”: [“CVE-ID”],
“cvss_score”: “5.0”,
“description”: ,
“id”: ,
“name”: ,
“status”: “enabled”
},
{ “cves”: [“CVE-ID”],
“cvss_score”: “10.0”,
“description”: ,
“id”: ,
“name”: ,
“status”: “enabled”
},
….
]
The rules are designed and curated by Trend Micro. The rules, the IDs as well as the description provided by the policy endpoints need to be a subset of the supported rules. Attempting to update a rule with an ID that doesn’t exist will fail, likewise, only the status attribute of a rule can be updated to one of the “enabled” or “disabled” values. Attempting to update other attributes such as name won’t have any effect.
File Access“file_access”“rules”: [
{“action”: “allow”,
“glob”: “.[eE][rR][bB]” }, {“action”: “allow”, “glob”: “.[hH][aA][mM][lL]”
},
{“action”: “allow”,
“glob”: “*.[pP][hH][pP]”
},

]
The action can be one of the two “allow” or “block” values.
The value for the “glob” attributes need to be PCRE compliant expression.
Open Redirect“redirect”“rules”: [
{“action”: “block”,
“glob”: “*”
},

]
The action can be one of the two “allow” or “block” values.
The value for the “glob” attributes need to be PCRE compliant expression.
Remote Command Execution“rce”“rules”: [
{“action”: “block”,
“command”: “.*”
}
]
The action can be one of the two “allow” or “block” values.
The value for the “command” attribute is glob format.
Malicious File Upload“malicious_file_upload”for algorithm:
“av_scanning”:
“buffered_scanning_max_bytes”:
“size_check”: “max_bytes”:

For all of the protection policies other than Malicious Payload , the payload syntaxes for getting and updating the policies are symmetrical. When updating the Malicious Payload policy, only the id and status in the patterns are used, because the id is needed to identify the rule and only the “status” can be updated. The other attributes, such as name or CVEs, are ignored.

The general syntax for all protection types policies is described as follows:

{
  <algorithm 1 name>: {
     "configuration": {
        <algorithm rules syntax>
     },
     "status": "enabled" or "disabled"
  },
  <algorithm 2 name>: {
     "configuration": {
        <algorithm rules syntax>
     },
     "status": "enabled" or "disabled"
  }
}

For example, for the SQL Injection policy:

{
    "always_false": {
        "configuration": {},
        "status": "enabled"
    },
    "always_true": {
        "configuration": {},
        "status": "enabled"
    },
    "bad_function": {
        "configuration": {},
        "status": "enabled"
    },
    "http_params": {
        "configuration": {},
        "status": "enabled"
    },
    "stacking_queries": {
        "configuration": {},
        "status": "enabled"
    },
    "syntax_error": {
        "configuration": {},
        "status": "disabled"
    },
    "trailing_comment": {
        "configuration": {},
        "status": "enabled"
    },
    "union_set": {
        "configuration": {},
        "status": "enabled"
    }
}

A payload for the Illegal File Access policy:

{
    "read_control": {
        "configuration": {
            "rules": [
                {
                    "action": "allow",
                    "glob": "*.[jJ][pP][gG]"
                },
                {
                    "action": "allow",
                    "glob": "/etc/mime.types"
                },
                {
                    "action": "block",
                    "glob": "/etc/*"
                },
            ]
        },
        "status": "enabled"
    },
    "write_control": {
        "configuration": {
            "rules": [
                {
                    "action": "block",
                    "glob": "/etc/*"
                },
                {
                    "action": "block",
                    "glob": "/proc/*"
                },
                {
                    "action": "allow",
                    "glob": "*"
                }
            ]
        },
        "status": "enabled"
    }
}

As mentioned above, for the Malicious Payload policy the policy syntax when getting the policy includes all attributes whereas when updating the policy, only the id and status are included. For example:

Getting policy
---------------
{
  "malicious_pattern_match": {
     "configuration": {
        "patterns": [
           {
             "cves": ["CVE-2007-1560"],
             "cvss_score": "5.0",
             "description": "The vulnerability is caused due to an error within the processing of TRACE requests in squid/src/client_side.c. This can be exploited to crash the service via a specially crafted TRACE request.",
             "id": 1000978,
             "name": "Squid Proxy TRACE Request DoS",
             "status": "enabled"
           },
           {
             "cves": ["CVE-2002-1654"],
             "cvss_score": "7.5",
             "description": "This rule blocks brute force attempt to web application by inspecting the number of error responses in a given time period. The IP address is blocked for 20 minutes after the brute force attempt is detected. Note: Configuration option should be used to enter custom error response.",
             "id": 1005208,
             "name": "Web Application Possible Brute Force Attempt (ATT&CK T1110)",
             "status": "enabled"
           }
         ]
     },
     "status": "enabled"
  }
}
Updating policy
----------------
{
  "malicious_pattern_match": {
     "configuration": {
        "patterns": [
           {
             "id": 1000978,
             "status": "enabled"
           },
           {
             "id": 1005208,
             "status": "disabled"
           }
         ]
     },
     "status": "enabled"
  }
}

Get the policies for a specific protection type and a given group:

GET /security/<protection type>/<group id:uuid>/policy HTTP/1.1
Authorization: ApiKey <api_key>
Accept: application/json
<---------------------------------------------->
200 Ok
Content-Type: application/json; version=2
{
  <algorithm 1 name>: {
     "configuration": {
        <algorithm rules syntax>
     },
     "status": "enabled" or "disabled"
  },
  <algorithm 2 name>: {
     "configuration": {
        <algorithm rules syntax>
     },
     "status": "enabled" or "disabled"
  }
}

The GET API call returns 200 OK with the payload content depending on the protection type. A 404 code is returned if the group_id doesn’t exist.

Update policies for protection types:

PUT /security/<protection type>/<group id:uuid>/policy HTTP/1.1
Content-Type: application/json; version=2
Content-Length: <length>
Authorization: ApiKey <api key>
{
  <algorithm 1 name>: {
     "configuration": {
        <algorithm rules syntax>
     },
     "status": "enabled" or "disabled"
  },
  <algorithm 2 name>: {
     "configuration": {
        <algorithm rules syntax>
     },
     "status": "enabled" or "disabled"
  }
}
<------------------------------------------>
204 No Content

The payload’s actual structure when updating the policies is dependent on the protection type. The endpoint call returns a 404 if the group_id doesn’t exist.