Assetmanager/docs/architecture/SOFTWARE-CLIENT-ARCHITECTURE.md

Proposal: Client communication and future software deployment

Target architecture

A small Windows client ("AssetManager Agent") runs on every managed computer. A Netlogon or GPO startup script only installs or updates this agent. Inventory and software jobs are then controlled through a secured HTTPS API.

Why not execute every command directly in a Netlogon script?

A startup script is useful for bootstrap and repair, but unsuitable for permanent job control:

• User and computer startup is delayed.
• Results and retries are difficult to track.
• A network share or domain controller may not yet be reachable during startup.
• Software installations require status, timeout, exit-code, and restart handling.
• Passwords or global API keys must not be stored in the script.

Recommended components

1. Bootstrap through GPO or Netlogon

The startup script:

1. creates C:\ProgramData\AssetManager\agent,
2. downloads a signed agent version from an internal HTTPS address,
3. installs a Windows service,
4. stores only the server URL and a one-time registration identifier,
5. starts the service.

2. Device identity

During initial registration, the agent reports:

• computer name,
• AD domain,
• BIOS serial number,
• Windows MachineGuid,
• optionally, the MeshCentral node ID.

The server then creates a device-specific token. Windows DPAPI protects the token locally. Do not use a shared API key for all clients.

3. Agent polling

For example, the client requests a job every five minutes over HTTPS:

GET /api/agent/v1/jobs/next

Response when no job is available:

{"job": null, "next_poll_seconds": 300}

Response with a job:

{
  "job": {
    "id": 4711,
    "type": "software_inventory",
    "expires_at": "2026-07-22T23:00:00Z",
    "payload": {}
  }
}

The client first acknowledges receipt and later reports the result, exit code, log excerpt, and timestamps.

4. Software inventory

The first agent function should:

• read installed MSI applications from the 32-bit and 64-bit registry,
• optionally include AppX packages,
• collect name, version, publisher, installation date, and uninstall string,
• send the compressed result to AssetManager,
• store inventory runs per asset on the server.

Do not use Win32_Product, because that WMI class may trigger MSI repairs and can be very slow.

5. Software catalog for future deployment

Server-side tables:

• software_packages
• software_package_versions
• software_jobs
• software_job_results
• agent_devices
• agent_tokens
• agent_inventory_runs

A software package contains:

• name and version,
• installation source,
• SHA-256 hash,
• installation command,
• uninstall command,
• detection rule,
• accepted exit codes,
• restart behavior,
• timeout,
• target architecture.

6. Installation source

Packages may initially remain on a file server, for example:

\\fileserver\software\packages\ExampleApp\1.0\

A job must not contain arbitrary PowerShell code. It refers to an approved package definition. The agent verifies that:

1. the package is approved on the server,
2. the source is below an allowed UNC base path,
3. the file hash matches,
4. the installation command matches the package definition.

An internal HTTPS package download is more robust in the long term because it does not require machine access to a share and is easier to audit.

7. Security rules

• use HTTPS only, with an internally trusted certificate,
• use a separate revocable token per device,
• sign jobs on the server or deliver them through an authenticated TLS connection,
• do not provide unrestricted shell or PowerShell input in the web interface,
• execute commands only through defined job types,
• verify package files with SHA-256,
• keep a complete audit log,
• use roles and permissions for approval and execution,
• enforce maximum runtime and retry limits,
• run the agent as SYSTEM only when a specific job requires it.

Suggested implementation phases

Phase 1 – Inventory

• agent registration
• heartbeat and last-contact tracking
• operating-system and software inventory
• display on the asset detail page
• manual inventory job

Phase 2 – Job model

• generic job queue
• statuses: pending, claimed, running, success, failed, expired
• exit codes, logs, timeout, and retry
• live status in AssetManager

Phase 3 – Software catalog

• package definitions
• detection rules
• installation and uninstallation
• single devices and device groups
• maintenance windows

Phase 4 – Rollout safety

• pilot groups
• approval workflow
• staged deployment
• abort on excessive failure rate
• restart coordination

Recommendation for the next development step

Implement Phase 1 first. The agent should not yet execute arbitrary commands. Once registration, heartbeat, and software inventory are stable, the same secured communication can be used for the job queue and later software deployment.