meds

Meds: net healing

High-performance firewall powered by NFQUEUE and Go

It integrates with Linux Netfilter via NFQUEUE, inspects inbound traffic in user space, and applies filtering to block malicious or unwanted traffic in real-time.

Designed to cure your network from malicious traffic.

🚀 Installation

Requirements:

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

The application manages iptables 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 4096)
  -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

• NFQUEUE-based packet interception
  Uses Linux Netfilter queues to copy inbound packets into user space with minimal overhead.

• 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] → [NFQUEUE] → [Meds]
                     ↳ 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: ACCEPT / DROP

1. Packet interception
   All inbound packets are queued from Netfilter (iptables rule with -j NFQUEUE).

2. 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

3. Decision engine

   • ACCEPT → packet is safe, passed to kernel stack
   • DROP → packet is malicious, discarded immediately

4. 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_packets_accepted_total Total number of accepted packets
# TYPE meds_core_packets_accepted_total counter
meds_core_packets_accepted_total{filter="domain",reason="WhiteList"} 1
meds_core_packets_accepted_total{filter="empty",reason="decode failed"} 1
meds_core_packets_accepted_total{filter="empty",reason="default"} 9785
meds_core_packets_accepted_total{filter="ip",reason="WhiteList"} 57

# 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"} 73
meds_core_packets_dropped_total{filter="geo",reason="IPLocate"} 2
meds_core_packets_dropped_total{filter="ip",reason="FireHOL"} 386
meds_core_packets_dropped_total{filter="rate",reason="Limiter"} 763

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

📜 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