ioc

How it works

check is the plugin’s only action. It takes five optional, comma-separated parameters (ip_addresses, domains, file_hashes, file_paths, ports); if none are supplied it writes one error|none|false|No IOC parameters provided row and returns 1 without ever writing the column-header line (ioc_plugin.cpp:802-809). Otherwise it writes a literal type|value|matched|detail header line (ioc_plugin.cpp:809), then runs each supplied check in a fixed order — IP, domain, hash, path, port — reporting progress at 30/50/70/90/100% (ioc_plugin.cpp:817-847). Active connections are enumerated once and shared by the IP and port checks (ioc_plugin.cpp:812-815). Domain checking is two different mechanisms depending on OS: the Windows leg queries the live DNS resolver cache via the undocumented DnsGetCacheDataTable export; Linux and macOS instead do a substring search over /etc/hosts (ioc_plugin.cpp:392-425,604-629). Hash checking never touches an IOC feed or reputation service — it computes SHA-256 (a from-scratch implementation, no OpenSSL) over every path in file_paths and compares against each requested hash (ioc_plugin.cpp:452-549,633-674); without file_paths every requested hash reports unmatched. The plugin deliberately does no network calls, no threat-intel lookup, and no quarantine or remediation action — it only reports what is locally observable at call time.

flowchart LR
  OP["Operator / workflow"] --> SRV["Server - authz: Security.Read"]
  SRV -->|"gRPC mTLS"| HOST["Agent plugin host"] --> EX["ioc.execute"]
  EX --> WIN["Windows leg - GetExtendedTcpTable/UdpTable, DnsGetCacheDataTable, GetFileAttributesEx-family"]
  EX --> MAC["macOS leg - libproc via macos_socket_walk.hpp, /etc/hosts + stat"]
  EX --> LIN["Linux leg - /proc/net/tcp[6] + /etc/hosts + stat"]
  WIN & MAC & LIN --> ROWS["pipe rows + UNDECLARED status"] --> RS[("ResponseStore")] --> API["REST /api/responses"]

OS capability

Declared limits per leg (descriptor fallback text, verbatim):

• check / macOS — UDP rows carry an empty state (no fabricated “LISTEN”) — a real UDP listener still matches a port check, but its detail text differs from a TCP match; a port shared by more than one process (SO_REUSEPORT, prefork) reports the pid of one arbitrarily-chosen owner in its match detail, not every owner

Privileges and prerequisites

No external binaries or subprocesses on any OS — all three legs read OS-native tables/files directly (ioc_plugin.cpp:21-25). No outbound network access; the Windows DNS check reads the local resolver cache, it does not resolve or query anything.

Data contract

Inputs

Outputs

Pipe-delimited rows, type|value|matched|detail (ioc_plugin.cpp:809). Unlike the collector-style plugins, the field-name header is itself written as the first output line whenever at least one check ran — it is not a data row and downstream consumers keying on type should skip it. Any literal | in value or detail is escaped to \| (ioc_plugin.cpp:107-118). There is no empty-row placeholder: a parameter that matches nothing simply gets matched=false with an explanatory detail, and a check call with no parameters at all skips the header and emits exactly one error row instead (ioc_plugin.cpp:802-809).

security.ioc.check — type|value|matched|detail

Result status

This plugin does not set a typed result status; the agent records UNDECLARED and every sample shows UNDECLARED / UNKNOWN / (ioc_plugin.cpp has no set_result_status/yuzu_ctx_set_result_status call anywhere in the file; confirmed against docs/samples/windows.txt:7, macos.txt:7, linux.txt:7).

Where the data goes

• Instruction result only. Rows travel over the agent’s mTLS gRPC channel as the command response and land in the ResponseStore (90-day default retention, response_store.hpp:8), queryable at /api/responses/{id} and aggregatable by (type, matched) count per the definition’s own aggregation block (content/definitions/ioc.yaml:112-114).
• Not consumed by daily-sync inventory, the Echo warehouse, DEX, or metrics. Nothing runs on a schedule; the plugin executes only when an operator or workflow dispatches security.ioc.check.
• Sensitivity. value is the operator-supplied IOC being checked (an IP, domain, hash, path, or port — not host state), and detail can name an owning process id (pid) on Windows/macOS matches — no row carries a device serial/hostname, a username, or an installed-software name/version.
• Siblings: grouped with security.quarantine.{isolate,release,status,whitelist}, security.certificates.{list,details,delete}, and security.sccm.{client_version,site} under the core.security.security-response instruction set (content/definitions/security_response_set.yaml:20-32).
• MCP / REST. Discover: discover_plugins (summary) → yuzu://plugin-docs (this page as data) → discover_instructions / get_definition("security.ioc.check"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}.

Sample output

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

== action=check ip_addresses=127.0.0.1 domains=localhost ports=22
type|value|matched|detail
ip|127.0.0.1|true|Active connection - ESTABLISHED (pid 6436)
domain|localhost|false|Not in DNS cache
port|22|true|Listening (pid 5148)
[result_status] UNDECLARED / UNKNOWN

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

== action=check ip_addresses=127.0.0.1 domains=localhost ports=22
type|value|matched|detail
ip|127.0.0.1|true|Active connection - LISTEN (pid 20945)
domain|localhost|true|Found in /etc/hosts
port|22|false|No listening service on this port
[result_status] UNDECLARED / UNKNOWN

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

== action=check ip_addresses=127.0.0.1 domains=localhost ports=22
type|value|matched|detail
ip|127.0.0.1|false|Not found in active connections
domain|localhost|true|Found in /etc/hosts
port|22|false|No listening service on this port
[result_status] UNDECLARED / UNKNOWN

Caveats and known gaps

1. IP matching includes local bind addresses, not just remote peers. check_ip_addresses() matches an IOC IP against either conn.local_addr or conn.remote_addr (ioc_plugin.cpp:575) — the macOS capture shows 127.0.0.1 reported matched=true with detail Active connection - LISTEN (pid 20945) (docs/samples/macos.txt:4), i.e. a socket merely bound to the checked address counts as a match even with no outbound connection to it.
2. Linux sees TCP only. get_connections() on Linux parses /proc/net/tcp and /proc/net/tcp6 only — there is no /proc/net/udp read (ioc_plugin.cpp:346-351) — so ip_addresses/ports checks against a UDP-only listener silently report “not found” on Linux even though the same check would match on Windows or macOS.
3. Silent degradation on API failure, not a typed error. If GetExtendedTcpTable/GetExtendedUdpTable returns a non-NO_ERROR status, get_connections() simply adds no rows for that table rather than surfacing a failure (ioc_plugin.cpp:141-179,222-242); combined with the plugin never setting a result status, a caller cannot distinguish “checked, not present” from “the connection table couldn’t be read.”
4. /etc/hosts domain matching is a raw substring search. check_domains() on Linux/macOS strips comments then does line.find(domain) (ioc_plugin.cpp:613-621) — a short or partial domain can match unrelated lines; there is no word-boundary or exact-hostname check.
5. PID is never available from the Linux TCP parse. parse_proc_net() hard-codes PID 0 for every connection (ioc_plugin.cpp:341), so Linux ip/port match details never name an owning process the way Windows and macOS do.

Source and tests

• Plugin: agents/plugins/ioc/src/ioc_plugin.cpp
• Definitions: content/definitions/ioc.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_d.hpp
• Tests: none found by name
• Privilege row: docs/agent-privilege-model.md (no row yet)