This document will guide you through the installation of the Farcaster Agent.
The Farcaster Agent connects Probely to your on-premises network, using an encrypted WireGuard tunnel, allowing Probely to scan your internal applications.
The Agent is open-source, and the code is freely available on the official repository.
The following diagram shows an example network topology depicting an on-premises network, the Agent, the Agent Hub (where on-premises Agents connect to), and Probely's infrastructure.
The Agent is a Docker container requiring very few resources, as detailed in the following table.
CPU | RAM | Storage |
---|---|---|
1 | 512 MB | 1 GB |
NOTE: you do not need to manually add firewall rules on most networks. Some rules may be required if the agent is running on a network with strict network policies (e.g., all traffic is denied by default).
To specify a port range, we use the :
character. For example, 1024:2048
means: all ports from 1024 to 2048, inclusive.
Name | Source | Destination | Protocol | Source Port | Destination Port |
---|---|---|---|---|---|
API | <agent-ip> 1 |
api.probely.com 4 |
TCP |
1024:65535 |
443 |
Tunnel | <agent-ip> |
54.247.135.113 , 44.212.186.140 |
UDP |
1024:65535 |
443 |
DNS | <agent-ip> |
<internal-dns-resolvers> |
TCP , UDP |
any |
53 |
Scan | <agent-ip> |
<target-ip> 2 |
TCP |
1024:65535 |
<target-port> 3 |
OOB Vulnerability Check 6 | <agent-ip> , <target-ip> |
52.17.201.157 , 52.72.180.55 |
TCP |
1024:65535 |
53 , 80 , 443 , 389 |
OOB Vulnerability Check 6 | <agent-ip> , <target-ip> |
52.17.201.157 , 52.72.180.55 |
UDP |
1024:65535 |
53 |
Docker | <agent-ip> |
auth.docker.io , registry*.docker.io 5 |
TCP |
1024:65535 |
443 |
Notes:
<agent-ip>
is the internal IP of the machine on your network where the Probely's Farcaster Agent is running. It is used by the agent to communicate with the Probely server.<target-ip>
is the internal IP of your web application. If your target is configured to use internal extra-hosts, include their IPs here. The same goes if the target login URL is served from a different internal web application.<target-port>
is the service port of the server of your web application. Typical values are 80 and 443.- The IP addresses of these hosts are subject to change. We recommend allowing
web access for the agent VM (HTTP and HTTPS ports). 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
andregistry-1.docker.io
- This server receives connections from potentially vulnerable systems on your infrastructure. It is used, for example, to detect "Log4Shell"-type vulnerabilities.
The agent runs on a Docker container. It should work on any system with a Docker installation.
The agent needs an API token to connect to Probely's network.
If you do not have an agent token, you can create one in the Scanning Agents management area.
Both Docker and Docker Compose must be installed for these instructions to work. Please make sure those requirements are met.
We provide an example Agent Kubernetes deployment here. If you need help setting the Agent up on a Kubernetes cluster, please contact Probely's support team.
-
Before installing the agent container, check that your host can run it:
curl -LO https://raw.githubusercontent.com/Probely/farcaster-onprem-agent/main/farcaster/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]
-
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 Probely. 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...
If the Agent is not connecting to Probely, please ensure that your firewall is properly configured.
Alternatively, the agent can use an HTTP proxy to connect to Probely, if the
HTTP_PROXY
environment variable is set on thedocker-compose.yml
file.
While the agent can use an HTTP proxy or a direct TCP connection to Probely, 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 to54.247.135.113
and44.212.186.140
onUDP
port443
.Once up and running, the Agent in the Docker container knows the URL or IP of the target to scan from the target configuration in Probely. The Agent communicates with Probely to get this information before starting a scan.
Learn more about how to scan internal applications with a Scanning Agent.
This step is not required to run the Agent.
Follow these instructions if you want to understand how the Container is built.
Check out the code from the repository:
git clone [email protected]:Probely/farcaster-onprem-agent.git
Unless otherwise specified, these instructions must be run on the repository root.
VERSION=local make build-local
Remember to reference your custom-built Docker images on the docker-compose.yml
file, or Kubernetes pod/deployment manifest you configure. If not specified,
the default Probely docker Agent images are used.
Installing third-party software on your network requires some degree of trust. Being security professionals ourselves, we are very aware of this, and designed Probely 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 that 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 Probely's "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, complex firewall rules are unnecessary or minimized.
- The Agent uses few hardware resources and is designed to scale easily.