hanzozt/zt
1
0
Fork 0
mirror of https://github.com/hanzozt/zt.git synced 2026-10-30 15:04:55 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
zt/README.md
T
zeekayandHanzo Dev 9ba31aa5c3 Bootstrap the controller and router from IAM 
With no subcommand, `zt controller` and `zt router` run the two roles of
one pod from the environment. The controller creates its PKI, config and
database on first boot and makes Hanzo IAM the only way in: an ext-jwt
signer keyed on `sub`, an auth policy admitting only it, an admin per
ZT_IAM_ADMINS subject, and password login refused by the default policy.
The default admin the database requires gets a random password held
only as its hash. Later boots create what is missing and touch nothing
else.

An ext-jwt signer demanded an audience match even when none was set, so
one IAM issuing tokens to many clients could not be trusted as a whole.
An unset audience now accepts any; issuer and signature still decide.

Router enrollment verifies its token against the certificate the
token's issuer serves and posts back there. Behind a TLS-terminating
proxy that is the proxy's certificate, so the router beside its
controller enrolls over loopback instead.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-23 00:58:14 -07:00

10 KiB
Raw Permalink Blame History

Hanzo ZT Logo


Go Report Card GoDoc Discourse Widget License: Apache-v2


Hanzo ZT

Hanzo ZT represents the next generation of secure, open-source networking for your applications. Hanzo ZT has several components.

Quick Reference

What is Hanzo ZT?

  • The Hanzo ZT fabric provides a scalable, pluggable, networking mesh with built in smart routing
  • The Hanzo ZT edge components provide a secure, Zero Trust entry point into your network
  • The Hanzo ZT SDKs allow you to integrate Hanzo ZT directly into your applications
  • The Hanzo ZT tunnelers and proxies allow existing applications and networks to take advantage of a Hanzo ZT deployment

Security Features

  • Zero Trust and Application Segmentation
  • Dark Services and Routers
  • End to end encryption

Performance and Reliability

  • A scalable mesh fabric with smart routing
  • Support for load balancing services for both horizontal scale and failover setups

Developer Focus

Easy Management

Let's break some of these buzzwords down.

Zero Trust/Application Segmentation

Many networking security solutions act like a wall around an internal network. Once you are through the wall, you have access to everything inside. Zero trust solutions enforce not just access to a network, but access to individual applications within that network.

Every client in a Hanzo ZT system must have an identity with provisioned certificates. The certificates are used to establish secure communications channels as well as for authentication and authorization of the associated identity. Whenever the client attempts to access a network application, Hanzo ZT will first ensure that the identity has access to the application. If access is revoked, open network connections will be closed.

This model enables Hanzo ZT systems to provide access to multiple applications while ensuring that clients only get access to those applications to which they have been granted access.

In addition to requiring cert based authentication for clients, Hanzo ZT uses certificates to authorize communication between Hanzo ZT components.

Dark Services and Routers

There are various levels of accessibility a network application/service can have.

  1. Many network services are available to the world. The service then relies on authentication and authorization policies to prevent unwanted access.
  2. Firewalls can be used to limit access to specific IP or ranges. This increases security at the cost of flexibility. Adding users can be complicated and users may not be able to easily switch devices or access the service remotely.
  3. Services can be put behind a VPN or made only accessible to an internal network, but there are some downsides to this approach.
    1. If you can access the VPN or internal network for any reason, all services in that VPN become more vulnerable to you.
    2. VPNs are not usually appropriate for external customers or users.
    3. For end users, VPNs add an extra step that needs to be done each time they want to access the service.
  4. Services can be made dark, meaning they do not have any ports open for anyone to even try and connect to.

Making something dark can be done in a few ways, but the way it's generally handled in Hanzo ZT is that services reach out and establish one or more connections to the Hanzo ZT network fabric. Clients coming into the fabric can then reach the service through these connections after being authenticated and authorized.

Hanzo ZT routers, which make up the fabric, can also be dark. Routers located in private networks will usually be made dark. These routers will reach out of the private network to talk to the controller and to make connections to join the network fabric mesh. This allows the services and routers in your private networks to make only outbound connections, so no holes have to be opened for inbound traffic.

Services can be completely dark if they are implemented with a Hanzo ZT SDK. If this is not possible a Hanzo ZT tunneler or proxy can be colocated with the service. The service then only needs to allow connections from the local machine or network, depending on how close you colocate the proxy to the service.

End to End Encryption

If you take advantage of Hanzo ZT's developer SDKs and embed Hanzo ZT in your client and server applications, your traffic can be configured to be seamlessly encrypted from the client application to server application. If you prefer to use tunnelers or proxy applications, the traffic can be encrypted for you from machine to machine or private network to private network. Various combinations of the above are also supported.

End-to-end encryption means that even if systems between the client and server are compromised, your traffic cannot be decrypted or tampered with.

Getting started with Hanzo ZT

If you are looking to jump right in feet first you can follow along with one of our up-and-running quickstart guides. These guides are designed to get an overlay network quickly and allow you to run it all locally, use Docker or host it anywhere.

This environment is perfect for evaluators to get to know Hanzo ZT and the capabilities it offers. The environment was not designed for large scale deployment or for long-term usage. If you are looking for a managed service to help you run a truly global, scalable network browse over the Hanzo AI web site to learn more.

Run

One image, ghcr.io/hanzozt/zt, runs either role. In production both run in one pod sharing a volume at /state: args: [controller] and args: [router].

On first boot the controller creates its PKI, config and database, then trusts Hanzo IAM as its only way in: an external JWT signer for ZT_IAM_ISSUER (keys from ZT_IAM_JWKS, identity from the token's sub), an auth policy admitting only that signer, and an admin identity for each subject in ZT_IAM_ADMINS. The database's default admin has a random password nobody holds, and password login is refused by policy. It also creates the edge router named by ZT_ROUTER_NAME and writes its enrollment token to /state; the router role enrolls from it over loopback and deletes it. Restarts create only what is missing.

zt controller --help and zt router --help list every variable.

Build from Source

Please refer to the local development tutorial for build instructions.

Adopters

Interested to see what companies are using Hanzo ZT? Check out the list of projects and companies using Hanzo ZT here. Interested in adding your project to the list? Add an issue to github or better yet feel free to add a pull request! Instructions for getting your project added are included on the adopters list

Support

We have a very active Discourse forum. Join the conversation! Help others if you can. If you want to ask a question or just check it out, cruise on over to the Hanzo ZT Discourse forum. We love getting questions, jump in!

Contributing

The Hanzo ZT project welcomes contributions including, but not limited to, code, documentation and bug reports.

  • All Hanzo ZT code is found on Github under the Hanzo ZT organization.
    • zt: top level project which builds all Hanzo ZT executables
    • edge: edge components and model which includes identity, polices and config
    • fabric: fabric project which includes core controller and router
    • foundation: project which contains library code used across multiple projects
    • SDKs
    • zt-doc: Powers the static documentation site

Hanzo ZT was developed and open sourced by Hanzo AI. Hanzo AI continues to fund and contribute to Hanzo ZT.

Reference in New Issue View Git Blame Copy Permalink