Skip to main content
emisar

Filesystem search and inspection

v0.2.0

Generic filesystem operations an LLM-driven runner needs constantly: bounded find, recursive grep, file head/tail/hash, du, ls -la, stat. All read-only. Paths are validated against simple patterns; the runner's symlink-containment + audit redaction layers still apply on top.

15 allowed by default
Pack ID
fs-search
Vendor
emisar
OS
linux
Actions
15
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
file sha256sum

Install

emisar pack install fetches this pack, re-validates it, and verifies its content hash against the --hash below — the exact bytes this page was rendered against, so a tampered copy is rejected — before copying it into the runner's packs dir. The command reloads a running daemon itself; no manual restart.

on the runner host 
sudo emisar pack install fs-search --hash sha256:70c6227eda860301b4f59cc6017b41068f05752f9253082628429a2f340d3dea

Setup

Reads the local filesystem on the runner host (find/grep/du/stat and friends) — no credentials needed; paths and patterns are passed as arguments.

Host access

Run these commands yourself on the runner host. Emisar shows and copies setup recipes; it never runs them.

Read root-owned or otherwise restricted target paths when those paths are intentionally in scope.

fs.find_by_namefs.find_recent_modifiedfs.find_world_writablefs.find_setuidfs.find_large_filesfs.du_topfs.ls_longfs.stat_pathfs.sha256_filefs.head_filefs.tail_filefs.grep_filefs.grep_recursivefs.count_linesfs.file_type

Run the Emisar service as root

Grant access 
sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'User=root' 'Group=root' | sudo tee /etc/systemd/system/emisar.service.d/10-fs-search-host-access.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar
Verify access 
test "$(systemctl show emisar --property=User --value)" = root

Impact: Every Emisar action on this runner executes as root and can read nearly every host path allowed by the runner's hard path policy, including credentials and private data.

Notes

  • The runner refuses any path inside its own configuration and state directories ( /etc/emisar and /var/lib/emisar by default, or wherever --etc-dir/--data-dir put them) for every action, whatever a pack declares. Those hold the enrollment key, the pack credentials you exported, and this runner's bearer token.
  • The content-returning reads — fs.head_file , fs.tail_file , fs.grep_file , fs.grep_recursive — are medium risk because they return operator-authored file content. They refuse /dev , /proc/kcore , and raw per-process environ , mem , and fd endpoints after canonical path validation. An fd link that resolves to an ordinary file receives the same final-target policy as a direct path. Useful /proc and /sys diagnostics such as memory, pressure, process status, and limits remain available.
  • A fleet that wants a human in the loop for any filesystem read adds a policy override ( action: fs.*_file or action: fs.grep_* , decision: require_approval ) instead of changing the tier for everyone.

Verify it works

Runs fs.stat_path, a low-risk read that confirms the pack can reach its target. Run it on the host once the pack is installed; pack install runs it for you.

on the runner host 
sudo emisar pack verify fs-search

Install and configure a pack walks through the whole sequence on a host.

Actions 15 total

View on GitHub
  • fs.count_lines exec low Low — read-only or trivially reversible

    wc -l <file>

    Count lines in one file.

    View source on GitHub
  • fs.du_top exec low Low — read-only or trivially reversible

    du -d1 — top N entries

    Show the 20 largest entries directly under one path, largest first — files and directories, hidden ones included. Use to find where the space went.

    View source on GitHub
  • fs.file_type exec low Low — read-only or trivially reversible

    file <path>

    Show the libmagic-detected type of one file (e.g. "ELF 64-bit executable", "ASCII text").

    View source on GitHub
  • fs.find_by_name exec low Low — read-only or trivially reversible

    find -name <glob> under <path>

    Find files matching one shell glob under one path. Capped at 1000 results.

    View source on GitHub
  • fs.find_large_files exec low Low — read-only or trivially reversible

    Files larger than N MB

    Find the top files by size under one path. Use to find disk-pressure culprits.

    View source on GitHub
  • fs.find_recent_modified exec low Low — read-only or trivially reversible

    Files modified in last N minutes

    Find files under one path modified within the last N minutes. Useful for "what just changed?".

    View source on GitHub
  • fs.find_setuid exec low Low — read-only or trivially reversible

    setuid + setgid files

    Find files with setuid or setgid bits. Audit for privilege escalation surface.

    View source on GitHub
  • fs.find_world_writable exec low Low — read-only or trivially reversible

    World-writable files

    Find files with the "world-writable" bit set under one path. Security audit.

    View source on GitHub
  • fs.grep_file script medium Medium — changes state, easily reversible

    grep <pattern> <file>

    Show matching lines in one file. Pattern is treated as POSIX ERE.

    View source on GitHub
  • fs.grep_recursive script medium Medium — changes state, easily reversible

    grep -rE <pattern> <path>

    Search recursively under one path. Bounded to 500 matches.

    View source on GitHub
  • fs.head_file script medium Medium — changes state, easily reversible

    head -n <N> <file>

    Show the first N lines of one file.

    View source on GitHub
  • fs.ls_long exec low Low — read-only or trivially reversible

    ls -la <path>

    List directory contents in long format.

    View source on GitHub
  • fs.sha256_file exec low Low — read-only or trivially reversible

    sha256sum <file>

    Show the SHA-256 of one file. Use to confirm a binary matches a known-good hash.

    View source on GitHub
  • fs.stat_path exec low Low — read-only or trivially reversible

    stat <path>

    Show inode + timestamps + permissions for one path.

    View source on GitHub
  • fs.tail_file script medium Medium — changes state, easily reversible

    tail -n <N> <file>

    Show the last N lines of one file.

    View source on GitHub
← Back to registry
Pack reference  Publish your own