Overview

This document will guide you through the installation of the Farcaster Agent.

The Farcaster Agent connects Snyk API & Web to your private networks (i.e. on-premise, private cloud, CICD runner environments, etc.) using an encrypted WireGuard tunnel and proxy, allowing Snyk API & Web to scan your internal applications with minimal network & security configuration changes.

The Agent is open-source, and the code is freely available on the official repository.

Network Architecture Overview

The following diagram shows an example network topology for Farcaster agent based connectivity from a private client network (on-premise, private cloud, CI/CD, etc.) to the Snyk API & Web Cloud infrastructure.

Architecture Notes

Client edge security devices (FW, IPS, WAF, etc.) should be configured to whitelist Snyk API & Web Scanner and Asset Discovery service IPs, which are listed in Scanner IP address and are not repeated in the table below. Internal security devices (FW, IPS, WAF, etc.) should be configured to whitelist any scanning agent IPs.
Firewall protocol inspection must be disabled for Farcaster Agent connectivity. TLS Inspection (e.g., NGFW or CASB) works only with the WebSocket transport (FARCASTER_TRANSPORT=ws) and FARCASTER_CUSTOM_CA set to the inspecting CA; otherwise, disable it for Agent connectivity rules in any edge/cloud security devices or services.
If required, Farcaster Agent will support tunnel connectivity via proxy, however performance may be impacted.
OOB Vulnerability checks are utilized to verify vulnerabilities that allow an attacker to initiate a connection from the target to a remotely controlled ip address / server (e.g. log4shell)
api.probely.com IP addresses may be subject to change, we recommend configuring firewall rules to allow Farcaster agents outbound https access based on DNS name, or allowing outbound communications to all https destinations.
Private container registries can be utilized if required.

System Resources

The Agent is a Docker container requiring minimal resources, as detailed in the following table.

CPU	RAM	Storage
1	512 MB	1 GB

Network Requirements

Name	Source	Destination	Protocol	Source Port	Destination Port
API	`<agent-ip>`¹	`api.probely.com`⁴	`TCP`	`any`	`443`
Tunnel	`<agent-ip>`	- EU: `54.247.135.113` - US: `44.212.186.140` - AU: `54.253.10.194`	`UDP`	`any`	`443`
Tunnel (WebSocket fallback)	`<agent-ip>`	- EU: `hub.farcaster.probely.com` - US: `hub.farcaster.us.probely.com` - AU: `hub.farcaster.au.probely.com`	`TCP`	`any`	`443`
DNS	`<agent-ip>`	`<internal-dns-resolvers>`	`TCP`, `UDP`	`any`	`53`
Scan	`<agent-ip>`	`<target-ip>`²	`TCP`	`any`	`<target-port>`³
OOB Vulnerability Check ⁶	`<agent-ip>`, `<target-ip>`	- EU: `szp.prbly.win` / `52.17.201.157` - US: `szpus.prbly.win` / `52.72.180.55` - AU: `szpau.prbly.win` / `52.62.50.85`	`TCP`	`any`	`53`, `80`, `443`, `389`
OOB Vulnerability Check ⁶	`<agent-ip>`, `<target-ip>`	- EU: `szp.prbly.win` / `52.17.201.157` - US: `szpus.prbly.win` / `52.72.180.55` - AU: `szpau.prbly.win` / `52.62.50.85`	`UDP`	`any`	`53`
Docker	`<agent-ip>`	`auth.docker.io`, `registry*.docker.io`⁵	`TCP`	`any`	`443`

Notes:

<agent-ip> is the IP address of the machine that the Farcaster Agent is installed on (e.g. the machine running Docker, the Kubernetes proxy IP for the pod, etc.)
<target-ip> is the internal IP of each of your web or API targets. If your target requires authentication via another host or your targets are configured to use extra hosts, include those IPs here as well.
<target-port> is the TCP port used to access your web applications & apis on the target host (typically 80, 443, 8080, 8443, etc.)
The IP addresses of these hosts are subject to change. We recommend allowing web access for the agent VM to all external destinations on tcp/443 (https). If this is not possible, the agent will use an HTTP proxy if you set the HTTP_PROXY variable.
At this time, the hosts are: registry.docker.io and registry-1.docker.io
This server receives connections from potentially vulnerable systems on your infrastructure. It is used, for example, to detect "Log4Shell"-type vulnerabilities. These connections are optional, but may impact the ability of Snyk API & Web to verify related vulnerabilities if the connections are not allowed. Allow the hostname as well as the IP address: some firewalls categorize the domain as malicious and sinkhole it, so an IP-only rule does not let the callback through.

Installation

The Farcaster agent can be deployed as a container in Docker or Kubernetes, or as Windows or Linux service.

The agent needs a token to connect to Snyk API & Web network.

If you do not have an agent token, you can create one in the Scanning Agents management area.

Required software

Docker

When using Docker Compose, both Docker and Docker Compose must be installed.

Kubernetes

We provide an example Agent Kubernetes deployment here.

If you need help setting the Agent up on a Kubernetes cluster, please contact Snyk API & Web support team.

Windows

Download the latest Windows binary from the releases page here

Linux

See Building from source to compile the Farcaster Agent for Linux.

System checks

Before installing the agent container on a Linux system, you can check that your host can run it by executing the following script or run the command below:

curl -LO https://raw.githubusercontent.com/Probely/farcaster-onprem-agent/main/farconn/host-check.sh
chmod +x host-check.sh
./host-check.sh

Verify that the checks succeeded:

  Checking if Docker is installed...                              [ok]
  Launching test container...                                     [ok]

Launch the agent

Use the docker-compose.yml you saved in Step 1 of How to install a Scanning Agent.
Start the Agent:

    docker compose up -d

Check that the Agent connected successfully

After starting the Agent, it should link-up with Snyk API & Web. Run the following command:

  docker logs probely-agent

If everything is running correctly, you should see output similar to:

    Downloading agent configuration ... done
    Deploying agent configuration   ... done
    Starting local DNS resolver     ... done
    Setting HTTP proxy rules        ... done
    Connecting to Probely (via UDP) ... done
    Setting local gateway rules     ... done
    Starting WireGuard gateway      ... done

    Running...

Once up and running, traffic destined for any targets configured to use the agent is routed through the vpn tunnel and proxied by the agent to connect to those targets on your private network. Learn more about how to scan internal applications with a Scanning Agent.

Configuration Options

The following configuration options can be set via environment variables when running the agent

Required/Optional	Environment Variable	Description
Req	FARCASTER_AGENT_TOKEN	Agent API Key
Opt	FARCASTER_API_URL	url of API server
Opt	FARCASTER_DEBUG_LEVEL	Logging level 0, 1, or 2
Opt	FARCASTER_TRANSPORT	`auto` (default): UDP, then TCP, then WebSocket. `udp`, `tcp` or `ws` use only that transport. WebSocket requires `FARCASTER_AGENT_TOKEN`
Opt	FARCASTER_WS_URL	WebSocket URL of the hub. Defaults to `wss://<hub host>/v1/wg`
Opt	FARCASTER_FORCE_TCP	TRUE, same as `FARCASTER_TRANSPORT=tcp`
Opt	FARCASTER_CUSTOM_CA	CA certificates (PEM file path or base64-encoded PEM) to trust in addition to the system CAs, such as an HTTPS-inspecting proxy's CA
Opt	FARCASTER_SKIP_CERT_VERIFY	TRUE, Skip certificate verification for the configuration download and the WebSocket transport. Prefer `FARCASTER_CUSTOM_CA`
Opt	HTTP_PROXY	Use the configured proxy address for all connections

Additional Windows Options

The Farcaster Agent can be run standalone or installed as a service in Windows, and controlled via environment variables or using the following command line switches as follows:

farcasterd -t <agent token> [optional switches]

Required/Optional	Switch	Description
Req	-t, --token string	Authentication token. Can either be the path to the token file, or the token itself
Opt	--api-url string	Override the default API URL
Opt	--check-token	Check if the token is valid and exit
Opt	--control string	Enable the control API on the Windows named pipe
Opt	-d, --debug	Enable debug logging
Opt	--group string	Group to grant access to the control API
Opt	--help	help for farcasterd
Opt	--ipv6	Enable IPv6/AAAA DNS query resolution
Opt	-l, --log string	Log file path. Log to stderr if not specified
Opt	--proxy-names	Use hostnames instead of IPs in proxy CONNECT/SOCKS5 requests
Opt	--transport string	Hub transport: `auto`, `udp`, `tcp` or `ws`, as in `FARCASTER_TRANSPORT`
Opt	--ws-url string	Override the hub's WebSocket URL, as in `FARCASTER_WS_URL`
Opt	-v, --version	Print the version and exit

Windows Service Control

Install the service, replacing <agent token> with your token:

farcasterd service install -t "<agent token>"

Use these commands to start, stop, or remove the service:

farcasterd service start
farcasterd service stop
farcasterd service remove

Troubleshooting

Connection issues typically fall into one or more of the following categories:

Unable to download Agent configuration

Ensure the host system can resolve api.probely.com and connect via https using e.g. curl or chrome.
Check to ensure proxy settings are not required for Agent connectivity.
CASB / HTTPS inspection capabilities which intercept the HTTPS connection for decode will result in the Agent being unable to verify the api.probely.com tls certificate. We recommend configuring the device / service performing HTTPS interception to allow the Farcaster Agent to connect directly to api.probely.com and the Farcaster hub, if that is not possible, tls cert verification can be disabled with the FARCASTER_SKIP_CERT_VERIFY=TRUE environment variable.

Unable to connect (UDP/443 or UDP & TCP/443)

If firewalls are not permitting UDP/443 outbound from the agent to the appropriate Farcaster hub, as well as the appropriate return traffic, the connection will fall back to TCP/443 and the agent will show "Connected over TCP" (with "UDP recommended") in the Snyk API & Web UI. Scans still run over TCP but can be slower, so UDP/443 is strongly recommended.
If firewalls are not permitting UDP/443 OR TCP/443 from the Agent to the Farcaster hub the agent will not be able to connect.
On networks that allow only HTTPS, the agent connects with WebSocket over TLS to the hub hostname on TCP/443, through HTTPS_PROXY or HTTP_PROXY when set. In auto mode it tries WebSocket after UDP and TCP fail, about 35 seconds after starting in userspace mode and about 3.5 minutes in kernel mode; set FARCASTER_TRANSPORT=ws to connect at once.
In some cases protocol level firewall rules (e.g allow HTTPS protocol ONLY over TCP/443, allow QUIC protocol ONLY over UDP/443, or allow "Standard Protocols only") the initial UDP connection or the initial TCP handshake will be successful, but subsequent communications will be blocked as the traffic is not using standard protocols. Protocol based rules should be disabled or set to allow the protocol identified by the firewall (typically wireguard) for Agent communications.

Please refer to network requirements for Agent connectivity requirements.

Proxy Configuration

The agent can use a proxy to connect to Snyk API & Web using standard environment variables. The agent honors HTTP_PROXY, HTTPS_PROXY, and NO_PROXY for outbound connections. HTTPS proxies are supported.

Performance Issues

While the agent can use an HTTP/S proxy or a direct TCP connection to Snyk API & Web, this can cause poor network performance. For more information, see this article about the TCP Meltdown problem. We strongly recommend that you allow the agent to connect to 54.247.135.113, 44.212.186.140, and 54.253.10.194 on UDP port 443.

UDP Connectivity testing

To confirm if nothing is blocking the UDP connections, you can set up a UDP server using the following script outside your network to "echo" the received messages:

import socket

def udp_server(host='0.0.0.0', port=12345):
    sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
    sock.bind((host, port))
    print(f"UDP server listening on {host}:{port}")

    while True:
        data, client_address = sock.recvfrom(1024)
        print(f"Received message from {client_address}: {data.decode()}")
        response = f"Received your message: {data.decode()}"
        sock.sendto(response.encode(), client_address)

if __name__ == "__main__":
    udp_server()

And test it with:

$ echo "AAAAAA" | nc -w 3 -u xx.xx.xx.xx 12345
Received your message: AAAAAA

You should test large messages:

$ python3 -c 'print("A"*2000)' | nc -w 3 -u xx.xx.xx.xx 12345
Received your message: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA....

Building from source

Build from source when developing the agent or creating a custom image. See AGENTS.md for the repository map and the two agent implementations.

Clone the repository and enter its directory:

git clone git@github.com:Probely/farcaster-onprem-agent.git
cd farcaster-onprem-agent

Run the following commands from the repository root.

Go binaries

Install Go at the version required by each module's go.mod, and GNU Make.

make -C farcaster-go VERSION=0.0.0
make -C farconn

The binaries are written to farcaster-go/bin/farcasterd and farconn/farconn.

Container images

Install Docker with Buildx to build the container. The local build target runs a privileged container to install binfmt handlers and prepares a Buildx builder.

make VERSION=0.0.0 build-local

This loads probely/farcaster-onprem-agent:v0.0.0 into Docker. Use that image name in your Docker command, Compose file, or Kubernetes deployment. Use build-local-modern for the newer Debian base; its image tag ends in -modern.

The build and build-modern targets publish images to Docker Hub. Use them only for release work.

Development checks

Install Go, GNU Make, Bash, and ShellCheck. Run the routine checks from the repository root:

make check

This runs shell syntax checks, ShellCheck, shell helper tests, and Go vet and tests in all three Go modules. The Go tests run without an agent token, so they skip the live agent lifecycle test. Use make check-shell or make check-go to run one group of checks.

For Go lint checks, install golangci-lint v2 and run make lint. This reports issues introduced since origin/main, matching CI's policy for new lint issues. CI also runs make check.

For proxy integration tests, install Docker with Compose and run:

make test-proxy
ENFORCE_PROXY=true make test-proxy

The second run blocks direct traffic inside the test container. Both commands use local test services, require container NET_ADMIN, and clean up the containers on exit. They do not need an agent token. Live agent checks are described in tests/agent/README.md.

Security considerations

Installing third-party software on your network requires some degree of trust. Being security professionals ourselves, we are very aware of this and designed Snyk API & Web following a set of security principles.

Transparency

No black boxes: code and build instructions are open source, with a permissive license.
You have complete control over the Agent and can ensure it has not been tampered with.

Least privilege

Services are containerized and run with least privileges.
The Agent is built around Zero Trust Networks design principles. All traffic is end-to-end encrypted between agents. Even inside Snyk API & Web "internal" networks.
The Agent has been hardened in several ways, from using memory-safe languages (e.g., Go and Rust) to modern, recommended cryptographic algorithms.
The Agent does not listen on any public Internet port, reducing its attack surface.

Simplicity

We believe simplicity enables security. The Agent follows simple design decisions and uses modern open-source standard components, such as WireGuard.
The Agent has minimal network requirements. Typical network requirements, such as public IP addresses and complex firewall rules, are unnecessary or minimized.
The Agent uses few hardware resources and is designed to scale easily.

Internal Firewalling

The agent may be installed in e.g. a partner DMZ or other firewalled segment to allow complete client control of the targets that can be accessed from the Agent, however, please keep in mind rules must allow connectivity for all Snyk API & Web targets, as well as any ancillary services and hosts required by those web apps and APIs.

Name		Name	Last commit message	Last commit date
.github		.github
assets		assets
compose		compose
contrib		contrib
farcaster-go		farcaster-go
farconn		farconn
scripts		scripts
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.gitleaksignore		.gitleaksignore
.golangci.yml		.golangci.yml
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
catalog-info.yaml		catalog-info.yaml

Navigation Menu

Repository navigation

About

Repository files navigation

Overview

Table of Contents

Network Architecture Overview

Architecture Notes

System Resources

Network Requirements

Installation

Required software

Docker

Kubernetes

Windows

Linux

System checks

Launch the agent

Configuration Options

Additional Windows Options

Windows Service Control

Troubleshooting

Unable to download Agent configuration

Unable to connect (UDP/443 or UDP & TCP/443)

Proxy Configuration

Performance Issues

UDP Connectivity testing

Building from source

Go binaries

Container images

Development checks

Security considerations

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Overview

Table of Contents

Network Architecture Overview

Architecture Notes

System Resources

Network Requirements

Installation

Required software

Docker

Kubernetes

Windows

Linux

System checks

Launch the agent

Configuration Options

Additional Windows Options

Windows Service Control

Troubleshooting

Unable to download Agent configuration

Unable to connect (UDP/443 or UDP & TCP/443)

Proxy Configuration

Performance Issues

UDP Connectivity testing

Building from source

Go binaries

Container images

Development checks

Security considerations

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages