### Install Sandfly Interactively or Automatically

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Run the install script to set up Sandfly. For automated installs, set environment variables for hostname and admin password before execution.

```bash
# Clone / unpack the release bundle then run:
cd setup/
./install.sh
```

```bash
# Fully automated (non-interactive) install:
export SANDFLY_SETUP_AUTO_HOSTNAME="sandfly.example.com"
export SANDFLY_SETUP_AUTO_ADMIN_PASSWORD="MyStr0ngP@ssword"
./install.sh
```

--------------------------------

### Start the Full Sandfly Stack

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Starts the PostgreSQL, Sandfly server, and optionally the credentials adapter containers.

```bash
cd start_scripts/
./start_sandfly.sh
```

--------------------------------

### Start a Sandfly Scanning Node

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Starts only the scanning node container, typically used on dedicated node hosts.

```bash
cd start_scripts/
./start_node.sh
```

--------------------------------

### Retrieve Server Version (GET /v4/version)

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Fetches version information for the currently running Sandfly server, including the version number, build details, and API version.

```bash
curl -s -k --request GET \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/version" | jq .
```

--------------------------------

### Integrate with Microsoft Sentinel

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Provides example commands for integrating Sandfly data with Microsoft Sentinel. This involves importing ARM/JSON templates into Azure to create custom tables for Sandfly Results, Host Assets, and SSH Keys.

```bash
RESOURCE_GROUP="my-sentinel-rg"
WORKSPACE="my-sentinel-workspace"


```

--------------------------------

### Start a scheduled scan on registered hosts

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Initiates a scheduled scan on hosts already present in the inventory. Allows specifying a subset of checks or running all active ones.

```APIDOC
## POST /v4/scan — Start a scheduled scan on registered hosts

### Description
Queues scanning tasks for hosts already in the inventory, identified by their `host_id` values. A subset of sandfly checks can be specified via `sandfly_list`; omit the field to run all active sandflies.

### Method
POST

### Endpoint
/v4/scan

### Request Body
- **host_ids** (array of strings) - Required - A list of host IDs to scan.
- **sandfly_list** (array of strings) - Optional - A list of specific sandfly checks to run. If omitted, all active sandflies are executed.
```

--------------------------------

### Generate Docker Compose Files for Deployment

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Generate Docker Compose files for multi-host deployments. Supports various TLS modes. After generation, use `docker compose up -d` to start containers.

```bash
cd setup/

# Interactive:
./generate_compose.sh
```

```bash
# Non-interactive with ACME certificate:
./generate_compose.sh \
  -hostname sandfly.example.com \
  -admin-password "MyStr0ngP@ssword" \
  -tls-mode acme \
  -acme-email admin@example.com
```

```bash
# Start everything on one host:
cd setup_data/
docker compose up -d
```

```bash
# Server-only on this host; node on a separate host:
docker compose -f docker-compose-server_only.yaml up -d
# On the node host (copy config.node.env + docker-compose-node_only.yaml):
docker compose -f docker-compose-node_only.yaml up -d
```

--------------------------------

### Start a Scheduled Scan on Registered Hosts

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Initiate a scheduled scan on hosts already present in the inventory, identified by their host IDs. You can optionally specify a subset of sandflies to run; omitting `sandfly_list` will run all active sandflies.

```bash
curl -s -k --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/scan" \
  --data '{
    "host_ids": [
      "694533a161736def4b8d55080a",
      "2487629282eae533a161736d55"
    ],
    "sandfly_list": [
      "user_history_anti_forensics",
      "process_persistence_cron_malicious",
      "kernel_module_hidden"
    ]
  }' | jq .
```

--------------------------------

### Export Custom Sandfly Checks (GET /v4/sandflies/backup)

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Downloads a JSON backup of all user-created custom sandfly checks. This is useful for version control or migrating checks to another Sandfly server.

```bash
curl -s -k --request GET \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/sandflies/backup" \
  | jq . > custom_sandflies_backup.json

echo "Backup written to custom_sandflies_backup.json"
```

--------------------------------

### List All Sandfly Names (GET /v4/sandflies)

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Retrieves the full catalog of available sandfly detection checks. Client-side filtering with 'jq' can be used to extract specific subsets, such as only active sandfly names or those of a particular type.

```bash
curl -s -k --request GET \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/sandflies" | jq -r '.data[].name'
```

```bash
curl -s -k --request GET \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/sandflies" \
  | jq -r '.data[] | select(.active==true) | .name'
```

```bash
curl -s -k --request GET \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/sandflies" \
  | jq -r '.data[] | select(.active==true and .sandfly_type=="process") | .name'
```

--------------------------------

### List All Registered Hosts

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Use this endpoint to retrieve the complete host inventory, including host IDs necessary for scheduling scans. Requires an access token for authorization.

```bash
curl -s -k --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/hosts" | jq .

# Example output (truncated):
# {
#   "data": [
#     { "id": "694533a161736def4b8d55080a", "ip": "web01.example.com",
#       "ssh_port": 22, "tags": ["production","web-tier"], ... },
#     ...
#   ]
# }
```

--------------------------------

### Clean Docker/Podman Resources Scripts

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Provides scripts to clean up Sandfly-related Docker or Podman resources. 'clean_docker.sh' removes containers and images while preserving the database volume. 'clean_docker_full.sh' removes all resources, including the database volume, resulting in data loss.

```bash
cd setup/
./clean_docker.sh       # Remove Sandfly containers and images (keeps DB volume)
./clean_docker_full.sh  # Remove everything including the database volume (DATA LOSS)
```

--------------------------------

### Deploy Sandfly Sentinel Templates via Azure CLI

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Use this script to deploy all three Sentinel integration templates for Sandfly. Ensure the RESOURCE_GROUP and WORKSPACE variables are set before execution.

```bash
for template in \
  integrations/sentinel/sentinel_template.json \
  integrations/sentinel/sentinel_template_hosts.json \
  integrations/sentinel/sentinel_template_sshkey.json
do
  az deployment group create \
    --resource-group "$RESOURCE_GROUP" \
    --template-file "$template" \
    --parameters workspaceName="$WORKSPACE"
done
```

--------------------------------

### POST /v4/hosts - Add hosts to inventory

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Registers one or more hosts with a named credential and SSH port. Tags can be applied for grouping. A `credentials_id` must reference a credential already stored.

```APIDOC
## POST /v4/hosts

### Description
Registers one or more hosts (by hostname or IP) with a named credential and an SSH port. Tags can be applied for grouping. A `credentials_id` must reference a credential already stored via `/v4/credentials/{id}`.

### Method
POST

### Endpoint
/v4/hosts

### Parameters
#### Request Body
- **ip_list** (array of strings) - Required - A list of hostnames or IP addresses to register.
- **tags** (array of strings) - Optional - Tags to apply to the registered hosts for grouping.
- **credentials_id** (string) - Required - The ID of the stored credentials to use for connecting to the hosts.
- **ssh_port** (integer) - Optional - The SSH port to use for connecting to the hosts. Defaults to 22.

### Request Example
```bash
curl -s -k --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/hosts" \
  --data '{ 
    "ip_list": [
      "web01.example.com",
      "db01.example.com",
      "192.168.10.50"
    ],
    "tags": ["production", "web-tier"],
    "credentials_id": "prod_ssh_key",
    "ssh_port": 22
  }' | jq .
```

### Response
#### Success Response (201)
- **status** (integer) - The HTTP status code, expected to be 201.
- **detail** (string) - A message indicating the success of the operation.

#### Response Example
```json
{
  "status": 201,
  "detail": "Hosts added successfully."
}
```
```

--------------------------------

### Add Hosts to Sandfly Inventory via API

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Registers hosts with Sandfly by providing IP addresses or hostnames, tags, a credentials ID, and an SSH port. The `credentials_id` must reference a pre-stored credential.

```bash
curl -s -k --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/hosts" \
  --data '{ 
    "ip_list": [
      "web01.example.com",
      "db01.example.com",
      "192.168.10.50"
    ],
    "tags": ["production", "web-tier"],
    "credentials_id": "prod_ssh_key",
    "ssh_port": 22
  }' | jq .
```

--------------------------------

### Generate Kubernetes Manifests

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Generates Kubernetes manifests for deploying Sandfly in a Kubernetes cluster.

```bash
cd setup/
./generate_k8s.sh
```

--------------------------------

### Retrieve Server Version

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Fetches the version information for the currently running Sandfly server, including the version number, build details, and API version.

```APIDOC
## GET /v4/version — Retrieve server version

### Description
Returns version information for the running Sandfly server.

### Method
GET

### Endpoint
/v4/version

### Response
#### Success Response (200)
- **version** (string) - The server version number.
- **build** (string) - The build identifier.
- **api_version** (string) - The API version.
```

--------------------------------

### List all registered hosts

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Retrieves the complete inventory of registered hosts, including their IDs which are necessary for scheduling scans.

```APIDOC
## GET /v4/hosts — List all registered hosts

### Description
Returns the full host inventory including host IDs needed for scheduled scans.

### Method
GET

### Endpoint
/v4/hosts

### Response
#### Success Response (200)
- **data** (array) - An array of host objects, each containing details like id, ip, ssh_port, and tags.
```

--------------------------------

### Query Scan Results (POST /v4/results)

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Fetches paginated and filterable scan results. Use 'filter.items' to narrow down results by status, time, host, etc. Set 'summary: true' for abbreviated records and 'flatten: false' to preserve nested JSON.

```bash
curl -s -k --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/results" \
  --data '{ \
    "size": 10, \
    "summary": true, \
    "flatten": false, \
    "filter": { \
      "items": [{ \
        "columnField": "data.status", \
        "operatorValue": "equals", \
        "value": "alert" \
      }] \
    }, \
    "sort": [{ \
      "field": "data.end_time", \
      "sort": "desc" \
    }] \
  }' | jq .
```

--------------------------------

### Ad-hoc Scan with Inline SSH Key

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Perform an immediate, one-off scan against hosts not necessarily in the inventory. Credentials are provided inline, and hosts can be specified as a list of IPs or a CIDR range. The script waits 60 seconds before retrieving per-host results. Ensure the SSH key is base64 encoded.

```bash
SSH_KEY_B64=$(base64 -w 0 ~/.ssh/id_rsa)

SCAN_RESPONSE=$(curl -s -k --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/scan/adhoc" \
  --data "{
    \"hosts\": { 
      \"ip_list\": [\"192.168.0.10\", \"192.168.0.11\"],
      \"ssh_port\": 22,
      \"credentials_id\": \"inline_key\" 
    },
    \"credentials\": {
      \"inline_key\": {
        \"credentials_type\": \"ssh_key\",
        \"username\": \"root\",
        \"ssh_key_b64\": \"${SSH_KEY_B64}\" 
      }
    },
    \"sandfly_list\": [
      \"user_history_anti_forensics\",
      \"process_persistence_cron_malicious\"
    ],
    \"tags\": [\"adhoc\", \"incident-response\"]
  }")

echo "$SCAN_RESPONSE" | jq .
# Returns: { "0": { "<host_id>": "<run_id>" }, ... }

# Wait for scans to finish, then retrieve results per run_id:
sleep 60
RUN_ID=$(echo "$SCAN_RESPONSE" | jq -r '.[0] | to_entries[0].value')
curl -s -k --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/results" \
  --data "{
    \"size\": 100,
    \"summary\": true,
    \"filter\": {\"items\": [{
      \"columnField\": \"header.run_id\",
      \"operatorValue\": \"equals\",
      \"value\": \"${RUN_ID}\" 
    }]}
  }" | jq .
```

--------------------------------

### Export Custom Sandfly Checks

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Downloads a backup of all user-created custom sandfly checks in JSON format. This is useful for version control or migrating checks to a different server.

```APIDOC
## GET /v4/sandflies/backup — Export custom sandfly checks

### Description
Downloads a backup of all user-created custom sandfly checks as JSON, suitable for version control or migration to another server.

### Method
GET

### Endpoint
/v4/sandflies/backup

### Response
#### Success Response (200)
- (JSON) - A JSON object containing all custom sandfly checks.
```

--------------------------------

### Reload TLS Certificate Script

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Reloads a new SSL/TLS certificate into a running Sandfly server without requiring a full server restart. Ensure new 'cert.pem' and 'key.pem' files are placed in 'setup/setup_data/server_ssl_cert/'.

```bash
# Place new cert.pem and key.pem in setup/setup_data/server_ssl_cert/
cd setup/setup_scripts/
./reload_server_https_certificate.sh
```

--------------------------------

### Integrate with Elasticsearch/Kibana

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Applies Sandfly index settings and mappings to an Elasticsearch cluster and imports Kibana dashboards via the Saved Objects API. This enables visualization of Sandfly scan results in Kibana.

```bash
ES_HOST="https://elasticsearch.example.com:9200"
KIBANA_HOST="https://kibana.example.com:5601"

# 1. Apply index settings (sets total_fields.limit):
curl -s -k -XPUT "${ES_HOST}/sandfly-results/_settings" \
  -H "Content-Type: application/json" \
  -d @integrations/elasticsearch/sandfly_elastic_settings.json

# 2. Apply index mappings:
curl -s -k -XPUT "${ES_HOST}/sandfly-results/_mapping" \
  -H "Content-Type: application/json" \
  -d @integrations/elasticsearch/sandfly_elastic_mappings.json

# 3. Import Kibana dashboards via the Saved Objects API:
curl -s -k -XPOST "${KIBANA_HOST}/api/saved_objects/_import" \
  -H "kbn-xsrf: true" \
  --form file=@integrations/elasticsearch/sandfly_elastic_dashboards.ndjson
```

--------------------------------

### List Sandfly Checks

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Retrieves the complete catalog of available Sandfly detection checks, including their metadata. Client-side filtering using tools like `jq` is recommended for specific subsets.

```APIDOC
## GET /v4/sandflies — List sandfly checks

### Description
Returns the full catalog of available sandfly detection checks with metadata. Filter with `jq` on the client side to get specific subsets.

### Method
GET

### Endpoint
/v4/sandflies

### Response
#### Success Response (200)
- **data** (array) - An array of sandfly check objects, each containing details like `name`, `active` status, and `sandfly_type`.
```

--------------------------------

### Ad-hoc Scan with Username/Password over a Subnet

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Perform an ad-hoc scan targeting a subnet using username and password credentials. This endpoint allows scanning a range of IPs by specifying an `ip_range` and `credentials_id` for authentication.

```bash
curl -s -k --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/scan/adhoc" \
  --data '{
    "hosts": {
      "ip_range": ["192.168.1.0/24"],
      "ssh_port": 22,
      "credentials_id": "inline_user"
    },
    "credentials": {
      "inline_user": {
        "credentials_type": "username",
        "username": "root",
        "password": "password"
      }
    },
    "sandfly_list": [
      "file_scripts_etc_initd_malicious",
      "log_suspicious_username_logged_in_past_24_hours",
      "kernel_module_hidden"
    ],
    "tags": ["subnet-sweep"]
  }' | jq .
```

--------------------------------

### Ad-hoc scan with inline credentials (SSH key)

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Performs an immediate scan against specified hosts using inline SSH key credentials. Supports IP lists or CIDR ranges.

```APIDOC
## POST /v4/scan/adhoc — Ad-hoc scan with inline credentials (SSH key)

### Description
Runs an immediate one-off scan against hosts not necessarily in the inventory. Credentials are provided inline and hosts can be specified as a list of IPs or as a CIDR range. After submitting, the script waits 60 seconds and then retrieves per-host results.

### Method
POST

### Endpoint
/v4/scan/adhoc

### Request Body
- **hosts** (object) - Required - Defines the target hosts and connection details.
  - **ip_list** (array of strings) - Optional - A list of IP addresses to scan.
  - **ip_range** (array of strings) - Optional - A CIDR range to scan.
  - **ssh_port** (integer) - Required - The SSH port to use for connections.
  - **credentials_id** (string) - Required - Identifier for the credentials to use (e.g., `inline_key`).
- **credentials** (object) - Required - Contains the inline credentials.
  - **[credentials_id]** (object) - Dynamic key matching the `credentials_id` in `hosts`.
    - **credentials_type** (string) - Required - Type of credentials, `ssh_key`.
    - **username** (string) - Required - The username for authentication.
    - **ssh_key_b64** (string) - Required - The SSH private key, base64-encoded.
- **sandfly_list** (array of strings) - Optional - A list of specific sandfly checks to run.
- **tags** (array of strings) - Optional - Tags to associate with the scan.

### Response
#### Success Response (200)
- **[host_id]** (string) - The run ID for the scan on the specific host.
```

--------------------------------

### Store SSH Credentials

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Store SSH credentials using either a username/password combination or an SSH private key (base64-encoded). Credentials are stored under a named ID for later reference. Ensure the SSH key is properly base64 encoded.

```bash
# Username/password credential:
curl -s -k --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/credentials/prod_ssh_password" \
  --data '{
    "credentials_type": "username",
    "username": "root",
    "password": "YourSSHPassword"
  }' | jq .

# SSH private key credential (key must be base64-encoded):
SSH_KEY_B64=$(base64 -w 0 ~/.ssh/id_rsa)
curl -s -k --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --url "https://${SANDFLY_HOST}/v4/credentials/prod_ssh_key" \
  --data "{
    \"credentials_type\": \"ssh_key\",
    \"username\": \"root\",
    \"ssh_key_b64\": \"${SSH_KEY_B64}\" 
  }" | jq .

# Expected output:
# { "status": 201, "detail": "Credential added." }
```

--------------------------------

### Query Scan Results

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Returns paginated and filterable scan results. Supports filtering by status, time range, run ID, host, or sandfly name. Options to return abbreviated records or preserve nested JSON are available.

```APIDOC
## POST /v4/results — Query scan results

### Description
Returns paginated, filterable scan results. Use `filter.items` to narrow by status (`alert`, `pass`, `error`), time range, run ID, host, or sandfly name. `summary: true` returns abbreviated records; `flatten: false` preserves nested JSON.

### Method
POST

### Endpoint
/v4/results

### Parameters
#### Request Body
- **size** (integer) - Optional - The number of results to return per page.
- **summary** (boolean) - Optional - If true, returns abbreviated records.
- **flatten** (boolean) - Optional - If false, preserves nested JSON.
- **filter** (object) - Optional - An object to filter the results.
  - **items** (array) - Required - An array of filter conditions.
    - **columnField** (string) - Required - The field to filter on.
    - **operatorValue** (string) - Required - The operator to use for filtering (e.g., 'equals').
    - **value** (string) - Required - The value to filter by.
- **sort** (array) - Optional - An array of sort conditions.
  - **field** (string) - Required - The field to sort by.
  - **sort** (string) - Required - The sort order ('asc' or 'desc').

### Request Example
```json
{
  "size": 10,
  "summary": true,
  "flatten": false,
  "filter": {
    "items": [
      {
        "columnField": "data.status",
        "operatorValue": "equals",
        "value": "alert"
      }
    ]
  },
  "sort": [
    {
      "field": "data.end_time",
      "sort": "desc"
    }
  ]
}
```

### Response
#### Success Response (200)
- **data** (array) - An array of scan result objects.
  - **header** (object) - Metadata about the scan run.
  - **data** (object) - The scan result details.
- **more_results** (boolean) - Indicates if there are more results available.
- **scroll_id** (string) - An identifier for scrolling through results.
- **total** (integer) - The total number of results.
```

--------------------------------

### Reset Admin Password Script

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Executes a script to reset the admin account password. This script spins up a temporary management container that resets the password and prints the new credentials to standard output.

```bash
cd setup/util_scripts/
./reset_admin_password.sh
```

--------------------------------

### Store SSH credentials

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Stores SSH credentials under a specified ID. Supports both username/password and SSH key authentication.

```APIDOC
## POST /v4/credentials/{id} — Store SSH credentials

### Description
Credentials are stored under a named ID (`credentials_id`) and referenced when adding hosts or triggering ad-hoc scans. Two `credentials_type` values are supported: `username` (password-based) and `ssh_key` (private key, base64-encoded).

### Method
POST

### Endpoint
/v4/credentials/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The identifier for the credentials.

#### Request Body
- **credentials_type** (string) - Required - Type of credentials, either `username` or `ssh_key`.
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required (if `credentials_type` is `username`) - The password for authentication.
- **ssh_key_b64** (string) - Required (if `credentials_type` is `ssh_key`) - The SSH private key, base64-encoded.

### Response
#### Success Response (201)
- **status** (integer) - Indicates success.
- **detail** (string) - A message confirming the credential addition.
```

--------------------------------

### Ad-hoc scan with username/password over a subnet

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Performs an ad-hoc scan against a subnet using inline username and password credentials.

```APIDOC
## POST /v4/scan/adhoc — Ad-hoc scan with username/password over a subnet

### Description
Same endpoint; targets a CIDR range instead of a discrete IP list using username/password credentials.

### Method
POST

### Endpoint
/v4/scan/adhoc

### Request Body
- **hosts** (object) - Required - Defines the target hosts and connection details.
  - **ip_range** (array of strings) - Required - A CIDR range to scan.
  - **ssh_port** (integer) - Required - The SSH port to use for connections.
  - **credentials_id** (string) - Required - Identifier for the credentials to use (e.g., `inline_user`).
- **credentials** (object) - Required - Contains the inline credentials.
  - **[credentials_id]** (object) - Dynamic key matching the `credentials_id` in `hosts`.
    - **credentials_type** (string) - Required - Type of credentials, `username`.
    - **username** (string) - Required - The username for authentication.
    - **password** (string) - Required - The password for authentication.
- **sandfly_list** (array of strings) - Optional - A list of specific sandfly checks to run.
- **tags** (array of strings) - Optional - Tags to associate with the scan.

### Response
#### Success Response (200)
- **[host_id]** (string) - The run ID for the scan on the specific host.
```

--------------------------------

### Shut Down Sandfly Containers

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Shuts down all running Sandfly containers.

```bash
cd start_scripts/
./shutdown_sandfly.sh
```

--------------------------------

### POST /v4/auth/login - Obtain a Bearer token

Source: https://context7.com/sandflysecurity/sandfly-setup/llms.txt

Obtain a short-lived JWT Bearer token required for all subsequent API calls. This token is obtained by providing username and password credentials.

```APIDOC
## POST /v4/auth/login

### Description
Obtain a Bearer token required for all subsequent API calls. The token is a short-lived JWT.

### Method
POST

### Endpoint
/v4/auth/login

### Parameters
#### Request Body
- **username** (string) - Required - The username for authentication.
- **password** (string) - Required - The password for authentication.

### Request Example
```bash
SANDFLY_HOST="sandfly.example.com"
APIVERSION="v4"

ACCESS_JSON=$(curl -s -k --request POST \
  --header "Content-Type: application/json" \
  --url "https://${SANDFLY_HOST}/${APIVERSION}/auth/login" \
  --data '{"username":"admin","password":"MyStr0ngP@ssword"}')

ACCESS_TOKEN=$(echo "$ACCESS_JSON" | jq -r ".access_token")

if [[ -z "$ACCESS_TOKEN" || "$ACCESS_TOKEN" == "null" ]]; then
  echo "AUTH FAILED: $ACCESS_JSON"
  exit 1
fi

echo "Token: $ACCESS_TOKEN"
```

### Response
#### Success Response (200)
- **access_token** (string) - The obtained Bearer token.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```
```