A decoy API is configured in ASE and the API gateway. It requires no changes to backend servers. It appears as part of the API ecosystem and is used to detect the attack patterns of hackers. When a hacker accesses a decoy API, ASE sends a predefined response (defined in the response_messageparameter in API JSON 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.

Note: In sideband ASE deployment you can configure only out-of-context decoy API.

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 ABS for further analysis. 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_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

Real-time API deception attack blocking

When a client probes a decoy API, ASE logs but does not drop the client connection. However, if the same client tries to access a legitimate business API, then ASE block the client in real-time. Here is a snippet of an ASE access log file showing real time decoy blocking:

[Tue Aug 1422:51:49:707 2018] [thread:209] [info] [connectionid:1804289383] [connectinfo:] [type:connection_drop] [api:decoy] [request_payload_length:0] GET /decoy/test/test HTTP/1.1
User-Agent: curl/7.35.0
Accept: */*
Host: app
The blocked client is added to the blacklist which can be viewed by running the view_blacklist CLI command:

/opt/pingidentity/ase/bin/cli.sh -u admin -p admin view_blacklist
Realtime Decoy Blacklist
1) type : ip, value :