The Sandfly server provides a REST API to further expand its functionality.
The full list of calls for the Sandfly API are available at: https://api.sandflysecurity.com/
For additional development related information, see the Forensics Keyword List section of the documentation.
Example API Script
As a reference, we have provided a bash script that authenticates and pulls the Sandfly version via the API:
#!/usr/bin/env bash # Sandfly Security LTD www.sandflysecurity.com # Copyright (c) 2016-2022 Sandfly Security LTD, All Rights Reserved. # A reference script for the Sandfly API, change data where appropriate cat << EOF ****************************************************************************** Sandfly API Reference Script Example This script will attempt to authenticate, get version data, and output it. DOC: https://api.sandflysecurity.com/#get-/version ****************************************************************************** EOF # Set changeable variables APIVERSION="v4" # Version of the API used by the Sandfly Server APIPATH="version" # API command to call on the Sandfly Server JQFILTER="." # Filter for jq in the output section REQUESTMETHOD="GET" # HTTP request method for data calls REQUESTDATA="" # Data for any POST calls, leave blank for GET # Check for required commands if ! command -v jq &> /dev/null then echo "the 'jq' command could not be found and is required to run this script." exit 1 fi if ! command -v curl &> /dev/null then echo "The 'curl' command could not be found and is required to run this script." exit 1 fi # Prompt for entering connection data read -p "Hostname for Sandfly server: " HOSTNAME if [[ "$HOSTNAME" == "" ]]; then echo "Must supply a hostname." exit 1 fi read -s -p "Password for Sandfly admin user: " PASSWORD if [[ "$PASSWORD" == "" ]]; then echo "Must supply a password." exit 1 fi # Attempt to connect to the API and obtain the access token echo "" echo "" echo "Attempting to connect to the Sandfly API at: $HOSTNAME" echo "" ACCESS_JSON=$(curl -s -k --request POST \ --header "Content-Type: application/json" \ --url https://"$HOSTNAME"/"$APIVERSION"/auth/login \ --data "{\"username\":\"admin\",\"password\":\"$PASSWORD\"}") ACCESS_TOKEN=$(echo $ACCESS_JSON | jq -r ".access_token") if [[ "$ACCESS_JSON" == "" ]]; then echo "AUTH STATUS: Failed, did not receive data from the host. Check hostname and credentials and try again." exit 1 elif [[ "$ACCESS_TOKEN" == "null" ]]; then echo "AUTH STATUS: Failed, did not get access token for REST API. Check hostname and credentials and try again." exit 1 else echo "AUTH STATUS: Passed, access token obtained." fi # Attempt to get and output the data OUTPUT_JSON=$(curl -s -k --request "$REQUESTMETHOD" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --url https://"$HOSTNAME"/"$APIVERSION"/"$APIPATH" \ --data "$REQUESTDATA") OUTPUT_STATUS=$(echo $OUTPUT_JSON | jq -r ".status") OUTPUT_DETAIL=$(echo $OUTPUT_JSON | jq -r ".detail") if [[ "$OUTPUT_JSON" == "null" ]]; then echo "CALL STATUS: Failed, no JSON response." exit 1 elif [[ "$OUTPUT_STATUS" -gt 399 ]]; then echo "CALL STATUS: Failed, CODE:$OUTPUT_STATUS - $OUTPUT_DETAIL" exit 1 else echo "CALL STATUS: Passed, the output is:" echo "$OUTPUT_JSON" | jq "$JQFILTER" fi # Wrap up the example echo "" echo "Script Finished!"
NOTE: Required External Commands for the Reference Script This example script requires the use of the curl and jq commands. If either of them are not found, the script will indicate it. Install any missing commands as appropriate for your Operating System to allow this script to run.
This script can be used from any host that can run / has access to bash, curl, and jq commands and can reach the administrative web interface of your Sandfly server.
API Example Scripts
The Sandfly distribution provides scripts that perform a variety of core functions including authentication, get / post operations, and performing scans via the API. These scripts are located at: sandfly-setup/api_examples/
Previous Article: | Next Article: | ![]() |