Moving from Shadow AI Guard

A Shadow AI Guard deployment moves to Nyxus in place with aiguardctl upgrade --edition nyxus, from Shadow AI Guard 0.35.0 or later. That command, and the operator's steps, are documented with it, in Shadow AI Guard's docs/upgrading-to-nyxus.md. This is what Nyxus does with what it is given.

0.35.0 is the floor because that is the release where aiguardctl stops the portal as well as the receiver during the move, and knows what to do about a Tailscale operator holding a service back with a finalizer. An earlier aiguardctl plans a receiver-only move and leaves the old portal running against the new receiver.

The receiver's database

Nyxus opens the database Shadow AI Guard's receiver wrote, and brings it up to date as it starts: every table Shadow AI Guard has is one Nyxus has, and the tables and columns Nyxus adds are created. Accounts, sessions, decisions, the identity map, budget, registry additions, candidates, finding statuses, settings and preferences read back as they were written. A database written by Shadow AI Guard 0.33.0 is part of the receiver's tests.

Credentials Shadow AI Guard issued keep working. Device credentials (aigd_) and enrollment tokens (aige_) are stored as the SHA-256 of the whole string in both editions, and the receiver accepts both prefixes as well as its own; the hash is the proof either way. New credentials are issued as nyxd_ and nyxe_.

An activation key Shadow AI Guard stored is checked again, against the keys this release was built with. One that does not verify is shown as such and grants nothing.

Findings in the log store

Shadow AI Guard's findings carry its own stream label, app="ai-guard-receiver", and no company. The portal's SHADOW_AI_GUARD_FINDINGS_BEFORE - set by the upgrade to the moment Shadow AI Guard stopped - makes the first company's pages and daily history also read those findings, and only from before that moment, so a Shadow AI Guard left running cannot add to the estate. They are read, not copied, and drop out of view as the reporting window moves past them. System health says when it is set. See the portal README.

Endpoints

Collectors from 2.2.0 take over the device credential and throttle state Shadow AI Guard's collector left on a machine, when they have none of their own, and leave the old files in place beside a moved-to-nyxus note. They do not edit schedules: the collector script is replaced in the same MDM policy, RMM job or Intune script. Each platform's README has the detail.

The browser extension is a different extension and enrolls again by policy.

After the move

The first time an owner or admin of the hosting company signs in after the move, the console opens on Finish moving to Nyxus, before the setup and the tour. It lists what the move could not change for itself, with the values this deployment has:

• The addresses it is reached on. They keep working; nothing has to change. To serve Nyxus under new names, the DNS record (Route 53, Cloudflare or your own DNS), the certificate and the ingress host or reverse proxy come first, then the portal address and the single sign-on redirect URI, and the receiver last, together with the collectors, because its address is built into every collector download.

• Anything set up by hand around the old release. On Kubernetes the Services and Ingresses are named after the Nyxus release (nyxus and nyxus-portal by default). The chart's own Ingresses move with their hosts; anything else that names the old Services needs the new names.

• Collectors and the browser extension, as above.

• Monitoring. The receiver's metrics are nyxus_* where they were aiguard_*, and findings carry app="nyxus-receiver" where they carried app="ai-guard-receiver". Alert rules, recording rules and dashboards written for the old names stop matching.

• The command line. aiguardctl is nyxusctl.

It opens for each of them until they mark it as done, and it stays under Settings › Getting started. A client company's administrators, viewers and a deployment installed as Nyxus never see it.