{"id":30131080,"url":"https://github.com/buanderie/slfw","last_synced_at":"2025-08-10T19:00:28.539Z","repository":{"id":306845694,"uuid":"1026226021","full_name":"Buanderie/slfw","owner":"Buanderie","description":null,"archived":false,"fork":false,"pushed_at":"2025-08-05T14:24:38.000Z","size":93,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-05T16:21:05.685Z","etag":null,"topics":["audit","cilium","cilium-ebpf","ebpf","ebpf-programs","firewall","golang"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Buanderie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-25T14:15:05.000Z","updated_at":"2025-08-05T14:23:37.000Z","dependencies_parsed_at":"2025-07-28T01:35:30.257Z","dependency_job_id":null,"html_url":"https://github.com/Buanderie/slfw","commit_stats":null,"previous_names":["buanderie/slfw"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Buanderie/slfw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Buanderie%2Fslfw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Buanderie%2Fslfw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Buanderie%2Fslfw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Buanderie%2Fslfw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Buanderie","download_url":"https://codeload.github.com/Buanderie/slfw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Buanderie%2Fslfw/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269772015,"owners_count":24473337,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-10T02:00:08.965Z","response_time":71,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audit","cilium","cilium-ebpf","ebpf","ebpf-programs","firewall","golang"],"created_at":"2025-08-10T19:00:24.634Z","updated_at":"2025-08-10T19:00:28.485Z","avatar_url":"https://github.com/Buanderie.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# secure-linux-firewall\r\n\r\n## Overview\r\nThis project implements a high-performance, auditable firewall for Linux environments using **eBPF (extended Berkeley Packet Filter)**. It leverages **XDP (eXpress Data Path)** for ingress filtering and **TC (Traffic Control)** for egress filtering, bypassing Docker’s problematic iptables NAT rules. Built with **Cilium’s eBPF library** in a portable **GoLang application**, the firewall uses a **YAML configuration file** and a **binary diff-based audit process** to ensure runtime rules match the intended policy. This solution provides superior security, performance, and auditability compared to traditional iptables-based firewalls.\r\n\r\n## Features\r\n- **XDP Ingress Filtering**: Blocks incoming packets at the network driver level for maximum performance and early threat mitigation.\r\n- **TC Egress Filtering**: Controls container-originated outbound traffic with fine-grained rules.\r\n- **Cilium/eBPF Integration**: Uses Cilium’s robust eBPF library for reliable program and map management.\r\n- **GoLang Binary**: Portable, single-binary deployment across platforms for easy distribution.\r\n- **YAML Configuration**: Human-readable, version-controllable rule definitions.\r\n- **Binary Diff Audits**: Verifies runtime eBPF map rules against YAML config to ensure policy integrity.\r\n- **Docker Compatibility**: Operates at the interface level to avoid conflicts with Docker’s iptables NAT rules.\r\n\r\n## Technical Justification\r\nDocker’s heavy reliance on iptables for NAT (e.g., port mapping, masquerading) creates challenges for traditional firewalls:\r\n- **iptables Limitations**:\r\n  - Docker dynamically modifies iptables rules (e.g., DOCKER chain), overwriting custom filters.\r\n  - Parsing `iptables -S` is error-prone due to NAT clutter, making audits unreliable.\r\n  - L3/L4 focus lacks container-aware context, limiting granularity.\r\n  - Netfilter hooks introduce performance overhead, increasing DoS risks.\r\n- **eBPF Advantages**:\r\n  - **Security**: XDP/TC filtering at the interface level bypasses Docker’s NAT, ensuring consistent rule enforcement. Container-aware rules (via Cilium) enhance granularity.\r\n  - **Auditability**: eBPF maps provide structured, queryable rule storage. Binary diff audits compare map contents to YAML-derived rules, guaranteeing policy alignment.\r\n  - **Performance**: XDP processes ingress packets at the driver level, and TC handles egress efficiently, minimizing latency and DoS exposure.\r\n  - **Flexibility**: Dynamic rule updates without traffic disruption and portable GoLang deployment simplify management.\r\n\r\n## Why eBPF Over iptables?\r\nThis eBPF firewall is more secure and auditable than iptables in Docker environments because:\r\n1. **No NAT Conflicts**: XDP/TC operate before Docker’s NAT stack, preventing rule overrides.\r\n2. **Reliable Audits**: Binary diff of eBPF maps against YAML config is precise and programmatic, unlike iptables’ messy text output.\r\n3. **Container Awareness**: Supports container-specific rules, surpassing iptables’ L3/L4 limitations.\r\n4. **Performance**: XDP/TC’s low-latency processing reduces attack surface compared to iptables’ Netfilter hooks.\r\n\r\n## Security Considerations\r\n- **Implementation**: Custom eBPF programs and audit logic require rigorous testing to prevent bugs or bypasses.\r\n- **Privileges**: The GoLang app requires CAP_BPF/CAP_NET_ADMIN; secure deployment is critical to prevent tampering.\r\n- **Dependencies**: Regular updates to Cilium/eBPF, GoLang, and the Linux kernel mitigate potential vulnerabilities.\r\n\r\n## Getting Started\r\n1. **Build Dependencies**:\r\n   - GoLang (v1.18+)\r\n   - Make\r\n   - LLVM\r\n   - Clang\r\n   - libc6-dev-i386\r\n   - libbpf-dev\r\n   - linux-headers-generic\r\n2. **Runtime Dependencies**:\r\n   - Linux kernel with eBPF support (v4.15+ for XDP, v4.19+ for TC clsact)\r\n3. **Build**:\r\n   ```bash\r\n   make\r\n   ```\r\n4. **Configure**:\r\n   - Edit a YAML configuration file to define rules (e.g., src_ip, dst_port, action).\r\n5. **Run**:\r\n    * Attach to an interface (no rules loaded)\r\n   ```bash\r\n   sudo ./ebpf-firewall -i eth0 attach\r\n   ```\r\n\r\n   * Attach and load a configuration to an interface\r\n   ```bash\r\n   sudo ./ebpf-firewall -i eth0 load -c config.yaml\r\n   xxx@xxx:$ sudo ./firewall -i eth0 load -c test_config.yaml\r\n    Using existing pinned eBPF objects at /sys/fs/bpf/slfw_eth0\r\n    Set inbound default policy to DROP\r\n    Set outbound default policy to DROP\r\n    Loading 3 rules for interface eth0...\r\n    ✓ Added block_specific_ip_inbound rule at index 0\r\n    ✓ Added block_specific_ip_inbound rule at index 1\r\n    ✓ Added block_specific_ip_inbound rule at index 2\r\n    Loading 6 rules for interface eth0...\r\n    ✓ Added allow_dns_udp_outbound rule at index 0\r\n    ✓ Added allow_dns_tcp_outbound rule at index 1\r\n    ✓ Added allow_doh_outbound rule at index 2\r\n    ✓ Added allow_dot_outbound rule at index 3\r\n    ✓ Added allow_icmp_outbound rule at index 4\r\n    ✓ Added block_specific_port_range_outbound rule at index 5\r\n    Firewall rules applied to interface eth0\r\n   ```\r\n\r\n   * Detach firewall from an interface\r\n   ```bash\r\n   sudo ./ebpf-firewall -i eth0 detach\r\n   ```\r\n\r\n   * Print rules enforced on an interface\r\n   ```bash\r\n   xxx@xxx:$ sudo ./firewall -i eth0 print\r\n    Inbound Rules:\r\n    Rule block_specific_ip_inbound: icmp any n/a:ALLOW\r\n    Rule block_specific_ip_inbound: udp any 53:ALLOW\r\n    Rule block_specific_ip_inbound: tcp any 53:BLOCK\r\n\r\n    Outbound Rules:\r\n    Rule allow_dns_udp_outbound: udp any 53:ALLOW\r\n    Rule allow_dns_tcp_outbound: tcp any 53:ALLOW\r\n    Rule allow_doh_outbound: tcp any 443:ALLOW\r\n    Rule allow_dot_outbound: tcp any 853:ALLOW\r\n    Rule allow_icmp_outbound: icmp any n/a:ALLOW\r\n    Rule block_specific_port_range_outbound: tcp 10.0.0.0/16 1000-2000:BLOCK\r\n   ```\r\n\r\n6. **Audit**:\r\n  Run the audit command to verify map rules against config:\r\n     ```bash\r\n     sudo ./firewall -i eth0 audit -c config.yaml\r\n      Audit result for INBOUND rules:\r\n      FAIL\r\n      Missing rules (in config but not enforced):\r\n        - 000000010000000000000000000000000000\r\n      rule_name: \"\"\r\n      action: DROP\r\n      protocol: icmp\r\n      ip: 0.0.0.0/0\r\n      description: \"\"\r\n\r\n      Extra rules (enforced but not in config):\r\n        - 010000010000000000000000000000000000\r\n      rule_name: \"\"\r\n      action: ACCEPT\r\n      protocol: icmp\r\n      ip: 0.0.0.0/0\r\n      description: \"\"\r\n\r\n      Audit result for INBOUND default policy:\r\n      PASS: (DROP)\r\n      Audit result for OUTBOUND rules:\r\n      PASS\r\n      Audit result for OUTBOUND default policy:\r\n      PASS: (DROP)\r\n      Error: audit failed: audit failed: rules do not match\r\n      Error: audit failed: audit failed: rules do not match\r\n     ```\r\n\r\n## Example YAML Config\r\n```yaml\r\ninbound_policy: \"DROP\"\r\ninbound:\r\n  - rule_name: \"block_specific_ip_inbound\"\r\n    action: \"allow\"\r\n    protocol: \"icmp\"\r\n    ip: \"any\"\r\n    description: \"Block all inbound traffic from 203.0.113.5\"\r\n  - rule_name: \"block_specific_ip_inbound\"\r\n    action: \"allow\"\r\n    protocol: \"udp\"\r\n    ip: \"any\"\r\n    port: 53\r\n    description: \"Block all inbound traffic from 203.0.113.5\"\r\n  - rule_name: \"block_specific_ip_inbound\"\r\n    action: \"block\"\r\n    protocol: \"tcp\"\r\n    ip: \"any\"\r\n    port: 53\r\n    description: \"Block all inbound traffic from 203.0.113.5\"\r\n\r\noutbound_policy: \"DROP\"\r\noutbound:\r\n  - rule_name: \"allow_icmp_outbound\"\r\n    action: \"allow\"\r\n    protocol: \"icmp\"\r\n    ip: \"any\"\r\n    description: \"Allow outbound ICMP traffic\"\r\n  - rule_name: \"block_specific_port_range_outbound\"\r\n    action: \"block\"\r\n    protocol: \"tcp\"\r\n    ip: \"10.0.0.0/16\"\r\n    port_range:\r\n      start: 1000\r\n      end: 2000\r\n    description: \"Block outbound TCP traffic to 10.0.0.0/16 on ports 1000-2000\"\r\n```\r\n\r\n## Future Improvements\r\n- Add observability with eBPF ring buffer logging for dropped packets.\r\n- Add stats for dropped packets\r\n- Add bandwidth control (global + per-rule ?)\r\n\r\n## License\r\nMIT License","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuanderie%2Fslfw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbuanderie%2Fslfw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbuanderie%2Fslfw/lists"}