quarantine

How it works

quarantine isolates an endpoint from the network by programming the host firewall so that everything is blocked except an allow-list: loopback, the address the agent itself connects to, and any whitelist_ips the operator supplies. The agent’s own server address is read from a value resolved once at agent startup, never at isolation time, so a host that is already compromised cannot steer its own DNS to decide what survives. On Windows it sets the all-profiles firewall policy to block inbound and outbound and adds named YuzuQuarantine_ Allow rules (IPv4 and IPv6); on Linux it builds a yuzu-quarantine chain and jumps to it first in the INPUT and OUTPUT chains of iptables, mirrored to ip6tables only when the host has an IPv6 stack and the ip6tables binary is installed; on macOS it writes a complete pf main ruleset ending in block all and loads it atomically with pfctl -f, then enables pf and re-reads pfctl -s info to confirm. unquarantine reverses it. status re-reads the live firewall and reports active, partial, degraded, uncertain or inactive, plus the current whitelist when the state is active or partial (not for inactive, uncertain or degraded). whitelist adds or removes IPs on a device that is already isolated. Every mutating action takes one process-wide gate first, and a caller that cannot get in within 2 seconds gets status|busy; status never takes the gate. Every firewall command runs without a shell under a 15-second deadline (10 seconds for reads).

Deliberately not: a state-preserving undo on macOS. unquarantine reloads the OS default /etc/pf.conf, so any other pf rules the host had are gone, which is why the capability catalogue classifies quarantine Irreversible on every OS even though Windows and Linux restore their own prior state. The plugin also does not decide who is quarantined: the server does, and the plugin only applies what it is told.

flowchart LR
  OP["Operator or MCP quarantine_device"] --> SRV["Server: Security Execute or Read, records intent in QuarantineStore"]
  SRV -->|"gRPC mTLS"| HOST["Agent plugin host"] --> EX["quarantine.execute"]
  EX --> WIN["Windows leg: netsh.exe, all-profiles policy and named Allow rules"]
  EX --> MAC["macOS leg: pfctl -f, atomic main-ruleset reload"]
  EX --> LIN["Linux leg: iptables and ip6tables, yuzu-quarantine chain"]
  WIN & MAC & LIN --> ROWS["key|value rows and typed result status"]
  ROWS --> RS[("ResponseStore")]
  SRV --> QS[("QuarantineStore: Postgres, authoritative record")]
  RS --> API["REST /api/responses and MCP"]
  QS --> API2["REST /api/v1/quarantine"]

What you can decide with it

What a “clean” answer means: quarantined and active show the plugin’s own rules and policy are in place, not that nothing else on the host can talk out. inactive means the plugin found none of its own containment; on Windows a host whose own policy already blocks both directions reads inactive with a note, because no YuzuQuarantine_ rule exists. Treat uncertain and degraded as not contained.

Diagrams

Containment state

stateDiagram-v2
  [*] --> inactive
  inactive --> active : quarantine succeeds
  inactive --> partial : quarantine only partly applied, Windows and Linux
  inactive --> degraded : macOS ruleset loaded but pf did not enable
  partial --> active : quarantine run again and completes
  degraded --> active : pf enabled again
  active --> partial : a rule or the policy is removed
  active --> degraded : macOS pf is disabled
  active --> inactive : unquarantine succeeds
  partial --> inactive : unquarantine succeeds
  degraded --> inactive : unquarantine succeeds
  active --> uncertain : status read fails
  partial --> uncertain : status read fails
  inactive --> uncertain : status read fails
  uncertain --> active : a later read confirms containment
  uncertain --> inactive : a later read finds none

These are the five answers status can give. uncertain is a statement about the read, not about the firewall: it is what you get when the firewall query or pfctl read fails or cannot be parsed, and it is never reported as active or inactive. degraded only exists on macOS, where pf can hold the blocking ruleset while pf itself is switched off.

Isolate, then re-apply on reconnect

sequenceDiagram
  participant Op as Operator via MCP
  participant Srv as Server
  participant QS as QuarantineStore
  participant Ag as quarantine plugin
  participant FW as OS firewall
  participant Rec as Reconciler (server background job)
  Op->>Srv: quarantine_device with agent, reason, optional whitelist
  Srv->>QS: write the active record
  Srv->>Ag: dispatch quarantine with whitelist_ips
  Note over Ag: take the mutation gate for up to 2 seconds, else status busy
  Note over Ag: add the agent's pre-resolved server address to the whitelist
  Ag->>FW: block all, allow loopback and the whitelist
  Ag-->>Srv: status quarantined, quarantined_partial or failed
  Note over Srv: other operator dispatches to the device are refused while the record is active
  Rec->>QS: read the stored record when the agent reconnects or on a timer
  Rec->>Ag: quarantine again using the stored whitelist only
  Rec->>Ag: status
  Ag-->>Rec: state active
  Rec->>QS: mark the endpoint confirmed

The server records the intent first, then dispatches. If the device was offline or restarted, the reconciler (a server background job that re-applies stored containment) re-applies from the stored record alone (never a caller-supplied value) and counts the device as confirmed only when a follow-up status reports active; a device it had already confirmed is re-checked with status first after a session change. The REST POST /api/v1/quarantine route only records the intent and relies on the reconciler to apply it; MCP quarantine_device dispatches immediately. The four quarantine actions are exempt from the dispatch gate so a contained device can still be released.

OS capability

Privileges and prerequisites

Binaries: netsh.exe (Windows), /usr/sbin/iptables and /usr/sbin/ip6tables (Linux), /sbin/pfctl (macOS). Every call goes through yuzu::agent::run_bounded_subprocess with a 15-second deadline for mutating calls and 10 seconds for reads, never a shell. There is no network access beyond the agent’s existing gRPC channel.

Data contract

Inputs

Outputs

Every action writes pipe-delimited key|value pairs via ctx.write_output — not a fixed-position row like the collector plugins’ field0|field1|… schema, so a caller reads by key name, never by column offset. A hard failure before any mutation is attempted (a missing/invalid parameter, a failed macOS whitelist-read prerequisite) emits error|<message> instead of the action’s normal status/state row. Several outcomes also carry extra keys the declared schema below does not enumerate — prior_policy, rules_attempted and note on quarantine; note on unquarantine, status and whitelist.

security.quarantine.isolate — status|rules_applied

security.quarantine.release — status

security.quarantine.status — state|whitelist

security.quarantine.whitelist — status|whitelist

Result status

Surfaced as plugin_result_status on the command response, set via ctx.set_result_status or forwarded from a runner failure via yuzu::agent::forward_runner_failure.

Where the data goes

• Instruction result. Every action’s output rows and result status travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore, queryable at /api/responses/{id}, like any other plugin dispatch.
• QuarantineStore (Postgres, authoritative). MCP quarantine_device writes the containment intent through QuarantineStore::quarantine_device before it dispatches this plugin’s quarantine action. The store holds at most one active record per agent and is not expendable telemetry: it persists until an administrator lifts it, with no clock-guarded retention. QuarantineContainmentReconciler re-drives containment from that stored record alone, never a fresh or caller-supplied value, when the agent reconnects, through the shared redispatch_stored_containment chokepoint.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX or metrics. Nothing runs on a schedule inside the plugin; it executes only when an operator, MCP quarantine_device or the reconciler dispatches one of its four definitions.
• Sensitivity. whitelist rows, emitted by status (when the state is active or partial) and by whitelist, carry the quarantine allow-list as raw IP addresses, network identifiers that can pinpoint a specific device or server. The other fields (status, state, rules_applied, note) are counts, enums and free-text failure descriptions; none names a person or installed software.
• Siblings: rdp_control.set_state shares the same Administrators-group-or-equivalent grant shape on Windows and cites it rather than declaring a new right (docs/agent-privilege-model.md, row for rdp_control.set_state).
• MCP / REST. Discover: discover_plugins (summary) then yuzu://plugin-docs (this page as data) then discover_instructions / get_definition("security.quarantine.isolate"). Run: execute_instruction {definition_id, parameters}, or MCP quarantine_device for the record plus live isolation. Read: /api/responses/{id} for the instruction result; /api/v1/quarantine for the QuarantineStore-backed record.

Sample output

Windows — captured: windows Microsoft Windows NT 10.0.26200.0 x64 · bare-metal · 2026-09-07 · SYSTEM · leg-hash f4d514eecc28

== action=quarantine
[not captured] Destructive/Irreversible: not executed on a live host

== action=unquarantine
[not captured] Mutating/Reversible: not executed on a live host

== action=status
state|inactive
[result_status] UNDECLARED / UNKNOWN

== action=whitelist
error|missing required parameter: action (add/remove)
[result_status] UNDECLARED / UNKNOWN
[rc] 1

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-09-07 · euid 501 (jsmith) · leg-hash f4d514eecc28

== action=quarantine
[not captured] Destructive/Irreversible: not executed on a live host

== action=unquarantine
[not captured] Mutating/Reversible: not executed on a live host

== action=status
state|uncertain|note|pf state could not be read -- containment can be neither confirmed nor ruled out
[result_status] UNAVAILABLE / PARTIAL / quarantine:macos_is_quarantined pf status unreadable
[rc] 1

== action=whitelist
error|missing required parameter: action (add/remove)
[result_status] UNDECLARED / UNKNOWN
[rc] 1

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-09-06 · euid 0 · leg-hash f4d514eecc28

== action=quarantine
[not captured] Destructive/Irreversible: not executed on a live host

== action=unquarantine
[not captured] Mutating/Reversible: not executed on a live host

== action=status
state|uncertain|note|ipv6_unavailable — IPv6 stack is up but ip6tables is not installed
[result_status] UNAVAILABLE / PARTIAL / subprocess_runner:spawn_error
[rc] 1

== action=whitelist
error|missing required parameter: action (add/remove)
[result_status] UNDECLARED / UNKNOWN
[rc] 1

Caveats and known gaps

1. macOS release is not a genuine undo. unquarantine reloads /etc/pf.conf, never the endpoint’s prior ruleset, so any runtime pf rules present before quarantine are permanently lost; if the reload itself fails it disables pf, which is more permissive than the host started. This is why the capability catalogue classifies quarantine Irreversible on every platform.
2. whitelist can isolate a clean macOS device. pf has no per-rule granularity, so add and remove rebuild and reload the whole main ruleset, which always ends in block all and enables pf, whatever the device’s current state. Running whitelist against a device that is not yet quarantined therefore quarantines it.
3. Releasing the server record does not lift the firewall. REST DELETE /api/v1/quarantine/{agent_id} and the console release end only the QuarantineStore record and stop the reconciler re-applying; the device stays isolated until the unquarantine action runs on it. REST POST /api/v1/quarantine is the mirror image and only records the intent, leaving the reconciler to apply it.
4. Linux coverage is INPUT and OUTPUT only. The chain is jumped to first from those two chains, so forwarded traffic and rules the plugin does not manage are untouched, and the plugin never calls nft. A host with an IPv6 stack but no ip6tables binary reports quarantined_partial because the IPv4 side is contained and the IPv6 side is not.
5. Release replays state captured at the first quarantine. The Windows pre-quarantine firewall policy and the Linux “ip6tables applied” marker are kept in agent storage, written once until a clean release clears them, so a repeat quarantine never overwrites a good restore image and a failed release keeps them for the retry. If no Windows policy was captured, release restores the Windows default (blockinbound,allowoutbound) and says so in a note.

Source and tests

• Plugin: agents/plugins/quarantine/src/quarantine_parsers.hpp · agents/plugins/quarantine/src/quarantine_plugin.cpp · agents/plugins/quarantine/src/quarantine_serialization.hpp
• Definitions: content/definitions/quarantine.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_c.hpp
• Tests: tests/unit/server/test_quarantine_containment_reconciler.cpp · tests/unit/server/test_quarantine_dispatch_decision.cpp · tests/unit/server/test_quarantine_dispatch_gate.cpp · tests/unit/server/test_quarantine_read_model.cpp · tests/unit/server/test_quarantine_reapply.cpp · tests/unit/server/test_quarantine_store.cpp · tests/unit/test_quarantine_argv.cpp · tests/unit/test_quarantine_parsers.cpp · tests/unit/test_quarantine_serialization.cpp
• Privilege row: docs/agent-privilege-model.md