# macr0phag3/toast architecture

> Architecture diagram of the GitHub repository macr0phag3/toast, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/macr0phag3/toast
- Repository: https://github.com/macr0phag3/toast

## Overview

#### 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`](https://github.com/macr0phag3/toast/blob/master/toast.py) (CLI and lifecycle), [`README.md`](https://github.com/macr0phag3/toast/blob/master/README.md) (Usage and validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["TOAST injector"]
  node_cli["CLI and lifecycle<br/>Python entry point<br/>[toast.py]"]
  node_bpf{{"Embedded BPF program<br/>eBPF logic<br/>[toast.py]"}}
  node_docs["Usage and validation<br/>documentation<br/>[README.md]"]
end

subgraph group_host["Linux host runtime"]
  node_root["Root privileges<br/>host permission"]
  node_bcc["BCC / bpfcc<br/>BPF runtime"]
  node_kernel["Linux TCP stack<br/>kernel networking"]
  node_cgroup["cgroup v2 boundary<br/>traffic scope"]
  node_processes["Selected local processes<br/>traffic source"]
end

subgraph group_receiver["Receiver integration"]
  node_peer["TOA-aware peer<br/>external receiver"]
  node_toa_module["Tencent toa.ko<br/>receiver kernel module"]
  node_nginx["Nginx access logs<br/>validation output"]
end

node_cli -->|"configures and attaches"| node_bpf
node_cli -->|"selects with --cg"| node_cgroup
node_cli -->|"uses"| node_bcc
node_root -.->|"authorizes execution"| node_cli
node_bcc -->|"loads"| node_bpf
node_bpf -->|"modifies outbound TCP"| node_kernel
node_cgroup -->|"limits affected traffic"| node_processes
node_processes -->|"originates TCP requests"| node_kernel
node_kernel -->|"sends TCP with TOA"| node_peer
node_peer -.->|"may use"| node_toa_module
node_toa_module -->|"exposes address for validation"| node_nginx
node_docs -.->|"documents usage"| node_cli

click node_cli "https://github.com/macr0phag3/toast/blob/master/toast.py"
click node_bpf "https://github.com/macr0phag3/toast/blob/master/toast.py"
click node_docs "https://github.com/macr0phag3/toast/blob/master/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_bpf,node_docs toneBlue
class node_root,node_bcc,node_kernel,node_cgroup,node_processes toneAmber
class node_peer,node_toa_module,node_nginx toneMint
```

## Components

### TOAST injector

- [CLI and lifecycle](https://github.com/macr0phag3/toast/blob/master/toast.py): Python entry point · Parses options, selects scope, and manages attachment lifetime. · `toast.py`
- [Embedded BPF program](https://github.com/macr0phag3/toast/blob/master/toast.py): eBPF logic · Intercepts eligible outbound TCP traffic and inserts the TOA option. · `toast.py`
- [Usage and validation](https://github.com/macr0phag3/toast/blob/master/README.md): documentation · `README.md`

### Linux host runtime

- **Root privileges**: host permission · Required for BPF attachment and cgroup access.
- **BCC / bpfcc**: BPF runtime · Loads and attaches the embedded eBPF program.
- **Linux TCP stack**: kernel networking · Carries modified outbound TCP requests.
- **cgroup v2 boundary**: traffic scope · Selects root-wide traffic or processes in the named cgroup.
- **Selected local processes**: traffic source · Placement in cgroup.procs is external to this repository.

### Receiver integration

- **TOA-aware peer**: external receiver · Recognizes the configured TCP option type and propagated client address.
- **Tencent toa.ko**: receiver kernel module · Optional validation receiver for --tot 200.
- **Nginx access logs**: validation output · Demonstrates receipt of the propagated address.

## Connections

- 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
