TTY Logging with BPF - Revision history

Jwgranville at 02:23, 20 August 2025

2025-08-20T02:23:53Z

← Older revision		Revision as of 02:23, 20 August 2025
Line 228:		Line 228:
	<OUTPUT pid=67 tid=67 time=1751051974227997645 rawtime=211192116397 cgid=1 inode=7863412966886368629 pidtgid=287762808899 nsid=12616466428 comm=b'kworker/u10:5' len=75>		<OUTPUT pid=67 tid=67 time=1751051974227997645 rawtime=211192116397 cgid=1 inode=7863412966886368629 pidtgid=287762808899 nsid=12616466428 comm=b'kworker/u10:5' len=75>
	b'Hello, World!\r\n\x1b[?2004h\x1b]0;joe@bpf: ~\x07\x1b[01;32mjoe@bpf\x1b[00m:\x1b[01;34m~\x1b[00m$ '		b'Hello, World!\r\n\x1b[?2004h\x1b]0;joe@bpf: ~\x07\x1b[01;32mjoe@bpf\x1b[00m:\x1b[01;34m~\x1b[00m$ '
	~~<INPUT pid=2579 tid=2579 time=1751051998831792273 rawtime=235795910526 cgid=7827 inode=89 pidtgid=11076720658963 nsid=12616466428 comm=b'sshd' len=1>~~

Jwgranville: Added some additional details that didn't make it in before pages were frozen to deal with bots

2025-08-19T20:06:03Z

Added some additional details that didn't make it in before pages were frozen to deal with bots

@@ Line 25: / Line 25: @@
 To account for this, first the raw time values must be captured as close to the actual TTY event as possible - preferably, as the first instruction in the probe. We note the system time as part of the record of the TTY event, which is then exfiltrated from the kernel using a shared memory buffer provided by BPF.
-In Python, a handler function reads events out of the buffer. In user space we have full access to wall clock time. Measuring the difference between system uptime and wall clock time is simple, but it may jump as a result of changes to the offset value used to calibrate it - such as when the system receives a time update via NTP
+In user space a handler function in the outer Python script reads events from the BPF buffer. There we have full access to wall clock time. Measuring the difference between system uptime and wall clock time is as simple as capturing both values, but it may occasionally jump as a result of changes to the offset value used to calibrate it - such as when the system receives a time update via network time protocol, which can occur quite frequently on modern operating systems.
 == Example Output ==

Jwgranville at 20:22, 30 June 2025

2025-06-30T20:22:34Z

← Older revision		Revision as of 20:22, 30 June 2025
Line 17:		Line 17:

	tty_write() and tty_receive_buf_common() are used to copy data in and out of kernel memory, as user-land processes talk to the physical device drivers represented in software by the TTY resource. In its basic usage, BPF calls the probe with the same parameters that the system call received. We use this to read the data buffers as TTY devices transmit and receive.		tty_write() and tty_receive_buf_common() are used to copy data in and out of kernel memory, as user-land processes talk to the physical device drivers represented in software by the TTY resource. In its basic usage, BPF calls the probe with the same parameters that the system call received. We use this to read the data buffers as TTY devices transmit and receive.

			To safely permit alterations to the kernel, BPF enforces safety checks above and beyond normal C language requirements. As such, the kernel probe code may appear pedantic in the amount of guards used. These are necessary for approval by the BPF checker.

			=== Timing ===
			BPF lacks a wall clock time source. In other words, all of the time values available in the kernel under BPF are based on the system's uptime clock, not a time source synced to time of day. The uptime clocks have some unusual behavior compared to typical clocks. When the host system is halted or put to sleep, the clocks stop. From the perspective of software running on the host system, the system clocks move forward at a smooth rate, but the wall clock time jumps forward unpredictably whenever the system wakes from sleep.

			To account for this, first the raw time values must be captured as close to the actual TTY event as possible - preferably, as the first instruction in the probe. We note the system time as part of the record of the TTY event, which is then exfiltrated from the kernel using a shared memory buffer provided by BPF.

			In Python, a handler function reads events out of the buffer. In user space we have full access to wall clock time. Measuring the difference between system uptime and wall clock time is simple, but it may jump as a result of changes to the offset value used to calibrate it - such as when the system receives a time update via NTP

	== Example Output ==		== Example Output ==
	When <code>echo Hello World!\n</code> is written to TTY, the following activity is captured:		When <code>echo Hello World!\n</code> was written to TTY, the following activity was captured:
	<INPUT pid=2579 tid=2579 time=1751051966371111181 rawtime=203335230775 cgid=7827 inode=89 pidtgid=11076720658963 nsid=12616466428 comm=b'sshd' len=1>		<INPUT pid=2579 tid=2579 time=1751051966371111181 rawtime=203335230775 cgid=7827 inode=89 pidtgid=11076720658963 nsid=12616466428 comm=b'sshd' len=1>
	b'e'		b'e'

Jwgranville at 19:21, 30 June 2025

2025-06-30T19:21:52Z

Show changes

Jwgranville: /* Instructions */

2025-06-20T20:32:32Z

Instructions

← Older revision		Revision as of 20:32, 20 June 2025
Line 5:		Line 5:

	== Instructions ==		== Instructions ==
	To run it one needs to have superuser privileges (for kernel access). The probes intercept all TTY activity on the host system - both inside and outside of containers. If the script is printing to a TTY device the prints will also be observed, creating a feedback loop that will quickly consume the kernel buffers. As such the output should be redirected to a file. I recommend redirecting both STDOUT and STDERR as follows:		To run it one needs to have superuser privileges (for kernel access). The probes intercept all TTY activity on the host system - both inside and outside of containers. If the script is printing to a TTY device the prints themselves will also be observed, creating a feedback loop that will quickly consume the kernel buffers. As such the output should be redirected to a file. I recommend redirecting both STDOUT and STDERR as follows:
	sudo python3 [https://github.com/edurange/demo-bpf-tty-logger/blob/main/parrotty.py parrotty.py] &> log		sudo python3 [https://github.com/edurange/demo-bpf-tty-logger/blob/main/parrotty.py parrotty.py] &> log

Jwgranville: Created page with "Category:Demonstrations See https://github.com/edurange/demo-bpf-tty-logger. Demonstrates how to capture TTY activity using BPF kernel probes. == Instructions == To run it one needs to have superuser privileges (for kernel access). The probes intercept all TTY activity on the host system - both inside and outside of containers. If the script is printing to a TTY device the prints will also be observed, creating a feedback loop that will quickly consume the kernel b..."

2025-06-20T18:55:22Z

Created page with "Category:Demonstrations See https://github.com/edurange/demo-bpf-tty-logger. Demonstrates how to capture TTY activity using BPF kernel probes. == Instructions == To run it one needs to have superuser privileges (for kernel access). The probes intercept all TTY activity on the host system - both inside and outside of containers. If the script is printing to a TTY device the prints will also be observed, creating a feedback loop that will quickly consume the kernel b..."

New page

[[Category:Demonstrations]]
See https://github.com/edurange/demo-bpf-tty-logger.

Demonstrates how to capture TTY activity using BPF kernel probes.

== Instructions ==
To run it one needs to have superuser privileges (for kernel access). The probes intercept all TTY activity on the host system - both inside and outside of containers. If the script is printing to a TTY device the prints will also be observed, creating a feedback loop that will quickly consume the kernel buffers. As such the output should be redirected to a file. I recommend redirecting both STDOUT and STDERR as follows:
sudo python3 [https://github.com/edurange/demo-bpf-tty-logger/blob/main/parrotty.py parrotty.py] &> log