Skip to main content

Connect your first discovery agent

Use guided setup​

Open Getting started in your workspace. Select an enrolled agent, choose a supported discovery type, and enter one authorized endpoint or absolute repository path. Download agent.local.json; it contains local scope only, never the agent credential.

Install the verified bundle and dependencies below, inject the scoped credential, and run the agent with that configuration. Choose Check connection again to read the latest server heartbeat. Recent contact does not prove your configuration was installed correctly. Create your first scan opens a pre-filled review form; nothing is queued until you submit that form.

Draft scope is kept only while the page remains open. After reloading, select your agent and prepare its scope again. Existing enrollment and contact status come from the server. An administrator enrolls new agents; administrators and analysts can create scans. The guided flow prepares local scope. Use Agents & sensors to publish managed configuration after explicitly opting in on the machine; see below. Native service installation remains separate.

1. Prepare a dedicated environment​

Use Python 3.12 or newer. Use an ordinary account with read access only to intended repositories and network access to authorized endpoints. TLS, SSH and source discovery do not require blanket administrator/root privileges. Native service installers and live packet capture are not available yet. Saved PCAP/PCAPNG files can be analyzed through the separate offline capture workflow.

Download the discovery bundle from Developer tools. Verify its signature before extraction or execution, using a reviewed verifier and independently trusted public key. Follow the published verification instructions. Do not run a verifier taken from an unverified archive.

From the extracted bundle directory, create a virtual environment:

python -m venv .venv

Activate it using the command for your shell, then install dependencies:

python -m pip install -r scanner/requirements.txt

2. Enroll in your workspace​

An administrator enrolls the agent in Agents & sensors and selects the capabilities it needs. Store the returned credential in a secret manager or protected environment. Never paste it into a support message, repository, URL, or screenshot.

Set QR_ENDPOINT to https://qscan.dev and inject the agent credential as QR_TOKEN. Do not use a broad administrator credential for the polling agent.

Use a protected credential file​

Scanner 0.14.0 or newer can read the credential from a local file instead of QR_TOKEN. This keeps the credential value out of command lines and service definitions. The file contains only the credential, optionally followed by a newline, and must be at most 4 KiB. Use an absolute local path. The agent rejects symlinks, Windows reparse points, network paths on Windows, directories and invalid contents.

On Linux/macOS, the file must be owned by the running account or root, with no group or other permissions, such as mode 0600 or 0400. It must still be readable by the running account. On Windows, disable ACL inheritance and allow access only to the running account, SYSTEM and Administrators. The owner must also be one of those identities. The loader checks Windows permissions through the system PowerShell executable using a fixed command; it does not pass the credential to that process. Run doctor as the intended agent account. Broader access causes rejection rather than a warning.

Create the file with your approved secret-management tooling, outside the bundle and repository. Do not put a credential literal in shell history. Then run:

python scanner/qr.py doctor --config agent.local.json --token-file C:/ProgramData/Sectigo/QuantumReady/agent.token
python scanner/qr.py agent --config agent.local.json --token-file C:/ProgramData/Sectigo/QuantumReady/agent.token

On Linux/macOS, substitute an approved absolute path such as /etc/sectigo-quantum-ready/agent.token. --token-file takes precedence over QR_TOKEN; an invalid file never falls back to the environment. The loader does not copy the file value into environment variables. Credentials are read at startup; restart the agent after rotating the file, and revoke the old credential from the workspace as appropriate.

3. Limit its local scope​

Copy scanner/agent.example.json to agent.local.json. Replace examples with your authorized scope:

{
  "source": "repository-agent-01",
  "allowedTargets": ["api.example.com:443"],
  "allowedSshTargets": [],
  "sshHostKeyPins": {},
  "repositoryRoots": ["/srv/repositories/my-project"],
  "pollSeconds": 15
}

Use paths that exist on the agent machine. In Windows JSON, escape backslashes or use forward slashes, for example C:/Repositories/my-project. An empty allowlist authorizes no targets of that kind. Remote jobs must pass local target or repository checks.

4. Check local readiness​

Run this from the verified bundle directory, in the same environment and account that will run the agent:

python scanner/qr.py doctor --config agent.local.json

Doctor returns JSON with a ready flag and a list of check codes and actionable messages. Exit code 0 means local checks passed; 2 means something needs attention. It validates the bounded configuration, exact endpoint allowlists, directory accessibility, polling interval, SSH pin shape, dependencies needed by your scope, and endpoint/credential environment shape. It never prints configured paths, hosts or credentials.

This command performs no network requests, scans, job claims or configuration changes. Passing does not verify credential validity, enrolled capabilities, remote connectivity or readability of every repository file. Start the agent below and review its heartbeat and first scan separately. Doctor is an explicit setup command; the polling agent does not run it automatically.

5. Start polling​

python scanner/qr.py agent --config agent.local.json

In Agents & sensors, check last contact and runtime versions. Recent contact confirms communication; it does not prove a particular scan will succeed. Start a scoped job from Discovery scans and inspect its final state and evidence.

Stop and restart safely​

Scanner 0.14.0 handles interrupt and termination signals by stopping new requests and interrupting polling/backoff waits. On Windows, console break is also handled. A running discovery checks the stop request at its next checkpoint. Repository and capture analysis check during processing; a running decoder is terminated when its checkpoint observes the stop. TLS/SSH operations and HTTP requests can finish their bounded in-flight calls before stopping. Shutdown is cooperative, not instantaneous.

A stopped scan is not falsely marked completed or failed, and no new upload starts after the stop is observed. Already accepted observations remain evidence. An in-flight request may already have reached the server; stopping does not undo it. An unfinished claimed job retains its lease until the server expires or otherwise resolves it. Review the job state before scheduling another run. Native Windows service, systemd and launchd installers remain in development; these runtime controls do not register an OS service.

6. Handle partial analysis​

A malformed supported manifest, Python parse failure or unreadable input can mark analysis incomplete. Fix the reported issue and scan again. Do not treat partial results as a complete repository assessment.

Agent credentials cannot upload arbitrary standalone scans: assigned jobs and live leases control ingestion. Standalone CI uploads use a separate ingestor credential. See the API reference for the implemented contract.

7. Manage configuration from your workspace​

With scanner 0.11.0 or newer, add "managedConfiguration": true to the local configuration and restart the agent. Keep the approved maximum host allowlists, repository roots, SSH trust pins and source label in that file. Its pollSeconds is the minimum permitted polling interval; remote configuration cannot increase polling frequency beyond it. An opted-in agent waits for its first published configuration before claiming work.

In Agents & sensors, an administrator selects Configure agent:

  1. Enter exact TLS/SSH endpoints or absolute repository directories, one per line, within local limits. Empty lists disable that discovery type. Only enrolled capabilities appear.
  2. Choose a polling interval and whether to allow new scans. New configurations default to paused.
  3. Publish the next revision. A stale editor must reload before publishing again.
  4. Refresh the agent page to review awaiting agent, applied, or rejected. Reopen Configure agent to see the rejection code. Acknowledgement is agent-reported, not independent attestation.

Each publication temporarily blocks new claims until the current revision is acknowledged. Remote hosts must match local endpoints; repository directories must resolve inside an approved local root. The agent keeps local trust pins and source identity. Rejected scope is not partially applied, and local files are never rewritten. Changes to local opt-in or maximum scope require a process restart.

The agent receives only its own configuration over its authenticated heartbeat. Only workspace administrators publish revisions. Configuration history lists earlier publications, newest first. Open a revision to inspect its settings. Administrators can choose Use as draft, review or edit the scope, then publish a new revision. The editor reloads the current revision before drafting and rejects conflicting later publications. Inspecting history never changes the agent. Viewers and analysts can inspect history but cannot restore settings. Revoked agents retain readable history for audit and cannot accept new configuration. Publication/application events are audited.

A running scan can finish under its previous configuration. Pause applies to new claims. To stop a running scan, cancel it; to remove all agent access, revoke the agent. Older agents cannot acknowledge managed configuration and will stop receiving new jobs after publication. Upgrade and opt in before publishing. Without managed configuration, existing agents continue using local scope.