filesystem

How it works

The filesystem plugin reads, inspects and edits files on the device the agent runs on. Its 16 actions fall into four groups: look (exists, list_dir, read, search, search_dir), identify (file_hash, find_by_hash, get_signature, get_version_info, get_acl), create (create_temp, create_temp_dir) and change (write_content, replace, append, delete_lines). Most actions turn the caller’s path into its canonical form, following symlinks, and, if the caller also passes base_dir, refuse a path that resolves outside that directory. The exceptions: find_by_hash and create_temp take no base_dir, and exists and a new-file write_content canonicalise only the parent directory when the target does not exist yet. Reads never alter the target. Changes to an existing file (replace, delete_lines, and write_content with overwrite=true) are written to a new sibling file and renamed over the target, so a reader sees either the old or the new content. append, write_content creating a new file, and the temp-file actions open the target directly. It is deliberately not a file manager: there is no whole-file delete, rename or copy, and no ACL write; get_acl only reads.

How the main actions work:

• Hashing one file. file_hash hashes in process on Windows (BCrypt). On macOS and Linux it runs shasum or sha256sum/sha1sum by absolute path, with no shell, through the bounded subprocess runner (compute_hash_unix, 300 second deadline).
• Finding a file by hash. find_by_hash hashes in process on every OS and starts no subprocess (filesystem_find_by_hash.hpp). It walks the tree under fixed bounds (20 seconds, 50,000 entries visited, 4 GiB hashed, 100 matches), does not follow a symlink it meets below the search root (on Windows and on older Linux only the final component is opened no-follow, Caveat 2), reads nothing but a regular file, and refuses a root on a network mount (on macOS and Linux also a network mount below it) before touching it. What it skipped is counted in one trailing truncated|... row and, when that matters, a CONSTRAINED result status; the diagram below and Result status say how to read it.
• Signature and version. get_signature and get_version_info exist on Windows and macOS only. Windows uses WinVerifyTrust and GetFileVersionInfoW in process; macOS runs /usr/bin/codesign and /usr/bin/plutil through the same runner, re-validating the path immediately before the exec. On Linux both answer error| with a non-zero return code.
• Search. search, search_dir and replace reject regexes with nested quantifiers (has_nested_quantifiers) to avoid catastrophic backtracking, and limit patterns to 256 characters. search_dir matches entry names only, as a glob (glob_match) or a regex, never file contents.
• Atomic writes. The temporary file is created exclusively with a random name, written, flushed to disk with fsync on macOS and Linux (F_FULLFSYNC first on macOS; the Windows leg does not fsync), then renamed into place (atomic_write_file). A new file gets the usual 0666 minus umask; an existing file keeps its permission bits on POSIX, but its owner, group, ACLs and hard links are not carried over because the rename replaces the file. A leftover file at the temp path fails the write rather than being followed.
• get_acl. Each OS reads its native ACL (see the table below) and prints it in the same ace|<type>|<principal>|<access>|<flags> row shape.

Only find_by_hash sets a typed result status, and only when it could not examine part of the tree or ran without its network-mount guard; every other outcome is carried in the rows and return code (see Result status).

flowchart LR
  OP["Operator or workflow"] --> SRV["Server: authz FileRetrieval Read, Write or Delete, gate None or AdminOrApproval"]
  SRV -- "gRPC mTLS" --> HOST["Agent plugin host"] --> EX["filesystem.execute"]
  EX --> VAL["validate_path: canonical path, optional base_dir"]
  VAL --> WIN["Windows leg: std::filesystem, BCrypt, WinVerifyTrust, version info, Win32 ACL"]
  VAL --> MAC["macOS leg: std::filesystem, shasum for file_hash, in-process SHA-256 for find_by_hash, codesign, plutil, ACL"]
  VAL --> LIN["Linux leg: std::filesystem, sha256sum and sha1sum for file_hash, in-process SHA-256 for find_by_hash, xattr ACL"]
  WIN --> ROWS["Pipe rows; a typed result status from find_by_hash only"]
  MAC --> ROWS
  LIN --> ROWS
  ROWS --> RS[("ResponseStore, 90 day default retention")] --> API["REST /api/responses, MCP execute_instruction"]

What you can decide with it

Safe workflow for changes. There is no backup and no undo: a change overwrites the file, and the old content is gone unless you kept a copy elsewhere. Work in this order: confirm the target with exists and read (or search to find the line); use replace with dry_run=true to see how many replacements it would make, since the other change actions have no preview; apply the change; verify by read, search or file_hash. Target rules: the path must already exist, except write_content with create=true, whose parent directory must exist. write_content refuses to touch an existing file unless overwrite=true, and refuses to create one unless create=true. replace, append and delete_lines need a regular file, and the text actions treat the file as lines (delete_lines rewrites the file so it ends with a newline, unless no lines remain). With regex=true, replace expands $1-style references in the replacement only when max_replacements is 0; with a limit it inserts the replacement text literally, so the same replacement string can behave differently with and without a limit.

get_acl by OS.

On Linux and macOS the whole ACL is read before any row is written, so a failure is one error| row. On Windows an error part-way through the entries can follow rows already written.

Diagrams

Write path

sequenceDiagram
  participant S as Server
  participant P as filesystem plugin
  participant D as Disk
  S->>P: replace with path, search, replacement, optional base_dir
  P->>D: canonicalize path, check base_dir, regular file, size cap
  D-->>P: file bytes read into memory
  P->>P: match and substitute in memory
  alt dry_run is true or nothing matched
    P-->>S: replacements_made and sizes, file untouched
  else changes to write
    P->>D: create sibling temp exclusively, write, fsync, rename over target
    P-->>S: replacements_made and sizes
  end

replace, delete_lines and write_content on an existing file all follow the atomic path above. append and write_content on a new file skip the temp-and-rename step and write straight into the target, so an interrupted write can leave a partial file. The size cap is checked before anything is read, and the result is built entirely in memory.

find_by_hash

flowchart TD
  S["find_by_hash with directory, sha256, max_depth"] --> MT["Read the network-mount list first: Linux /proc/self/mountinfo, macOS getmntinfo_r_np, Windows the root's own spelling and drive type"]
  MT --> RM{"Is the directory as given on a network mount, a UNC path or a non-fixed drive?"}
  RM -->|"yes"| RX["Refused before anything touches it: skipped_network_mount, CONSTRAINED"]
  RM -->|"no"| V["validate_path: canonical directory; then max_depth is clamped to 1-10"]
  V --> RC{"Canonical root under a listed network mount (macOS, Linux), or not listable?"}
  RC -->|"yes"| RR["rc 0: skipped_network_mount=1 or skipped_unreadable=1, CONSTRAINED"]
  RR --> OUT
  RC -->|"no"| NX["Next entry"]
  NX --> B{"20 seconds or 50,000 entries reached, or the agent shutting down?"}
  B -->|"yes"| STOP["Stop with reason deadline, file_cap or cancelled"]
  B -->|"no"| K{"What is the entry, judged without following it?"}
  K -->|"under a network mount (macOS, Linux)"| SN["skipped_network_mount, not entered"]
  K -->|"symlink or junction"| SL["skipped_symlink, never followed"]
  K -->|"FIFO, device or socket"| SR["skipped_not_regular, never opened"]
  K -->|"directory"| D{"Can it be listed? On Linux: not a pseudo-filesystem such as /proc"}
  D -->|"no"| SU["skipped_unreadable"]
  D -->|"yes, or at max_depth: not opened, not counted"| NX
  K -->|"regular file"| O["Open no-follow; regular file and size decided on that descriptor or handle"]
  O -->|"over 10 GB, or larger than the bytes left in the budget"| SO["skipped_oversize; the second also makes the reason byte_cap"]
  O -->|"cannot open or read, cloud placeholder, unknown reparse tag"| SU
  O -->|"a link at open time"| SL
  O -->|"not a regular file at open time"| SR
  O -->|"ok"| H["Stream 64 KiB chunks through SHA-256, budget checked per chunk"]
  H -->|"equals the target"| M["match row; at 100 matches stop with max_results if entries remain"]
  H -->|"differs"| NX
  H -->|"a bound trips mid-file: byte_cap, deadline or cancelled"| STOP
  SN --> NX
  SL --> NX
  SR --> NX
  SU --> NX
  SO --> NX
  M --> NX
  NX -->|"none left"| OUT
  STOP --> OUT["Closing rows: network_mount_guard unavailable when the mount table could not be read, one truncated row when anything was skipped or the walk stopped, then matches_found"]

The mount check is a string comparison that runs before any call touching a path, because an open or listing on a dead hard-mounted server would hold one of the agent’s shared command workers with no deadline. Every skip the walk sees lands in a counter of the trailing truncated|<reason>|visited=N|hashed=N|skipped_unreadable=N|skipped_symlink=N|skipped_not_regular=N|skipped_oversize=N|skipped_network_mount=N row, written only when something was skipped or the walk stopped early (reason is none when no bound tripped). hashed= counts bytes admitted to the hasher, including a file abandoned part-way (no match is reported for it). Empty files are hashed. Stopping at 100 matches counts as a bound only when entries remained, so exactly 100 matches in a fully walked tree is clean. A search root that cannot be listed is not an error| line either: it answers return code 0 with skipped_unreadable=1 and CONSTRAINED. Caveat 2 lists the races that can still skip a directory uncounted.

How the “never followed” holds per OS. macOS opens every candidate with O_NOFOLLOW_ANY (no symlink in any path component) and turns the thread’s dataless-file materialisation off for the walk, so an iCloud or File Provider item that is not downloaded fails to open and is counted unreadable instead of being fetched. Linux 5.6 or later opens with openat2(RESOLVE_NO_SYMLINKS); on an older kernel, or where a seccomp profile denies openat2, it falls back to O_NOFOLLOW on the final component only, for the rest of the process’s life once openat2 has been refused (an architecture with no known openat2 number always uses the fallback). Windows opens the final component with FILE_FLAG_OPEN_REPARSE_POINT and classifies the handle before any read: a symlink, junction or other name-surrogate reparse point is a link, a compressed (WOF) or deduplicated file is hashed through a handle reopened without the reparse flag, and a cloud placeholder, an offline file or any other reparse tag is counted unreadable and never recalled. On Windows a mounted folder below the root is a reparse point and is skipped as a junction, and a \\?\ root reads as a UNC path and is refused. A relative directory is judged by its absolute spelling (the working directory joined lexically), so pass absolute paths.

OS capability

Privileges and prerequisites

Subprocesses: shasum (macOS) and sha256sum/sha1sum (Linux) for file_hash only (compute_hash_unix; find_by_hash starts none); /usr/bin/codesign for macOS get_signature (do_get_signature); /usr/bin/plutil for macOS get_version_info (do_get_version_info). Every one is invoked by absolute path with no shell through yuzu::agent::run_bounded_subprocess. No network access on any OS.

Who may run what is decided by the compiled capability row, not by the header’s role line. The plugin description says “admin-only”, but the read actions run for endpoint-operator as well as endpoint-admin; the write actions, create_temp, create_temp_dir and find_by_hash carry the AdminOrApproval gate. permissions.executeRoles in the definition YAML is documentation only and is not an access-control guarantee.

Data contract

Inputs

Outputs

Every action writes pipe-delimited lines. A repeating row (list_dir’s entry rows, get_acl’s ace rows on every OS, search_dir’s result rows, find_by_hash’s match rows, read’s and search’s line rows) starts with a literal word naming its kind, then its fields; a single-value field is its own key|value line. There is no placeholder row for “found nothing”: a zero-hit action reports only its trailing count (total_matches|0, matches_found|0). find_by_hash adds up to two rows between its match rows and its count: network_mount_guard|unavailable when the mount table could not be read, then one truncated|... row when it skipped anything or stopped early; only match rows have the three fields a column matcher reads. A match path containing CR or LF shows a space in its place, | is escaped, and a trailing backslash becomes /. Failure ends with an error|<message> line and a non-zero return code, never a placeholder success row (see Result status), with two exceptions: get_signature reports its verdict in signature_status (including unknown and error_0x...) and get_version_info on macOS reports version_status|not_available, both with return code 0. An unknown action name writes unknown action: <name> with return code 1. For get_acl the ace row is ace|<type>|<principal>|<access>|<flags>, with - for an empty field and <access> as permission text on Linux and macOS but a hex access mask on Windows; acl|<none|extended|unsupported>|<acl flags or -> (Linux, macOS) and control|<flags or -> (Windows) are single-value rows.

Two places where the emitted rows and the declared columns differ, so match on the emitted names. delete_lines emits lines_deleted, total_lines_before and total_lines_after, while its definition declares lines_before and lines_after. append’s total_size is not the size after the append (see Caveat 3).

device.filesystem.append — status|bytes_appended|total_size

device.filesystem.create_temp — path|persist

device.filesystem.create_temp_dir — path|persist

device.filesystem.delete_lines — lines_deleted|lines_before|lines_after

device.filesystem.exists — exists|type|size

device.filesystem.file_hash — hash|algorithm|size

device.filesystem.find_by_hash — row_kind|path|size

device.filesystem.get_acl — sddl|ace_type|account|access_mask|owner|group|permissions|mode|ace_perms|ace_flags|acl|acl_flags|control

device.filesystem.get_signature — signature_status

device.filesystem.get_version_info — file_version|product_version|company_name|file_description|internal_name|original_filename|product_name|legal_copyright|version_status

device.filesystem.list_dir — entry_name|entry_type|entry_size

device.filesystem.read — line_number|content|total_lines|file_size

device.filesystem.replace — replacements_made|file_size_before|file_size_after|dry_run

device.filesystem.search — line_number|content|total_matches

device.filesystem.search_dir — path|entry_type|total_matches

device.filesystem.write_content — status|bytes_written|path

workflow.config_search_and_replace — replacements_made|file_size_before|file_size_after

workflow.version_compliance_check — file_version|product_version|company_name|product_name|file_description

Result status

Reading a find_by_hash result. The status number is stored with the response and, when not zero, rides on the agent-transition event of the execution event stream (GET /api/v1/events), but the REST and MCP response rows and the CSV export do not carry it, and the completeness and provenance reach only the agent log (the wire carries the status enum alone, plugin_result_status in agent.proto). The rows are the signal you can see: the search is incomplete when the truncated reason is not none, when skipped_unreadable or skipped_network_mount is above zero, or when a network_mount_guard|unavailable row is present. matches_found|0 beside either row means “not found in the part examined”, never “not present”. A result-set column matcher takes only rows of the declared width, so it sees only match rows and cannot pick out the devices a search covered only in part: read the output rows for that. The bounds are fixed, not parameters: search a large tree one subdirectory at a time, and set stagger_seconds on a fleet-wide dispatch so every agent does not hash at once.

The truncated row’s counters:

• skipped_unreadable: an entry, directory or root that could not be opened or listed (permissions, vanished, a Linux pseudo-filesystem directory, a macOS dataless item, a Windows cloud placeholder, offline file or unknown reparse tag), an entry whose type could not be read, or an enumeration error (which also ends the walk). Makes the result CONSTRAINED.
• skipped_network_mount: a root on a network mount, a UNC share or a non-fixed Windows drive, or (macOS and Linux only) a subtree on a network mount, refused before anything under it was read. Makes the result CONSTRAINED.
• skipped_symlink: a symlink or junction, including one the no-follow open met, never followed. By design; does not constrain.
• skipped_not_regular: a FIFO, device or socket, or a non-file found at open time, never read. Does not constrain.
• skipped_oversize: a file over 10 GB (by design, does not constrain), or one larger than the bytes left in the 4 GiB budget (the walk goes on, the reason becomes byte_cap, and the result is CONSTRAINED).
• visited, hashed: entries seen; bytes admitted to the hasher.

The output never names a skipped path: when a counter is above zero, narrow it down by searching subdirectories.

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), queryable at /api/responses/{id}.
• Not consumed by daily-sync inventory, the Echo warehouse, DEX or metrics: no sync source, Echo or DEX consumer reads device.filesystem.* results, only the generic result parser does. Nothing runs on a schedule; the plugin executes only when an operator or workflow dispatches one of its 16 definitions.
• Sensitivity. get_acl rows carry local account names (owner and group on Linux and macOS, and the principal of every ace row on all three OSes), potentially real usernames. get_version_info and get_signature rows name specific installed software (company_name, product_name, file_description), an installed-software inventory by another route. read, search and write_content carry whatever the operator pointed them at, which can include credentials or personal data in file contents or usernames in paths.
• Siblings: filesystem_posture.mounts, .quotas and .snapshots are a separate, similarly named, read-only plugin (mount, quota and snapshot inventory only; no read, hash or write actions); do not confuse the two. Two shipped workflow definitions chain this plugin’s actions: workflow.config_search_and_replace (in t2_chaining_examples.yaml) searches a config file then dispatches replace, and workflow.version_compliance_check dispatches get_version_info and compares the result against a minimum version.
• MCP / REST. Discover: discover_plugins (summary), then yuzu://plugin-docs (this page as data), then discover_instructions or get_definition("device.filesystem.file_hash"). Run: execute_instruction {definition_id, parameters}. Read: /api/responses/{id}.

Sample output

Windows — captured: windows Windows 10.0.26200 x86_64 · bare-metal · 2026-10-04 · LocalSystem (elevated) · leg-hash 802f5467fb09

== action=exists path=C:\Windows\System32\drivers\etc\hosts
exists|true
type|file
size|1405
[result_status] UNDECLARED / UNKNOWN

== action=list_dir path=C:\Windows\System32\drivers\etc
entry|hosts|file|1405
entry|hosts.ics|file|444
entry|lmhosts.sam|file|3683
entry|networks|file|407
entry|protocol|file|1358
entry|services|file|17635
[result_status] UNDECLARED / UNKNOWN

== action=file_hash path=C:\Windows\System32\drivers\etc\hosts
hash|9321feab332edbba521c7ea3eb978d9844cb4f62a4730dab9cf60fb79649037d
algorithm|sha256
size|1405
[result_status] UNDECLARED / UNKNOWN

== action=create_temp
path|C:\WINDOWS\TEMP\yuzu-391d5e4c88ea2e641a93b5dd96849117.tmp
persist|true
[result_status] UNDECLARED / UNKNOWN

== action=create_temp_dir
path|C:\WINDOWS\TEMP\yuzu-41a05a87a8d5aae48423ac53334d0429
persist|true
[result_status] UNDECLARED / UNKNOWN

== action=read path=C:\Windows\System32\drivers\etc\hosts
line|1|# Copyright (c) 1993-2009 Microsoft Corp.
line|2|#
line|3|# This is a sample HOSTS file used by Microsoft TCP/IP for Windows.
line|4|#
line|5|# This file contains the mappings of IP addresses to host names. Each
line|6|# entry should be kept on an individual line. The IP address should
line|7|# be placed in the first column followed by the corresponding host name.
line|8|# The IP address and the host name should be separated by at least one
line|9|# space.
line|10|#
line|11|# Additionally, comments (such as these) may be inserted on individual
line|12|# lines or following the machine name denoted by a '#' symbol.
… 12 of 39 rows shown
[result_status] UNDECLARED / UNKNOWN

== action=get_acl path=C:\WINDOWS\TEMP\yuzu_acl_599f97e1\cond.txt
sddl|O:BAD:PAI(XA;;FA;;;WD;(Member_of {SID(BA)}))
control|protected,auto_inherited
ace|allow_conditional|\Everyone|0x001f01ff|-
[result_status] UNDECLARED / UNKNOWN

== action=get_signature path=C:\Windows\System32\notepad.exe
signature_status|unsigned
[result_status] UNDECLARED / UNKNOWN

== action=find_by_hash directory=C:\Windows\System32\drivers\etc sha256=031da282a9436540be78beab34801f32c1429491e881838b0ddf4f8c16e122cc
match|C:\Windows\System32\drivers\etc\hosts|1224
matches_found|1
[result_status] UNDECLARED / UNKNOWN

== action=search_dir root=C:\Windows\System32\drivers\etc pattern=*hosts*
total_matches|0
[result_status] UNDECLARED / UNKNOWN

== action=get_version_info path=C:\Windows\System32\notepad.exe
file_version|6.2.26100.9278
product_version|10.0.26100.9278
company_name|Microsoft Corporation
file_description|Notepad
internal_name|Notepad
original_filename|NOTEPAD.EXE.MUI
product_name|Microsoft® Windows® Operating System
legal_copyright|© Microsoft Corporation. All rights reserved.
[result_status] UNDECLARED / UNKNOWN

== action=search path=C:\Windows\System32\drivers\etc\hosts pattern=localhost
match|19|# localhost name resolution is handled within DNS itself.
match|20|#	127.0.0.1       localhost
match|21|#	::1             localhost
total_matches|3
[result_status] UNDECLARED / UNKNOWN

== action=replace path=C:\WINDOWS\TEMP\yuzu_capture_599f97e1\yuzu_capture_tmp.txt search=yuzu-capture replace=yuzu-replaced
replacements_made|1
file_size_before|24
file_size_after|12
[result_status] UNDECLARED / UNKNOWN

== action=write_content path=C:\WINDOWS\TEMP\yuzu_capture_599f97e1\yuzu_capture_tmp.txt content="yuzu-capture written" overwrite=true
status|ok
bytes_written|20
path|C:\Windows\Temp\yuzu_capture_599f97e1\yuzu_capture_tmp.txt
[result_status] UNDECLARED / UNKNOWN

== action=append path=C:\WINDOWS\TEMP\yuzu_capture_599f97e1\yuzu_capture_tmp.txt content="yuzu-capture appended"
status|ok
bytes_appended|22
total_size|20
[result_status] UNDECLARED / UNKNOWN

== action=delete_lines path=C:\WINDOWS\TEMP\yuzu_capture_599f97e1\yuzu_capture_tmp.txt start_line=1 end_line=1
lines_deleted|1
total_lines_before|2
total_lines_after|1
[result_status] UNDECLARED / UNKNOWN

macOS — captured: macos macOS 26.6.2 arm64 · bare-metal · 2026-10-04 · euid 501 (jsmith) · leg-hash 802f5467fb09

== action=exists path=/etc/hosts
exists|true
type|file
size|213
[result_status] UNDECLARED / UNKNOWN

== action=list_dir path=/etc
entry|manpaths|file|36
entry|rc.common|file|1560
entry|auto_master|file|195
entry|csh.login|file|121
entry|syslog.conf|file|96
entry|krb5.keytab|file|1946
entry|sudoers.d|directory|0
entry|ssl|directory|0
entry|csh.logout|file|39
entry|aliases.db|file|16384
entry|bashrc_Apple_Terminal|file|9293
entry|yuzu|directory|0
… 12 of 76 rows shown
[result_status] UNDECLARED / UNKNOWN

== action=file_hash path=/etc/hosts
hash|c7dd0e2ed261ce76d76f852596c5b54026b9a894fa481381ffd399b556c0e2da
algorithm|sha256
size|213
[result_status] UNDECLARED / UNKNOWN

== action=create_temp
path|/var/folders/hq/lc3t_rsx2blfc8rhys6kzh4r0000gn/T//yuzu-oqRhjd.tmp
persist|true
[result_status] UNDECLARED / UNKNOWN

== action=create_temp_dir
path|/var/folders/hq/lc3t_rsx2blfc8rhys6kzh4r0000gn/T//yuzu-sPr64l
persist|true
[result_status] UNDECLARED / UNKNOWN

== action=read path=/etc/hosts
line|1|##
line|2|# Host Database
line|3|#
line|4|# localhost is used to configure the loopback interface
line|5|# when the system is booting.  Do not change this entry.
line|6|##
line|7|127.0.0.1	localhost
line|8|255.255.255.255	broadcasthost
line|9|::1             localhost
total_lines|9
file_size|213
[result_status] UNDECLARED / UNKNOWN

== action=get_acl path=/tmp/yuzu_test_acl_Rw0R2f/acl_file
owner|jsmith
group|wheel
permissions|rw-r--r--
mode|0644
acl|extended|-
ace|deny|group:staff|delete|-
ace|allow|user:_www|read,write|file_inherit
[result_status] UNDECLARED / UNKNOWN

== action=get_signature path=/bin/ls
signature_status|valid
[result_status] UNDECLARED / UNKNOWN

== action=find_by_hash directory=/etc sha256=c7dd0e2ed261ce76d76f852596c5b54026b9a894fa481381ffd399b556c0e2da
match|/private/etc/hosts|213
truncated|none|visited=261|hashed=2997701|skipped_unreadable=17|skipped_symlink=4|skipped_not_regular=0|skipped_oversize=0|skipped_network_mount=0
matches_found|1
[result_status] CONSTRAINED / PARTIAL / filesystem:skipped_unreadable

== action=search_dir root=/etc pattern=*hosts*
total_matches|0
[result_status] UNDECLARED / UNKNOWN

== action=get_version_info path=/bin/ls
version_status|not_available
[result_status] UNDECLARED / UNKNOWN

== action=search path=/etc/hosts pattern=localhost
match|4|# localhost is used to configure the loopback interface
match|7|127.0.0.1	localhost
match|9|::1             localhost
total_matches|3
[result_status] UNDECLARED / UNKNOWN

== action=replace path=/var/folders/hq/lc3t_rsx2blfc8rhys6kzh4r0000gn/T//yuzu_capture_MaI1z1B3/yuzu_capture_tmp.txt search=yuzu-capture replace=yuzu-replaced
replacements_made|2
file_size_before|37
file_size_after|13
[result_status] UNDECLARED / UNKNOWN

== action=write_content path=/var/folders/hq/lc3t_rsx2blfc8rhys6kzh4r0000gn/T//yuzu_capture_MaI1z1B3/yuzu_capture_tmp.txt content="yuzu-capture written" overwrite=true
status|ok
bytes_written|20
path|/private/var/folders/hq/lc3t_rsx2blfc8rhys6kzh4r0000gn/T/yuzu_capture_MaI1z1B3/yuzu_capture_tmp.txt
[result_status] UNDECLARED / UNKNOWN

== action=append path=/var/folders/hq/lc3t_rsx2blfc8rhys6kzh4r0000gn/T//yuzu_capture_MaI1z1B3/yuzu_capture_tmp.txt content="yuzu-capture appended"
status|ok
bytes_appended|22
total_size|20
[result_status] UNDECLARED / UNKNOWN

== action=delete_lines path=/var/folders/hq/lc3t_rsx2blfc8rhys6kzh4r0000gn/T//yuzu_capture_MaI1z1B3/yuzu_capture_tmp.txt start_line=1 end_line=1
lines_deleted|1
total_lines_before|2
total_lines_after|1
[result_status] UNDECLARED / UNKNOWN

Linux — captured: linux Debian GNU/Linux 13 (trixie) aarch64 · container · 2026-10-04 · euid 0 · leg-hash 802f5467fb09

== action=exists path=/etc/hosts
exists|true
type|file
size|177
[result_status] UNDECLARED / UNKNOWN

== action=list_dir path=/etc
entry|nsswitch.conf|file|494
entry|update-motd.d|directory|0
entry|dpkg|directory|0
entry|skel|directory|0
entry|rc1.d|directory|0
entry|xattr.conf|file|681
entry|fstab|file|37
entry|logrotate.d|directory|0
entry|libaudit.conf|file|191
entry|os-release|file|286
entry|pam.d|directory|0
entry|issue.net|file|20
… 12 of 82 rows shown
[result_status] UNDECLARED / UNKNOWN

== action=file_hash path=/etc/hosts
hash|5ed49ae76ca451e9f063a9b28d11f6e8784a851e983664cb495206b75453c412
algorithm|sha256
size|177
[result_status] UNDECLARED / UNKNOWN

== action=create_temp
path|/tmp/yuzu-GqGF5B.tmp
persist|true
[result_status] UNDECLARED / UNKNOWN

== action=create_temp_dir
path|/tmp/yuzu-CtDWtd
persist|true
[result_status] UNDECLARED / UNKNOWN

== action=read path=/etc/hosts
line|1|127.0.0.1	localhost
line|2|::1	localhost ip6-localhost ip6-loopback
line|3|fe00::	ip6-localnet
line|4|ff00::	ip6-mcastprefix
line|5|ff02::1	ip6-allnodes
line|6|ff02::2	ip6-allrouters
line|7|172.17.0.3	yuzu-capture-host
total_lines|7
file_size|177
[result_status] UNDECLARED / UNKNOWN

== action=get_acl path=/tmp/yuzu_test_acl/f
owner|root
group|root
permissions|rw-rwxr--
mode|0674
acl|extended|-
ace|user|-|rw-|-
ace|user|1001|rw-|-
ace|group|-|r--|-
ace|group|1002|r-x|-
ace|mask|-|rwx|-
ace|other|-|r--|-
[result_status] UNDECLARED / UNKNOWN

== action=get_signature path=/bin/ls
error|code signature verification is not supported on this platform
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=find_by_hash directory=/etc sha256=ed9ab7f958d4c01aa81e80a108e2c69db299b3e7cd6577b286905f1ee4c47b4c
match|/etc/hosts|413
truncated|none|visited=1676|hashed=1922709|skipped_unreadable=0|skipped_symlink=720|skipped_not_regular=0|skipped_oversize=0|skipped_network_mount=0
matches_found|1
[result_status] UNDECLARED / UNKNOWN

== action=search_dir root=/etc pattern=*hosts*
total_matches|0
[result_status] UNDECLARED / UNKNOWN

== action=get_version_info path=/bin/ls
error|version info extraction is not supported on this platform
[result_status] UNDECLARED / UNKNOWN
[rc] 1

== action=search path=/etc/hosts pattern=localhost
match|1|127.0.0.1	localhost
match|2|::1	localhost ip6-localhost ip6-loopback
total_matches|2
[result_status] UNDECLARED / UNKNOWN

== action=replace path=/tmp/yuzu_capture_vySwPCm6/yuzu_capture_tmp.txt search=yuzu-capture replace=yuzu-replaced
replacements_made|2
file_size_before|37
file_size_after|13
[result_status] UNDECLARED / UNKNOWN

== action=write_content path=/tmp/yuzu_capture_vySwPCm6/yuzu_capture_tmp.txt content="yuzu-capture written" overwrite=true
status|ok
bytes_written|20
path|/tmp/yuzu_capture_vySwPCm6/yuzu_capture_tmp.txt
[result_status] UNDECLARED / UNKNOWN

== action=append path=/tmp/yuzu_capture_vySwPCm6/yuzu_capture_tmp.txt content="yuzu-capture appended"
status|ok
bytes_appended|22
total_size|20
[result_status] UNDECLARED / UNKNOWN

== action=delete_lines path=/tmp/yuzu_capture_vySwPCm6/yuzu_capture_tmp.txt start_line=1 end_line=1
lines_deleted|1
total_lines_before|2
total_lines_after|1
[result_status] UNDECLARED / UNKNOWN

Caveats and known gaps

1. Size and count limits apply, and most stop without a marker. read, search, replace and delete_lines refuse a file over 100 MB, and write_content refuses content over 100 MB, each with an error| row; file_hash refuses a file over 10 GB; append has no size check. list_dir stops at 1000 entries and says so with a warning| row, but search_dir (default 100 results, at most 1000) and search (default 100 lines, at most 10000) simply stop at their cap, so a count equal to the cap in force (the default unless you raised it) means there may be more.
2. find_by_hash is a bounded sweep, not proof of absence. Whichever of 20 seconds, 50,000 entries visited or 100 matches comes first ends the walk, at most 4 GiB is hashed (a file larger than what is left is skipped and the reason becomes byte_cap), it goes at most 10 levels deep (max_depth, default 3; the agent reads a value below 1 as 1, above 10 as 10 and one with no leading integer as 3), and these bounds are fixed in the plugin. What it skipped is counted in the truncated row, but matches_found|0 still means only “not found in the part examined” (Result status). The deadline is checked between system calls, so a single blocked read or directory listing is not interrupted, and only the agent’s shutdown cancels a running search, never a single command (#4875). Residuals: on Windows, and on Linux without openat2 (a kernel before 5.6, or a seccomp profile that denies it), only the final path component is opened no-follow (#6348); a directory whose permissions change after the readability check is skipped without being counted (a symlink swapped in between that check’s access() and its no-follow directory open is refused there and counted unreadable); on macOS a directory swapped for a symlink between its classification and its descent is listed (names only: each child then fails its own no-follow open) and can block on a dead mount. The mount guard is a deny-list of filesystem names read once at the start, so a stacked filesystem, a bare fuse mount and a mount made mid-walk are not caught, and a root reached through a symlink, or spelt in a different letter case on macOS, reaches validate_path before the canonical re-check can refuse it (#4875). Windows hands the walk no mount list: only the root’s own spelling and drive type are judged, so a root that is itself a link to a share is not refused. When the mount table cannot be read in full (an unreadable or over-16 MiB /proc/self/mountinfo, a failed getmntinfo_r_np) the walk runs unguarded, logs once and reports network_mount_guard|unavailable and CONSTRAINED. A Windows drive letter that does not exist is answered directory is not accessible, not as a mount. An agent older than this release still runs the unbounded, symlink-following walk.
3. append reports a stale total_size. The size is read while the written bytes are still buffered, so on the captured 20-byte file it reported total_size|20 after appending 22 bytes; treat it as the size before the append and use exists or read to get the real size. Because the same check runs before the buffer is flushed, a write failure at flush time (for example a full disk) can still print status|ok.
4. base_dir is the caller’s own narrowing, and path checks leave a small race. It is an optional parameter on each request, not an agent-side policy, so a request that omits it is not restricted, and find_by_hash and create_temp do not take it at all. The re-validation just before codesign and plutil narrows but cannot close the window in which a writer inside base_dir swaps the path for a symlink, so base_dir must not be writable by lower-privileged principals.
5. Signature and version answers are narrow. On Windows get_signature verifies only an embedded Authenticode signature and does not check revocation, so a file signed only through a Windows catalog is expected to report unsigned; the captured sample shows notepad.exe reporting unsigned, which is consistent with that (the cause is inferred, not shown). On macOS valid means the code signature’s seal is intact, not that the code is trusted or notarized, and a timed-out or truncated codesign or plutil run is reported as unknown or not_available rather than as a failure.

Source and tests

• Plugin: agents/plugins/filesystem/src/filesystem_acl_parsers.hpp · agents/plugins/filesystem/src/filesystem_find_by_hash.hpp · agents/plugins/filesystem/src/filesystem_macos_sig.hpp · agents/plugins/filesystem/src/filesystem_plugin.cpp
• Definitions: content/definitions/filesystem.yaml · content/definitions/t2_capabilities.yaml · content/definitions/t2_chaining_examples.yaml
• Capability rows: server/core/src/capability_decls/plugin_action_catalogue_a.hpp
• Tests: tests/test_filesystem_definition.py · tests/unit/test_filesystem_acl_parsers.cpp · tests/unit/test_filesystem_actions.cpp · tests/unit/test_filesystem_find_by_hash.cpp · tests/unit/test_filesystem_find_by_hash_dispatcher.cpp · tests/unit/test_filesystem_get_acl_dispatcher.cpp · tests/unit/test_filesystem_local_dispatcher.cpp · tests/unit/test_filesystem_macos_sig.cpp · tests/unit/test_filesystem_posture_local_dispatcher.cpp · tests/unit/test_filesystem_posture_parsers.cpp · tests/unit/test_filesystem_read.cpp
• Privilege row: docs/agent-privilege-model.md