{"id":21454381,"url":"https://github.com/timothyye/knock-rs","last_synced_at":"2025-10-24T23:06:41.953Z","repository":{"id":225626008,"uuid":"764728644","full_name":"TimothyYe/knock-rs","owner":"TimothyYe","description":"A port-knocking implementation in Rust","archived":false,"fork":false,"pushed_at":"2024-11-10T06:06:46.000Z","size":1040,"stargazers_count":104,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-05T21:53:21.919Z","etag":null,"topics":["knocking","port","port-knocking"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimothyYe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2024-02-28T15:54:59.000Z","updated_at":"2025-04-03T07:23:15.000Z","dependencies_parsed_at":"2024-11-10T07:18:19.641Z","dependency_job_id":"39982f86-79a9-4641-a128-2ee5f24b2697","html_url":"https://github.com/TimothyYe/knock-rs","commit_stats":null,"previous_names":["timothyye/knock","timothyye/knock-rs"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyYe%2Fknock-rs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyYe%2Fknock-rs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyYe%2Fknock-rs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimothyYe%2Fknock-rs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimothyYe","download_url":"https://codeload.github.com/TimothyYe/knock-rs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247622986,"owners_count":20968575,"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":["knocking","port","port-knocking"],"created_at":"2024-11-23T05:03:03.288Z","updated_at":"2025-10-24T23:06:36.842Z","avatar_url":"https://github.com/TimothyYe.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# knock-rs: A port-knocking implementation in Rust\n\n[中文文档](https://github.com/TimothyYe/knock-rs/blob/master/README_CN.md)\n\n\u003cimg src=\"https://raw.githubusercontent.com/TimothyYe/knock-rs/master/images/knock.png\" width=\"600\"\u003e\n\n## What is port-knocking?\n\nPort-knocking is a method of externally opening ports on a firewall by generating a connection attempt on a set of prespecified closed ports. Once a correct sequence of connection attempts is received, the firewall rules are dynamically modified to allow the host which sent the connection attempts to connect over specific port(s). \n\n`knock-rs` __only detects the SYN packets and doesn't listen to the opened ports__, it uses the [pnet](https://docs.rs/pnet/latest/pnet/) crate to capture the raw packets.\n\nA common use of this technique is to secure connections to an SSH server by only allowing access to the SSH port after a successful port-knocking sequence has been executed.\n\nThis project is inspired by another [knock](https://github.com/jvinet/knock) project which is written in C, but it is written in Rust and has a different configuration format.\n\n## Why use port-knocking?\n\nPort-knocking is a simple and effective way to secure your server from unauthorized access. It is a lightweight and secure method to protect your server from unauthorized access.\n\n## Common Use Cases\n\n- Secure your SSH server from brute-force attacks\n- Open and close any ports on your firewall dynamically based on your needs\n\n## Download\n\nYou can download the pre-built binaries from the [releases](https://github.com/TimothyYe/knock-rs/releases) page.\n\n## Build\n\n```bash\ncargo build --release\n```\n\n## Configuration\n\n### Server Configuration\n\nCreate a configuration file named `config.yaml` in the same directory as the `knockd` binary.\n\n```yaml\ninterface: \"eth0\"\ntimeout: 5\nrules:\n  - name: \"enable_ssh\"\n    command: \"/usr/sbin/iptables -I INPUT -s %IP% -p tcp --dport 22 -j ACCEPT\"\n    sequence:\n      - 15523\n      - 17767\n      - 32768\n      - 28977\n      - 51234\n  - name: \"disable_ssh\"\n    command: \"/usr/sbin/iptables -D INPUT -s %IP% -p tcp --dport 22 -j ACCEPT\"\n    sequence:\n      - 51234\n      - 28977\n      - 32768\n      - 17767\n      - 15523\n```\n\n- `interface`: The network interface to listen on\n- `timeout`: The timeout in seconds to wait for the client to send the complete sequence\n- `rules`: The rules to apply when the correct sequence is received\n\t- `name`: The name of the rule\n\t- `command`: The command to execute when the correct sequence is received. `%IP%` will be replaced with the client's IP address\n\t- `sequence`: The sequence of ports that the client should knock\n\n### Client Configuration\n\nCreate a configuration file named `config.yaml` in the same directory as the `knock-cli` binary. \n\n__Do make sure that the client has the same sequence as the server.__\n\n```yaml\nrules:\n  - name: \"enable_ssh\"\n    host: \"example.com\"\n    sequence:\n      - 12345\n      - 54321\n      - 32768\n      - 18933\n  - name: \"disable_ssh\"\n    host: \"example.com\"\n    sequence:\n      - 18933\n      - 32768\n      - 54321\n      - 12345\n```\n\n- `rules`: The rules to apply when the correct sequence is sent\n\t- `name`: The name of the rule, the name doesn't need to match the server's rule name, but the sequence does. And also, the name should be unique in the client's configuration file\n\t- `host`: The host to send the sequence to\n\t- `sequence`: The sequence of ports to knock\n\n## Usage\n\n### Server\n\n```bash\n./knockd -c config.yaml\n```\n\nThe default config path is `config.yaml`, you can also specify the config file path by using the `-c` option.\n\n### Client\n\n```bash\n./knock-cli -c config.yaml -r enable_ssh\n```\n\nThe default config path is `config.yaml`, you can also specify the config file path by using the `-c` option.\n\nThe `-r` option is used to specify the rule name to knock.\n\n## Run Server as docker container\n\n```bash\ndocker run --network host --cap-add=NET_RAW --cap-add=NET_BIND_SERVICE --cap-add=NET_ADMIN -d --restart=always --name=knockd -v ./config.yaml:/config.yaml:ro ghcr.io/timothyye/knockd:latest\n```\nSince the server needs to listen to the raw packets, you need to add the `NET_RAW`, `NET_BIND_SERVICE` and `NET_ADMIN` capabilities to the container.\n\n## Examples\n\nAssume that you have already added one firewall rule to block all incoming connections to the SSH port. E.g.:\n\n```bash\niptables -A INPUT -p tcp --dport 22 -j DROP\n```\n\nUse the following command to enable the SSH port on the server:\n\n```bash\n./knock-cli -r enable_ssh\n```\n\nAfter the correct sequence is sent, the SSH port will be opened for the client's IP address. Now you can connect to the SSH server.\n\nTo close the SSH port, use the following command:\n\n```bash\n./knock-cli -r disable_ssh\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimothyye%2Fknock-rs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimothyye%2Fknock-rs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimothyye%2Fknock-rs/lists"}