A lot of information about detected malicious requests is already available in the Wallarm console UI. However, the search functionality of the Wallarm UI does not provide full visibility into every type of potential attack or full details of a particular alert.  If this level of visibility is desired, a script can use the Wallarm API to extract this data and send it to one of a number of different targets.

This article provides an introduction to using the Wallarm API to extract request details from Wallarm. By configuring and running the script as described below, it is possible to perform full-text analysis of the requests seen by the Wallarm WAF.

Using the Wallarm API to Extract Alert Data

Wallarm provides a client script that is designed to interact with the Wallarm API and extract full-text alert data. The following sections describe how to install and configure this script to work with your Wallarm installation and the target where the data should be sent.

Installing the Wallarm API Client Script

This client script is freely available on Github.  Install and configure the script by taking the following steps.

Accessing the Script

If you have a Git client installed on your Wallarm WAF node, then navigate to directory /usr/share/wallarm-common/ and pull a copy of the repository with the command “git clone https://github.com/wallarm/api-examples.git”.

Otherwise, you can visit the page directly and download a ZIP file containing the script by clicking on the green button labeled Code.  Select the Download ZIP option, and, once the ZIP has been downloaded, extract the files that it contains to directory /usr/share/wallarm-common/.

Installing Dependencies

The Wallarm API client script requires Python version 3.7 or greater and a set of dependencies listed in requirements.txt.  If you do not already have a compatible version of Python installed, download it from the Python downloads page or install it with your package manager.

Once Python is installed, navigate in the terminal to the directory where the Git repository is downloaded.  From inside the folder, install the necessary dependencies with the command 

pip install -r requirements.txt

This should automatically install all of the Python packages that the client script requires.

Setting Up the Environment

The Wallarm API client script requires access to certain pieces of information about your Wallarm account to function.  These should be configured as environment variables on your system. Additionally, you can configure a cron job to automatically run the Wallarm API client script at regular intervals.

The Wallarm API client script requires three values: your UUID, SECRET, and the address of the Wallarm API. To get the first two of these, contact Wallarm Support or use the Swagger Wallarm Console as described on page https://docs.wallarm.com/admin-en/api-en/. The address of the Wallarm API should be api.wallarm.com if you are using the EU Wallarm Cloud or us1.api.wallarm.com for the US Wallarm Cloud.

Once you have these values, add them to the environment with the following commands in the terminal, inserting your UUID, SECRET, and API address:

export WALLARM_UUID=’<Insert UUID value here>’ 
printf --  'export WALLARM_UUID=$WALLARM_UUID’ >> $HOME/.profile
export WALLARM_SECRET=’<Insert SECRET value here>’
printf -- ‘export WALLARM_SECRET=$WALLARM_SECRET’ >> $HOME/.profile
export WALLARM_API=’<INSERT API address here>’
printf -- ‘export WALLARM_API=$WALLARM_API’ >> $HOME/.profile

The first line in each of these pairs of commands adds the value to the environment for this session. The second ensures that the value remains in the environment if the computer is rebooted or the user’s session is reset for some reason.

At this point, the environment is correctly configured for the current run.  However, it is possible to create a cron job to automatically run the script in the future.  To do so, use the following terminal command:

printf -- ‘0 * * * * root . $HOME/.profile;/usr/share/wallarm-common/main.py’ > /etc/cron.d/wapi

Setting Up the Environment

The Wallarm API client script is designed to support a number of different destinations for the alert data.  To configure the script to send the alert data to a particular target, open main.py.

# In case of Elasticsearch
# elastic = SenderData(address='http://localhost:9200', http_auth='admin:password')
# [await elastic.send_to_elastic(body=rawhit, index='wallarm') for rawhit in raw_hits]

# In case of Sumologic HTTP collector
# sumo = SenderData(address='https://endpoint5.collection.us2.sumologic.com/receiver/v1/http/')
# [await sumo.send_to_collector(rawhit) for rawhit in raw_hits]

# In case of Splunk/Fluentd/HTTP collectors
# splunk = SenderData(address='https://localhost:8088')
# [await splunk.send_to_collector(rawhit, token='<token>', verify_ssl=False) for rawhit in raw_hits]

# In case of tcp/syslog_tcp collectors
# sys_tcp = SenderData(address='tcp://localhost:5140')
# [await sys_tcp.send_to_collector(rawhit) for rawhit in raw_hits]

# In case of udp/syslog
# sys_udp = SenderData(address='udp://localhost:514')
# [await sys_udp.send_to_collector(raw_hit) for raw_hit in raw_hits]

Toward the bottom of the script, you should see a number of lines commented out as shown above.  Select the appropriate case, comment out the two lines below it (not including the statement starting with “In case”), and update the address and any other configuration information to match your implementation.

Conclusion

The provided script only scratches the surface of the functionality available via the Wallarm API.  Examining the main.py script referenced above reveals a number of API calls that are currently disabled and not supported by the script since they are unnecessary for most users. Advanced users with the desire to access this information can modify the script according.  For more information on the Wallarm API, how it works, and the information that can be extracted from it, check out the Wallarm API documentation.