From 6b1bfb3a01ba87c2f79bd1604d1f155a3d01deb9 Mon Sep 17 00:00:00 2001 From: Steven Polley Date: Sat, 20 Apr 2024 18:31:14 -0600 Subject: [PATCH] Better usage in hyp and hypd readme's --- README.md | 6 ++++-- hyp/README.md | 37 +++++++++++++++++++++++++++++++------ hypd/README.md | 16 ++++++++++++++-- 3 files changed, 49 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index ca9e83c..f2082e2 100644 --- a/README.md +++ b/README.md @@ -20,13 +20,15 @@ Compared to most port knocking daemons, hyp is extremely fast, lightweight and h Port knocking clients have minimal requirements and can run on x86, ARM, MIPS, PowerPC, IBM390, or RISC-V. Currently only supported OS's are Linux and Windows, with support for Android planned to be added in the future. -The port knocking daemon has more strict requirements and is only available for Linux. It requires the kernel be built with CONFIG_DEBUG_INFO_BTF, which most major distributions have out of the box. +The port knocking daemon has more strict requirements and is only available for Linux. It requires the kernel be built with CONFIG_DEBUG_INFO_BTF, which most major distributions have out of the box. Additionally, hypd has some network requirements. hypd is only expected to work on ethernet networks with IPv4. + +Once you get the runtime requirements sorted, be sure to check out the hyp and hypd directories of the repository for README information for how to use hyp. ### Build Requirements Pre-built binaries for configurations I've tested are available on the [releases page](https://deadbeef.codes/steven/hyp/releases). This will likely run in many CPU architectures I haven't tested yet though. -To build this yourself, you will need Linux with packages for: git, clang, linux-headers- libbpf-dev and golang. Check out the [Dockerfile ](https://deadbeef.codes/steven/hyp/src/branch/main/Dockerfile) as a reference for how the build environment for official releases is configured. Once the environment is ready, you can clone the repo and build. +To build this yourself, you will need Linux with packages for: git, clang, linux-headers- libbpf-dev and golang. Check out the [Dockerfile](https://deadbeef.codes/steven/hyp/src/branch/main/Dockerfile) as a reference for how the build environment for official releases is configured. Once the environment is ready, you can clone the repo and build. ```sh # Clone repository diff --git a/hyp/README.md b/hyp/README.md index a307bb7..7fea70e 100644 --- a/hyp/README.md +++ b/hyp/README.md @@ -1,9 +1,34 @@ -# hyp-client +# hyp | Hide Your Ports Client -The client expects there to be a file named hyp.secret in the same directory. This file is generated by the hypd server using ./hypd generate secret. +The hyp client is used on machines to perform an authentic knock sequence. + +### Usage + +You can use -h to get help for hyp and all its commands. When figuring out how to do something, -h is your friend. ```bash -# Example Usage -# ./hyp knock -./hyp knock 192.168.50.5 -``` \ No newline at end of file +# Get general hyp help +./hyp -h + +# Get help specific to the hyp knock command +./hyp knock -h +``` + +In order to use the hyp client, it must have the secret. Secrets are generated by hypd, the knock daemon. See the hypd README.md file for more information about generating secrets. + +Once you have the secret, you can then perform an authentic knock sequence to a server. + +```bash +# Assumes secret is in file named my-first-secret in same directory +./hyp knock 8.69.4.20 --secret my-first-secret + +# If you omit --secret, hyp will look for a file named hyp.secret +./hyp knock 8.69.4.20 +``` + +This will perform a single one-shot knock sequence and then hyp will exit. You can also run hyp in a persistent mode where it will perform an authentic knock sequence at a specified interval. + +```bash +# Performs an authentic knock sequence every 45 minutes +./hyp knock 8.69.4.20 --refreshtime=45 +``` diff --git a/hypd/README.md b/hypd/README.md index bd0e1f1..1fc6989 100644 --- a/hypd/README.md +++ b/hypd/README.md @@ -1,9 +1,19 @@ # hypd | Hide Your Ports Daemon -hypd is the pork knocking daemon which listens for incoming authentic knock sequences. +hypd is the pork knocking daemon which listens for incoming authentic knock sequences. When it sees an authentic knock sequence, it then performs an action. ### Usage +You can use -h to get help for hypd and all its commands. When figuring out how to do something, -h is your friend. + +```bash +# Get general hypd help +./hypd -h + +# Get help specific to the hypd generate command +./hypd generate -h +``` + Running hypd requires generating secrets which are then shared with hyp clients. hypd is used to generate these secrets, and it's recommended you create a directory just for hyp secrets. ```bash @@ -30,4 +40,6 @@ Once you have set your config file, you can finally run hypd. ```bash # As root or sudo, specify the configuration file sudo ./hypd server hypd.conf -``` \ No newline at end of file +``` + +If you encounter any errors while trying to run, address those. If not, then you're now listening for incoming authentic knock sequences. Make sure you distribute the secret to the client. \ No newline at end of file