{"id":22195406,"url":"https://github.com/leonjza/port-jump","last_synced_at":"2025-07-19T22:04:02.490Z","repository":{"id":264916472,"uuid":"850240874","full_name":"leonjza/port-jump","owner":"leonjza","description":"Some security by obscurity using port-jumping.","archived":false,"fork":false,"pushed_at":"2025-06-27T17:22:58.000Z","size":2309,"stargazers_count":14,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-03T03:44:37.133Z","etag":null,"topics":["firewall","poc","portjump","security"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/leonjza.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-08-31T08:34:51.000Z","updated_at":"2025-06-27T17:22:59.000Z","dependencies_parsed_at":"2024-11-26T21:17:32.805Z","dependency_job_id":null,"html_url":"https://github.com/leonjza/port-jump","commit_stats":null,"previous_names":["leonjza/port-jump"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/leonjza/port-jump","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonjza%2Fport-jump","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonjza%2Fport-jump/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonjza%2Fport-jump/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonjza%2Fport-jump/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/leonjza","download_url":"https://codeload.github.com/leonjza/port-jump/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/leonjza%2Fport-jump/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266026177,"owners_count":23866030,"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":["firewall","poc","portjump","security"],"created_at":"2024-12-02T13:27:13.536Z","updated_at":"2025-07-19T22:04:02.459Z","avatar_url":"https://github.com/leonjza.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# port-jump\n\nSome security by obscurity using \"port-jumping\". A silly PoC to use HOTP to update port numbers to a service as time progresses.\n\n![logo](./images/port-jump.png)\n\n\u003e [!WARNING]\n\u003e This is a PoC-scratching-an-itch project. Don't actually use this somewhere important, okay? Nothing beats a firewall actually blocking stuff.\n\n## introduction\n\nPort jumping is a post-wake up \"hmmm\" idea that I wanted to PoC. This code is that result.\n\nThe idea is simple. Instead of having a service like SSH statically listen on port 22 (or whatever port you use) forever, what if that port number changed every `$interval`? Sounds like an excellent security by obscurity choice! This project does that by implementing an HOTP generator based on a secret, generating valid TCP port numbers within a range to use.\n\nUsing a simple config file in `~/.config/port-jump/config.yml`, shared secrets and port mappings are read, and rotated on a configured interval, just like a TOTP does! An example configuration is:\n\n```yml\njumps:\n  - enabled: false\n    dstport: 23\n    interval: 30\n    sharedsecret: YIHWTYNSBRGWFPR4\n  - enabled: true\n    dstport: 22\n    interval: 30\n    sharedsecret: FWX2CC3PLA4ZYGCI\n  - enabled: true\n    dstport: 80\n    interval: 60\n    sharedsecret: HPQY7R45TFSZWTST\n```\n\nThis configuration has three jumps configured, with one being disabled.\n\nAssuming we're targeting SSH, you can now get the remote service port by running `port-jump get port` as follows:\n\n```console\nssh -p $(port-jump get port -p22) user@10.211.55.6\n```\n\nOr, if its say a web service, how about:\n\n```console\ncurl $(port-jump get uri --url remote-service.local -p 443)\n```\n\nOf course, you could also just update the port section of a URL, just like the SSH example:\n\n```console\ncurl https://remote-service.local:$(port-jump get port -p 443)/\n```\n\n## example run\n\nIn the below image, in the bottom panes I have an ubuntu server running the `port-jump jump` command that reads the configuration file and updates `nftables` to NAT incoming connections to port 22. In the top pane is a macOS SSH client that uses the `port-jump get port` command to get the current port to use to connect to the remote SSH service. This command is run every 30 seconds as an example as the configured interval changes the port.\n\n![example](./images/example.png)\n\n## building \u0026 installing\n\nHow you want to install this depends on what you prefer. You can run it as is, as a [systemd unit](#systemd-unit) or as a [docker container](#docker). Do what works for you.\n\nIn most cases you'd need to build the program though, so do that with:\n\n```console\ngo build -o port-jump\n```\n\nYou can also install it using `go install` which would typically install `port-jump` to wherever `GOBIN` points to.\n\n```console\ngo install github.com/leonjza/port-jump@latest\n```\n\n### systemd unit\n\nA systemd [unit](./port-jump.service) is available that will start the `port-jump jump` command as a systemd service. To install:\n\n*Note:* If you have no jumps configured in the configuration file, one will be added as an example, but will be disabled. With no enabled jumps, the service will exit. Be sure to check out `~/.config/port-jump/config.yml` to configure your jumps.\n\n- Copy the example unit file over to something like `/etc/systemd/system/port-jump.servive`\n- Make sure the contents reflects the correct paths where you put your build of `port-jump`.\n- Reload the available daemons with `systemctl daemon-reload`.\n- Enable the service with `systemctl enable port-jump.service`.\n- Start the service with `systemctl start port-jump.service`.\n- Check out the status of `port-jump` with `systemctl status port-jump.service`.\n- Check out the logs with `journalctl -fu port-jump.service`.\n\n### docker\n\nIt's possible to run `port-jump` using Docker. It’s going to require the `--privileged` flag which is generally discouraged. However, assuming you trust this code and understand what that flag means, you could get a docker container up and running.\n\nBuild it with:\n\n```console\ndocker build -t portjump:local .\n```\n\nThen run it with:\n\n```console\ndocker run --rm -it \\\n  -v /root/.config/port-jump/config.yml:/root/.config/port-jump/config.yml \\\n  --network host \\\n  --privileged \\\n  portjump:local jump\n```\n\nNote the volume mapping with `-v`. This is where the jump mapping lives.\n\n## configuration\n\nConfiguration for `port-jump` lives in a configuration file. Depending on your Operating System, this may be relative to wherever the Golang [os.UserHomeDir](https://pkg.go.dev/os#UserHomeDir) call resolves to as `$HOME`. i.em, `$HOME/.config/port-jump/config.yml`. Feel free to edit this file manually, or use the `port-jump config` set of commands to perform create, toggle and delete operations on the configuration.\n\n```console\n$ port-jump config\nWork with port-jump configurations\n\nUsage:\n  port-jump config [command]\n\nAvailable Commands:\n  add         Add a new jump\n  delete      Delete a jump\n  list        List the current jumps\n  toggle      Toggle jump status\n\nFlags:\n  -h, --help   help for config\n\nGlobal Flags:\n  -D, --debug   debug\n\nUse \"port-jump config [command] --help\" for more information about a command.\n```\n\n## todo\n\nThis is a PoC, but to give you an idea of stuff to do includes:\n\n- Adding a floor / ceiling limit to a jump so that ports do not overlap with existing services that may already be running.\n- Add some more firewall support. Right now only `nftables` is supported on Linux.\n- IPv6 Suport.\n- Potentially faster interval support \u003chttps://infosec.exchange/@singe@chaos.social/113057901149163673\u003e\n- Use names / id's to identify jumps. Right now, it's just a port map, but what if you want more than one service, on the same port but separate keys?\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonjza%2Fport-jump","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleonjza%2Fport-jump","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleonjza%2Fport-jump/lists"}