# netscope

**Repository Path**: shibuchou/netscope

## Basic Information

- **Project Name**: netscope
- **Description**: 基于 eBPF（libbpf CO-RE）的网络服务监控工具，支持 DNS/gRPC/TCP/UDP/ICMP/MySQL/Redis/Netfilter 及丢包原因追踪，运行开销≤5%
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-18
- **Last Updated**: 2026-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# netscope — eBPF Network Service Monitor

![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
![Kernel](https://img.shields.io/badge/Kernel-6.6%2B-green.svg)
![Framework](https://img.shields.io/badge/Framework-libbpf--CO--RE-orange.svg)
![Language](https://img.shields.io/badge/Language-C%20%2F%20eBPF-yellow.svg)
![Platform](https://img.shields.io/badge/Platform-Linux%20x86__64-lightgrey.svg)

**A comprehensive eBPF-based network monitoring tool that captures, analyzes, and reports on DNS, gRPC, TCP, UDP, ICMP, MySQL, Redis, Netfilter, and packet-drop events with minimal overhead (≤ 5% CPU/memory).**

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                         User Space                                  │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │  netwatcher.c                                                │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────────┐ │   │
│  │  │ argp CLI │  │ Ring Buf │  │ LRU/LFU  │  │ Log Output  │ │   │
│  │  │ Parser   │  │ Handlers │  │ Cache    │  │ (data/)     │ │   │
│  │  └──────────┘  └────▲─────┘  └──────────┘  └─────────────┘ │   │
│  └──────────────────────┼───────────────────────────────────────┘   │
├─────────────────────────┼───────────────────────────────────────────┤
│                  Ring Buffers / BPF Maps                             │
├─────────────────────────┼───────────────────────────────────────────┤
│                     Kernel Space                                    │
│  ┌──────────────────────┴───────────────────────────────────────┐   │
│  │  netwatcher.bpf.c                                            │   │
│  │  ┌──────┐ ┌──────┐ ┌─────┐ ┌─────┐ ┌──────┐ ┌───────────┐ │   │
│  │  │ TCP  │ │ UDP  │ │ DNS │ │ICMP │ │ gRPC │ │ Netfilter │ │   │
│  │  │Probes│ │Probes│ │Probe│ │Probe│ │Probes│ │  Probes   │ │   │
│  │  └──────┘ └──────┘ └─────┘ └─────┘ └──────┘ └───────────┘ │   │
│  │  ┌───────┐ ┌───────┐ ┌──────┐ ┌──────┐ ┌──────┐           │   │
│  │  │ MySQL │ │ Redis │ │ Drop │ │ RTT  │ │ RST  │           │   │
│  │  │uProbe │ │uProbe │ │Trace │ │Probe │ │Trace │           │   │
│  │  └───────┘ └───────┘ └──────┘ └──────┘ └──────┘           │   │
│  └──────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
```

---

## Quick Start

```bash
# Build
make

# Run DNS monitoring
sudo ./netwatcher -D

# In another terminal, trigger DNS traffic
nslookup google.com
```

---

## Features

| Feature | Flag | Description | Hook Points |
|---------|------|-------------|-------------|
| TCP connections | `-a` | Track all TCP connections (including CLOSED) | `inet_csk_accept`, `tcp_v4_connect`, `tcp_set_state` |
| TCP errors | `-e` | Detect invalid seq/checksum packets | `tcp_validate_incoming`, `__skb_checksum_complete` |
| Extended conn info | `-x` | Cwnd, RTT, backlog, retrans counters | `tcp_sock` fields via CO-RE |
| Retransmission | `-r` | Fast-retransmit and timeout-retransmit events | `tcp_enter_recovery`, `tcp_enter_loss` |
| Layer timing | `-t` | Per-packet latency across MAC/IP/TCP layers | `eth_type_trans` → `skb_copy_datagram_iter` |
| HTTP inspection | `-i` | Extract HTTP header data from packets | `tcp_sendmsg` payload |
| UDP monitoring | `-u` | UDP send/receive with latency | `udp_rcv`, `udp_send_skb` |
| DNS monitoring | `-D` | DNS query/response parsing (port 53) | `udp_rcv`, `udp_send_skb` |
| gRPC/HTTP2 | `-G` | gRPC method extraction, stream latency | `__tcp_transmit_skb`, `skb_copy_datagram_iter` |
| Netfilter | `-n` | IPv4 packet filter path timing | `ip_rcv` → `ip_finish_output` chain |
| Packet drops | `-k` | kfree_skb drop reason analysis | `tp/skb/kfree_skb` tracepoint |
| ICMP timing | `-I` | ICMP round-trip time measurement | `icmp_rcv`, `icmp_reply` |
| TCP state | `-S` | TCP state transition tracing | `tracepoint/sock/inet_sock_set_state` |
| MySQL queries | `-M` | Query text, duration, pid (uprobe) | `dispatch_command` uprobe |
| Redis commands | `-R` | Command extraction, latency (uprobe) | `processCommand`, `call` uprobe |
| Redis stats | `-b` | Key access statistics | `lookupKey`, `addReply` uprobe |
| RTT histogram | `-T` | RTT distribution per connection | `tcp_rcv_established` |
| RST tracking | `-U` | TCP RST send/receive counters | `tcp_send_reset`, `tcp_receive_reset` tracepoints |
| Protocol count | `-p` | Per-protocol packet counters (TCP/UDP/ICMP) | `eth_type_trans`, `dev_hard_start_xmit` |

---

## Installation

### Prerequisites

| Dependency | Version | Purpose |
|------------|---------|---------|
| Linux kernel | ≥ 6.6 (BTF enabled) | eBPF CO-RE support |
| clang / LLVM | ≥ 14 | BPF program compilation |
| libbpf | via libbpf-bootstrap | User-space BPF loading library |
| bpftool | system or libbpf-bootstrap | Skeleton generation, vmlinux.h |
| libelf | any | ELF parsing |
| zlib | any | Compression support |
| Python 3 + grpcio | ≥ 3.8 | gRPC test infrastructure |

### Setup libbpf-bootstrap

```bash
cd ~
git clone --recurse-submodules https://github.com/libbpf/libbpf-bootstrap.git
```

> 如果目录不同，可通过 `LIBBPF_BOOTSTRAP` 变量指定：
> ```bash
> make LIBBPF_BOOTSTRAP=/path/to/libbpf-bootstrap
> ```

### Generate vmlinux.h

```bash
cd ~/netscope
bpftool btf dump file /sys/kernel/btf/vmlinux format c > vmlinux.h
```

### Install system dependencies (Ubuntu/Debian)

```bash
sudo apt-get update
sudo apt-get install -y clang llvm libelf-dev zlib1g-dev \
    linux-tools-$(uname -r) linux-headers-$(uname -r)
```

---

## Build

```bash
cd competition/

# Full build (checks dependencies, compiles libbpf, bpftool, BPF program, user-space binary)
make

# Incremental rebuild (skip libbpf/bpftool, recompile BPF + user-space only)
make clean2 && make

# Full clean
make clean
```

The build pipeline:

1. `clang -target bpf` compiles `netwatcher.bpf.c` → `.bpf.o`
2. `bpftool gen object` produces the final relocatable BPF object
3. `bpftool gen skeleton` generates `netwatcher.skel.h`
4. `cc` compiles `netwatcher.c` and links with `libbpf.a`, `-lelf`, `-lz`

---

## Usage

```
sudo ./netwatcher [OPTIONS]
```

### Options

| Flag | Long Form | Argument | Description |
|------|-----------|----------|-------------|
| `-a` | `--all` | — | Trace CLOSED connections |
| `-e` | `--err` | — | Trace TCP error packets |
| `-x` | `--extra` | — | Trace extended connection info |
| `-r` | `--retrans` | — | Trace retransmission events |
| `-t` | `--time` | — | Trace per-layer packet timing |
| `-i` | `--http` | — | Trace HTTP info |
| `-s` | `--sport` | `PORT` | Filter by source port |
| `-d` | `--dport` | `PORT` | Filter by destination port |
| `-u` | `--udp` | — | Trace UDP messages |
| `-n` | `--net_filter` | — | Trace Netfilter path |
| `-k` | `--drop_reason` | — | Trace packet drops (kfree_skb) |
| `-F` | `--addr_to_func` | — | Translate drop address to function name |
| `-I` | `--icmptime` | — | Trace ICMP timing |
| `-S` | `--tcpstate` | — | Trace TCP state changes |
| `-L` | `--timeload` | — | Analyze time load |
| `-D` | `--dns` | — | Trace DNS queries and responses |
| `-A` | `--stack` | — | Capture kernel stack traces |
| `-M` | `--mysql` | — | Trace MySQL queries (requires `-b` path) |
| `-R` | `--redis` | — | Trace Redis commands (requires `-b` path) |
| `-b` | `--redis-stat` | — | Trace Redis key statistics |
| `-C` | `--count` | `N` | Count requests over N seconds |
| `-T` | `--rtt` | — | Trace RTT distribution |
| `-U` | `--rst_counters` | — | Trace TCP RST events |
| `-p` | `--protocol_count` | — | Count packets per protocol |
| `-G` | `--grpc` | — | Trace gRPC calls (HTTP/2 on port 50051) |

### Examples

```bash
# Monitor DNS with port filter
sudo ./netwatcher -D -d 53

# Monitor TCP connections with extended info and retransmission
sudo ./netwatcher -a -x -r

# Monitor gRPC traffic
python3 test/grpc/server.py &
sudo ./netwatcher -G

# Track packet drops with function name resolution
sudo ./netwatcher -k -F

# MySQL slow query monitoring
sudo ./netwatcher -M

# Combined: all connections + layer timing + HTTP data
sudo ./netwatcher -a -t -i
```

---

## Dual-Cache Mechanism (LRU + LFU)

netscope implements a dual-cache strategy to reduce redundant symbol lookups and repeated query processing:

### LRU Cache (Kernel-side)

- **Implementation**: `BPF_MAP_TYPE_LRU_HASH` maps in eBPF
- **Usage**: `timestamps`, `conns_info`, `sock_stores`, `icmp_time`, `grpc_start_time`
- **Behavior**: Automatically evicts least-recently-used entries when the map reaches `max_entries`
- **Purpose**: Prevent unbounded memory growth in kernel space for connection tracking

### LRU Cache (User-side)

- **Implementation**: Fixed-size array (`cache[CACHEMAXSIZE]`) in `netwatcher.c`
- **Size**: `CACHEMAXSIZE = 5` entries
- **Usage**: Symbol address → function name resolution for `--addr_to_func` mode
- **Algorithm**: On hit, the accessed entry is moved to index 0 (most-recent position); on eviction, the entry at index `CACHEMAXSIZE-1` is discarded
- **Fallback**: On cache miss, performs binary search over the full symbol table (`symbols[300000]`)

### LFU Extension (Planned)

- User-space frequency tracking to dynamically switch between LRU and LFU policies
- When access patterns show high-frequency repeated lookups, LFU retains hot entries longer
- Applicable to DNS domain caching and gRPC method name caching

---

## Directory Structure

```
competition/
├── Makefile                # Build system (libbpf-bootstrap based)
├── netwatcher.c            # User-space main program (CLI, ring buffer handlers, output)
├── netwatcher.bpf.c        # eBPF kernel-side probe entry points (SEC macros)
├── netwatcher.h            # Shared data structures (kernel ↔ user)
├── vmlinux.h               # Kernel BTF type definitions (generated by bpftool)
├── common.bpf.h            # Common BPF helpers, macros, map definitions
├── tcp.bpf.h               # TCP connection/packet probes
├── udp.bpf.h               # UDP + DNS receive/send probes
├── packet.bpf.h            # Per-layer packet timing (MAC/IP/TCP)
├── dns.bpf.h               # DNS query/response parsing (port 53)
├── grpc.bpf.h              # gRPC/HTTP2 frame parsing (port 50051)
├── icmp.bpf.h              # ICMP timing probes
├── mysql.bpf.h             # MySQL uprobe (dispatch_command)
├── mysql_helper.bpf.h      # MySQL helper structures
├── redis.bpf.h             # Redis uprobe (processCommand / call)
├── redis_helper.bpf.h      # Redis helper structures
├── netfilter.bpf.h         # Netfilter path timing
├── drop.bpf.h              # kfree_skb drop reason tracing
├── dropreason.h            # Drop reason code → string mapping
├── data/                   # Runtime log output directory
│   └── doc/                # Per-session log files
├── test/
│   └── grpc/
│       ├── hello.proto     # Protobuf service definition
│       ├── server.py       # Python gRPC test server (port 50051)
│       ├── client.py       # Python gRPC test client
│       ├── hello_pb2.py    # Generated protobuf code
│       └── hello_pb2_grpc.py # Generated gRPC stubs
└── .output/                # Build artifacts (libbpf.a, .bpf.o, .skel.h)
```

---

## Known Limitations

| Limitation | Details |
|------------|---------|
| IPv6 gRPC | gRPC probe currently only handles IPv4 addressing |
| gRPC stream_id parsing | Payload pointer offset may be incorrect in certain kernel versions; validated on 6.8.0-106-generic |
| KVM monitoring | Not yet implemented; requires bare-metal or nested-virt capable host (WSL2 unsupported) |
| MySQL/Redis uprobes | Require the target binary path (`-b`) and specific symbol names; symbol mangling varies by version |
| WSL2 `iov_iter` | WSL2 kernels use `iov` field instead of `__iov`; patched in `common.bpf.h` via `GET_USER_DATA` macro |
| Monitoring overhead | Target ≤ 5% CPU/memory; not formally benchmarked yet |
| Single-mode operation | Most monitoring modes are mutually exclusive (e.g., `-D` and `-u` cannot run simultaneously) |

---

## License

This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).

```
Copyright 2023 The LMP Authors.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    https://github.com/linuxkerneltravel/lmp/blob/develop/LICENSE

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
```