Package Discovery

Package Discovery is an Ordyn service that checks public vendor pages for software updates.

It runs as an enrolled service client through an assigned Edge service and uses an assigned cache node for downloaded installers and scan evidence.

Features

• uses a real Chrome browser to explore public vendor and download pages
• use an OpenAI-compatible model to choose the next browser action
• detect available package versions and resolve offline installer artifacts
• download and import the discovered package into Ordyn

Deployment

Only a single package-discovery may exist per installation.

Setup flow:

1. an admin configures the package discovery service in the UI under Administration > Services on the Package Discovery tab
2. Ordyn assigns one Edge service and one cache node to it
3. an admin issues a service-client enrollment token scoped to the package discovery service
4. the service enrolls through the configured edge service by using the scoped token once
5. it keeps a service-client connection to Edge
6. Ordyn sends requests to the service
7. the service collects the requested artifacts and returns them

This means package discovery does not need a direct connection to the Ordyn server.

Installation

Checkout the package discovery deployment folder from the Ordyn compose repository:

if [ ! -d /opt/ordyn-compose/.git ]; then
  git clone --filter=blob:none --sparse https://github.com/ordyn-project/compose.git /opt/ordyn-compose
fi
cd /opt/ordyn-compose
git sparse-checkout add package-discovery

Create the environment file:

cd /opt/ordyn-compose/package-discovery
cp .env.example .env

Set these values in .env:

ORDYN_PACKAGE_DISCOVERY_EDGE_HOST=ordyn-edge.example.com
ORDYN_PACKAGE_DISCOVERY_SERVICE_CLIENT_ID=<service-client-id>
ORDYN_PACKAGE_DISCOVERY_LLM_API_KEY=<llm-api-key>
ORDYN_PACKAGE_DISCOVERY_LLM_MODEL=gpt-5.4-mini

Start the service:

docker compose pull
python3 /opt/cosign-docker-verify/verify.py

Continue with docker compose up -d only when the package discovery image verifies successfully and no failed verification message appears.

docker compose up -d

Issue a service-client enrollment token for the package discovery service client in Ordyn. Enroll the service once:

printf '%s' '<enrollment-token>' | docker compose exec -T package-discovery node dist/index.js enroll --token-stdin

Package discovery does not need public ingress or Traefik. It connects outbound to the assigned Edge service and receives signed work through that connection.

How discovery works

At a high level, one scan works like this:

1. Ordyn creates a discovery scan for a software product
2. Ordyn builds a prompt from:
   • the base package discovery prompt
   • the product details
   • known aliases
   • latest known packages
   • product-specific prompt append
   • product-local discovery memory from previous successful scans
3. Ordyn sends a package-discovery scan command to the service client
4. the service opens a Chrome browser session that presents itself as a Windows desktop browser
5. the service summarizes the current browser state and asks the configured reasoning model for the next action
6. the service repeats browser actions until it:
   • finds no update
   • finds an update without import
   • downloads and stages an artifact for import
   • or fails
7. the service sends the scan result back through Edge
8. for import runs, Ordyn fetches the staged artifact from the assigned cache node, imports it, and deletes the staged file
9. for screenshots, Ordyn fetches the staged screenshots, stores them in scan evidence, and deletes the staged cache files

Discovery modes

Each software product has a discovery mode.

discovery_only

• discovery checks whether an available version exists
• it still tries to resolve a concrete offline-installable artifact
• it does not import a package
• successful result status is update_available

discovery_and_download

• discovery checks for an available version
• if it finds a valid offline installer, it downloads and imports it
• successful result status is imported

Manual runs can override the product default for that one run. Scheduled runs use the product's configured mode.

Product-level configuration

Package discovery is configured per software product.

Current product settings:

• enabled state
• discovery mode
• schedule
• preferred architecture
• preferred locale
• preferred file formats
• download timeout
• maximum browser steps
• troubleshooting screenshot capture
• package discovery prompt append

Related product fields that discovery also uses:

• vendor URL
• direct download URL
• product aliases
• known existing packages
• product discovery version parsing policy

Discovery uses the product discovery version parsing policy before comparing a discovered version to known package versions and before importing a downloaded artifact. This is the place to handle vendor-specific discovery versions or filenames, such as compact installer names where the actual version is embedded in the artifact name.

The direct download URL may point at a public download permalink. If opening the source URL immediately starts a browser download, discovery treats the downloaded artifact as the scan result. The final downloaded filename is preferred for version detection, which supports vendor links such as latest permalinks where the URL stays stable but the resolved filename contains the actual version.

Scheduling

Scheduled discovery uses a cron expression per product.

Important behavior:

• scheduled products default to 0 2 * * *
• a due scan is not started immediately
• Ordyn adds a random delay between 5 and 60 minutes before execution
• this reduces synchronized bursts when many products share the same schedule

Manual discovery is separate from scheduled discovery and can be run even when scheduling is disabled.

Prompt append

The product-level prompt append is for product-specific hints that the generic discovery prompt does not know.

Typical use cases:

• vendor-specific naming quirks
• which edition to prefer
• which download variant is considered the real offline installer
• locale or architecture caveats

Service-level configuration

The package discovery service itself is configured in the UI.

Current service settings:

• name
• enabled state
• assigned Edge service
• assigned cache node
• artifact upload lifetime

The assigned Edge service and cache node are managed separately in Administration > Services. Both use a remote bootstrap token during registration or reconfiguration. The token is shown by the pending remote service and is pasted into Ordyn once.

When editing a cache node, use Reconfigure existing cache node only after resetting the remote cache node so it is pending again. This option tells Ordyn to configure the same cache node host with the new remote bootstrap token. If the host is unchanged and the option is not enabled, the edit is treated as a normal settings change and a bootstrap token is not accepted.

Operational status shown in the UI includes:

• service client ID
• connection state
• version
• certificate serial
• certificate expiration
• last enrolled
• last connected
• last seen
• last error

Admins can revoke the current service-client certificate. After revocation, issue a service-client enrollment token and run enrollment again before the service can connect. See service-client certificate lifetime and renewal for planned renewal and recovery after expiration.

Runtime Control And Local Logging

The service accepts scan and cancel commands from Ordyn.

Behavior:

• scans can be started by manual or scheduled package discovery
• scans can be cancelled from Ordyn
• active scans are also aborted if the service-client connection is interrupted

Reasoning traffic is logged locally by the service.

Local logging behavior:

• every request to the configured reasoning endpoint is recorded
• raw response bodies and HTTP status codes are recorded too
• failed requests also record the thrown error message
• the default audit directory is /data/llm-audit
• files rotate daily as llm-audit-YYYY-MM-DD.ndjson

Discovery memory

Ordyn keeps a product-local discovery memory summary.

How it works:

• it is rebuilt automatically from successful scans with status imported or update_available
• it is deterministic and generated by Ordyn, not by a second model call
• it is included in future discovery requests as prior successful patterns
• admins can view it on the product overview page
• admins can clear it manually from the product actions dropdown

This helps discovery repeat successful vendor-specific flows without turning the memory into a hard rule.

Screenshots

Screenshots are optional and are enabled per product for troubleshooting.

When enabled:

• the service captures screenshots during the browser flow
• Ordyn stores the screenshots inside the scan evidence shown in the UI
• users can inspect the evidence from the scan detail view

Screenshots are meant for troubleshooting difficult vendor pages and should not be enabled everywhere by default.

Duplicate handling

Package discovery does not blindly import every found version string.

Important behavior:

• discovered versions are normalized before duplicate checks
• if the same normalized version already exists for the same software product, platform, and architecture, discovery does not create a duplicate package
• if Ordyn imports a package and there is an existing package with the same platform and architecture, Ordyn copies its install and uninstall workflow steps to the imported package
• the discovered artifact download URL is stored on the imported package

Browser Behavior

Package discovery opens vendor pages in a browser session so it can handle common download pages that require page interaction.

Supported behavior includes:

• a Windows desktop browser profile
• popup and new-tab handling
• modal-aware interaction
• iframe-aware interaction
• retry and recovery for stale or blocked actions
• automatic waiting for JS-rendered pages to hydrate

Discovery can run multiple scans at the same time. Size the service host for the expected scan volume and browser workload.

Limitations

• vendor anti-bot, geo, reputation, or consent flows can still block discovery
• some sites require unusual manual reasoning that the model may still miss
• cross-origin iframe restrictions can limit what discovery can inspect
• closed shadow DOM cannot be traversed

In practice, some products need prompt hints or manual memory clearing when the vendor changes the download flow.

Security model

Package discovery is the highest-risk service in the package flow because it interacts with untrusted public websites and downloads untrusted artifacts.

Security guidance:

• run the package discovery service on a host dedicated to Ordyn service work
• review imported installers before approving them for broad rollout

Treat the service as internet-facing automation because it opens public websites and downloads untrusted artifacts.