How macr0phag3/toast works
Purpose and Entry Point
This is a Linux host-side TCP Option Address (TOA) injector. Running toast.py attaches eBPF-based logic so outbound TCP requests carry a configured client IP in a TOA TCP option. The sole application entry point is toast.py.
Execution Model
toast.py is run directly with privileged Python (sudo python3 toast.py). It requires Linux kernel support at or above 5.10, Python 3.10+, kernel headers, and BCC/bpfcc tooling. Its effective scope is either the root cgroup (all local TCP traffic) or a named cgroup selected with --cg.
Paths:
• toast.py
• README.md
Packet Modification Pipeline
The core pipeline is: parse CLI values such as --ip, optionally select a cgroup, attach the BPF program, then intercept applicable TCP traffic and insert the TOA option containing the configured address. The configured TOA type is selectable; --tot 200 targets the Tencent Cloud toa.ko receiver convention.
Path:
• toast.py
Cgroup Isolation Boundary
Cgroups are the principal traffic-selection boundary. Without --cg, the program applies host-wide; with --cg toast, only processes assigned to /sys/fs/cgroup/toast are affected. Process placement is performed externally through cgroup v2’s cgroup.procs, not by this repository.
Paths:
• toast.py
• README.md
Kernel and Runtime Dependencies
The implementation depends on the Linux networking stack and eBPF/BCC runtime rather than an application server or persistent service. Required host infrastructure includes:
• Linux kernel headers matching the running kernel.
• bpfcc-tools / BCC for loading and attaching BPF programs.
• cgroup filesystem support for scoped operation.
• Root privileges for BPF attachment and cgroup access.
Paths:
• toast.py
• README.md
Receiver Validation / External Integration
TOA insertion is validated outside this repository by loading Tencent Cloud’s toa.ko kernel module and observing the propagated address in Nginx access logs. Nginx is only a demonstration receiver; the architecture’s external interoperability point is any peer/kernel/module that recognizes the chosen TCP option type.
Paths:
• README.md
• toast.py
Repository Shape
The repository is intentionally single-unit: toast.py contains the executable orchestration and likely embedded BPF program definition, attachment lifecycle, argument handling, and signal/exit behavior. There are no separate packages, services, deployment manifests, or test suites represented in the tree.
Paths:
• toast.py
• README.md
Main entry points: toast.py CLI and lifecycle · README.md Usage and validation
Components 11
TOAST injector
- CLI and lifecycle · Parses options, selects scope, and manages attachment lifetime.
toast.py - Embedded BPF program · Intercepts eligible outbound TCP traffic and inserts the TOA option.
toast.py - Usage and validation
README.md
Linux host runtime
- Root privileges · Required for BPF attachment and cgroup access.
- BCC / bpfcc · Loads and attaches the embedded eBPF program.
- Linux TCP stack · Carries modified outbound TCP requests.
- cgroup v2 boundary · Selects root-wide traffic or processes in the named cgroup.
- Selected local processes · Placement in cgroup.procs is external to this repository.
Receiver integration
- TOA-aware peer · Recognizes the configured TCP option type and propagated client address.
- Tencent toa.ko · Optional validation receiver for --tot 200.
- Nginx access logs · Demonstrates receipt of the propagated address.
Connections 12
- CLI and lifecycle → Embedded BPF program: configures and attaches
- CLI and lifecycle → cgroup v2 boundary: selects with --cg
- CLI and lifecycle → BCC / bpfcc: uses
- Root privileges → CLI and lifecycle: authorizes execution
- BCC / bpfcc → Embedded BPF program: loads
- Embedded BPF program → Linux TCP stack: modifies outbound TCP
- cgroup v2 boundary → Selected local processes: limits affected traffic
- Selected local processes → Linux TCP stack: originates TCP requests
- Linux TCP stack → TOA-aware peer: sends TCP with TOA
- TOA-aware peer → Tencent toa.ko: may use
- Tencent toa.ko → Nginx access logs: exposes address for validation
- Usage and validation → CLI and lifecycle: documents usage