4 · Terminal UI Guide

← CLI Reference · Home · Next: Evidence Container →

arachnid-tui is the second front end over the same engine. It drives the library crates directly — it never shells out to arachnid-core, and it can do nothing the CLI cannot. A container written by the TUI verifies with the CLI and validates against the same published schemas.

arachnid-tui
# or, from the repository:
cargo run -p arachnid-core-tui

Contents

• Launch and the splash
• The frame
• Global keys
• The nine screens
  • 1 · Dashboard
  • 2 · Collect
  • 3 · Capture
  • 4 · Parse PCAP
  • 5 · Verify
  • 6 · Report
  • 7 · Sanitize
  • 8 · Recover
  • Chain of custody
• Editing fields
• Confirmations
• The operational log pane
• Layout, colour and accessibility
• What the TUI does not expose
• Persisted state
• Crash safety

Launch and the splash

On launch it shows the wordmark while it probes the host in the background:

• effective privilege — read from /proc/self/status on Linux, IsUserAnAdmin() on Windows;
• capture availability — whether the packet-capture library loads and any devices are visible.

                  \   \  \   /\   /  /   /
                   \   \  \ (oo) /  /   /
                    \   \__\/__\/__/   /
                     \____/ /  \ \____/
                      ___/ /(  )\ \___
                     /   /  \__/  \   \
                    /   /    /\    \   \
                          ARACHNID
                     F O R E N S I C S

                  ⠋ checking host…
              authorized DFIR use only

The mark draws itself row by row while the probes run. On a terminal at least 92 columns and 53 rows the full spider is drawn instead of the compact one above; below 29×14 both give way to a plain wordmark, because scaling the art down turns it into noise.

The splash shows for at least 900 ms and at most 1600 ms; it exits early once the probes finish, and any key skips it after the minimum. Then the dashboard.

A failed probe becomes a warning banner, never a refusal to start. An unprivileged operator can still verify and report on a container collected elsewhere, and that is a legitimate thing to want to do.

Typical warnings:

not running elevated: collection will miss processes owned by other users,
and live capture will not open a device

no capture devices visible (needs root/CAP_NET_RAW on Linux, Npcap on Windows);
capture is unavailable

The frame

 arachnid  1:Dashboard  2:Collect  3:Capture  4:Parse PCAP  5:Verify  6:Report  7:Sanitize  8:Recover
 ! not running elevated: collection will miss processes …  (Esc dismisses)
╭ privilege ─────────╮╭ packet capture ────╮╭ evidence session ──╮╭ recover ───────────╮╭ sanitize ──────────╮
│root                ││2 device(s)         ││./ev-host01         ││5 recovered         ││no wipe running     │
│full collection ava.││eth0, lo            ││operator analyst-7@.││1 High 2 Med 2 Low  ││2 device(s), 1 syst.│
│                    ││                    ││verified 8 artifacts││./ev-host01/disk.img││none this session   │
╰────────────────────╯╰────────────────────╯╰────────────────────╯╰────────────────────╯╰────────────────────╯
 go to
 > Collect     collect volatile system state
   Capture     capture live network traffic
   Parse PCAP  analyse an existing PCAP
   Verify      verify an evidence container
   Report      render a container's report
   Recover     recover deleted files — read-only scan
   Sanitize    securely erase a device — destroys data
 no startup warnings; every check passed
 ? this help  ·  j/k move  ·  Enter open  ·  Tab next screen  ·  1-8 jump …

Five status cards, one per module plus the two host checks. Below about 165 columns they lose their borders and list flat instead — the values stay, the boxes go. The tab strip’s own threshold is computed from the tab titles rather than hardcoded, so adding a module cannot leave it silently truncated.

Five bands, top to bottom:

Global keys

Available from every screen.

The keymap is a single table in the source. The help overlay renders it and the dispatcher scans it, so a binding cannot appear in the help without working, or work without appearing — there is a test asserting exactly that.

Esc walks back in a defined order: an open toast first, then the Custody drill-down (returning to whichever screen opened it), then to the Dashboard.

The nine screens

1 · Dashboard

Status at a glance, and a launcher.

Cards: privilege · packet capture availability and device list · current evidence session (last container, operator, last verify result) · Recover scan status · Sanitize job status. The last two state what is running even when that is “nothing”, so an operator never has to open a module’s screen to find out whether a job is in flight.

Below: the seven quick-launch tiles, and every startup warning in full.

2 · Collect

Runs collect against the local host.

Fields: output directory · operator · signing key · hash-binaries toggle.

While it runs you get a live per-collector checklist — the same five collectors in the same order the CLI runs them, driven by a progress callback rather than a guess, so the checklist cannot drift from the collection.

When it finishes: artifact counts per collector, the key fingerprint, and any warnings.

3 · Capture

Runs a live packet capture.

Fields: device (chosen from the probed list) · output directory · BPF filter · operator · signing key · promiscuous toggle.

The capture keeps running while you navigate. It is a background thread; the header shows [capturing] from every screen. Come back to this screen at any time to see the counters.

Live figures are counters only — packets and bytes, published through plain atomics. Decoding frames to fill a packet table would put per-frame work in the capture loop, which is how a capture falls behind the link and drops evidence.

Once stopped, the savefile is flushed, sealed into the custody log, and then re-read read-only to produce a flow and protocol breakdown for display. That breakdown is display only: nothing from it is added to the container, because arachnid-core capture does not add it either.

4 · Parse PCAP

Analyse an existing savefile. Read-only analysis first, export second — which is the order an analyst actually works in.

Fields: pcap path · BPF filter · output directory · operator · signing key. Recent PCAPs are offered under the path field.

Analysing produces nothing on disk. Only e mints evidence — and the source file’s digest is taken at export time, so the container binds the bytes as they are when the evidence is created.

5 · Verify

Verify an evidence container.

Shows a per-artifact hash status table, the overall verdict, and both the collection time and the verify time — so the gap between them is visible.

6 · Report

Render and export a container’s report.

Fields: container path · export path · format.

Format cycles json → markdown → html → json, the same three the CLI offers. Shows the container’s contents grouped by artifact type.

7 · Sanitize

This screen destroys data. Full reference: Secure Erasure.

A four-step flow: device list → method → confirm → progress.

The commit key is deliberately Shift-W — not Enter, and not y. Both of those are what the ordinary confirmation dialog takes, and a wipe must not be clearable by the reflex that clears those.

The device list refuses to hand a system disk to the wipe flow unless f is set, so the operator never types a serial for a device they cannot wipe.

8 · Recover

File carving and recovery. Read-only against its source. Full reference: File Recovery.

A five-step flow: source → configuration → progress → results → export.

Source offers three things to read from: an image file, a device from the read-only device list (the same enumeration Sanitize uses, opened without write access), or an artifact out of a prior Core evidence container.

The container picker reads artifact names with read_log, which deliberately does not check signatures. It is a file picker; presenting it as though the log had been verified would be a lie. Verification is screen 5’s job, on the same path.

Results is the part worth knowing about. Every row shows its confidence label, and the pane below shows the checks behind the selected row — always, not behind a drill-down:

 recovered  1 High  ·  2 Medium  ·  2 Low   (5 shown)
 c confidence: all  ·  t type: all  ·  e export  ·  Esc back
  CONF    TYPE        SIZE  METHOD      NAME / PATH
  High    pdf           37  NTFS MFT    Cases/quarterly.pdf
> Medium  jpg          206  NTFS MFT    Cases/evidence-photo.jpg
  Medium  txt           45  NTFS MFT    <unknown>/orphan.txt
  Low     jpg          206  carved      carve-000000-at-90112.jpg
  Low     pdf           36  carved      carve-000001-at-81920.pdf

 Medium  MFT record intact and every extent reads back, but the record is
 deleted: the clusters are free and may since have been reallocated
  [  ] mft_entry_in_use          record is marked deleted; its clusters are free
  [ok] run_list_complete         1 run(s) decoded to the declared end of the file
  [ok] allocation_covers_size    206 byte(s) mapped for a 206 byte file
  [ok] extents_readable          1 extent(s) sampled and readable

A recovered file looks identical in a folder whether the filesystem handed over its name and timestamps or a carver found its bytes in unallocated space. Those are very different claims, so the screen never shows the file without the claim.

Export takes an output directory and a confidence threshold, defaulting to Medium and better — Low includes every carved fragment, which is rarely what you want on a first pass. The export runs on its own thread and writes a signed custody log, exactly as a collection does.

A running scan survives navigating away, like a capture and a wipe: carving a full disk is an hours-long read. Pressing f raises an error-styled toast saying the override is active.

A 3-second cooldown precedes the first write, and the commit key is rejected, not merely ignored, until it elapses. Cancelling a running job asks first, and says plainly that the device will be left partially overwritten and will not be certified.

Chain of custody

Reached with c from Verify or Report. Not a tab — a drill-down; Esc returns to whichever screen opened it.

Every record in order, with the selected one shown in full: the complete digest, not a prefix. Nothing on that screen is summarized away — a chain of custody you have to trust a truncation of is not one.

The custody view reads the log; it does not validate it. Signatures and the hash chain are verify’s business. Use screen 5 for the verdict.

Editing fields

Fields have an explicit edit mode, so a path containing q can actually be typed.

While editing, global bindings stand down — the field sees everything except the way out. Changing screens always leaves edit mode, because carrying an edit across screens would send keystrokes somewhere the operator is not looking.

Confirmations

Anything that starts, replaces or stops evidence collection asks first. Nothing that touches evidence happens on a single keypress.

y / Y / Enter confirms, n / N / Esc cancels.

Confirming a quit during a capture sets the stop flag rather than dropping the thread, so the savefile is flushed and sealed rather than lost. There is a test asserting exactly this.

One job at a time. Starting a second while one runs is refused with a toast (collect is still running); two concurrent runs would mean two containers with interleaved custody timestamps.

Toasts clear themselves after six seconds, and Esc dismisses one early.

The operational log pane

Ctrl-L toggles a nine-row pane showing the last lines of the tracing output. Verbosity comes from ARACHNID_LOG (default info).

The buffer holds the last 1000 lines — bounded because a chatty capture can emit for hours and the pane is a debugging aid, not evidence.

Timestamps are omitted: the pane is narrow, and the timestamps that matter forensically are in the container’s custody log. This pane is not the evidence log and is never written into a container.

Below 18 rows the pane is suppressed — it is the first thing to go when there is no room, because the screen under it is the work.

Layout, colour and accessibility

• The accent colour is magenta, for the spider the suite is named after. It is the one ANSI slot that collides with none of the three verdict colours, so “you are here” can never be misread as a verdict. Everything else on screen — green for verified, red for failed, yellow for a warning — is unchanged.
• NO_COLOR is respected, per no-color.org: set and non-empty means monochrome, whatever the terminal claims to support.
• Every verdict is stated in text as well as colour, so nothing is lost in a monochrome terminal or to a colour-blind reader. “VERIFIED” is a word, not a green box.
• Layout degrades rather than breaks down to 32×8: the tab strip collapses to a position indicator, cards lose their borders, tables truncate with a … n more marker, the log pane and banner disappear.
• Below 32×8 it prints terminal too small / needs 32x8 rather than drawing something corrupt.
• The test suite renders every screen at every supported size with every overlay combination, so a layout that would panic and take the terminal with it fails in CI instead of on a responder’s laptop.

What the TUI does not expose

The TUI covers the common path. These CLI options have no field on any screen — use arachnid-core for them:

This is a deliberate subset, not a gap to be filled: the TUI is a view and controller layer with no engine logic of its own.

Persisted state

The TUI remembers the operator name and recent paths in:

Contents: operator name, last container, and up to eight recent PCAPs and containers, plus the last verify result.

That file is a convenience, never evidence. Deleting it costs two retyped paths. A write failure becomes a debug log line and nothing else — a UI convenience file is never worth failing a run over.

Crash safety

A panic hook restores the terminal — raw mode off, alternate screen left — before the panic message prints. A crash cannot leave your shell unusable, and the backtrace lands somewhere you can read it.

← CLI Reference · Home · Next: Evidence Container →