{"id":19764292,"url":"https://github.com/theobori/tinyknock","last_synced_at":"2026-05-13T18:03:13.554Z","repository":{"id":216407436,"uuid":"737877540","full_name":"theobori/tinyknock","owner":"theobori","description":"🐝 XDP port knocking","archived":false,"fork":false,"pushed_at":"2024-04-05T01:55:22.000Z","size":52,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-10T23:47:20.765Z","etag":null,"topics":["bpf","ebpf","port-knocking","xdp"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theobori.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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}},"created_at":"2024-01-01T20:21:49.000Z","updated_at":"2024-09-12T07:15:23.000Z","dependencies_parsed_at":"2024-01-14T23:25:44.386Z","dependency_job_id":"d6932beb-5d9d-418b-8166-8c323872bbfc","html_url":"https://github.com/theobori/tinyknock","commit_stats":null,"previous_names":["theobori/tinyknock"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theobori%2Ftinyknock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theobori%2Ftinyknock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theobori%2Ftinyknock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theobori%2Ftinyknock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theobori","download_url":"https://codeload.github.com/theobori/tinyknock/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241096177,"owners_count":19908931,"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":["bpf","ebpf","port-knocking","xdp"],"created_at":"2024-11-12T04:13:04.009Z","updated_at":"2026-05-13T18:03:08.506Z","avatar_url":"https://github.com/theobori.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🐝 tinyknock\n\neBPF (XDP) port knocking, it is compatible with the [knock](https://github.com/jvinet/knock) client.\n\nThe filtering is zero trust, it means there are zero ports allowed by default on the concerned protocol(s). Since the port knocking rules are applied at XDP level, it must take a decision on every incoming XDP packet.\n\nThe rules mechanism is inspired by [OpenState](https://sdn.ieee.org/newsletter/march-2017/openstate-an-interface-for-stateful-packet-processing-in-programmable-switches) but it is not designed for a switch.\n\n\u003e ⚠️ It is only experimental and should not run in production.\n\u003e \n\u003e Note that every port knocking sequence starts with the port 0\n\u003e like `knock ipaddr 0 100 200 300`\n\n## 📖 Build and run\n\nYou only need the following requirements (packages):\n- `llvm`\n- `clang`\n- `make`\n- `libcyaml`\n- `libxdp`\n\n### Debian / Ubuntu\n\n```bash\napt install -y llvm clang make libcyaml-dev libxdp-dev\n```\n\n### RHEL / Fedora\n\n```bash\ndnf install -y llvm clang make libcyaml-devel libxdp-devel\n\n# There are no official repositories for libcyaml\ngit clone https://github.com/tlsa/libcyaml\ncd libcyaml\nmake VARIANT=release\nmake install VARIANT=release\ncd ..\nrm -rf libcyaml\n```\n\nYou should also have `bpftool` if you need to debug.\n\nTo build, run the following command.\n```bash\nmake\n```\n\nThen you can run.\n```bash\n./tinyknock -h\n```\n\n## 🤝 Contribute\n\nIf you want to help the project, you can follow the guidelines in [CONTRIBUTING.md](./CONTRIBUTING.md).\n\n## 📏 YAML policies\n\nHere is a full YAML schema:\n\n```yaml\npolicies:\n  - target: 8000\n    action: open\n    sequence:\n      - value: 1000\n        protocol: tcp\n      - value: 2000\n        protocol: udp\n      - value: 3000\n        protocol: tcp\n\n  - target: 8000\n    action: close\n    sequence:\n      - value: 3000\n        protocol: tcp\n      - value: 2000\n        protocol: tcp\n      - value: 1000\n        protocol: tcp\n```\n\nOverview of the possible values and what it does:\n\n```c\nstatic const cyaml_strval_t action_strings[] = {\n\t{ \"open\", XDP_PASS },\n\t{ \"close\", XDP_DROP },\n\t{ \"abort\", XDP_ABORTED }\n};\n\nstatic const cyaml_strval_t protocol_strings[] = {\n\t{ \"tcp\", IPPROTO_TCP },\n\t{ \"udp\", IPPROTO_UDP },\n\t{ \"icmp\", IPPROTO_ICMP }\n};\n```\n\n## ⭐ Use cases\n\nTo test the program, I have created two Linux network namespaces (both reachable by each other) following [this steps](https://medium.com/@technbd/creating-network-namespaces-in-linux-system-and-connecting-two-network-namespaces-using-virtual-6031d295f69b).\n\n```bash\n# Creates namespaces\nip netns add ns1\nip netns add ns2\n\n# Creates two wirtual network interface peered\nip link add veth1 type veth peer name veth2\n\n# Assigns virtual interface to the namespaces\nip link set veth1 netns ns1\nip link set veth2 netns ns2\n\n# Assigns IP addresses to the virtual interfaces inside the namespaces\nip netns exec ns1 ip addr add 10.10.0.2/24 dev veth1\nip netns exec ns2 ip addr add 10.10.0.3/24 dev veth2\n\n# Enables the virtual interfaces inside the namespaces\nip netns exec ns1 ip link set dev veth1 up\nip netns exec ns2 ip link set dev veth2 up\n```\n\nNow everything is setup, you can run the XDP program inside the first network namespace.\n\n```bash\nip netns exec ns1 ./tinyknock -f file.yaml -b ./src/tinyknock.bpf.o -i veth1\n```\n\nIf you this error `libxdp: No bpffs found at /sys/fs/bpf`, you can mount the filesystem using the following command.\n\n```bash\nmount -t bpf bpf /sys/fs/bpf/\n```\n\nAnd knock with the second one, assuming you have the following policies.\n```yaml\npolicies:\n  - target: 8000\n    action: open\n    sequence:\n      - value: 1000 # TCP port\n        protocol: tcp\n      - value: 2000 # UDP port\n        protocol: udp\n      - value: 4 # ICMP code\n        protocol: icmp\n```\n\nYou can knock in the order above.\n```bash\nip netns exec ns2 knock 10.10.0.2 0 1000 2000:udp\nip netns exec ns2 hping3 10.10.0.2 --icmpcode 4\n```\n\nIf it worked, you should have a response like this:\n```bash\nip netns exec ns2 curl 10.10.0.2:8000\ncurl: (7) Failed to connect to 10.10.0.2 port 8000 after 0 ms: Couldn't connect to server\n```\n\n## 🎉 Tasks\n\n- [x] Fancier user stdout print (ring buffer event)\n- [x] Support ICMP protocol\n- [x] Implement the policies via YAML file\n- [x] User log with a ring buffer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheobori%2Ftinyknock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftheobori%2Ftinyknock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftheobori%2Ftinyknock/lists"}