Skip to main content

Install the Linux agent service (preview)

Run discovery continuously as a dedicated, unprivileged system service. This preview is validated on Ubuntu 24.04, x86_64, Python 3.12 and systemd 255. Windows, Windows Server and macOS native installers are still in development; use the foreground Python workflow on those systems.

The administrator installs the service. Discovery runs as sectigoqr, with no login shell, supplementary groups or Linux capabilities. The service starts at boot. Root retains the credential source; systemd provides a private read-only copy to the service. Installation does not grant access to repositories or captures automatically.

1. Prepare and verify the release​

Use the 0.25.1 discovery bundle from Developer tools. Download its ZIP, manifest and signature, then follow the verification instructions with a reviewed verifier and independently trusted release key. Do not execute code from an unverified ZIP. Keep the verified ZIP, manifest, signature and trusted key for installation.

The preview uses the published development signing key. Enterprise key custody, automatic updates, other distributions and physical power-loss recovery validation remain unfinished. Test the preview on a dedicated host before wider rollout.

On a connected machine with Python and pip, from the verified extracted bundle:

python scanner/download_dependencies.py --directory wheels-linux-x86_64-py312

This prepares seven exact, hash-locked Linux dependencies. It can run on Windows; the downloaded wheels are for Linux. Copy the completed wheel directory and verified release files to the Ubuntu host. The download command does not need root or an agent credential. Existing matching directories are verified and reused; incomplete or changed directories are preserved and rejected.

On Ubuntu, provision the distribution's Python 3.12 and python3-venv packages through your normal package-management process. From the extracted bundle, create the protected environment:

sudo /usr/bin/python3 scanner/create_environment.py --python /usr/bin/python3 --directory /opt/sectigo-python --wheelhouse /path/to/wheels-linux-x86_64-py312

Replace the wheel directory with its real absolute path. Environment creation runs offline. Its parent must already exist and be root-owned. A failed environment is retained with a pending marker; correct the cause and use a new environment directory. Do not remove the marker to bypass checks.

2. Enroll and set local access​

In Getting started, enroll an agent with only the discovery capabilities you need. Select Linux, prepare one authorized target or directory, and download agent.local.json. Save the one-time credential through your approved secret-management tooling into a regular file, readable only by root, such as /root/sectigo-agent.token with mode 0600. Do not place the credential value in command history.

The installer creates sectigoqr if absent. An existing account must have a dedicated group of the same name, a non-login shell, and no supplementary groups. For private repository or capture directories, provision this account and grant narrowly scoped read/traverse ACLs before installation. Avoid granting access to entire home directories. TLS and SSH discovery need network access to the configured endpoints, not filesystem access to private repositories.

The local configuration is the maximum allowed scope. To manage narrower scope from the portal, add "managedConfiguration": true before installation. An opted-in agent waits for its first published configuration before claiming scans. See managed configuration.

Offline capture also needs a separately installed trusted TShark 4.6.9+ in the 4.6 series, with its absolute path in tsharkExecutable. Linux decoder installation and native-service capture execution are not yet validated. Start this preview with TLS, SSH or repository discovery. It does not collect live traffic.

3. Install and check contact​

Replace the example paths below with absolute paths to your verified files. Use the protected environment created above to run the installer:

sudo /opt/sectigo-python/bin/python scanner/linux_service.py install \
  --manifest /path/to/manifest.json \
  --signature /path/to/manifest.sig \
  --archive /path/to/sectigo-quantum-ready-bundle.zip \
  --trusted-key /path/to/trusted-release-key.json \
  --expected-version 0.25.1 \
  --python /opt/sectigo-python/bin/python \
  --config /path/to/agent.local.json \
  --token-file /root/sectigo-agent.token \
  --endpoint https://qscan.dev

Installation verifies the signed release again, writes protected configuration, stages immutable code, and starts the service. Boot enablement happens only after local preflight succeeds. If startup fails, the installer restores the previous service definitions where possible and retains recovery state when intervention is needed.

sudo /opt/sectigo-python/bin/python scanner/linux_service.py status

Review active, enabledAtBoot and any failed checks. Local startup does not prove cloud authentication. In Getting started, choose Check connection again, then create one authorized scan and inspect its result. If managed configuration is enabled, publish it from Agents & sensors first.

Operate, upgrade and remove​

Run these commands from the verified extracted bundle:

sudo /opt/sectigo-python/bin/python scanner/linux_service.py stop
sudo /opt/sectigo-python/bin/python scanner/linux_service.py start
sudo /opt/sectigo-python/bin/python scanner/linux_service.py status

To upgrade, independently verify the new release, then use upgrade with its manifest, signature, archive, trusted key and expected version. The installer preserves local scope, credential, logs, interpreter and boot preference. It rejects an older sequence, a changed signing key, or different bytes at the same sequence. Retain the previous environment and releases until your upgrade is verified. Automatic updating is not enabled.

Removal stops and disables the service but preserves configuration, credential, logs, account and releases:

sudo /opt/sectigo-python/bin/python scanner/linux_service.py remove

Revoke the agent in the workspace if access is no longer required. Removal alone does not revoke its cloud credential.

Diagnose startup or interrupted installation​

Start with status. Failed checks provide fixed recovery hints. If it reports pending recovery, run:

sudo /opt/sectigo-python/bin/python scanner/linux_service.py recover

Recovery refuses to overwrite administrator changes. For service failures, inspect systemctl status sectigo-quantum-ready and the bounded service logs in /var/lib/sectigo-quantum-ready/logs/. Check Python/dependency readiness, directory permissions, target scope, clock accuracy and outbound HTTPS access. The root-only /etc/sectigo-quantum-ready/recovery.json may contain credential material: never attach it or the credential file to support requests.

Real VM acceptance covers startup, least-privilege execution, TLS/SSH jobs, allowlist refusal, upgrade rollback, reboot, stop/start and removal against a local test API. It does not establish every distribution's behavior or end-to-end native deployment against your tenant. Confirm contact and scan evidence in your own workspace.