You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This document will guide you through the installation of the Farcaster Agent.
4
4
5
-
The Farcaster Agent connects Probely to your on-premises network using an encrypted WireGuard
6
-
tunnel, allowing Probely to scan your internal applications.
5
+
The Farcaster Agent connects Probely to your private networks (i.e. on-premise, private cloud, CICD runner environments, etc.) using an encrypted WireGuard tunnel and proxy, allowing Probely to scan your internal applications with minimal network & security configuration changes.
7
6
8
7
The Agent is open-source, and the code is freely available on the official
1. Client edge security devices (FW, IPS, WAF, etc.) should be configured to whitelist Snyk API & Web Scanner and Asset Discovery service IPs. Internal security devices (FW, IPS, WAF, etc.) should be configured to whitelist any scanning agent IPs.
31
+
2. Firewall protocol inspection must be disabled for Farcaster Agent connectivity. TLS Inspection (e.g NGFW or CASB) is not currently supported and should be disabled for Agent connectivity rules in any edge/cloud security devices or services.
32
+
3. If required, Farcaster Agent will support tunnel connectivity via proxy, however performance may be impacted.
33
+
4. 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)
34
+
5. api.probably.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.
35
+
6. Private container registries can be utilized if required.
36
+
17
37
# System Resources
18
38
19
-
The Agent is a Docker container requiring very few resources, as detailed in the following table.
39
+
The Agent is a Docker container requiring minimal resources, as detailed in the following table.
20
40
21
-
| CPU | RAM | Storage |
22
-
| ------- | ------- | ----------- |
23
-
| 1 | 512 MB | 1 GB |
41
+
| CPU | RAM | Storage |
42
+
| ------- | ------- | ----------- |
43
+
| 1 | 512 MB | 1 GB |
24
44
25
45
# Network Requirements
26
46
27
-
**NOTE**: You do not need to manually add firewall rules on most networks.
28
-
Some rules may be required if the agent runs on a network with strict network policies (e.g., all **output** traffic
29
-
is denied by default).
30
-
31
-
To specify a port range, we use the `:` character. For example, `1024:2048`
32
-
means: *all ports from 1024 to 2048, inclusive*.
33
-
34
47
| Name | Source | Destination | Protocol | Source Port | Destination Port |
| API |`<agent-ip>`<sup>1</sup> |`api.probely.com`<sup>4</sup> |`TCP`|`any`|`443`|
@@ -43,107 +56,151 @@ means: *all ports from 1024 to 2048, inclusive*.
43
56
44
57
Notes:
45
58
46
-
1.`<agent-ip>` is the internal IP of the machine on your network where Probely's Farcaster Agent is running. The agent uses it to communicate with the Probely server.
47
-
2.`<target-ip>` is the internal IP of your web application.
48
-
If your target is configured to use internal extra-hosts, include their IPs here.
49
-
The same goes for the target login URL if a different internal web application serves it.
50
-
3.`<target-port>` is the service port of the server of your web application.
51
-
Typical values are 80 and 443.
52
-
4. The IP addresses of these hosts are subject to change. We recommend allowing
53
-
web access for the agent VM (HTTP and HTTPS ports). If this is not possible, the agent
54
-
will use an HTTP proxy if you set the `HTTP_PROXY` variable.
55
-
5. At this time, the hosts are: `registry.docker.io` and `registry-1.docker.io`
56
-
6. This server receives connections from potentially vulnerable systems on your infrastructure.
57
-
It is used, for example, to detect "Log4Shell"-type vulnerabilities.
59
+
1.`<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.)
60
+
2.`<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.
61
+
3.`<target-port>` is the TCP port used to access your web applications & apis on the target host (typically 80, 443, 8080, 8443, etc.)
62
+
4. 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.
63
+
5. At this time, the hosts are: `registry.docker.io` and `registry-1.docker.io`
64
+
6. 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 vulnerabilitites if the connections are not allowed.
58
65
59
66
# Installation
60
67
61
-
The agent runs on a Docker container. It should work on any system with a Docker installation.
68
+
The Farcaster agent can be deployed as a container in Docker or Kubernetes, or as Windows or Linux service.
62
69
63
-
The agent needs a token to connect to Probely's network.
70
+
The agent needs a token to connect to Probely's network.
64
71
65
-
> If you do not have an agent token, you can create one in the
If you need help setting the Agent up on a Kubernetes cluster, please contact
78
-
Probely's support team.
80
+
### Kubernetes
81
+
We provide an example Agent Kubernetes deployment [here](https://github.com/probely/farcaster-onprem-agent/tree/main/contrib/kubernetes/).
79
82
80
-
## System checks
81
-
* Before installing the agent container, check that your host can run it:
83
+
If you need help setting the Agent up on a Kubernetes cluster, please contact Probely's support team.
84
+
85
+
### Windows
86
+
Download the latest Window binary from the releases page [here](https://github.com/Probely/farcaster-onprem-agent/releases)
87
+
88
+
### Linux
89
+
Download and compile the source code to run the Farcaster Agent as a service on Linux.
90
+
91
+
## System checks
92
+
Before installing the agent container on a Linux system, you can check that your host can run it by executing the following [script](https://raw.githubusercontent.com/Probely/farcaster-onprem-agent/main/farconn/host-check.sh) or run the command below:
* Use the `docker-compose.yml` you saved in**Step 1.** of
96
-
[How to install a Scanning Agent](https://help.probely.com/en/articles/6503388-how-to-install-a-scanning-agent).
104
+
```
105
+
106
+
## Launch the agent
107
+
* Use the `docker-compose.yml` you saved in**Step 1** of
108
+
[How to install a Scanning Agent](https://help.probely.com/en/articles/6503388-how-to-install-a-scanning-agent).
97
109
98
-
* Start the Agent:
110
+
* Start the Agent:
99
111
100
-
```shell
101
-
docker-compose up -d
102
-
```
112
+
```shell
113
+
docker-compose up -d
114
+
```
103
115
104
-
* Check that the Agent connected successfully
116
+
* Check that the Agent connected successfully
105
117
106
-
After starting the Agent, it should link-up with Probely. Run the following command:
107
-
```shell
118
+
After starting the Agent, it should link-up with Probely. Run the following command:
119
+
```shell
108
120
docker logs probely-agent
109
-
```
121
+
```
110
122
111
123
If everything is running correctly, you should see output similar to:
112
-
```
113
-
Downloading agent configuration ... done
114
-
Deploying agent configuration ... done
115
-
Starting local DNS resolver ... done
116
-
Setting HTTP proxy rules ... done
117
-
Connecting to Probely (via UDP) ... done
118
-
Setting local gateway rules ... done
119
-
Starting WireGuard gateway ... done
120
-
121
-
Running...
122
-
```
123
-
124
-
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.
125
-
Learn more about [how to scan internal applications with a Scanning Agent](https://help.probely.com/en/articles/4615595-how-to-scan-internal-applications-with-a-scanning-agent).
126
124
127
-
### Connection issues
128
-
If the Agent is not connecting to Probely, please ensure that your [firewall](#network-requirements) is properly configured.
129
-
130
-
Alternatively, the agent can use a proxy to connect to Probely using standard environment variables. The agent honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`for outbound connections. HTTPS proxies are supported. `ALL_PROXY` is honored for WebSocket connections (ws://, wss://) via the standard library HTTP transport, but not for raw TCP connections.
131
-
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](https://web.archive.org/web/20220103191127/http://sites.inka.de/bigred/devel/tcp-tcp.html) 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`.
132
-
133
-
### Unsuccessful UDP connection issues
134
-
If the Agent is not connecting through UDP, and you are getting the log:
135
-
136
-
```
137
-
...
138
-
Connecting to Probely (via UDP) ... unsuccessful
139
-
Configuring fallback TCP tunnel ... done
140
-
Connecting to Probely (via TCP) ... done
141
-
...
142
-
```
125
+
```
126
+
Downloading agent configuration ... done
127
+
Deploying agent configuration ... done
128
+
Starting local DNS resolver ... done
129
+
Setting HTTP proxy rules ... done
130
+
Connecting to Probely (via UDP) ... done
131
+
Setting local gateway rules ... done
132
+
Starting WireGuard gateway ... done
133
+
134
+
Running...
135
+
```
143
136
144
-
It's because the UDP connection is being blocked.
137
+
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.
138
+
Learn more about [how to scan internal applications with a Scanning Agent](https://help.probely.com/en/articles/4615595-how-to-scan-internal-applications-with-a-scanning-agent).
145
139
146
-
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:
140
+
### Configuration Options
141
+
The following configuration options can be set via environment variables when running the agent
| Opt | HTTP_PROXY | Use the configured proxy address for all connections |
151
+
152
+
### Additional Windows Options
153
+
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:
| Req | -t, --token string | Authentication token. Can either be the path to the token file, or the token itself
160
+
| Opt | --api-url string | Override the default API URL
161
+
| Opt | --check-token | Check if the token is valid and exit
162
+
| Opt | --control string | Enable the control API on the Windows named pipe
163
+
| Opt | -d, --debug | Enable debug logging
164
+
| Opt | --group string | Group to grant access to the control API
165
+
| Opt | --help |helpfor farcasterd
166
+
| Opt | --ipv6 | Enable IPv6/AAAA DNS query resolution
167
+
| Opt | -l, --log string | Log file path. Log to stderr if not specified
168
+
| Opt | --proxy-names | Use hostnames instead of IPs in proxy CONNECT/SOCKS5 requests
169
+
| Opt | -v, --version | Print the version and exit
170
+
171
+
#### Windows Service Control
172
+
farcasterd service install -t [Agent token] Install Farcasterd Service
173
+
farcasterd servive start | stop Start or Stop Farcasterd Service
174
+
farcasterd service remove Uninstall Farcasterd Service
175
+
176
+
177
+
# Troubleshooting
178
+
Connection issues typically fall into one or more of the following categories:
179
+
180
+
### Unable to download Agent configuration
181
+
- Ensure the host system can resolve api.probely.com and connect via https using e.g. curl or chrome.
182
+
- Check to ensure proxy settings are not required for Agent connectivity.
183
+
- CASB / HTTPS inpection capabilitites which intercept the HTTPS connection for decode will result
184
+
in the Agent being unable to verify the api.probely.com tls cerfificate. We recommend configuring the
185
+
device / service performing HTTPS interception to allow the Farcaster Agent to connect directly to
186
+
api.probely.com and the Farcaster hub, if that is not possible, tls cert verification can be disabled with
187
+
the FARCASTER_SKIP_CERT_VERIFY=TRUE environment variable.
188
+
189
+
### Unable to connect (UDP/443 or UDP & TCP/443)
190
+
- 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 with Issues"in the Snyk API & Web UI.
191
+
- 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.
192
+
- In some cases protocol level firewall rules (e.g allow HTTPS protocol ONLY over TCP/443, allow QUIC prorocol 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.
193
+
194
+
Please refer to [network requirements](#network-requirements) for Agent connectivity requirements.
195
+
196
+
### Proxy Configuration
197
+
The agent can use a proxy to connect to Probely using standard environment variables. The agent honors `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`for outbound connections. HTTPS proxies are supported. `ALL_PROXY` is honored for WebSocket connections (ws://, wss://) via the standard library HTTP transport, but not for raw TCP connections.
198
+
199
+
### Performance Issues
200
+
While the agent can use an HTTP/S proxy or a direct TCP connection to Probely, this can cause poor network performance. For more information, see this article about the [TCP Meltdown](https://web.archive.org/web/20220103191127/http://sites.inka.de/bigred/devel/tcp-tcp.html) 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`.
201
+
202
+
### UDP Connectivity testing
203
+
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:
Received your message: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA....
178
235
```
179
236
237
+
180
238
# Building from source
181
239
182
240
This step is **not** required to run the Agent.
@@ -195,10 +253,10 @@ root.**
195
253
```shell
196
254
VERSION=0.0.0 make build-local
197
255
```
198
-
199
-
Remember to reference your custom-built Docker images on the `docker-compose.yml`
200
-
fileor Kubernetes pod/deployment manifest you configure. If not specified,
201
-
the default Probely docker Agent images are used.
256
+
# Container Images
257
+
Remember to reference your custom-built Docker images in your docker command, in your`docker-compose.yml`
258
+
file, or Kubernetes pod/deployment manifest. If not specified,
259
+
the default Probely docker Agent images are used. Internal repositories can be used by pushing the appropriate images and modifying docker, docker compose, or Kubernetes manifests appropriately.
202
260
203
261
# Security considerations
204
262
@@ -232,3 +290,8 @@ components, such as [WireGuard](https://www.wireguard.com/).
232
290
* The Agent has minimal network requirements. Typical network requirements,
233
291
such as public IP addresses and complex firewall rules, are unnecessary or minimized.
234
292
* The Agent uses few hardware resources and is designed to scale easily.
293
+
294
+
**Internal Firewalling**
295
+
296
+
The agent may be installed in e.g. a partner DMZ or other firwalled 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.
0 commit comments