{"id":13510422,"url":"https://github.com/gawen/WireHub","last_synced_at":"2025-03-30T15:31:28.856Z","repository":{"id":144742856,"uuid":"162724674","full_name":"gawen/WireHub","owner":"gawen","description":"🌍 Decentralized, peer-to-peer and secure overlay networks","archived":true,"fork":false,"pushed_at":"2019-07-02T08:12:34.000Z","size":243,"stargazers_count":501,"open_issues_count":9,"forks_count":32,"subscribers_count":34,"default_branch":"master","last_synced_at":"2025-03-24T12:18:11.791Z","etag":null,"topics":["decentralized","dht","peer-to-peer","vpn","wireguard"],"latest_commit_sha":null,"homepage":"","language":"Lua","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/gawen.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}},"created_at":"2018-12-21T14:41:36.000Z","updated_at":"2025-02-08T11:36:57.000Z","dependencies_parsed_at":null,"dependency_job_id":"77647b71-a3fc-466a-b5cf-bffcc4c28c60","html_url":"https://github.com/gawen/WireHub","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gawen%2FWireHub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gawen%2FWireHub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gawen%2FWireHub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gawen%2FWireHub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gawen","download_url":"https://codeload.github.com/gawen/WireHub/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246339003,"owners_count":20761473,"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":["decentralized","dht","peer-to-peer","vpn","wireguard"],"created_at":"2024-08-01T02:01:38.350Z","updated_at":"2025-03-30T15:31:23.847Z","avatar_url":"https://github.com/gawen.png","language":"Lua","funding_links":[],"categories":["Lua","vpn"],"sub_categories":[],"readme":"# WireHub\n\nWireHub (in a shell, *wh*) builds decentralized, peer-to-peer and secure overlay\nnetworks. It is small (\u003c10KLOC) and tends to be simple-to-use and easily\nextendable.\n\nIt is built upon [WireGuard tunnels][wireguard] and provides distributed peer\ndiscovery \u0026 routing capabilities, NAT trasversal, extendable name resolving, ...\n\n⚠️ **Not ready for production!** This is still a work-in-progress. It still\nrequires some work to be clean and secure. The current code is provided for\ntesting only.\n\n## Features\n\n- **Single file network description**: a configuration of a network is a list\n  of the public key, private IPs and hostnames for each node.\n\n- **Decentralized peer discovery**: WireHub peers form a authentified [Kademilia\n  DHT][kademilia] network, which is the by-default discovery mechanism to find\n  new peers. [Sybil attack][sybil] is mitigated with a configurable\n  Proof-of-Work parameter (see `workbits`);\n\n- **Peer-to-peer and relayed communication**: WireHub goes through NATs, using\n  [UPnP IGD][igd] to map new ports on compatible routers, or using [UDP Hole\n  Punching][udp-hole-punching] techniques. If a P2P communication cannot be\n  established, network traffic is relayed through the DHT.\n\n## Getting started\n\n### Quickstart with Docker\n\nRun a minimal environment with WireHub installed.\n\n```bash\ndocker run -it --cap-add NET_ADMIN wirehub/wh /bin/sh\n```\n\nRun a testing environment with auto-completion enabled, testing scripts and\ndebug tools installed, ...\n\n```bash\ndocker run -it --cap-add NET_ADMIN wirehub/sandbox /bin/bash\n```\n\nIf you want to compile the Docker images from source,\n\n```bash\ngit clone --recursive https://github.com/gawen/wirehub\ncd wirehub\nmake docker docker-sandbox\n```\n\n### A simple network with two nodes\n\nFirst, generate two keys, one for each node.\n\n```bash\n$ wh genkey | tee node_a.sk | wh pubkey | tee node_a.k\nzW-1lBeQ7IkT6NW6hL_NsV4eOPOwJi_rt1vO-omOEmQ\n$ wh genkey | tee node_b.sk | wh pubkey | tee node_b.k\ng878Bf9ZDc4IzFSUhWFTO1VYFVmHD5XfvEsVn83Dsho\n```\n\nThe private keys are stored in the `.sk` files. The public keys are stored in\nthe `.k` files.\n\nGenerate a WireHub configuration\n\n```bash\necho \"name tutorial\nsubnet 10.0.42.0/24\n\nboot P17zMwXJFbBdJEn05RFIMADw9TX5_m2xgf31OgNKX3w bootstrap.wirehub.io\ntrust node_a `cat node_a.k`\ntrust node_b `cat node_b.k`\" \u003e config\n```\n\nFile `config` should be like this:\n\n```\nname tutorial           # name of network\nsubnet 10.0.42.0/24     # private subnetwork\n\n# one DHT bootstrap node\nboot P17zMwXJFbBdJEn05RFIMADw9TX5_m2xgf31OgNKX3w bootstrap.wirehub.io\n\n# two nodes, node_a \u0026 node_b\ntrust node_a zW-1lBeQ7IkT6NW6hL_NsV4eOPOwJi_rt1vO-omOEmQ\ntrust node_b g878Bf9ZDc4IzFSUhWFTO1VYFVmHD5XfvEsVn83Dsho\n```\n\nTo start the network, run on `node_a` ...\n\n```bash\nwh up ./config private-key ./node_a.sk\n```\n\n... and on `node_b` ...\n\n```bash\nwh up ./config private-key ./node_b.sk\n```\n\nAfter some time, each node should be able to ping themselves.\n\n```\n# ping node_b\nPING 10.0.42.3 (10.0.42.3): 56 data bytes\n64 bytes from 10.0.42.2: seq=0 ttl=64 time=106.801 ms\n64 bytes from 10.0.42.2: seq=1 ttl=64 time=49.778 ms\n\n```\n\nYou can check the overlay network status\n\n```\n# wh\ninterface wh-zW-1lBeQ7, network tutorial, node node_a \u003cNAT\u003e\n  public key: zW-1lBeQ7IkT6NW6hL_NsV4eOPOwJi_rt1vO-omOEmQ\n\n  peers\n     node_b\n\n```\n\nWhile the daemon is running, you can modify the network configuration and reload\nit.\n\n```\n# echo \"trust node_c 9OtorxsAqPqZkJ-fAYNRAPr9piMWKMLnGqOVVpMUvXY\" \u003e\u003e ./config\n# wh reload wh-zW-1lBeQ7\n```\n\nYou may stop the WireHub node as so:\n\n```bash\nwh down wh-zW-1lBeQ7\n```\n\nAdvise: use auto-completion to avoid writing wirehub interface, peer's keys or\nother arguments. For example,\n\n```\n# wh do\u003cTAB\u003e\n  wh down \u003cTAB\u003e\n  wh down wh-zW-1lBeQ7\n```\n\n### A use-case with WireHub: zero-netcat\n\n[![demo](https://asciinema.org/a/217931.svg)](https://asciinema.org/a/217931?autoplay=1)\n\nZero Netcat, or `0nc`, is a modified version of [Netcat][netcat] which runs over\nWireHub. It has the nice property to be secure, peer-to-peer and agnostic of the\nnetwork topology.\n\nOn one node, run the WireHub sandbox.\n\n```\n$ docker run -it --cap-add NET_ADMIN wirehub/sandbox /bin/bash\n```\n\nRun `0nc`.\n\n```\nnode_a # 0nc.lua\nznc invitation: ncuJonSJOS1DlFtb3HdgDJczPilrs0oPR9pwRpa_7WXwO0z-xioe_g9cdcMZkpV2b5lN7j3eLILjplBffvjdcw\n```\n\nCopy the znc invitation. Run another WireHub sandbox, call `0nc` with the\ninvitation as argument.\n\n```\nnode_b # 0nc.lua ncuJonSJOS1DlFtb3HdgDJczPilrs0oPR9pwRpa_7WXwO0z-xioe_g9cdcMZkpV2b5lN7j3eLILjplBffvjdcw\n```\n\n`STDIN` of `node_a` is now pipe-d into `STDOUT` of `node_b`, and vice-versa.\n\n### Start a public node\n\nThe minimal configuration for a node is something like this,\n\n```\nname public\nworkbit 8\nboot P17zMwXJFbBdJEn05RFIMADw9TX5_m2xgf31OgNKX3w bootstrap.wirehub.io\n```\n\nOnly a bootstrap node is listed, but no trusted nodes. A node with this\nconfiguration will join the WireHub DHT and only provide support for discovery\npeers and relaying data (which is a good thing for the DHT's health).\n\nStart a public node,\n\n```bash\ncurl https://raw.githubusercontent.com/gawen/wirehub/master/config/public \u003e ./config\nwh up ./config\n```\n\nCheck the neighbour peers in the DHT,\n\n```\n# wh show wh-gOVQwCSUxK all\ninterface wh-gOVQwCSUxK, network public, node \u003c\u003e\n  public key: gOVQwCSUxKUhUrkUSF0aDvssDfWVrrnm47ZMp5GJtDg\n\n  peers\n  ◒  BB_O_4Qxzw: 1.2.3.4:55329 (bucket:1)\n  ◒  C4mfi1ltU9: 1.2.3.4:46276 (bucket:1)\n  ◒  Dng_TaMHei: 1.2.3.4:6465 (bucket:1)\n  ◒  GjIX1RdmDj: 1.2.3.4:53850 (bucket:1)\n  ◒  G9qk6znNL5: 1.2.3.4:4523 (bucket:1)\n  ◒  J_RXehMJiw: 1.2.3.4:13962 (bucket:1)\n  ◒  PgjYqFfsyS: 1.2.3.4:39582 (bucket:1)\n  ●  P17zMwXJFb: 51.15.227.165:62096 (bucket:1)\n  [...]\n```\n\n## Dependencies\n\n- [Libpcap][libpcap]\n- [Libsodium][libsodium]\n- [Lua][lua]\n- [miniupnpc][miniupnpc]\n- [WireGuard][wireguard]\n- optionally, [Docker][docker]\n\n## Requirements\n\n- Linux or Docker\n- WireGuard\n\n## Current limitations\n\n- **Untrusted cryptography**: even if WireHub basics cryptographic routines are\n  based on the trusted [Libsodium][libsodium], the WireHub cryptographic\n  architecture has not been audited yet. If you're interested to contribute on\n  this part, help is very welcome!\n\n- **Automatic testing**: a lot of work needs to be done to make real automatic\n  testing possible with WireHub. Current efforts are on branch\n  [`dev-testbed`](https://github.com/Gawen/WireHub/tree/develop-testbed) and\n  [`micronet`][micronet].\n\n- **Still panic**: still quite rough to use. Do not expect the daemon to be stable;\n\n- **Poor documentation**: WireHub was a side project and still lacks\n  documentation.\n\n- **For a relayed peer, only one relay is used**: the traffic is not distributed\n  yet between several relays, which makes a single point of failure of WireHub\n  relay mechanisms;\n\n- **Only IPv4 private addresses**: implemeting IPv6 private addresses requires\n  some additional work;\n\n- and related to WireGuard, which is still under active development.\n\n## Future\n\n- **Zero-configuration IP6 networking** with IPv6 [ORCHID][orchid] addresses, to\n  automatically allocate each peer a default private IP (see `wh orchid`);\n\n## Overall source code architecture\n\nWireHub's source code is stored in `src/`. `wh.lua` is the main Lua module to\nimport WireHub's engine.\n\nThe source code of the CLI tool `wh` is stored in `src/tools/`. Its entry point is `src/tools/cli.lua`.\n\nThe core of WireHub is written in C and stored in `src/core/`. It is a native\nLua module called `whcore`, defined in `src/core/whcorelib.c`.\n\nPlease refer to the documentation in each files for more info.\n\n[curve25519]: https://cr.yp.to/ecdh.html\n[docker]: https://www.docker.com/\n[igd]: https://en.wikipedia.org/wiki/Internet_Gateway_Device_Protocol\n[kademilia]: https://en.wikipedia.org/wiki/Kademlia\n[libpcap]: https://www.tcpdump.org/\n[libsodium]: https://download.libsodium.org/doc/\n[lua]: https://www.lua.org/\n[micronet]: https://github.com/Gawen/WireHub/tree/develop-testbed/contrib/micronet\n[miniupnpc]: http://miniupnp.free.fr/\n[netcat]: https://en.wikipedia.org/wiki/Netcat\n[orchid]: https://datatracker.ietf.org/doc/rfc7343/\n[pow]: https://en.wikipedia.org/wiki/Proof-of-work_system\n[sybil]: https://en.wikipedia.org/wiki/Sybil_attack\n[udp-hole-punching]: https://en.wikipedia.org/wiki/UDP_hole_punching\n[wireguard]: https://www.wireguard.com/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgawen%2FWireHub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgawen%2FWireHub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgawen%2FWireHub/lists"}