{"id":32532711,"url":"https://github.com/yosebyte/passport","last_synced_at":"2025-10-28T12:56:15.941Z","repository":{"id":261342475,"uuid":"884026573","full_name":"yosebyte/passport","owner":"yosebyte","description":"Powerful yet simple solution for network tunneling and port forwarding with access control all using 1-URL command.","archived":false,"fork":false,"pushed_at":"2025-04-05T00:21:19.000Z","size":1572,"stargazers_count":171,"open_issues_count":0,"forks_count":14,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-05T01:22:44.381Z","etag":null,"topics":["access-controls","forwarding","golang","networking","tunneling"],"latest_commit_sha":null,"homepage":"","language":"Go","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/yosebyte.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-11-06T02:10:01.000Z","updated_at":"2025-04-05T00:21:22.000Z","dependencies_parsed_at":null,"dependency_job_id":"1a7c36f5-369a-4327-bbf1-b2db5eabd540","html_url":"https://github.com/yosebyte/passport","commit_stats":null,"previous_names":["yosebyte/link","yosebyte/passport"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/yosebyte/passport","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yosebyte%2Fpassport","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yosebyte%2Fpassport/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yosebyte%2Fpassport/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yosebyte%2Fpassport/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yosebyte","download_url":"https://codeload.github.com/yosebyte/passport/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yosebyte%2Fpassport/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281441020,"owners_count":26501758,"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","status":"online","status_checked_at":"2025-10-28T02:00:06.022Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["access-controls","forwarding","golang","networking","tunneling"],"created_at":"2025-10-28T12:56:15.001Z","updated_at":"2025-10-28T12:56:15.934Z","avatar_url":"https://github.com/yosebyte.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Passport](https://img.shields.io/badge/Yosebyte-Passport-blue)\n![GitHub License](https://img.shields.io/github/license/yosebyte/passport)\n[![Go Report Card](https://goreportcard.com/badge/github.com/yosebyte/passport)](https://goreportcard.com/report/github.com/yosebyte/passport)\n[![Go Reference](https://pkg.go.dev/badge/github.com/yosebyte/passport.svg)](https://pkg.go.dev/github.com/yosebyte/passport)\n![GitHub Release](https://img.shields.io/github/v/release/yosebyte/passport)\n![GitHub last commit](https://img.shields.io/github/last-commit/yosebyte/passport)\n![GitHub commits since latest release](https://img.shields.io/github/commits-since/yosebyte/passport/latest)\n\n\u003e **Note**  \n\u003e The tunnel functionality of the `passport` project has been separated into a new project called [NodePass](https://github.com/yosebyte/nodepass), which focuses on secure and efficient TCP tunneling. The remaining port forwarding components in `passport` are currently being refactored.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://cdn.yobc.de/assets/passport.png\" alt=\"passport\"\u003e\n\u003c/div\u003e\n\n\u003ch4 align=\"center\"\u003e\"Access pass required to pass through port.\"\u003c/h4\u003e\n\n## Overview\n\n**Passport** is a powerful connection management tool that simplifies network tunneling, port forwarding and more. By seamlessly integrating three distinct running modes within a single binary file, Passport bridges the gap between different network environments, redirecting services and handling connections seamlessly, ensuring reliable network connectivity and ideal network environment. Also with highly integrated authorization handling, Passport empowers you to efficiently manage user permissions and establish uninterrupted data flow, ensuring that sensitive resources remain protected while applications maintain high performance and responsiveness.\n\n## Features\n\n- **Unified Operation**: Passport can function as a server, client, or broker, three roles from a single executable file.\n- **Authorization Handling**: By IP address handling, Passport ensures only authorized users gain access to sensitive resources.\n- **In-Memory Certificate**: Provides a self-signed HTTPS certificate with a one-year validity, stored entirely in memory.\n- **Network Tunneling**: Supports both TCP and/or UDP intranet penetration services with full-process TLS encryption processing.\n- **Port Forwarding**: Efficiently manage and redirect your TCP and/or UDP services from one port to entrypoints everywhere.\n- **Auto Reconnection**: Providing robust short-term reconnection capabilities, ensuring uninterrupted service.\n- **Zero Dependencies**: Fully self-contained, with no external dependencies, ensuring a simple and efficient setup.\n- **Zero Configuration File**: Simply execute with a single URL command, making it ideal for containerized environments.\n\n## Designs\n\n### Network Tunneling\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://cdn.yobc.de/assets/tunnel.png\" alt=\"tunnel\"\u003e\n\u003c/div\u003e\nTunneling establishes seamless access to otherwise unreachable resources. A user’s request is sent to the server, which forwards it through a pre-established TLS-encrypted channel to the client. The client then connects to the target service, creating two secure links: one to the server and another to the target. This enables data exchange between the client and the target, and subsequently between the server and the user. For concurrent user requests, multiple TLS-encrypted connections are established, supporting native high-concurrency performance. Notably, UDP tunneling leverages the same TLS-encrypted TCP channels between the server and client, ensuring security and eliminating latency caused by unsuccessful NAT traversal attempts.\n\n### Port Forwarding\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://cdn.yobc.de/assets/forward.png\" alt=\"forward\"\u003e\n\u003c/div\u003e\nForwarding simplifies the process by directly relaying user TCP/UDP requests to the target service via a broker. The broker establishes a connection with the target, exchanges data with the service, and returns responses to the user. While this mode supports high concurrency if the user-side supports multithreading, it does not employ TLS encryption. For secure usage, ensure the target service provides its own transmission security.\n\n### Access Control\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://cdn.yobc.de/assets/access.png\" alt=\"access\"\u003e\n\u003c/div\u003e\nThe authentication system employs a secure and dynamic IP whitelisting mechanism designed to manage access control effectively. Verified IP addresses are stored in memory for the duration of the server or broker's runtime, with all entries cleared upon server restart to ensure that no stale or unauthorized IPs remain active. This design prioritizes security by requiring reauthentication after a restart. When a user attempts to access a resource, their IP is checked against the whitelist. If the IP is present, access is granted seamlessly. If the user's IP has changed, or if the IP is not whitelisted, the system blocks access and redirects the user to an authentication URL. Successful authentication not only verifies the user's access but also updates the whitelist by temporarily storing the IP in memory and returning the current IP address to confirm the process. Unauthorized IPs remain blocked until proper authentication is completed. This approach combines real-time validation, adaptability to changing IPs, and enhanced security measures to provide a reliable access control solution.\n\n## Basic Usage\n\nYou can easily learn how to use it correctly by running passport directly without parameters.\n\n```\nUsage:\n    passport \u003ccore_mode\u003e://\u003clink_addr\u003e/\u003ctarg_addr\u003e#\u003cauth_mode\u003e\n\nExamples:\n    # Run as server\n    passport server://10.0.0.1:10101/:10022#http://:80/secret\n\n    # Run as client\n    passport client://10.0.0.1:10101/127.0.0.1:22\n\n    # Run as broker\n    passport broker://:8080/10.0.0.1:8080#https://:443/secret\n\nArguments:\n    \u003ccore_mode\u003e    Select from \"server\", \"client\" or \"broker\"\n    \u003clink_addr\u003e    Tunneling or forwarding address to connect\n    \u003ctarg_addr\u003e    Service address to be exposed or forwarded\n    \u003cauth_mode\u003e    Optional authorizing options in URL format\n```\n\n### Server Mode\n\n- `linkAddr`: The address for accepting client connections. For example, `:10101`.\n- `targetAddr`: The address for listening to external connections. For example, `:10022`.\n\n**Run as Server**\n\n```\n./passport server://:10101/:10022\n```\n\n- This command will listen for client connections on port `10101` , listen and forward data to port `10022`.\n\n**Run as Server with authorization**\n\n```\n./passport server://:10101/:10022#https://hostname:8443/server\n```\n\n- The server handles authorization at `https://hostname:8443/server`, on your visit and your IP logged.\n- The server will listen for client connections on port `10101` , listen and forward data to port `10022`.\n\n### Client Mode\n\n- `linkAddr`: The address of the server to connect to. For example, `server_ip:10101`.\n- `targetAddr`: The address of the target service to connect to. For example, `127.0.0.1:22`.\n\n**Run as Client**\n\n```\n./passport client://server_hostname_or_IP:10101/127.0.0.1:22\n```\n\n- This command will establish link with `server_hostname_or_IP:10101` , connect and forward data to `127.0.0.1:22`.\n\n### Broker Mode\n\n- `linkAddr`: The address for accepting client connections. For example, `:10101`.\n- `targetAddr`: The address of the target service to connect to. For example, `127.0.0.1:22`.\n\n**Run as Broker**\n\n```\n./passport broker://:10101/127.0.0.1:22\n```\n\n- This command will listen both `tcp` and `udp` on port `10101` , connect and forward data to `127.0.0.1:22`.\n\n**Run as Broker with authorization**\n\n```\n./passport broker://:10101/127.0.0.1:22#https://hostname:8443/broker\n```\n\n- The server handles authorization at `https://hostname:8443/broker`, on your visit and your IP logged.\n- This command will listen both `tcp` and `udp` on port `10101` , connect and forward data to `127.0.0.1:22`.\n\n## Container Usage\n\nYou can also run **Passport** using docker or podman. The image is available at [ghcr.io/yosebyte/passport](https://ghcr.io/yosebyte/passport).\n\nTo run the container in server mode with or without authorization:\n\n```\ndocker run -d --rm \\\n    ghcr.io/yosebyte/passport \\\n    server://:10101/:10022#https://hostname:8443/server\n```\n\n```\ndocker run -d --rm \\\n    ghcr.io/yosebyte/passport \\\n    server://:10101/:10022\n```\n\nTo run the container in client mode:\n\n```\ndocker run -d --rm \\\n    ghcr.io/yosebyte/passport \\\n    client://server_hostname_or_IP:10101/127.0.0.1:22\n```\n\nTo run the container in server mode with or without authorization:\n\n```\ndocker run -d --rm \\\n    ghcr.io/yosebyte/passport \\\n    broker://:10101/127.0.0.1:22#https://hostname:8443/broker\n```\n\n```\ndocker run -d --rm \\\n    ghcr.io/yosebyte/passport \\\n    broker://:10101/127.0.0.1:22\n```\n\n## License\n\nThis project is licensed under the [MIT](LICENSE) License.\n\n## Stargazers\n[![Stargazers over time](https://starchart.cc/yosebyte/passport.svg?variant=adaptive)](https://starchart.cc/yosebyte/passport)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyosebyte%2Fpassport","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyosebyte%2Fpassport","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyosebyte%2Fpassport/lists"}