# hmgle/graftcp architecture

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

- Interactive diagram: https://gitdiagram.com/hmgle/graftcp
- Repository: https://github.com/hmgle/graftcp

## Overview

##### Main Components
- Graftcp (Tracer Component):
– Written in C (files such as graftcp.c, cidr-trie.c/h, conf.c/h, main.c, etc.),
– Its job is to attach to any target program (using ptrace) and intercept connect(2) syscalls.
– It modifies the syscall arguments so that the connection is redirected to the local proxy (graftcp-local).
– Communicates critical destination connection information via a pipe (or FIFO) to the proxy.

- Graftcp-local (Local Proxy Component):
– Written in Go (files under local/, including the main.go in local/cmd/graftcp-local),
– Listens on a defined local port (default is :2233) for “grafted” connections.
– Processes the original destination info sent through the pipe and then establishes a connection either to a SOCKS5 or an HTTP proxy.
– Provides a configuration interface and supports logging, service control, and integration with systemd.

- mgraftcp (Combined Binary):
– Acts as a combined executable that integrates the functionality of both graftcp and graftcp-local.
– It streamlines the user experience by eliminating the need to run the two components separately.

- Configuration and Example Files:
– There are example configuration files (like example-graftcp.conf and example-blacklist-ip.txt/whitelist-ip.txt).
– The project contains Makefiles to build both the C and Go components.
– Service files (for systemd) are provided under local/contrib/systemd to help deploy the local proxy as a service.

- External Systems:
– The actual proxy servers (SOCKS5 and/or HTTP) are external to this project.

##### Out Relationships and Data Flows
- Target application (“tracee”) initiating a TCP connection.
- That graftcp sends the intercepted destination address (via a pipe) to graftcp-local.
- From graftcp-local, illustrate how it speaks to the external proxy server (SOCKS5 or HTTP) establishing the actual connection.
- Optionally, indicate the implications of running mgraftcp, which merges the above steps into one binary.

##### Architectural Patterns and Principles
- Separation of Concerns: The design clearly partitions the syscall interception (C-based “tracer”) from the connection management and external proxy handling (Go-based “local proxy”).
- Inter-Process Communication (IPC): Emphasize the use of pipes/FIFOs for passing destination data between graftcp and graftcp-local.
- Dynamic Hooking and Redirection: The use of ptrace for intercepting and modifying system calls is a central design idea.
- Configurability: The multiple configuration files and options for controlling behavior (e.g., blacklist/whitelist IP files, proxy selection modes) should also be noted.

##### Relevant Technologies, Frameworks, and Services
- C: For low-level system call tracing and hooking.
- Go: For building the local proxy management daemon (graftcp-local) with networking, configuration, and logging capabilities.
- ptrace(2): As the Linux kernel interface used for tracing.
- systemd: For service management (the provided systemd service file shows integration with Linux service management).
- External Proxies (SOCKS5/HTTP): These are the targets for actual outbound connections.
- Make & Go Modules: For building dependencies and compiling the project.

## Diagram (Mermaid)

```mermaid
graph TD
    T["Target Application"]:::target

    subgraph "Graftcp (Tracer) - C-based"
        GT["graftcp (Tracer)"]:::ccomponent
        G1["graftcp.c"]:::cfile
        G2["graftcp.h"]:::cfile
        G3["main.c"]:::cfile
        G4["conf.c"]:::cfile
        G5["conf.h"]:::cfile
        G6["cidr-trie.c"]:::cfile
        G7["cidr-trie.h"]:::cfile
        G8["util.c"]:::cfile
        G9["uthash.h"]:::cfile
    end

    subgraph "Graftcp-local (Local Proxy) - Go-based"
        LL["graftcp-local (Local Proxy)"]:::gcomponent
        L1["local/cmd/graftcp-local/main.go"]:::gofile
        L2["local/cmd/graftcp-local/config.go"]:::gofile
        L3["local/local.go"]:::gofile
        L4["local/http_proxy.go"]:::gofile
        L5["local/log.go"]:::gofile
        L6["local/util.go"]:::gofile
        L7["local/Makefile"]:::gofile
    end

    subgraph "mgraftcp (Combined Binary)"
        MG["mgraftcp (Unified)"]:::mgcomponent
        M1["local/cmd/mgraftcp/main.go"]:::gofile
        M2["local/cmd/mgraftcp/log.go"]:::gofile
    end

    subgraph "Configuration & Examples"
        C1["example-graftcp.conf"]:::configfile
        C2["example-blacklist-ip.txt"]:::configfile
        C3["example-whitelist-ip.txt"]:::configfile
        C4["local/example-graftcp-local.conf"]:::configfile
    end

    subgraph "Systemd Service"
        S1["graftcp-local.service"]:::configfile
    end

    E["External Proxy Server (SOCKS5/HTTP)"]:::external

    T -->|"ptrace_interception"| GT
    GT -->|"dest_info_via_pipe"| LL
    LL -->|"connects_to"| E
    T -->|"direct_unified_interception"| MG
    MG -->|"redirects_to"| E

    click G1 "https://github.com/hmgle/graftcp/blob/master/graftcp.c"
    click G2 "https://github.com/hmgle/graftcp/blob/master/graftcp.h"
    click G3 "https://github.com/hmgle/graftcp/blob/master/main.c"
    click G4 "https://github.com/hmgle/graftcp/blob/master/conf.c"
    click G5 "https://github.com/hmgle/graftcp/blob/master/conf.h"
    click G6 "https://github.com/hmgle/graftcp/blob/master/cidr-trie.c"
    click G7 "https://github.com/hmgle/graftcp/blob/master/cidr-trie.h"
    click G8 "https://github.com/hmgle/graftcp/blob/master/util.c"
    click G9 "https://github.com/hmgle/graftcp/blob/master/uthash.h"

    click L1 "https://github.com/hmgle/graftcp/blob/master/local/cmd/graftcp-local/main.go"
    click L2 "https://github.com/hmgle/graftcp/blob/master/local/cmd/graftcp-local/config.go"
    click L3 "https://github.com/hmgle/graftcp/blob/master/local/local.go"
    click L4 "https://github.com/hmgle/graftcp/blob/master/local/http_proxy.go"
    click L5 "https://github.com/hmgle/graftcp/blob/master/local/log.go"
    click L6 "https://github.com/hmgle/graftcp/blob/master/local/util.go"
    click L7 "https://github.com/hmgle/graftcp/tree/master/local/Makefile"

    click M1 "https://github.com/hmgle/graftcp/blob/master/local/cmd/mgraftcp/main.go"
    click M2 "https://github.com/hmgle/graftcp/blob/master/local/cmd/mgraftcp/log.go"

    click C1 "https://github.com/hmgle/graftcp/blob/master/example-graftcp.conf"
    click C2 "https://github.com/hmgle/graftcp/blob/master/example-blacklist-ip.txt"
    click C3 "https://github.com/hmgle/graftcp/blob/master/example-whitelist-ip.txt"
    click C4 "https://github.com/hmgle/graftcp/blob/master/local/example-graftcp-local.conf"

    click S1 "https://github.com/hmgle/graftcp/blob/master/local/contrib/systemd/graftcp-local.service"

    classDef target fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef cfile fill:#ff9999,stroke:#cc0000,stroke-width:1px;
    classDef gofile fill:#99ccff,stroke:#0066cc,stroke-width:1px;
    classDef configfile fill:#ccffcc,stroke:#009900,stroke-width:1px;
    classDef external fill:#e6e6e6,stroke:#666,stroke-width:2px,stroke-dasharray:5,5;
    classDef ccomponent fill:#ffcc99,stroke:#cc6600,stroke-width:2px;
    classDef gcomponent fill:#cceeff,stroke:#3399ff,stroke-width:2px;
    classDef mgcomponent fill:#ddddff,stroke:#6666ff,stroke-width:2px;
```
