Patching

Patching turns a verified vulnerability into a fix that is rehearsed, approved, installed and then independently verified before it counts as done. It needs the patch module and the Theseus agent on the machine (the install command run with --patching; see Enrol endpoints).

The workflow

Verify & gather  →  Plan  →  Dry run  →  Approval  →  Patching  →  Verification

1. Verify and gather. The job starts from a confirmed finding. The machine's current state is read through its Theseus agent.

2. Plan. The exact package version (or Windows KB) that fixes the finding is chosen.

3. Dry run. The installation is rehearsed on the machine without changing it.

4. Approval. A person approves (or an unattended-approval policy, below).

5. Patching. The exact version is installed, then the monitoring agent is restarted so it reports the new software list.

6. Verification. The job is not done when the install succeeds. It is done when:

   • the installed version is at least the target version (on Windows, Microsoft's data is the proof);
   • the machine's software list shows the new version;
   • vuln-verify reports every fixable vulnerability of the job as remediated.

   The job then ends Remediated. If vuln-verify reports that a reboot is needed, it ends Reboot required. If the installed version is lower than the target, or vuln-verify has not confirmed the fix within 90 minutes, it ends Not verified.

A job's steps read Planned and checked, Rehearsed on the machine, Approved, Installed, Fix verified and Done; a restart reads Restart requested, Went offline, Back online, Software list refreshed, Fixes verified, Done.

Job states

State	Label in the console
PROPOSED	Proposed
CONTEXT_GATHERED	Host read
PLANNED	Planned
VALIDATED	Validated
DRY_RUN_OK	Dry run passed
AWAITING_APPROVAL	Awaiting approval
SCHEDULED	Scheduled (waits for the maintenance window)
PRECHECK	Pre-check
EXECUTING	Patching
VERIFYING	Verifying
REBOOTING	Restarting
PENDING_REBOOT	Reboot required
REMEDIATED	Remediated
VERIFY_FAILED	Not verified
FAILED	Failed, then Rollback offered
ROLLED_BACK	Rolled back
BLOCKED	Blocked: a safety policy refused it
REJECTED, CANCELLED	Rejected, Cancelled
REBOOT_FAILED	Restart failed

A job is blocked when, for example, the finding is stale, the machine is not mapped to its agent yet, it is disabled ("enable it on the Agents page first"), or the package is on the deny list.

The Patching page

Vulnerabilities → Patching (/detection/patch-management) is organised by machine: a list of machines on the left, and the machine you select beside it. The header sentence sums up the fleet. Settings opens Patching settings; Add machines opens Add agents with patching on.

The list of machines

Needs action (the default) shows the machines waiting on someone, those waiting on a person first; All shows every machine. Find a machine searches by name. Beside each machine, in a few words, how its patching stands:

Shown	Meaning
Approve 1 patch, Approve N patches	Jobs wait for your approval
A job failed, N jobs failed	A job needs someone to look at it
Patching, Restarting	A job is running
Needs a restart	A fix is installed and finishes with a restart
1 fix ready, N fixes ready	Fixes can be patched now
Nothing to run here	Fixes exist, but none can be installed from the console (for example a third-party application)
Patching not installed	The machine has the monitoring agent but not the Theseus agent with patching
Up to date	Nothing is waiting

When no machine needs action, the list shows every machine.

The machine pane

The selected machine shows, top to bottom:

• its name, the state of its Theseus agent (Connected, Not answering, Mapping incomplete, Connecting… or Offline), its operating system and agent ids;
• Rescan now (the monitoring agent reads the installed software again; results within about 5 minutes) and Restart machine;
• its settings: Restarts (Allowed or Not allowed) and Criticality (Normal or Critical: two approvers), and its environment when one is set;
• Waiting on you: jobs that need your decision;
• Running: jobs in progress;
• Fixes available: each package with the installed and the fixed version, its severity, the CVEs it closes, and Exploited when the vulnerability is known to be exploited. Patch starts a job. Open a row to see the CVEs closed by the update, those still open after it (the vendor has not fixed them yet), the job it last had, and Accept the risk;
• History: past jobs, and fixes the verification engine confirmed on the machine that no Athena job made, marked updated outside Athena (for example an automatic update overnight). They count as fixed, not as a miss;
• Activity log: every action on this machine from the console, including refused ones.

A machine without the Theseus agent says Patching is not installed on this machine, with Add patching: its vulnerabilities are known through the monitoring agent, but fixes can be installed only where the Theseus agent runs with patching on.

A job opens in the same pane, with its steps, what changes, who approved it, and the verification.

Approve a job

Open the job and choose Approve and install or Reject. Other actions, when they apply: Roll back (after a failed install), Restart machine (for Reboot required), Mark as handled (for Not verified and Restart failed), Cancel job.

• Approvals are recorded with the signed-in person.
• Machines marked critical need two different approvers.
• A job approved by the unattended-approval policy says so: Approved automatically by policy. No person reviewed this change.
• Packages on the deny list, held packages and plans that reboot without permission are "restricted" and need escalated approval. The default deny list: docker-ce*, containerd*, linux-firmware and the monitoring agent's own package.
• One job patches one host. Several hosts at once are a campaign.

Approving needs edit access to the Patching page (analysts and administrators by default).

Machine settings

Each patch target has settings that the safety checks use. Restarts and Criticality are set in the machine pane:

Setting	Effect
Environment	Unattended approval matches on it. A machine without one counts as PATCH_ENVIRONMENT_DEFAULT (default prod)
Criticality	critical needs two approvers; high and critical machines are never approved unattended
Maintenance window	HH:MM-HH:MM, daily, UTC; overnight windows work. Scheduled jobs wait for it; reboots outside it are refused. Empty means always
Restarts (allow reboot)	Without it, reboots are refused, by a patch or by a person
Deny packages	Extra packages that need escalated approval
Auto patch	Opt-in for unattended approval

Patching settings

Patching → Settings holds the rules every patch runs under, in three tabs: Approval policy, Rollouts and Accepted risks. Machines goes back to the list.

Approval policy (unattended approval)

Off by default: every patch needs a person. Approve matching jobs without a person turns it on. A job is then approved without a person only if all of these hold:

• its risk is at most the Highest risk allowed (Low only, or Low and medium);
• the machine's environment is in Environments (default test). A machine with no environment set counts as prod, so it is never approved unattended until you label it;
• the machine has opted in (auto patch enabled), when Only machines individually opted in is on;
• the machine is not high or critical;
• nothing in the plan is restricted.

Dry run and verification still happen.

Rollouts (campaigns)

A campaign patches one package across rings of hosts, in order: ring 0 is the canary, and the next ring starts only when every job in the ring before it has succeeded. When failed jobs in a ring reach the threshold (default 1), the campaign halts and the later rings never start.

New campaign: pick a package that has a patch available, put each host that needs it in ring 0, 1 or 2 (or leave it out), and set Halt after (the failure threshold). Ring 0's jobs are created at once. There is no start time: like every job, they wait for approval and then run in the host's maintenance window.

State	Meaning	Actions
Running	Rings are in progress	Halt campaign (no new ring starts; patched hosts are not reverted)
Halted	Stopped by a person, or by failures (the reason is shown)	Resume campaign
Done	The last ring has finished	none

Approve campaign (shown until someone approves) approves the campaign's jobs in every ring, so nobody has to approve them one by one. Until then, each job waits for its own approval. Critical machines still need a second approver on their own job. A resumed campaign halts again while its current ring's failed jobs still reach the threshold.

Creating, approving, halting and resuming need edit access to the Patching page.

Accepted risks

When a fix cannot or should not be installed, record the decision instead: Accept the risk on a fix in the machine pane, or Record an accepted risk here. Give the owner, a justification (required) and an expiry. The tab lists every accepted risk with machine, package, CVEs, owner and expiry. An accepted risk does not fix anything: the machine is still exposed, and the finding is not counted as fixed.

Channels

Channel	Status
apt, dnf (Linux)	Available
Windows Update KBs	Pilot
winget, pip	Pilot
Homebrew (macOS)	Pilot
macOS system updates, other third-party applications	Not deployable from the console: install them on the machine

In a two-server install

The immediate re-check after a patch does not cross servers; verification waits for vuln-verify's next regular cycle (up to 30 minutes).

Problems: see Patching and Pallas troubleshooting.