Deploy and maintain the device collector

This guide is for administrators deploying the signed collector to explicitly approved computers through Microsoft Intune, Jamf or Linux configuration management. Start with a small canary group, then a reviewed pilot. Installing the collector does not establish complete device coverage or approve discovered AI.

Pilot release and platform limits

The signed RC9 pilot is for explicitly approved administrator deployments. Windows has bounded native service lifecycle evidence. Linux service evidence comes from a QA WSL systemd environment, not a standalone Linux fleet. On macOS 15 ARM64, isolated same-boot checks passed service startup, update, restoration, rollback and removal; a separate check passed root credential provisioning and actual readback from the locked Keychain by the non-root service identity. Reboot, sustained unattended operation, Intel Mac compatibility, Intune/Jamf rollout and full fleet acceptance remain unverified. Start with a separately approved small pilot.

Prepare the deployment

Before assigning a machine package, confirm all of the following:

• Your Briard workplace has the relevant fleet and local inventory features enabled. In the local inventory setup, choose your deployment method and checks, review their scope, then select Approve inventory profile.
• An administrator has approved the release, publisher policy and exact computers in the deployment group. Prepare an approved Python 3.11 or later with cryptography installed through your management system; the installer does not download dependencies.
• Each computer has its own enrollment, secret-free configuration and protected credentials. An enrollment for one computer must not be cloned across a deployment group.
• The runtime service identity can read the explicitly approved source folders or loopback APIs. Approve each intended employee home locally; the service account's home does not represent all employees. The installer does not grant access to inventory folders.
• Bootstrap code, the interpreter and its libraries, publisher policy, installation control paths and their parent directories are administrator/root controlled. Use absolute local paths without symlinks or junctions. Keep immutable code separate from service-writable data.

The service needs the configured Briard HTTPS endpoint for signed collection and delivery. An offline queue does not authorize a new scan: new acquisition requires current server authorization. Do not substitute a proxy, remote runtime or new folder for the approved local scope. Review the source and capability prerequisites before selecting checks.

Establish trust before running the bootstrap

Download the ZIP, manifest and detached signature from the RC9 pilot section, along with the public pilot policy. Public downloads do not require access to Briard's private source repository.

Before extracting or executing bootstrap code, independently confirm the ZIP SHA-256, exact policy-file SHA-256 and publisher public-key fingerprint with an already established Briard support contact. Compare the downloaded ZIP and policy with those approved values using your organization's hash-verification tooling. A key or policy downloaded beside an archive cannot approve that archive by itself. If a digest, signature, validity period or release pin differs, stop and obtain the correct approved material.

After this independent approval, use your management staging process to extract the approved ZIP into a protected bootstrap directory. Keep its companion modules together with install-service.py or install-service-windows.ps1; copying only the installer script is insufficient. Provision the separately approved public policy through your management channel and retain the original ZIP, manifest and detached signature as installer inputs. The installer verifies the release signature, archive members and allowed sequence before activation.

These are Briard Ed25519 signatures, not Windows Authenticode or Apple notarization. Follow your organization's script-execution and application-control policies; do not disable them to bypass a refusal. RC9 is a pinned pilot release with a validity window. Obtain a newly approved release for a fresh installation after expiry rather than editing the policy or dates.

Profiles with optional hardware matching require RC8 or another explicitly compatible release and separate device-match review after inventory arrives. The original RC7 artifacts remain unchanged for legacy profiles. A package upgrade does not approve hardware collection automatically.

Enroll and protect this computer's configuration

In the approved local inventory connection's collector setup, review the signed release and complete the publisher/package confirmation. Use Create key for this computer and Download setup template. Save the exact approved configuration and provision the one-time-displayed installer key through your protected management channel. If the feature or signed package is unavailable, retain the approved profile and resolve that availability before installation.

The configuration contains enrollment references and approved settings, not credentials. Supply the intended local home paths in the deployment configuration; do not add secret values. Managed machine configuration requires fleet_delivery.encrypted_spool to be true.

Your credential provisioner must supply these entries in the native protected credential JSON:

Entry	Purpose and lifecycle
BRIARD_COLLECTOR_TOKEN	This computer's enrollment token; replace it when rotating access.
BRIARD_COLLECTOR_PSEUDONYM_KEY	Stable per-device privacy key; retain across updates, rollback and token rotation.
BRIARD_COLLECTOR_SPOOL_KEY	Base64-encoded 32-byte spool key; retain so buffered evidence remains readable.

Required source credentials, if any, must follow the selected profile's approved local credential contract. Do not put tokens or keys in the downloaded configuration, ZIP, management policy, command line, shell history, service definition, inventory report or support attachment. Changing privacy or spool keys is not routine token renewal: it can change device references or make saved evidence unreadable.

The installers consume already provisioned native credentials; they are not a credential-generation or import tool. Use the operating-system-specific method below. Do not share one credential bundle across hosts.

Windows with Microsoft Intune

Package the approved bootstrap and signed release inputs as an Intune Win32 app. Select the System installation context and 64-bit Windows PowerShell 5.1 or later. Install the approved machine-wide Python and cryptography first. Replace the example Python path with the actual approved interpreter path.

Use an administrator-owned root under C:\ProgramData\Briard-AI\Collectors. Its protected access list gives SYSTEM and Administrators full control and LocalService read/execute. The wrapper creates a private data child writable by LocalService. Provision the device credential as a DPAPI LocalMachine-encrypted blob with access limited to SYSTEM, Administrators and LocalService. Deliver it separately from the .intunewin package; the wrapper tightens that explicit credential file.

Run with an elevated administrator or System token:

& 'C:\ProgramData\Briard-AI\Bootstrap\install-service-windows.ps1' -Mode install `
  -InstallRoot 'C:\ProgramData\Briard-AI\Collectors\site-inventory' `
  -Name 'site-inventory' -Python 'C:\Program Files\Python313\python.exe' `
  -PublisherPolicy 'C:\ProgramData\Briard-AI\publisher-policy.json' `
  -Archive 'C:\ProgramData\Briard-AI\Incoming\release.zip' `
  -Manifest 'C:\ProgramData\Briard-AI\Incoming\manifest.json' `
  -Signature 'C:\ProgramData\Briard-AI\Incoming\signature.json' `
  -Config 'C:\ProgramData\Briard-AI\Incoming\connection.json' `
  -CredentialFile 'C:\ProgramData\Briard-AI\Credentials\site-inventory.dpapi' `
  -IntervalMinutes 15

This registers the automatic SCM service BriardCollector-site-inventory under LocalService. For an Intune detection rule, compare installation.json with the approved release, confirm disabled is false, inspect the SCM identity/command/running state, then check matching-release data/health.json. Report only reduced state and release identifiers. A detected installation is not proof of a completed inventory check.

LocalService does not automatically inherit employee folder access, user runtime access or per-user WSL registrations. Do not expand permissions or enroll a wider group simply to turn a partial check green.

Linux with configuration management

Use a systemd machine manager supporting LoadCredentialEncrypted. Through your existing configuration manager, provision a dedicated non-root account with a disabled login shell, for example briardcollector. Approve its existing read access to the chosen source folders.

Use your credential provisioner with systemd-creds encrypt --name=briard-collector to create the root-only encrypted credential. Supply plaintext through protected stdin, not an argument or durable package file, and select your organization's host/TPM protection policy. The service reads the mounted credential named briard-collector; a plaintext environment file is not an equivalent substitute.

Stage the bootstrap and inputs under root-owned paths. Invoke as root, substituting the approved interpreter if it differs:

/usr/bin/python3 -E -s -B /opt/briard-ai/bootstrap/install-service.py install \
  --install-root /opt/briard-ai/collectors/site-inventory \
  --name site-inventory --service-user briardcollector \
  --python /usr/bin/python3 \
  --publisher-policy /opt/briard-ai/publisher-policy.json \
  --archive /opt/briard-ai/incoming/release.zip \
  --manifest /opt/briard-ai/incoming/manifest.json \
  --signature /opt/briard-ai/incoming/signature.json \
  --config /opt/briard-ai/incoming/connection.json \
  --credential-file /opt/briard-ai/native-credential.cred \
  --interval-minutes 15

The resulting ai.briard.collector.site-inventory.service is enabled for multi-user.target and runs without user login under the dedicated account. Its system/home access is read-only; its private data directory is writable. Deploy per host with your existing Ansible, Puppet, Salt or equivalent workflow. A QA WSL systemd lifecycle result does not establish unattended boot or compatibility across standalone Linux distributions.

macOS with Jamf — limited pilot

Do not assign this recipe broadly. The isolated macOS checks described above do not establish reboot recovery, sustained operation or a customer Jamf rollout. RC8's earlier service-readiness limitation remains historical; RC8 does not include RC9's new credential provisioner and explicit Keychain selection.

For a separately approved Mac pilot, prepare administrator-controlled Python 3.11+ with cryptography, the independent publisher policy, and a dedicated disabled-login non-root account/group such as _briardcollector. Your management system must run the approved bootstrap as root in the system security session, through a system LaunchDaemon or equivalent approved machine job. An interactive administrator terminal is insufficient. Do not rely on a logged-in user's unlocked Keychain or approve unexpected prompts automatically.

For a fresh enrollment, provide the exact three credential fields listed above through a protected stdin pipe to this command in that job. Do not put the JSON in its arguments, environment, package or a temporary plaintext file. The parent directory must already be root-controlled; the credential directory and its adjacent provisioning receipt must not exist.

/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13 -E -s -B \
  /opt/briard-ai/bootstrap/provision_macos_credentials.py \
  --directory /opt/briard-ai/credentials/site-inventory \
  --name site-inventory --service-user _briardcollector

The provisioner creates the private credential Keychain, establishes its machine unlock relationship with the existing System Keychain, locks it, then hands the private bundle to the service identity. It does not create or replace the System Keychain. Keep all approved bootstrap modules together. Retain the returned exact credential_keychain path in the management job as CREDENTIAL_KEYCHAIN; do not assume a .keychain-db suffix. If provisioning fails or is interrupted, preserve its journal and files for review: do not retry, force replacement or reuse that directory. This fresh-enrollment tool does not rotate existing credentials.

After successful provisioning, invoke the installer below from the approved management context. Replace the example interpreter with the actual approved installation. macOS uses --credential-keychain, with no --credential-file argument:

/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13 -E -s -B \
  /opt/briard-ai/bootstrap/install-service.py install \
  --install-root /opt/briard-ai/collectors/site-inventory \
  --name site-inventory --service-user _briardcollector \
  --python /Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13 \
  --publisher-policy /opt/briard-ai/publisher-policy.json \
  --archive /opt/briard-ai/incoming/release.zip \
  --manifest /opt/briard-ai/incoming/manifest.json \
  --signature /opt/briard-ai/incoming/signature.json \
  --config /opt/briard-ai/incoming/connection.json \
  --credential-keychain "$CREDENTIAL_KEYCHAIN" \
  --interval-minutes 15

The installer targets /Library/LaunchDaemons/ai.briard.collector.site-inventory.plist in the system launchd domain with the dedicated account and RunAtLoad. It preserves the exact credential selector for the service and its collection child; a failed read does not search other Keychains. Jamf reporting should expose only release identifiers, native state and reduced health. Validate installation, actual inventory delivery, update, recovery, removal and logged-out/reboot behavior in the intended environment before expanding the pilot.

Check readiness and received evidence

Keep these checks separate when deciding whether to expand a deployment:

1. Installed: the approved release is selected and its native service has the intended identity and command.
2. Ready locally: reduced health names the selected release and a fresh readiness_at, and the native service is active. The installer waits up to 120 seconds for readiness.
3. Collected and received: the intended approved checks completed and their evidence reached Briard. Open fleet coverage and inspect the device's capability gaps, source inventory date and received date.

A heartbeat, a successful key check or an online service cannot replace actual source evidence. A stopped runtime, inaccessible folder, missing nested reader or unknown inventory date remains a gap. Partial scans preserve positive observations but do not prove that previously reported software disappeared.

Update, rollback and remove

Approve each new release and retain its exact ZIP, manifest and signature. Reuse the protected bootstrap and the existing installation root. Normal updates preserve the registered publisher-policy path, interpreter, service identity, credential reference and schedule; they are not a way to silently change collection scope.

For Windows:

& 'C:\ProgramData\Briard-AI\Bootstrap\install-service-windows.ps1' -Mode update `
  -InstallRoot 'C:\ProgramData\Briard-AI\Collectors\site-inventory' `
  -Archive 'C:\ProgramData\Briard-AI\Incoming\release.zip' `
  -Manifest 'C:\ProgramData\Briard-AI\Incoming\manifest.json' `
  -Signature 'C:\ProgramData\Briard-AI\Incoming\signature.json'

For Linux, or a Mac whose separate pilot prerequisites have been met, use the approved platform interpreter:

/usr/bin/python3 -E -s -B /opt/briard-ai/bootstrap/install-service.py update \
  --install-root /opt/briard-ai/collectors/site-inventory \
  --archive /opt/briard-ai/incoming/release.zip \
  --manifest /opt/briard-ai/incoming/manifest.json \
  --signature /opt/briard-ai/incoming/signature.json

The installer stages and verifies the new release before stopping the previous service. A failed start attempts restoration of the retained verified release and checks readiness again. Failed restoration needs administrator repair; retain the failure result and protected state. Do not erase or reinstall over an initial failed installation's retained data without a reviewed recovery plan.

Action	Windows wrapper arguments	Linux/macOS installer arguments
Deliberate rollback	-Mode rollback -InstallRoot ROOT	rollback --install-root ROOT
Remove native service	-Mode remove -InstallRoot ROOT	remove --install-root ROOT

Use the same wrapper/interpreter as above and replace ROOT with the existing absolute installation path. Rollback selects the retained verified prior release, subject to the approved policy; it does not lower the highest accepted sequence or erase inventory history. A new installation does not automatically have an earlier approved release available for rollback.

Removal stops and unregisters the service and disables the installation pointer. It preserves configuration, release proofs, credentials and buffered evidence. Revoke the enrollment separately in Briard, then dispose of retained material only under your organization's retention process. Uninstalling is not credential revocation.

Rotate or revoke access

Use the collector setup's Rotate access action for an existing, unrevoked enrollment when authorized; complete the required fresh MFA check. Provision the replacement token into that computer's native credential store. Keep the same configuration, privacy key and spool key. The old token stops working, and the new token is displayed once. If it was not securely retained, rotate again rather than attempting to recover it from logs.

Restart the existing native service through your management system after replacement, particularly on systemd where the credential is mounted when the service starts. Check local readiness and a new authorized delivery. Monitor the expiry shown in Briard so renewal happens before collection is interrupted.

Use Revoke key to stop that enrollment's authorization. Replacing a revoked collector creates a separate enrollment; rotation preserves the existing collector identity and history. A revoked or expired collector's old observations can remain visible, but they do not establish current coverage.

Troubleshooting

Retain the installer's fixed stage and code, approved release identifier, native service state and reduced health result. Do not send credentials, the native credential file, configuration containing local paths, raw spool contents or unrelated host logs to support.

Symptom	Administrator action
Publisher, signature, expiry or release-pin refusal	Compare the exact independently approved inputs. Obtain a newly approved release or policy when needed; do not change pins, dates or sequence values to bypass the refusal.
validate_installation or registration failure	Check elevation, absolute protected paths, approved interpreter/dependencies and the dedicated service identity. Preserve existing installations instead of overwriting them.
await_readiness failure	Check that the native service runs the selected release and can read its protected credential. Local readiness is separate from network delivery.
macOS credential read failure or timeout	Keep rollout blocked; resolve Keychain placement and noninteractive access for the dedicated identity. A prompt accepted in an interactive session is insufficient.
macOS credential provisioning failure or interruption	Preserve the reduced result, journal and protected files. Do not retry on the same directory or force System Keychain changes; obtain administrator review before recovery.
restore_service failure	Stop expansion of the deployment group and retain installation state for administrator repair. Do not automatically erase the prior release or buffered evidence.
Service online, check incomplete	Review exact selected homes, permissions, API state, nested scope and acquisition limits. Do not broaden access or report an empty complete inventory to hide the gap.
No current delivery	Check enrollment expiry/revocation and approved HTTPS connectivity. Preserve the encrypted queue and its key. An old receipt or heartbeat cannot establish fresh inventory.

Review changes in a small approved group before expanding. Record your own installation, permissions, received evidence, update, recovery and removal results; the signed package and these instructions do not replace that acceptance.