Discovery Proxies

Objective: Deploy a vScope Discovery Proxy and connect it to the main vScope to scan remote/segmented networks.

When to use

• DMZs, remote sites, customer/tenant networks, or any segment the main vScope cannot reach directly.
• You can run multiple proxies; assign each to its own target ranges.

Prerequisites

• Port open from proxy → main vScope (default TCP 4445; configurable).
• Host near the target network:
  • OS: Windows (full features). Linux, Docker, and Kubernetes proxies cannot use WMI; use WinRM/PowerShell for Windows targets.
  • Windows/Linux host sizing: CPU: 2 cores; RAM: 6 GB (4 GB to vScope); Disk: ~10 GB.
• Main vScope address/hostname and chosen port.
• Network access from the proxy to the discovery targets on the ports required by each datasource.

Secure design

All communication between the proxy and master is secured by TLSv1.3 and that every proxy needs to be approved in the master before it is allowed to take part in discoveries.

Install the proxy

Windows

1. Download the installer: latest-Setup.exe
2. Run installer; set Host Address to the main vScope (IP/DNS).
3. Set Port (default 4445) if different.
4. Finish and start the service.

Change the host or port after installation

Rerun the Windows proxy installer and update Host Address or Port.

If you change the port, also set proxy.master.port=<port> in the main vScope’s config.ini and allow that port through the firewall. All proxies must use the port configured on the main vScope.

Linux

Caution

Linux proxy cannot do WMI; use WinRM/PowerShell for Windows targets.

1. Download the package as vscope-proxy-amd64.deb, then install it:

   curl -fL -o vscope-proxy-amd64.deb https://dist.vscope.net/proxy/release/latest-amd64.deb
   sudo apt install ./vscope-proxy-amd64.deb

2. Edit /etc/vscopeproxy/config.ini. Replace YOUR-VSCOPE-MASTER with the main vScope hostname or IP, and change the port if needed:

   proxy.master.host=YOUR-VSCOPE-MASTER
   proxy.master.port=4445

3. Edit /etc/default/vscopeproxy. Set the existing JAVA_OPTS line to allocate a 4 GB maximum Java heap, preserving any other custom JVM options:

   JAVA_OPTS="$JAVA_OPTS -Xmx4g"

   This assumes the recommended 6 GB proxy host, leaving headroom for the OS and the JVM memory outside the heap.

4. Restart the proxy service to apply the settings:

   sudo service vscopeproxy restart

5. Continue with Register in vScope, then run a discovery to verify the connection.

Change the host or port after installation

Edit proxy.master.host and proxy.master.port in /etc/vscopeproxy/config.ini, then run sudo service vscopeproxy restart.

If you change the port, also set proxy.master.port=<port> in the main vScope’s config.ini and allow that port through the firewall. All proxies must use the port configured on the main vScope.

Docker

You need a Docker host with access to the image registry. Commands below use a Bash-compatible shell.

1. Create a volume for the proxy’s identity, configuration, and logs:

   docker volume create vscope-proxy-data

2. Set -Dproxy.master.host and -Dproxy.master.port in JAVA_OPTS. Replace YOUR-VSCOPE-MASTER with the main vScope hostname or IP, and change 4445 if needed.

   docker run -d \
     --pull always \
     --name vscope-proxy \
     --restart unless-stopped \
     --stop-timeout 330 \
     --memory 6g \
     -v vscope-proxy-data:/data \
     -e 'JAVA_OPTS=-Xmx4g -Dproxy.master.host=YOUR-VSCOPE-MASTER -Dproxy.master.port=4445' \
     europe-docker.pkg.dev/isl-vscope/release/vscope-proxy:latest

   Adjust the heap for your discovery workload. Keep the volume mounted at /data.

3. Check that the container is running:

   docker ps --filter name=vscope-proxy

   If startup fails, inspect the container logs.

4. Continue with Register in vScope, then run a discovery to verify the connection.

Change the host or port after installation

Update -Dproxy.master.host or -Dproxy.master.port in the docker run command’s JAVA_OPTS, then recreate the container with the same data volume mounted at /data.

If you change the port, also set proxy.master.port=<port> in the main vScope’s config.ini and allow that port through the firewall. All proxies must use the port configured on the main vScope.

Kubernetes

You need a cluster, kubectl access, and a default StorageClass that can provision a ReadWriteOnce volume. Nodes must be able to pull the image, and pods must be able to resolve and reach the main vScope and discovery targets.

1. Choose an existing namespace. The commands and manifest below use default, matching the server installation guide; replace it throughout if needed:

   kubectl get namespace default
   kubectl get storageclass

   Check that a StorageClass is marked (default). If your cluster has no default, or you need a different class, add storageClassName: <your-storage-class> under the PVC’s spec in the manifest below.

2. Save the following as vscope-proxy.yaml. Set the master hostname and port in JAVA_OPTS, replacing YOUR-VSCOPE-MASTER and changing 4445 if needed.

   If the server was deployed using the server installation guide in the same namespace, use vscope-server as the master hostname. From another namespace, use vscope-server.<server-namespace> (for example, vscope-server.default). For a server outside the cluster, use its reachable hostname or IP. The proxy connects to TCP 4445, not the server’s HTTP Ingress.

   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
     name: vscope-proxy-data
     namespace: default
   spec:
     accessModes:
       - ReadWriteOnce
     resources:
       requests:
         storage: 10Gi
   ---
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: vscope-proxy
     namespace: default
   spec:
     replicas: 1
     strategy:
       type: Recreate
     selector:
       matchLabels:
         app: vscope-proxy
     template:
       metadata:
         labels:
           app: vscope-proxy
       spec:
         terminationGracePeriodSeconds: 330
         containers:
           - name: vscope-proxy
             image: europe-docker.pkg.dev/isl-vscope/release/vscope-proxy:latest
             imagePullPolicy: Always
             env:
               - name: JAVA_OPTS
                 value: >-
                   -Xmx4g
                   -Dproxy.master.host=YOUR-VSCOPE-MASTER
                   -Dproxy.master.port=4445
             resources:
               requests:
                 cpu: "1"
                 memory: 6Gi
               limits:
                 memory: 6Gi
             volumeMounts:
               - name: data
                 mountPath: /data
         volumes:
           - name: data
             persistentVolumeClaim:
               claimName: vscope-proxy-data

   Keep one replica and Recreate. Reuse the PVC when upgrading.

3. Apply the manifest:

   kubectl apply -f vscope-proxy.yaml

4. Wait for the deployment and check its storage:

   kubectl -n default rollout status deployment/vscope-proxy --timeout=600s
   kubectl -n default get pods -l app=vscope-proxy
   kubectl -n default get pvc vscope-proxy-data

   Expect a running pod and a PVC with status Bound. If startup fails, see Check Kubernetes startup.

5. Continue with Register in vScope, then run a discovery to verify the connection.

Change the host or port after installation

Update -Dproxy.master.host or -Dproxy.master.port in the manifest’s JAVA_OPTS, then apply the change:

kubectl apply -f vscope-proxy.yaml

If you change the port, also set proxy.master.port=<port> in the main vScope’s config.ini and allow that port through the firewall. All proxies must use the port configured on the main vScope.

Register in vScope

1. In vScope, go to Discovery → Proxies → Available; click Refresh if needed.
2. Approve the proxy; it moves to Approved. If it shows Pending, wait for first data to be sent and validated.
3. (Optional) Rename and assign targets/ranges to the proxy; click Save.

Tip

You may also assign targets to proxy from Discovery > Targets.

Verify

1. Assign a target, an IP or a range to the proxy.
2. Run discovery; open Log History or build a quick IP table to confirm assets are found via the proxy.

Frequently asked questions Review the FAQ for Discovery proxies.

Troubleshooting

• Proxy disconnected/pending: see detailed guide → Proxy not appearing or disconnected
• Pending status persists: ensure proxy reaches main vScope on the chosen port; check proxy log C:\vScopeProxyData\log\debug.log (Windows) or /var/log/vscopeproxy/debug.log (Linux, path may vary).
• Failed discovery results: assign correct credentials to targets; ensure target ports are open from the proxy.

Related

• Concept: Proxies
• Ports: Ports used by vScope
• FAQ: Discovery Proxy FAQ
• Troubleshooting: Proxy not appearing or disconnected