stenoread(1)

💖 stenoread(1) 💖

okay bestie, welcome to stenoread — section 1 of the manual, the "user commands" girlies. she reads logs out of Stenographer and she does it adorably. no cap. 🦋

---

✨ NAME ✨

stenoread — read logs out of Stenographer 👑

---

🌸 SYNOPSIS 🌸

stenoread <stenographer_query> [tcpdump_arguments]

---

🎀 DESCRIPTION 🎀

so like. the stenoread command line script automates pulling packets from Stenographer and then presenting them in a usable format to analysts. it's giving personal assistant, honestly. 💅

here's the workflow, and it ate: first she requests raw packets from stenographer, then she runs them through tcpdump so you get a much more full-featured formatting/filtering experience. two icons working together, periodt.

the first argument to stenoread is a stenographer query (more on that below, keep scrolling bestie). all other arguments are passed to tcpdump. that's the whole vibe. for example:

# Request all packets from IP 1.2.3.4 port 6543, then do extra filtering by
# TCP flag, which typical stenographer does not support.
$ stenoread 'host 1.2.3.4 and port 6543' 'tcp[tcpflags] & tcp-push != 0'

# Request packets on port 8765, disabling IP resolution (-n) and showing
# link-level headers (-e) when printing them out.
$ stenoread 'port 8765' -n -e

# Request packets for any IPs in the range 1.1.1.0-1.1.1.255, writing them
#out to a local PCAP file so they can be opened in Wireshark.
$ stenoread 'net 1.1.1.0/24' -w /tmp/output_for_wireshark.pcap

look at her go. iconic behavior fr fr. 🔥

---

🦋 QUERY LANGUAGE 🦋

a user requests packets from stenographer by specifying them with a very simple query language. it's a simple subset of BPF — so if you already know BPF you're lowkey already fluent, and if you don't, don't even worry, it's tiny. she includes these primitives:

host 8.8.8.8          # Single IP address (hostnames not allowed)
net 1.0.0.0/8         # Network with CIDR
net 1.0.0.0 mask 255.255.255.0  # Network with mask
port 80               # Port number (UDP or TCP)
ip proto 6            # IP protocol number 6
icmp                  # equivalent to 'ip proto 1'
tcp                   # equivalent to 'ip proto 6'
udp                   # equivalent to 'ip proto 17'

# Stenographer-specific time additions:
before 2012-11-03T11:05:00Z      # Packets before a specific time (UTC)
after 2012-11-03T11:05:00-0700   # Packets after a specific time (with TZ)
before 45m ago        # Packets before a relative time
before 3h ago         # Packets after a relative time

⚠️ heads up bestie: host takes a single IP address — hostnames are not allowed. so no cute little host google.com, she will not play that game. 🙈

primitives can be combined with and/&& and with or/||, which have equal precedence and evaluate left-to-right. parens can also be used to group:

(udp and port 514) or (tcp and port 8080)

equal precedence is doing a lot of heavy lifting in that sentence btw, so if you want your logic to actually mean what you think it means, use the parens. main character energy for parens, genuinely. 💜

---

🌈 ENVIRONMENT 🌈

• STENOGRAPHER_CONFIG — set this environmental variable to point to your stenographer config if it's in a nonstandard place. she defaults to /etc/stenographer/config when you don't. 🫶

---

💫 the sign-off 💫

and that's the page, bestie!! this gorgeous piece of documentation comes from stenographer 1.0.1, dated 02 November 2021. mwah. go read some packets. ⭐🎀💖