Installing the Sentinel agent

Register an agent in the portal, install the signed package, register on the host with the one-time token, and confirm the tunnel. Covers the network requirements, updates from the portal or the package, host and tunnel health, and the check command for troubleshooting. mTLS to your tenant, no inbound ports.

The WASViking^® Sentinel agent installs from a signed package. The whole flow is driven from your portal: create the agent record to get a one-time token, install the package on the host, register with the token to fetch certificates, and confirm the tunnel. The mTLS tunnel comes up and the WASViking cloud can then scan your internal targets.

Supported platforms

Minimum requirements: 1 vCPU, 512 MB RAM, 1 GB disk for cache and ephemeral scan output. The commands on this page use the Ubuntu / Debian package.

For the walkthrough with portal screenshots, see WASViking Sentinel Tunnel in Getting Started. This page is the full installation reference.

Network requirements

The agent only connects out. Allow these destinations from the agent host:

• No inbound port. Nothing on the internet connects to the host, and no firewall opening toward it is needed.
• No TLS inspection on sentinel.wasviking.com. The tunnel uses mutual TLS: the agent proves its identity with its own certificate and only trusts the WASViking private CA. A proxy, firewall or endpoint security product that terminates and re-signs TLS cannot carry that handshake. Add the domain to the product's inspection bypass list. Where that list usually lives in common products is described in Endpoint protection exclusions.
• Cloud instances. Outbound rules can live in more than one place. On Amazon EC2, for example, check the security group outbound rules, the subnet network ACL, the route to a NAT or internet gateway, and any proxy in the VPC.
• Clock. Keep NTP enabled on the host. Certificate validation fails on a skewed clock.

The check command tests each of these from the host.

Step 1: Register a new agent in the portal

Sign in to portal.wasviking.com. In the left sidebar, under WASVIKING SENTINEL, open Sentinel Agents and click Add Sentinel Agent.

Set the Agent display name: a human-friendly label shown in the portal, for example London - DMZ Scanner 01. It is not the machine hostname, must be unique within your organization, and is renameable later.

Click Create. The portal issues a bootstrap token, displayed once. Copy it and keep it safe. If you lose it, revoke this agent record and create a new one.

Step 2: Download the package

Click Get Agent at the top of the Sentinel Agents page. The portal serves the right package for the platform you select.

Verify the download before installing. The Verify download (SHA256 & signature) action on the modal gives you the expected checksum and the signature to validate the artifact has not been tampered with.

Step 3: Install and enable the service

On Ubuntu / Debian:

sudo dpkg -i wasviking-sentinel_<version>_amd64.deb
sudo systemctl enable --now wasviking-sentinel

Replace <version> with the release version shown in the portal. The package installs the agent under /opt/wasviking-sentinel/, creates the wasviking-sentinel service account, and registers a systemd unit named wasviking-sentinel.

Starting the service before registering is expected. The service stays running and waits for the registration. Its status and its journal name the exact command to run next.

Step 4: Register the agent

Register the agent once, with the bootstrap token from Step 1. Run the command from any directory:

sudo /opt/wasviking-sentinel/wasviking-sentinel register --token <YOUR_TOKEN_FROM_PORTAL>

The command downloads the agent's client certificates, writes them and the configuration into /opt/wasviking-sentinel/, and hands the files to the service account. The running service picks up the registration and connects by itself within about 15 seconds. No restart is needed.

If you see instructions that run ./wasviking-sentinel register from inside the agent directory without sudo, use the command above instead. The older form fails on file permissions.

In provisioning scripts, read the token from an environment variable instead of pasting it on the command line:

export WASVIKING_BOOTSTRAP_TOKEN="<paste-from-portal>"
sudo /opt/wasviking-sentinel/wasviking-sentinel register --token "$WASVIKING_BOOTSTRAP_TOKEN"

Registration output:

Registering with WASViking API...
Certificates downloaded successfully into /opt/wasviking-sentinel/certs
Config written to /opt/wasviking-sentinel/configs/config.yaml
Agent files handed to the service account wasviking-sentinel
Next: sudo systemctl enable --now wasviking-sentinel (a service that is already running connects on its own within 15 seconds)
Then confirm the tunnel with: sudo /opt/wasviking-sentinel/wasviking-sentinel check

The private key never leaves the host. The CA certificate, the client certificate, and the client key are written under /opt/wasviking-sentinel/certs/ and belong to the service account:

sudo ls -l /opt/wasviking-sentinel/certs

-rw-r--r--  wasviking-sentinel wasviking-sentinel  ca.crt
-rw-r--r--  wasviking-sentinel wasviking-sentinel  client.crt
-rw-------  wasviking-sentinel wasviking-sentinel  client.key

Step 5: Confirm the agent is connected

sudo systemctl status wasviking-sentinel
sudo /opt/wasviking-sentinel/wasviking-sentinel status

• In the service status, the latest lines include Tunnel connected to sentinel.wasviking.com:443.
• status shows the agent state and, while the tunnel is down, the last connection error.
• In the portal, the agent shows as Active on the Sentinel Agents page within a few seconds.

If one of the three does not match, run the check command.

The config file

register writes /opt/wasviking-sentinel/configs/config.yaml:

grpc_server: sentinel.wasviking.com
agent_hostname: dmz-scanner-01
agent_id: ""
use_tls: true
tls_ca_cert: certs/ca.crt
tls_cert: certs/client.crt
tls_key: certs/client.key
use_mtls: true
log_path: logs/sentinel_agent.log

agent_id is empty until the first run. The service populates it automatically and persists it back to the file. You do not need to edit this file by hand in the common case.

# After the first run, agent_id is filled in:
agent_id: 56b3bd08aa4d5201edafd434740d9c140c1e477742d47360d71a76842b09ec21  # auto-generated on first run, do not edit

Agent status

In Sentinel Agents, each agent shows one of:

Counters at the top of the page summarize the fleet: Total · Active · Pending · Offline · Revoked.

If the agent stays Pending

If an agent remains Pending for more than a few minutes, run the check on the host:

sudo /opt/wasviking-sentinel/wasviking-sentinel check

Its verdict names the cause and the next step. The usual causes are an agent that was never registered, a service that cannot read its files, outbound TCP 443 to sentinel.wasviking.com blocked, TLS inspection on the path, and a skewed clock. See Troubleshooting with the check command.

How the portal lists agents

On Sentinel → Sentinel Agents, the Scan Tunnels list shows:

Connected agents come first, then the ones that need attention, the ones still waiting for their registration and the revoked ones. Click a column header to sort the list by it and click it again to reverse the order; Status brings back the default order.

Trigger your first internal scan

With the agent Active, create a target whose URL resolves only inside your network. On the New Scan screen, the agent appears in the routing selector (Execution Mode). Pick it, configure auth if needed, and start the scan. Every analyzer routes its HTTP probes through the tunnel.

See Internal scanning for the full walkthrough.

Certificate rotation and revocation

Both are operator actions in the portal, no host change needed.

• Rotate. From the agent's row actions, click Rotate certificate. The portal issues a new certificate set; the agent picks it up on the next reconnect. The previous certificate is immediately revoked WASViking-side.
• Revoke. Click Revoke. The certificate is invalidated immediately; the agent's status flips to Revoked and the tunnel drops. The host record stays in the list for audit.

The client certificate also auto-rotates before expiry as defense-in-depth.

Update from the portal

From version 1.23.0, an agent installed from the Debian package can be updated from the portal. You choose the agents to update, and each one downloads, verifies and installs the new signed release by itself. No session on the host is needed.

Requirements

Update one agent or all of them

1. Open Sentinel → Sentinel Agents and select the Scan Tunnels tab.
2. Click Update on the agent row. To update every agent that can be updated, click Update all (N) in the tab header.
3. Review the confirmation and confirm. The agent downloads the signed package, verifies it and installs it. Its tunnel restarts and reconnects in about a minute, and scans running through it pause until then.

The page refreshes by itself while the update runs, and the row follows it to the end. To avoid pausing a long internal scan, update the agent when no scan is running through it.

The update installs the standard Debian package, the same one you install by hand. The package manager on the host shows the new version, and the certificates and the configuration are kept:

dpkg -l wasviking-sentinel

Reading the Version column

On the Scan Tunnels tab, the Version column shows the version each agent runs, for example v1.23.0, with a badge:

The Scan Tunnels card at the top of the page counts the agents behind the current release, for example 2 UPDATES AVAILABLE (vX.Y.Z).

An agent older than 1.23.0 does not report its version. Its row shows Not reported and the note Update once from the package to enable remote updates. When an update is available but the agent cannot take it from the portal, a note under the badge says why, for example that the agent is not connected or that remote updates are turned off on that host. The agent's Details page shows the same information in its Remote updates line.

How remote updates are protected

• Only packages signed by WASViking are installed. The agent verifies the signature and the checksum of the package. A separate installer, which runs with administrator rights on the host, verifies them again before it installs anything.
• No downgrades. A package that is not newer than the installed version is refused.
• The agent stays unprivileged. The agent keeps running under its own wasviking-sentinel service account. Only the installer runs with administrator rights, and only to install a verified package.
• The host administrator decides. Remote updates can be turned off on any host, as described below.

Turning remote updates off on a host

An agent installed from the package accepts remote updates. A host administrator can turn them off on that host:

sudo systemctl mask wasviking-sentinel-update.path

The setting survives package upgrades. While remote updates are off, the portal shows that they are turned off on that host and refuses an update with that reason. Upgrades from the package keep working.

To turn remote updates back on:

sudo systemctl unmask wasviking-sentinel-update.path
sudo systemctl enable --now wasviking-sentinel-update.path

The check command has a Remote updates line that says whether the host accepts remote updates and how the last one ended. On a host where they are turned off:

  [INFO] Remote updates
         remote updates are turned off on this host (wasviking-sentinel-update.path is masked)
         Next step: To allow them again: sudo systemctl unmask wasviking-sentinel-update.path &&
         sudo systemctl enable --now wasviking-sentinel-update.path

If an update fails

The row shows UPDATE FAILED with the cause in plain words under the badge, for example Download failed or Package failed verification. View details opens:

• where the update stopped: requested, delivered to the agent, downloaded and verified, installed and reconnected;
• what happened, and whether the host was left as it was;
• the next steps for that cause, with the commands to run on the host and Retry update when the agent can take the update now;
• Technical details: a reference, the versions, the times and the original message, which Copy details for support puts on the clipboard for a support request.

On the host, the installer log and the check give the full detail:

sudo journalctl -u wasviking-sentinel-update -n 50
sudo /opt/wasviking-sentinel/wasviking-sentinel check

Fix the cause and click Update again, or upgrade from the package. When the download or a verification fails, nothing is installed and the agent keeps its current version.

Upgrade from the package

Use the package for an agent that cannot be updated from the portal: an agent older than 1.23.0, one installed by other means, or a host where remote updates are turned off. Download the new package from Get Agent and install it over the existing one:

sudo dpkg -i wasviking-sentinel_<new-version>_amd64.deb
sudo systemctl enable --now wasviking-sentinel

The upgrade keeps certs/ and configs/config.yaml, so the agent does not need to register again. The second command makes sure the service is enabled and running on the new version, and changes nothing when it already is. Then confirm the tunnel with sudo /opt/wasviking-sentinel/wasviking-sentinel check. Once the host runs 1.23.0 or later from the Debian package, the next updates can run from the portal.

If you added a local systemd override for an older version, for example to run the agent as root, it is no longer needed: the current version runs as the wasviking-sentinel account. The check reports it as [WARN] Local service overrides and prints the exact command that removes it.

Host and tunnel health

When scans through a private tunnel run slow or time out, start with that tunnel's details. Open Sentinel → Sentinel Agents, select the Scan Tunnels tab and click Details on the agent row. The Host and tunnel health section shows how the host is doing and how much scan work the tunnel is carrying.

What the agent reports

From version 1.24.0, the agent sends a report once a minute while its tunnel is connected. The report travels over the outbound connection the agent already uses, so there is nothing new to open in a firewall.

• The report carries numbers, plus the name of the host's operating system and its kernel version. The Details page shows them in its Operating system and Kernel lines.
• It carries no request or response content, no target data and no process list.
• Reports are kept for seven days.
• Host numbers are measured on Linux. An agent running on macOS, which is supported for local evaluation, shows only the agent and tunnel numbers.

On an older agent, the section reads Host and tunnel health needs a newer agent and sends you to the Sentinel Agents page to update it. See Update from the portal, or Upgrade from the package for a host that cannot take remote updates.

Tiles and charts

A status line says when the last report arrived. The tiles show the latest report:

A tile turns amber or red when its value crosses a warning level.

The charts below the tiles follow the same numbers over time:

Switch the window between 1h, 24h and 7d. While the page is open, the charts refresh every minute. A gap in a line means the agent did not report during that time. Click a legend entry to hide or show its line.

Observations

Above the tiles, the section describes what it sees in plain language, mostly over the last 15 minutes:

The built-in check runs on the host:

sudo /opt/wasviking-sentinel/wasviking-sentinel check

How to read it

• Tunnel busy near 100%. Scans are queuing on that agent. Install more agents that reach the same targets and spread the targets across them, or schedule the scans at different times.
• High host CPU or memory. The host needs more resources, or fewer other workloads running next to the agent.
• Repeated reconnections. The cause is on the network path between the host and WASViking. The check names the root cause and the next step. See Troubleshooting with the check command.

Uninstall

sudo systemctl disable --now wasviking-sentinel
sudo dpkg -r wasviking-sentinel
sudo rm -rf /opt/wasviking-sentinel

In the portal, Revoke the agent record so the certificate's CN is no longer accepted on the WASViking side.

Troubleshooting with the check command

check is a read-only diagnostic of the agent installation and of the path from the host to the WASViking platform. Run it when an agent stays Pending, goes Offline, or before you contact support:

sudo /opt/wasviking-sentinel/wasviking-sentinel check

Run it with sudo. Without elevation the check cannot read the agent files, and the report says so.

Reading the report

The report opens with a verdict, the most likely root cause and the next step, given as an exact command or setting to change. For example, on a cloud instance whose outbound traffic is dropped:

VERDICT: FAIL
  Root cause candidate: Tunnel endpoint TCP reachability. TCP connection to
  sentinel.wasviking.com:443 failed: connection timed out; the packets are being silently dropped,
  which is typical of a firewall, security group or egress filter.
  Next step: Allow outbound TCP 443 to sentinel.wasviking.com:443: the instance security group
  outbound rules, the subnet network ACL (including return traffic on ephemeral ports), the route to
  a NAT or internet gateway, and any proxy or network firewall in the VPC.

The verdict is PASS, WARN or FAIL. Three sections follow, and each finding in them is marked PASS, WARN, FAIL, INFO or SKIP:

Live tunnel test

When the agent's own tunnel is down, the check briefly opens the tunnel with the agent's identity to confirm that the platform accepts it. During those few seconds the portal shows the agent as Active. A scan routed to the agent during the test is answered as not executed; start it again afterward. Add --no-tunnel to skip the test, or --tunnel to run it even when the agent reports its tunnel up.

Support bundle

Each run writes two files in the current directory: wasviking-sentinel-check_<host>_<timestamp>.json and wasviking-sentinel-check_<host>_<timestamp>.txt. They are created with mode 0600, belong to your account even when you run the check with sudo, and contain no tokens or private keys. Send both files to WASViking support: they let the team analyze the host without a session on it.

Options and exit codes

The exit code is 0 when the agent is healthy, 1 with warnings and 2 with failures, so a provisioning script can stop on a failed check.

Common problems

If the verdict is PASS and the portal still shows the agent as Pending or Offline, send the support bundle to WASViking support.