When a hacker accesses a decoy API, ASE sends a predefined response (defined in the response_message parameter in the API file) to the client request and collects the request information as a footprint to analyze API ecosystem attacks. ASE acts as a backend for decoy APIs configured in the API gateway.

Decoy API traffic is separately logged in files named with the following format: decoy_pid_<pid_number>__yyyy-dd-mm-<log_file_rotation_time (for example: decoy_pid_8787__2017-04-04_10-57.log). Decoy log files are rotated every 24 hours and stored in the opt/pingidentity/ase/logs directory.

Decoy APIs are independent APIs where every path is a decoy API. Any sub- paths accessed in the API are treated as part of the decoy API. The figure shows an example.

Important:

In sideband ASE deployment, you can only configure out-of-context decoy APIs.

Flow chart of decoy API traffic subverting an attack with ASE as a backend for decoy API requests

The following steps explain the flow of decoy API traffic:

  1. The attacker sends decoy API request
  2. API gateway forwards the request is to the configured decoy API which is ASE functioning as a backend server for the decoy API.
  3. The configured response is sent to the API gateway.
  4. The configured response from ASE is sent back to the attacker.

The decoy request is logged in decoy.log file and sent to PingIntelligence API Behavioral Security (ABS) AI Engine for further analysis. The following is a snippet of an API JSON file which has been deployed as an out-of-context decoy API:


{
 "api_metadata": { 
 "protocol": "http",
 "url": "/account",
 "hostname": "*",
; 
; Note – other configuration parameters removed
;
 "decoy_config":
 {
 "decoy_enabled": true,
 "response_code" : 200,
 "response_def" : "OK",
 "response_message" : "OK", decoy API configuration
 "decoy_subpaths": [
 
 ]
 }

Since the decoy_subpaths parameter is empty, any sub-path accessed by the attacker after /account is regarded as a decoy path or decoy API.

After configuring a decoy API, check the API listings by running the list_api command:


opt/pingidentity/ase/bin/cli.sh list_api -u admin -p
flight ( loaded ), https
trading ( loaded ), https, decoy: out-context