Integrate with service API

Application Security provides service APIs that enable certain management tasks to be automated, for example as part of a CI/CD pipeline.

The provided APIs enable you to do the following:

1. Receive the list of active groups in a given account.
2. Update the settings for the groups' protection types.
3. Update the protection types policies for the given groups.

When using any of the APIs endpoints, there are two considerations that need to be taken into account:

1. Authenticating and authorizing the API calls.
2. The API endpoint versioning.

Authenticate and authorize the API calls

API Keys are managed in your Cloud One Account Management. Learn how to manage your API Keys

API versioning

APIs are expected to evolve over time. When integrating with API endpoints, the version can be specified on a per-endpoint basis. When the version is specified upon content negotiation, the endpoints honour 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 Application Security API does not use the api-version version header.

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 <Your 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 specifies the version associated with the API response.

GET /accounts/groups HTTP/1.1
Authorization: ApiKey <Your 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 in a given region is:

https://application.<region>.cloudone.trendmicro.com

For example, the base URL for connecting to the US region is: https://application.us-1.cloudone.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. See Add a Group for more information.

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 <Your 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 <Your 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 either 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 <Your 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:

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

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:

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

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.\n\nNote:
             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 <Your 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.