https://github.com/gotoolkits/lightmon
lightmon is a lightweight, Docker/K8s container-aware network traffic monitoring tool based on eBPF technology.
https://github.com/gotoolkits/lightmon
docker ebpf ebpf-go k8s
Last synced: 10 days ago
JSON representation
lightmon is a lightweight, Docker/K8s container-aware network traffic monitoring tool based on eBPF technology.
- Host: GitHub
- URL: https://github.com/gotoolkits/lightmon
- Owner: gotoolkits
- License: apache-2.0
- Created: 2025-04-19T01:34:15.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2025-05-15T01:30:08.000Z (11 days ago)
- Last Synced: 2025-05-15T02:30:34.453Z (11 days ago)
- Topics: docker, ebpf, ebpf-go, k8s
- Language: C
- Homepage:
- Size: 6.59 MB
- Stars: 14
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Security: securitySocketConnectSrc.c
Awesome Lists containing this project
README
# lightmon
lightmon is a lightweight, Docker/K8s container-aware network traffic monitoring tool based on eBPF technology. It can capture and analyze network connections established by host and container applications in real-time, providing monitoring data in multiple formats. Suitable for system monitoring, security auditing, and network troubleshooting scenarios.
## DeepWiki Docs
[DeepWiki Docs](https://deepwiki.com/gotoolkits/lightmon)
## Architecture Overview
```
+---------------------+
| User-space Program |
| (Implemented in Go) |
+----------+----------+
|
| via perf buffer
|
+----------v----------+
| eBPF Program |
| (Implemented in C) |
| - Trace syscalls |
| - Filter network events |
+---------------------+
```
## Features
- **Lightweight & Efficient**: Based on eBPF technology with minimal performance overhead
- **Comprehensive Monitoring**: Tracks TCP connection information
- **Container-Aware**: Automatically identifies K8s/Docker container environments
- **Process-Aware**: Automatically identifies processes associated with traffic and their executable paths
- **Flexible Filtering**: Supports multi-condition combined filtering rules
- **Multiple Output Formats**: Supports log files, JSON, tables and other output formats
## Installation Guide
### Dependencies
```sh
# Basic dependencies
sudo apt update
sudo apt install -y llvm clang
# Go environment (recommended 1.23+)
```
### Build & Install
```sh
git clone https://github.com/gotoolkits/lightmon.git
cd lightmon
go mod tidy
make build
```
## Usage
### Basic Usage
```sh
# Specify config file
bin/amd64/lightmon -c ./config.yaml
bin/arm64/lightmon -c ./config.yaml
# Run with default configuration
bin/amd64/lightmon
bin/arm64/lightmon
```
### Output Formats
lightmon supports multiple output formats ('-f'):
1. **LOG format** (default)
```
[container] [dest IP] [dest port] [protocol] [level] [message] [PID] [process args] [process name] [src ip] [src port] [time] [user]
{"conatiner":"dreamy_carson","dip":"183.2.172.17","dport":"65535","ipv6":0,"level":"info","msg":"","pid":"501750","procArgs":"www.baidu.com","procPath":"/usr/bin/busybox","sip":"10.1.8.14","sport":"7825","time":"2025-04-17T14:01:48+08:00","user":"root"}
```
2. **JSON format** (use `-output json`)
```json
{
"kernelTime": "13898485459656",
"goTime":"2025-04-17T14:09:49.162027869+08:00",
"pid": 1234,
"comm": "nginx",
"addressFamily": "AF_INET",
"saddr": "192.168.1.100",
"sport": 34567,
"daddr": "10.0.0.1",
"dport": 80,
"container":"web-server",
}
```
3. **Table format** (use `-output table`)
```
+----------+-------+-------+------+-----------------+-----------------+--------------+------------------------+
| TIME | USER | PID | AF | SRC | DEST | CONTAINER | PROCESS |
+----------+-------+-------+------+-----------------+-----------------+---------------------------------------+
| 14:05:56 | root | 1234 | v4 | 10.4.0.16:3425 | 10.0.0.1:80 | web-server | /usr/local/bin/python |
+----------+-------+-------+------+-----------------+-----------------+---------------------------------------+
```
### Filtering
Use `-exclude` parameter to exclude unwanted connections:
```sh
# Exclude traffic to specific ports
./lightmon -exclude 'dport=80'
# Exclude traffic to specific IP ranges
./lightmon -exclude 'dip="192.168.1.0/24"'
# Combined conditions
./lightmon -exclude 'dport=80;dip="192.168.1.1";keyword="nginx"'
```
#### Filter Syntax
- **Basic conditions**:
- `dport=port` - Filter by destination port
- `dip='IP/CIDR'` - Filter by destination IP
- `keyword='string'` - Filter by process path/name
- `container='string'` - Filter by container name
- **Logical operators**:
- `&&` - AND logic
- `||` - OR logic
- `;` - Condition group separator
#### Filter Examples
1. Exclude local network and DNS traffic:
```sh
./lightmon -exclude 'dip="192.168.1.0/24";dport=53'
```
2. Exclude specific services:
```sh
./lightmon -exclude 'keyword="nginx";keyword="mysql"'
```
3. Complex condition combinations:
```sh
./lightmon -exclude 'dip="10.0.0.1" && dport=80; dip="10.0.0.1" && dport=443'
```
4. Exclude traffic from containers with specific names:
```sh
./lightmon -exclude 'container="nginx";container="redis"'
```
## Development Guide
### Code Structure
```
lightmon/
├── conv/ # Protocol conversion
├── dockerinfo/ # Container info processing
├── event/ # Event type definitions
├── filter/ # Filtering logic
├── headers/ # eBPF headers
├── linux/ # Linux-specific functions
├── outputer/ # Output handlers
├── fentryTcpConnectSrc.c # Fentry eBPF program type
├── sysEnterConnectSrc.c # Tracepoint eBPF program
└── main.go # Program entry
```
### Build & Test
```sh
# Run unit tests
go test ./...
# Build binary
make build
# Clean build
make clean
```
## Contributing
Issues and PRs are welcome. Contribution process follows standard GitHub workflow.
## License
Apache License 2.0, see LICENSE.txt file for details.