plexsphere

Appearance

plexctl integrity ​

Synopsis ​

plexctl integrity is the operator surface for the integrity-violation triage workflow. Nodes report violations of three kinds — binary, hook, and host_key — and each violation moves through the lifecycle open → acknowledged → resolved. The family exposes three leaves:

  • list — page the violations visible to the caller, narrowed by optional residency and lifecycle filters.
  • get — fetch a single violation by identifier.
  • acknowledge — record an operator triage decision against a violation with a mandatory, audited reason.
text
plexctl integrity <subcommand> [flags]

Subcommands ​

plexctl integrity list ​

GETs /v1/integrity-violations. Pagination is keyset-based via --cursor / --limit; the response carries a next_cursor the caller threads into the next --cursor to walk the pages. The optional --domain-id / --project-id / --node-id residency filters and the --kind / --status filters compose to narrow the page. --kind and --status are validated locally against the known enums; an unknown value exits 2 before the request reaches the wire. Each row renders ID, DOMAIN_ID, NODE_ID, KIND, ARTIFACT_ID, STATUS, and DETECTED_AT.

plexctl integrity get <id> ​

Fetches a single violation by identifier. There is no server-side single-violation operation — the read API exposes only the list endpoint and the acknowledge transition. get is therefore a client-side projection: it pages the list following next_cursor and returns the first row whose id matches the requested identifier. The scan is bounded by a page cap so a mistyped id can never spin the CLI across an unbounded result set; when the identifier is not found within the cap the command exits 1. Local UUID validation rejects a malformed id with exit 2.

plexctl integrity acknowledge <id> ​

POSTs /v1/integrity-violations/{id}/acknowledge with the supplied reason, transitioning the violation from open to acknowledged. The server responds 200 OK with the updated violation row, which the CLI renders on stdout.

--reason is required and is recorded in the audit trail; cobra rejects an invocation that omits it with exit 2 before the request is sent. The non-empty / non-whitespace rule on the reason itself is server-authoritative — a rejected reason surfaces as a 400 the CLI maps onto its exit-code taxonomy, so the CLI does not drift when the bound changes.

The acknowledge path is elevated. A credential that is expired or under-scoped for the transition surfaces as a 4xx — for example a 401 step-up challenge maps to exit 3, and a 403 maps to exit 4 (or 77 for a ReBAC denial) per the shared taxonomy. Local UUID validation rejects a malformed id with exit 2.

Flags ​

plexctl integrity list ​

FlagTypeRequiredDescription
--domain-idUUIDnoOptional owning-Domain UUID filter.
--project-idUUIDnoOptional Project UUID filter.
--node-idUUIDnoOptional reporting-Node UUID filter.
--kindstringnoViolation-kind filter: binary, hook, or host_key. Validated locally.
--statusstringnoLifecycle filter: open, acknowledged, or resolved. Validated locally.
--cursorstringnoContinuation token returned by a previous call's next_cursor.
--limitintnoMaximum items per page (server default when zero).

plexctl integrity get <id> ​

get takes the violation identifier as a positional argument and has no command-specific flags.

plexctl integrity acknowledge <id> ​

FlagTypeRequiredDescription
--reasonstringyesAudit-recorded acknowledgement rationale. The non-empty rule is enforced server-side.

Persistent flags inherited from root ​

--server, --profile, --token-file, --output, --yes. See ../plexctl.md.

Exit codes ​

See ../plexctl.md#exit-code-taxonomy.

Examples ​

List the open violations for a Node ​

shell
plexctl integrity list \
  --server  "${PLEXSPHERE_URL}" \
  --node-id 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0b1 \
  --status  open

Filter by kind and walk the pages ​

shell
plexctl integrity list \
  --server "${PLEXSPHERE_URL}" \
  --kind   binary \
  --limit  50

plexctl integrity list \
  --server "${PLEXSPHERE_URL}" \
  --kind   binary \
  --limit  50 \
  --cursor "${NEXT_CURSOR}"

Get a single violation ​

shell
plexctl integrity get 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --server "${PLEXSPHERE_URL}"

Acknowledge a violation with an audited reason ​

shell
plexctl integrity acknowledge 0190a8b8-a0c0-7a0a-8a0a-a0a0a0a0a0c0 \
  --server "${PLEXSPHERE_URL}" \
  --reason "investigated, confirmed false positive"

Cross-references ​