Welcome to the Sandfly Security Server API Reference documentation.

API Info

Sandfly API Version: 5.7.0

License: Sandfly Security, Ltd. ( https://www.sandflysecurity.com/🡵 )

Open API Version: 3.0.1

OAS Link: https://docs.sandflysecurity.com/v5.7.0/openapi/openapi-public.yaml🡵

NOTE: The API version number is independent of the version of Sandfly and the "v" number within API URLs.

Packaged API Spec: The sandfly-setup package includes the associated OpenAPI spec at this file location: sandfly-setup/api_examples/sandfly-openapi.yaml

For additional development related information, see the Forensic Keyword List and API Endpoint Role Security Matrix sections of the documentation.

API Use

In order to use the Sandfly API, you need to be able to run commands from a host that can reach your Sandfly server and which is capable of running whichever language(s) that you choose to use. The Operating System does not have to be Linux, any OS can be used as long as the selected command is compatible.

❗️
IMPORTANT: Make API calls from your internal network and use placeholders
For your security, these API calls should only be made from your internal network. For these instructions to work directly within the API Reference, your Sandfly server would need to be reachable from the Internet and use actual query parameters, both of which could expose your data.

API Authentication

First, you need to obtain an authentication token before any other API calls can be made.

Get authentication token - https://docs.sandflysecurity.com/reference/apilogin.
In the Body Params section enter "u" for the username and "p" for the password as placeholders.
Select the Language that you would like to use locally and then make a copy of the request command.
Paste the request command into a command line that supports the selected language, but do not run it.
Modify the pasted command line by replacing any placeholder values:
- Change sandfly-api-host with the resolvable hostname or IP address of your Sandfly server.
- Change the "u" and "p" values with an actual Sandfly username and password.
Once all of the placeholders have been changed, run the command.
The API will return a response that will contain the associated data in the JSON format.
- The post_auth-login call should return a value that looks similar to this, just minified:

{
  "access_token": "fvJhbFciOkJIUzI1NiIsInR5cCI6IkpXVCJ4.eyJzaWQiOiIyYTA4YjNkZjNhOTk2ZWRiM2FjNzMxYmM5YWVjZDVjMCIsInR5cGUiOiJhY2Nlc3MiLCJleHAiOjE3MjQ0NDU0OTgsImp0aSI6IjZhZGM4Y2E5OWI1MzE2NzM2NDRjZmQ2OGU4OTFlOGZjIiwiaWF0IjoxNzI0NDQzNjk4LCJuYmYiOjE3MjQ0NDM2OTgsInN1YiI6InNiIn0.vUmppR1S58B3u1EN4ATHiRIsUofExCDAqXo0O61FIDQ",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzaWQiOiIyYTA4YjNkZjNhOTk2ZWRiM2FjNzMxYmM5YWVjZDVjMCIsInR5cGUiOiJyZWZyZXNoIiwiZXhwIjoxNzI0NTMwMDk4LCJqdGkiOiI4MGQ1N2ZkYmFhYWQ1MGFmFjIyMwQ3NDMwZDhhMWZhNiUsImlhdCI6MTcyNDQ0MzY5OCwibmJmIjoxNzI0NDQzNjk4HCJydWIiOiJzYiJ7.CQtgw4cOQ3C3Rhl4W7mjvk7qGgOc3mhb5hs_P3b5PCk"
}

An obtained bearer / access token will remain valid for 60 minutes.

API Calls

Once an authentication token is generated, use it for all other API calls while the token remains active.

Select a desired API call from the Sandfly API.
- For example: Get all hosts - https://docs.sandflysecurity.com/reference/gethosts
Add placeholder values for the Bearer field and any content sensitive Params so that they appear in the request.
- For example: set the summary field to "false" for Get all hosts.
Select the Language that you would like to use locally and then make a copy of the request command.
Paste the request command into a command line that supports the selected language, but do not run it.
Modify the pasted command line by replacing any placeholder values:
- Change sandfly-api-host with the hostname or IP address of your Sandfly server.
- Change the bearer placeholder with the value of the "access_token" from the authentication step.
- Change any other placeholder "params" to their expected values.
Once all of the placeholders have been changed, run the command.
The API will return a response that will contain the associated data in the JSON format.