{"id":28716323,"url":"https://github.com/al-oladko/ebpfilter","last_synced_at":"2026-04-30T07:40:52.061Z","repository":{"id":296083186,"uuid":"992259925","full_name":"al-oladko/ebpfilter","owner":"al-oladko","description":"A lightweight firewall with stateful session tracking, L2–L4 filtering, DPI-based inspection, connection rate limiting, and NAT support.","archived":false,"fork":false,"pushed_at":"2025-06-13T20:40:45.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-13T21:31:51.779Z","etag":null,"topics":["dpi","ebpf","firewall","nat","rate-limiting","xdp"],"latest_commit_sha":null,"homepage":"","language":"C","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/al-oladko.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-05-28T21:46:54.000Z","updated_at":"2025-06-13T21:10:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"0627c4d9-28d6-433b-9586-a1ec7788e275","html_url":"https://github.com/al-oladko/ebpfilter","commit_stats":null,"previous_names":["al-oladko/ebpfilter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/al-oladko/ebpfilter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/al-oladko%2Febpfilter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/al-oladko%2Febpfilter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/al-oladko%2Febpfilter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/al-oladko%2Febpfilter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/al-oladko","download_url":"https://codeload.github.com/al-oladko/ebpfilter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/al-oladko%2Febpfilter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259914866,"owners_count":22931323,"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","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":["dpi","ebpf","firewall","nat","rate-limiting","xdp"],"created_at":"2025-06-15T03:00:15.252Z","updated_at":"2026-04-30T07:40:52.048Z","avatar_url":"https://github.com/al-oladko.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ebpfilter\n\n**ebpfilter** is an eBPF XDP-based stateful firewall with support for L7 (application-layer) traffic filtering using DPI (Deep Packet Inspection). It maintains connection state, so once a session is allowed, packets within that session do not need to be re-evaluated against the rules.\n\nIt supports standard L4-level firewall filtering options such as source and destination IP addresses, protocols, and port numbers. L7 protocol detection is performed using a lightweight DPI engine. DPI analysis is independent of destination port, and currently has the following limitation: the L7 protocol must be detected in the first packet carrying payload data.\n\n#### Features\n\n- Stateful session tracking\n- Layer 3–4 packet filtering\n- DPI-based filtering\n- Rate limiting for new sessions\n- Source NAT\n- Support for IP fragmentation handling (the firewall applies the session policy to all fragments based on the first fragment, as subsequent fragments do not contain the Layer 4 header)\n\n---\n\n## Installation\n\nTo install ebpfilter, follow these steps:\n\n```bash\ngit clone https://github.com/al-oladko/ebpfilter\n./configure\nmake\nsudo make install\n````\n\n---\n\n## Usage\n\nUse the `ebpfilter` utility to load, unload, and manage filtering rules.\n\n### Load XDP program\n\nAttach the XDP filter to a network interface:\n\n```bash\nebpfilter load dev \u003cifname\u003e\n```\n\n### Show attached interfaces\n\nList all interfaces where the XDP program is currently attached:\n\n```bash\nebpfilter status\n```\n\nYou can attach the program to multiple interfaces. Each interface maintains its own independent rule set.\n\n### Unload XDP program\n\nUnload the XDP program from a specific interface:\n\n```bash\nebpfilter unload [dev \u003cifname\u003e]\n```\n\nIf `\u003cifname\u003e` is not specified, the program will be unloaded from all interfaces.\n\n### Reload XDP program\n\nReattaching the XDP program while preserving the loaded rule set:\n\n```bash\nebpfilter reload [dev \u003cifname\u003e]\n```\n\nIf `\u003cifname\u003e` is not specified, the program will be reloaded on all interfaces.\n\n### View connection\n\nView connection tracking table:\n\n```bash\nebpfilter connection [dev \u003cifname\u003e]\n```\n\nThe 5-tuple of the session is displayed, along with the firewall rule that allowed the session and the session's expiration status.\n\n---\n\n## Managing Rules\n\n### Set default policy\n\nSpecify the default action for packets that do not match any rule:\n\n```bash\nebpfilter rule set default {accept|drop} [dev \u003cifname\u003e]\n```\n\n### Add a rule\n\nAdd a new filtering rule:\n\n```bash\nebpfilter rule add \u003crule-options\u003e [dev \u003cifname\u003e]\n```\n\nYou may omit `ifname` if the program is attached to only one interface. If attached to multiple interfaces, `ifname` is required.\n\n**Example L3 rule (IP-based filtering):**\n\n```bash\nebpfilter rule add src 10.20.0.0/16 dst 192.168.1.0/24 action accept\n```\n\n**Example L7 rule (DPI-based protocol detection):**\n\n```bash\nebpfilter rule add service tls action accept\n```\n\nThis rule allows TLS traffic regardless of the destination port (not limited to port 443). L7 rules can be combined with L3/L4 filters:\n\n```bash\nebpfilter rule add src any dst 192.168.1.1 tcp port 443 service tls action accept\n```\n**Setting connection limit**\n\n```bash\nebpfilter rule add tcp port 443 connlimit 100/1s action accept\n```\n\nLimit of new connections for the rule. The format is [connections_per_period]/[period], where the period is specified in seconds, minutes, or hours, and must be indicated with the suffixes s, m, or h, respectively.\n\nTo get information about other options when adding a rule, see the help for the rule command.\n\n### View help for rule syntax\n\n```bash\nebpfilter rule help\n```\n\n### Show current policy\n\nDisplay the currently loaded rule set:\n\n```bash\nebpfilter rule show [dev \u003cifname\u003e]\n```\n\nEach rule includes statistics on matches, such as packet and byte counts.\n\n### Delete a rule\n\nRemove a rule by its number:\n\n```bash\nebpfilter rule delete [dev \u003cifname\u003e]\n```\n\n### Flush all rules\n\nRemove all rules from the policy:\n\n```bash\nebpfilter rule flush [dev \u003cifname\u003e]\n```\n\n---\n\n## Example Policy\n\n```bash\nebpfilter rule add udp port 53 service dns action accept\nebpfilter rule add service tls action accept\nebpfilter rule set default drop\n```\n\nThis configuration allows:\n\n* DNS traffic over UDP port 53\n* TLS traffic on any port\n* All other traffic will be dropped by default.\n\n---\n\n## Policy Management\n\nThe policy command is used to manage firewall policies. Each network interface has its own policy, which is configured separately and stored in a dedicated file. By default, policies are saved in YAML format, but you can also use the txt format by specifying the format parameter in the command.\n\n### Save a Policy\n\nCurrently, firewall policy changes made using the rule or nat commands are not saved automatically. To save the current policy, run:\n\n```bash\nebpfilter policy save\n```\n\nBy default, the policy will be saved to the /etc/firewall directory. You can specify a different file name and path using the file parameter. For example:\n\n```bash\nebpfilter policy save file policy_allow_http.yaml\n```\n\nOr save the policy in txt format:\n\n```bash\nebpfilter policy save file policy_deny_ssh.txt format txt\n```\n\n### Apply a Policy\n\nTo load a policy from a file, use:\n\n```bash\nebpfilter policy apply file policy.yaml\n```\n\nOr, to load the default policy file:\n\n```bash\nebpfilter policy apply\n```\n\n### View a Policy\n\nTo view a saved policy, use the show parameter. For example:\n\n```bash\nebpfilter policy show file policy_allow_ssh.yaml\n```\n\n---\n\n## NAT\n\nCurrently, only **source NAT** is supported.\nA NAT rule must be defined for a network interface, and the IP address of that interface will be used as the **source IP address** in translated packets.\n\nCurrent NAT limitations:\n- If, after translating the source IP address, the new 5-tuple matches the 5-tuple of another session that is already being NATed, the NAT rule will not be applied.\n\n### Add a NAT Rule\n\nTo add a source NAT rule, use the following command:\n\n```bash\nebpfilter nat add src-translation set-ip IP-address|auto [dev IFNAME]\n```\n\n- If an explicit `IP-address` is given, it will be used as the new source IP.\n- If `auto` is specified, the IP address of the given `IFNAME` interface will be used.\n- If only one XDP program is attached to a single interface, the `dev` parameter is optional — the NAT rule will be applied to that interface.\n\nYou can also use a shorthand alias to add a source NAT rule:\n\n```bash\nebpfilter snat add set-ip IP-address|auto [dev IFNAME]\n```\n\n### Flush NAT Rules\n\nTo remove all NAT rules, use:\n\n```bash\nebpfilter nat flush [dev IFNAME]\n```\n\n### View NAT Rules\n\nTo view currently configured NAT rules and their parameters, run:\n\n```bash\nebpfilter nat show [dev IFNAME]\n```\n\n## License\n\nThis project is licensed under the GNU General Public License v2 only.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fal-oladko%2Febpfilter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fal-oladko%2Febpfilter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fal-oladko%2Febpfilter/lists"}