Agent Dispatcher — Getting Started¶

Dispatcher version: 3.9.1 Faraday server version: 5.19.0 Python requirement: 3.10+

The Faraday Agent Dispatcher is middleware that sits between the Faraday server and your security tools. It manages communication, launches tool executors on demand, and sends scan results back to your workspace automatically.

Table of Contents¶

• Overview
• Prerequisites
• Installation
• pip install (recommended)
• Install from source
• Docker
• Configuration
• Configuration wizard (interactive)
• Manual YAML configuration
• Configuration reference
• Registering the Agent
• Obtaining a registration token
• First run
• Subsequent runs
• Running an Executor from the UI
• Running an Executor via API
• CLI Reference
• Troubleshooting

Overview¶

Faraday Agents solve a key limitation of the traditional plugin system: they allow non-interactive, automated tool execution without requiring the Faraday console. Instead of manually running a tool and importing results, agents run as persistent background processes that:

1. Connect to the Faraday server via Socket.IO
2. Advertise their available executors (security tools)
3. Wait for RUN commands from the server (manual, scheduled, or API-triggered)
4. Launch the requested executor as a subprocess
5. Stream results to the Faraday bulk_create API

Each agent can host multiple executors. An executor is a script (any language) that wraps a specific tool and outputs Faraday-compatible JSON to stdout.

Prerequisites¶

Before installing the Agent Dispatcher, ensure you have:

• Faraday Server v5.x running and accessible (HTTP or HTTPS)
• Python 3.10 or later (for pip installation)
• Network access from the agent host to the Faraday server on:
• API port (default: 5985 for HTTP, 443 for HTTPS behind NGINX)
• WebSocket port (same as API port in modern deployments)
• Registration token from the Faraday admin panel (see Obtaining a registration token)
• Security tools installed locally for any executors you want to run (e.g., Nmap, Nessus CLI, Nuclei)

Installation¶

pip install (recommended)¶

pip install faraday_agent_dispatcher

This installs the faraday-dispatcher CLI command and all 27 official executor scripts.

Install from source¶

git clone https://github.com/infobyte/faraday_agent_dispatcher.git
cd faraday_agent_dispatcher
pip install .

Docker¶

See the [[agent-docker|Docker Deployment Guide]] for complete Docker instructions. Quick start:

docker pull faradaysec/faraday_agent_dispatcher

Configuration¶

The dispatcher reads its configuration from a YAML file located at:

~/.faraday/config/dispatcher.yaml

You can override this path with the -c / --config-file flag.

Note: The dispatcher also supports the legacy .ini format and will automatically convert it to YAML on first load.

Configuration wizard (interactive)¶

The easiest way to configure a new agent:

faraday-dispatcher config-wizard

The wizard walks through the following sections:

1. Server settings

Server host (e.g., 127.0.0.1 or faraday.example.com)
SSL enabled? (True/False)
SSL certificate path (leave empty for system default)
SSL ignore invalid certs? (True/False)
API port (e.g., 5985 for HTTP, 443 for HTTPS)
WebSocket port (same as API port in most deployments)

2. Agent settings

Agent name (unique identifier displayed in the UI)
Agent description (optional)

3. Executor settings

For each executor, choose between:

• Official executor — Select from the 27 built-in integrations (Nmap, Nessus, Burp, ZAP, Nuclei, etc.). The wizard pages through available executors.
• Custom executor — Provide a command path and define environment variables and arguments manually.

For official executors, the wizard prompts for required credentials (e.g., NESSUS_USERNAME, NESSUS_PASSWORD, NESSUS_URL).

You can configure multiple executors per agent.

Wizard options:

faraday-dispatcher config-wizard [OPTIONS]

Options:
  -c, --config-filepath PATH  Path to config file (default: ~/.faraday/config/dispatcher.yaml)
  -p, --page-size INT         Executor list page size, 2-20 (default: 10)
  --logdir PATH               Log directory (default: ~)
  --log-level TEXT             Log level: notset|debug|info|warning|error|critical
  --debug                     Enable debug logging (overrides --log-level)

Manual YAML configuration¶

Create or edit ~/.faraday/config/dispatcher.yaml:

# Server connection settings
server:
  host: faraday.example.com
  ssl: true
  ssl_cert: ''           # Path to custom CA cert, or empty for system default
  ssl_ignore: false      # Set true to skip cert verification (not recommended)
  api_port: 443
  websocket_port: 443

# Agent identity
agent:
  agent_name: production-scanner
  description: "Nmap and Nuclei scanner on DMZ host"
  executors:
    nmap_scan:
      repo_executor: nmap.py       # Official executor script filename
      repo_name: nmap              # Manifest name (auto-set by wizard)
      max_size: 65536              # Max stdout buffer per line (bytes)
      varenvs: {}                  # Persistent environment variables (credentials)
      params: {}                   # Overridden by manifest for official executors
    nuclei_scan:
      repo_executor: nuclei.py
      repo_name: nuclei
      max_size: 65536
      varenvs: {}
      params: {}

# Agent token (auto-populated after first registration)
# tokens:
#   agent: <auto-generated-agent-token>

Custom executor example:

agent:
  agent_name: custom-agent
  executors:
    my_scanner:
      cmd: /opt/tools/my_scanner.sh    # Absolute path to your script
      max_size: 65536
      varenvs:
        SCANNER_API_KEY: "your-api-key"
      params:
        target:
          mandatory: true
          type: string
          base: string
        port_range:
          mandatory: false
          type: string
          base: string

Configuration reference¶

* Either repo_executor (official) or cmd (custom) is required per executor.

Registering the Agent¶

Obtaining a registration token¶

1. Log in to Faraday as an administrator
2. Navigate to Administration > Agents (URL: https://<server>/#/admin/agents)
3. Click "Create Agent Token" or copy an existing registration token
4. The token is a one-time secret used only during the agent's first connection

First run¶

Pass the registration token with the --token flag:

faraday-dispatcher run --token=<REGISTRATION_TOKEN>

On successful registration: - The dispatcher connects to /_api/v3/agents and POSTs the agent name plus the token - The server returns a persistent agent token (different from the registration token) - The agent token is saved to the config file under tokens.agent - The dispatcher then requests a WebSocket token from /_api/v3/agent_websocket_token - A Socket.IO connection is established to /dispatcher namespace

Subsequent runs¶

After initial registration, the token is stored in the config file. Simply run:

faraday-dispatcher run

The agent will appear as online (green indicator) in the Faraday UI under Automation > Agents.

CLI options:

faraday-dispatcher run [OPTIONS]

Options:
  -c, --config-file PATH  Path to config YAML file
  --token TEXT             Registration token (first run only)
  --logdir PATH            Log directory (default: ~)
  --log-level TEXT         Log level: notset|debug|info|warning|error|critical
  --debug                  Enable debug logging (overrides --log-level)

Running an Executor from the UI¶

1. Navigate to Automation > Agents in the Faraday web interface
2. Find your agent (it must show an Online status)
3. Click the green Play button next to the agent
4. In the dialog:
5. Select the executor (e.g., "nmap_scan")
6. Fill in the arguments (e.g., target IP, port range)
7. Select the target workspace(s)
8. Click Run

The execution status is tracked in the Automation panel. Results (hosts, services, vulnerabilities) appear in the target workspace.

Running an Executor via API¶

You can also trigger an agent run programmatically:

# Get the agent ID and executor name
curl -s -H "Authorization: Token <API_TOKEN>" \
  https://<server>/_api/v3/agents | jq '.rows[].value'

# Trigger execution
curl -X POST \
  -H "Authorization: Token <API_TOKEN>" \
  -H "Content-Type: application/json" \
  https://<server>/_api/v3/agents/<agent_id>/run \
  -d '{
    "executor_name": "nmap_scan",
    "args": {
      "target": "192.168.1.0/24"
    },
    "workspace_name": "pentest-2026"
  }'

CLI Reference¶

Troubleshooting¶

Agent shows "Offline" in the UI¶

• Verify the dispatcher process is running (ps aux | grep faraday-dispatcher)
• Check that the server host, ports, and SSL settings are correct
• Review logs at ~/.faraday/logs/ for connection errors
• Ensure the agent token hasn't been revoked (re-register with a new --token if needed)

"Invalid registration token" error¶

• Registration tokens are one-time use. Generate a new one from Administration > Agents
• Ensure the Faraday server version is compatible with the dispatcher version (check RELEASE.md)

SSL certificate errors¶

• If using self-signed certs, set ssl_cert to the CA certificate path in the config
• As a temporary workaround, set ssl_ignore: true (not recommended for production)
• If behind an HTTPS proxy, the dispatcher respects the HTTPS_PROXY environment variable

"Invalid data supplied by the executor to the bulk create endpoint"¶

• The executor's stdout output is not valid Faraday JSON
• Run the executor manually and validate its output against the bulk_create schema
• Check max_size — if the output exceeds the buffer limit, increase it in the config

License errors (HTTP 402)¶

• The Faraday server returned an "Unauthorized" response when requesting a WebSocket token
• Verify your Faraday license is active and not expired
• Contact Faraday support if the issue persists

File paths¶