meds

Meds: net healing

High-performance firewall powered by NFQUEUE, Conntrack, and Go

It integrates with Linux Netfilter via NFQUEUE, inspects inbound traffic in user space, and applies filtering to block malicious traffic in real-time. Once a connection is verified, Meds offloads it back to the kernel using Conntrack marks for maximum throughput.

Designed to cure your network from malicious traffic.

🚀 Installation

Requirements:

• Linux with iptables + NFQUEUE + conntrack support
• Root privileges (sudo) — required for interacting with Netfilter/Netlink

The application manages iptables and conntrack rules automatically.

Download

Download the latest binary from Releases or build from sources.

Build from sources

go build -o meds ./cmd/daemon

🧩 Quickstart

sudo MEDS_USERNAME=admin MEDS_PASSWORD=mypass ./meds
# Metrics available at: http://localhost:8000/metrics
# API available at: http://localhost:8000/swagger/index.html
# Basic Auth: admin / mypass

Command-line options

./meds -help
Usage of ./meds:
  -api-addr string
    	api server address (default ":8000")
  -db-path string
    	path to database file (default "meds.db")
  -log-level string
    	zerolog level (default "info")
  -logger-queue-len uint
    	logger queue length (all workers) (default 2048)
  -loggers-count uint
    	logger workers count (default 3)
  -rate-limiter-burst uint
    	max packets at once (per ip) (default 1500)
  -rate-limiter-cache-size uint
    	rate limiter cache size (all buckets) (default 100000)
  -rate-limiter-cache-ttl duration
    	rate limiter cache ttl (per bucket) (default 3m0s)
  -rate-limiter-rate uint
    	max packets per second (per ip) (default 3000)
  -reader-queue-len uint
    	nfqueue queue length (per reader) (default 8192)
  -readers-count uint
    	nfqueue readers count (default 12)
  -update-interval duration
    	update frequency (default 4h0m0s)
  -update-timeout duration
    	update timeout (per filter) (default 1m0s)
  -workers-count uint
    	nfqueue workers count (per reader) (default 1)

Prometheus metrics

👉 http://localhost:8000/metrics

The metrics endpoint is protected by the same BasicAuth credentials as the API.

Swagger UI

Interactive API docs:
👉 http://localhost:8000/swagger/index.html

You can browse and test all API endpoints directly from your browser.

OpenAPI spec (JSON):
👉 http://localhost:8000/swagger/doc.json

You can import this spec into Postman, Insomnia, or Hoppscotch.

✨ Key Features

• Hybrid Processing (Conntrack Acceleration)
  Uses Conntrack marks to offload trusted connections. Once a flow is validated in user space, it is marked in the kernel's connection tracking table. Subsequent packets of that flow stay in the kernel, achieving wire-speed performance.

• NFQUEUE-based packet interception
  Uses Linux Netfilter queues to copy inbound packets into user space with minimal overhead, only for the "Decision Phase" of a connection.

• Lock-free core
  Meds itself does not use any mutexes — all filtering, counters, and rate-limiters use atomic operations.

• Decoupled reader / worker / logger model

  • Readers drain NFQUEUE as fast as possible
  • Workers perform CPU-intensive filtering
  • Logger uses zerolog with async worker-based logging

• Fast packet parsing with gopacket
  Parses traffic efficiently (lazy and no copy modes enabled).

• Efficient lookups
  Uses radix tree and bart for IP/domain matching at scale.

• Rate Limiting per IP
  Uses token bucket algorithm to limit burst and sustained traffic per source IP.
  Protects against high-frequency floods (SYN, DNS, ICMP, or generic packet floods).

• Blacklist-based filtering

  • IP blacklists: FireHOL, Spamhaus DROP, Abuse.ch
  • ASN blacklists: Spamhaus ASN DROP using IPLocate.io for IP-to-ASN mapping
  • Domain blacklists: StevenBlack hosts, SomeoneWhoCares hosts

• Geo-blocking (ASN-based)
  Efficiently blocks traffic from specific countries using ASN metadata from IPLocate.io:

  • Lightweight alternative to heavy GeoIP databases
  • Dynamic configuration via API/Swagger

• TLS SNI & JA3 filtering
  Extracts and inspects TLS ClientHello data directly from TCP payload before handshake completion:

  • Filters by SNI (domain in TLS handshake)
  • Filters by JA3 fingerprint using the Abuse.ch SSLBL JA3 database

  Enables real-time blocking of malicious TLS clients such as malware beacons, scanners, or C2 frameworks.

• HTTP API for runtime configuration
  Built-in API server (powered by Gin) allows dynamically adding or removing IP, Domain, or Country entries in global white/black lists.
  Auth via BasicAuth using MEDS_USERNAME / MEDS_PASSWORD.

• Prometheus metrics export
  Exposes metrics for observability:

  • Total packets processed
  • Dropped packets (with reasons)
  • Accepted packets (with reasons)
  • Internal errors (with types)

  Metrics are available at /metrics via the built-in API server, compatible with Prometheus scrape targets.

• Extensible design
  Modular architecture allows adding new filters.

🔍 How It Works

[Kernel: Mangle] → Restore Connmark → [Mark set?] → (Yes) → [Kernel: Filter: ACCEPT] (Fast Path)
                                        ↓ (No)
[Kernel: Filter] → [NFQUEUE] → [Meds: User Space] (Slow Path)
                              ↳ Global IP Whitelist
                              ↳ Rate Limiter (per source IP)
                              ↳ Global IP Blacklist
                              ↳ IP Filters
                              ↳ Geo Filters
                              ↳ ASN Filters
                              ↳ Global Domain/SNI Whitelist
                              ↳ Global Domain/SNI Blacklist
                              ↳ Domain/SNI Filters
                              ↳ TLS JA3 Filters
                              ↳ Decision: DROP / MARK / ACCEPT

• Hybrid Traffic Flow
  Meds optimizes traffic by splitting it into two paths:

  • Fast Path (Kernel): packets belonging to established/trusted connections (marked via CONNMARK) are processed entirely by the Linux kernel.
  • Inspection Path (User Space): new or unmarked packets are sent to Meds via NFQUEUE.

• Classification pipeline
  Packets are processed according to the following pipeline:

  • Global IP Whitelist — immediate pass for trusted source IPs
  • Rate Limiter — protects system resources by limiting packet rate per source IP
  • Global IP Blacklist — immediate block for malicious source IPs
  • IP Filters — applies granular IP-based filtering rules
  • Geo Filters — filters traffic by country of origin using ASN metadata
  • ASN Filters — checks Autonomous System reputation against blacklists
  • Global Domain/SNI Whitelist — permits trusted domains extracted from DNS or TLS SNI
  • Global Domain/SNI Blacklist — blocks malicious domains from DNS or TLS SNI
  • Domain/SNI Filters — applies granular domain-based filtering rules
  • TLS JA3 Filters — detects malicious clients via TLS fingerprinting

• Decision engine

  • DROP → packet is malicious, discarded immediately
  • MARK → marks the connection as trusted in the kernel (via Netlink) once all checks are passed
  • ACCEPT → packet is safe, passed to kernel stack

• Metrics & logging
  Every decision is counted and exported for monitoring and alerting.
  Metrics are Prometheus-compatible and can be visualized in Grafana.
  All events are asynchronously logged to minimize packet processing latency.

📊 Example Metrics (Prometheus)

# HELP meds_core_connections_trusted_total Total number of trusted connections
# TYPE meds_core_connections_trusted_total counter
meds_core_connections_trusted_total{reason="trusted packet"} 92

# HELP meds_core_packets_accepted_total Total number of accepted packets
# TYPE meds_core_packets_accepted_total counter
meds_core_packets_accepted_total{filter="empty",reason="default"} 798
meds_core_packets_accepted_total{filter="ip",reason="WhiteList"} 84

# HELP meds_core_packets_dropped_total Total number of dropped packets
# TYPE meds_core_packets_dropped_total counter
meds_core_packets_dropped_total{filter="asn",reason="Spamhaus"} 14
meds_core_packets_dropped_total{filter="geo",reason="IPLocate"} 7
meds_core_packets_dropped_total{filter="ip",reason="FireHOL"} 350

# HELP meds_core_packets_processed_total Total number of processed packets
# TYPE meds_core_packets_processed_total counter
meds_core_packets_processed_total 1253

📜 License

Meds is released under the MIT License.
See LICENSE for details.

🤝 Contributing

Pull requests and feature suggestions are welcome!
If you find a bug, please open an issue or submit a fix.

Made with ❤️ in Go