Skip to main content
emisar

Process forensics

v0.2.0

Deep per-process diagnostics for "why is this process stuck / slow / leaking?" — strace (HIGH RISK; slows the target), pid memory maps, per-thread state, /proc walking, gdb backtrace, full lsof, syscall summary. Read-only — but strace and gdb attach via ptrace and WILL slow the target.

7 allowed by default 3 need approval by default
Pack ID
process-forensics
Vendor
emisar
OS
linux
Actions
10
Required binaries. Install these on the host before relying on the pack — an action that calls a missing one fails at run time.
lsof

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 process-forensics --hash sha256:8bf2636dcdf0403c01bf68fc00967a656a035b1be66baacb5dac7b903e5281fe

Setup

Inspects processes on the local runner host — no credentials needed.

Host access

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

Inspect protected process files and attach to processes owned by other users.

forensics.pid_mapsforensics.pid_smaps_summaryforensics.pid_threads_stateforensics.pid_open_filesforensics.pid_statusforensics.pid_ioforensics.pid_syscallforensics.strace_pid_shortforensics.gdb_backtraceforensics.strace_summary

Grant process-inspection capabilities to the Emisar service

Grant access 
sudo install -d -m 0755 /etc/systemd/system/emisar.service.d
printf '%s\n' '[Service]' 'AmbientCapabilities=CAP_SYS_PTRACE CAP_DAC_READ_SEARCH' | sudo tee /etc/systemd/system/emisar.service.d/10-process-forensics-host-access.conf >/dev/null
sudo systemctl daemon-reload
sudo systemctl restart emisar
Verify access 
systemctl show emisar --property=AmbientCapabilities --value | grep -Fwi cap_sys_ptrace
systemctl show emisar --property=AmbientCapabilities --value | grep -Fwi cap_dac_read_search

Impact: Every Emisar action on this runner inherits CAP_SYS_PTRACE and CAP_DAC_READ_SEARCH. It can inspect or attach to processes outside the runner user, including their memory and secrets, and bypass file read and directory search permissions across the host.

Verify it works

Runs forensics.pid_status, 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 process-forensics

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

Actions 10 total

View on GitHub
  • forensics.gdb_backtrace exec high High — service-affecting

    gdb -ex "thread apply all bt"

    Attach gdb to one PID and dump native stack for every thread, then detach. The target is briefly stopped during the dump.

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

    Process I/O accounting

    Show `/proc/<pid>/io` for one process — bytes read and written (logical and physical), syscall counts, and cancelled writes. Use to find which process is driving disk I/O.

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

    /proc/PID/maps

    Show memory map for one PID. Use to see loaded libraries + heap/stack ranges.

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

    lsof -p <pid>

    List all open files (regular, sockets, pipes) for one PID. Richer than /proc/PID/fd alone.

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

    /proc/PID/smaps_rollup

    Show aggregated memory stats — Rss, Pss, Shared, Private. Better than RSS for diagnosing memory pressure.

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

    Process status block

    Show `/proc/<pid>/status` for one process — uid/gid, capability set, signal masks, RSS and peak RSS, voluntary and involuntary context switches, and OOM score. More detail than `ps` for one PID.

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

    /proc/PID/syscall

    Show current syscall (or "running" if user-space). Snapshot of where the kernel is for one thread.

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

    Per-thread state for one PID

    Tabulate each thread's state (R/S/D/Z) from /proc/PID/task/*/status.

    View source on GitHub
  • forensics.strace_pid_short exec high High — service-affecting

    strace -p <pid> (5 seconds)

    Attach strace to one PID for 5 seconds. Slows the target process significantly while attached. Detaches automatically.

    View source on GitHub
  • forensics.strace_summary exec high High — service-affecting

    strace -c -p <pid> (5 seconds)

    Attach strace in counting mode for 5 seconds — outputs a syscall-frequency table. Slows target less than -y mode but still significant.

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