boundary

module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2021 License: MPL-2.0

README

Boundary

CircleCI

Please note: We take Boundary's security and our users' trust very seriously. If you believe you have found a security issue in Boundary, please responsibly disclose by contacting us at security@hashicorp.com.


Boundary provides simple and secure access to hosts and services.

Traditional approaches like SSH bastion hosts or VPNs require distributing and managing credentials, configuring network controls like firewalls, and exposing the private network. Boundary provides a secure way to access hosts and critical systems without having to manage credentials or expose your network, and is entirely open source.

Boundary is designed to be straightforward to understand, highly scalable, and resilient. It can run in clouds, on-prem, secure enclaves and more, and does not require an agent to be installed on every end host.

Unlike firewalls, Boundary performs per-access authentication and authorization checks, allowing for much higher level mappings of users to services or hosts than at network layers. Although complementary to secrets managers (like HashiCorp's own Vault), Boundary fills a different niche, allowing the credential that is eventually used to be hidden entirely from the user.

Getting Started

Boundary consists of two server components: Controllers, which serve the API and coordinate session requests; and Workers, which perform the actual session handling. A normal Boundary installation will consist of one or more Controllers paired with one or more Workers. A single Boundary binary can act in either of these two modes.

Additionally, Boundary provides a client that provides access to request and connect to authorized sessions.

Boundary does not require software to be installed on the endpoint hosts and services.

Requirements

Boundary has two external dependencies: a SQL database, and one or more KMSes. Both are readily available from cloud vendors, but can be satisfied by on-premises technologies as well.

  • The database contains Boundary's configuration and session information and must be accessible by Controller nodes. Values that are secrets (such as credentials) are encrypted in the database. Currently, PostgreSQL is supported as a database and has been tested with Postgres 11 and above. Boundary uses only common extensions and both hosted and self-run instances are supported. In most instances all that is needed is a database endpoint and appropriate credentials.

  • Any cloud KMS or Vault's Transit Secrets Engine can be used to satisfy the KMS requirement. Currently, two keys within the KMS are required: one for authenticating other cluster components, which must be accessible by both Controllers and Workers; and one for encrypting secret values in the database, which need only be accessible to Controllers. These keys can be changed over time (so long as the original key remains available for any decryption needs), and key derivation is used extensively to avoid key sprawl of these high-value keys. If available, other keys can be used for other purposes, such as recovery functionality and encryption of sensitive values in Boundary's config file.

Boundary has a dev mode that can be used for testing. In this mode both a Controller and Worker are started with a single command, and they have the following properties:

  • The Controller will start a PostgreSQL Docker container to use as storage. This container will be shut down and removed (if possible) when the Controller is (gracefully) shut down.
  • The Controller will use an internal KMS with ephemeral keys

Trying out Boundary

Running Boundary in a more permanent context requires a few more steps, such as writing some simple configuration files to tell the nodes how to reach their database and KMS. The steps below, along with the extra information needed for permanent installations, are detailed in our Installation Guide.

Build and Start Boundary in Dev Mode

If you have the following requirements met locally:

You can get up and running with Boundary quickly. Simply run:

make dev

This will build Boundary. (The first time this is run it will fetch and compile UI assets; which will take a few extra minutes.) Once complete, run Boundary in dev mode:

$GOPATH/bin/boundary dev

Please note that development may require other tools; to install the set of tools at the versions used by the Boundary team, run:

make tools

Without doing so, you may encounter errors while running make dev. It is important to also note that using make tools will install various tools used for Boundary development to the normal Go binary directory; this may overwrite or take precedence over tools that might already be installed on the system.

Specify a UI Commitish at Build Time

By default the UI will be built from a preselected commit ID from the UI repo. A different commitish from which to build UI assets may be specified via the UI_COMMITISH environment variable. For example:

UI_COMMITISH=feature-branch make build-ui

will update your local UI assets.

UI Build Troubleshooting

UI assets are built within a Docker container. If you encounter issues with this build step, trying increasing memory and swap available to Docker.

UI Development

It would be impractical to rebuild the binary on every change when actively developing the UI. To make UI development more convenient, the binary supports a passthrough directory. This is an arbitrary local directory from which UI assets are served. Note this option is only available in dev mode. For example:

BOUNDARY_DEV_UI_PASSTHROUGH_DIR=/boundary-ui/ui/admin/dist ~/go/bin/boundary dev

Download and Run from Release Page

Download the latest release of the server binary and appropriate desktop client(s) from our releases page

Start Boundary

Start the server binary with:

boundary dev

This will start a Controller service listening on http://127.0.0.1:9200 for incoming API requests and a Worker service listening on http://127.0.0.1:9202 for incoming session requests. It will also create various default resources and display various useful pieces of information, such as a login name and password that can be used to authenticate.

Configuring Resources

For a simple test of Boundary in dev mode you don't generally need to configure any resources at all! But it's useful to understand what dev mode did for you so you can then take further steps. By default, dev mode will create:

  • The global Scope for initial authentication, containing a Password-type Auth Method, along with an Account for login.
  • An organization Scope under global, and a project Scope inside the organization.
  • A Host Catalog with a default Host Set, which itself contains a Host with the address of the local machine (127.0.0.1)
  • A Target mapping the Host Set to a set of connection parameters, with a default port of 22 (e.g. SSH)

You can of course go into Boundary's web UI or use its API to change these default values, for instance if you want to connect to a different host or need to modify the port on which to to connect.

Making the Connection

Next, let's actually make a connection to your local SSH daemon via Boundary:

  1. Authenticate to Boundary; using default dev values, this would be boundary authenticate password -auth-method-id ampw_1234567890 -login-name admin -password password. (Note that if you do not include the password flag you will be prompted for it.)
  2. Run boundary connect ssh -target-id ttcp_1234567890. If you want to adjust the username, pass -username <name> to the command.

A lot more is possible with Boundary, even at this early stage. Check out the possibilities for target configuration to test out limiting (or increasing) the number of connections per session or setting a maximum time limit; try canceling an active session from the sessions page or via boundary sessions, make your own commands with boundary connect -exec, and so on.

Going Further

This example is a simple way to get started but omits several key steps that could be taken in a production context:

  • Using a firewall or other means to restrict the set of hosts allowed to connect to a local service to only Boundary Worker nodes, thereby making Boundary the only means of ingress to a host
  • Using the Boundary Terraform provider to easily integrate Boundary with your existing code-based infrastructure
  • Pointing a BI tool (PowerBI, Tableau, etc.) at Boundary's session warehouse to generate insights and look for anomalies with respect to session access

There are many, many more things that Boundary will do in the future in terms of integrations, features, and more. We have a long roadmap planned out, so stay tuned for information about new features and capabilities!

Contributing

Thank you for your interest in contributing! Please refer to CONTRIBUTING.md for guidance.

Directories

Path Synopsis
api module
cmd
internal
authtoken
Package authtoken provides an authtoken with an encrypted value and an associated expiration time.
Package authtoken provides an authtoken with an encrypted value and an associated expiration time.
boundary
Package boundary contains global interfaces and other definitions that define the Boundary domain.
Package boundary contains global interfaces and other definitions that define the Boundary domain.
cmd
cmd/commands/accountscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/authmethodscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/authtokenscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/credentiallibrariescmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/credentialstorescmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/groupscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/hostcatalogscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/hostscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/hostsetscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/managedgroupscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/rolescmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/scopescmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/sessionscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/targetscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
cmd/commands/userscmd
Code generated by "make cli"; DO NOT EDIT.
Code generated by "make cli"; DO NOT EDIT.
credential
Package credential defines interfaces shared by other packages that manage credentials for Boundary sessions.
Package credential defines interfaces shared by other packages that manage credentials for Boundary sessions.
credential/vault
Package vault provides access to credentials retrieved from a Vault server.
Package vault provides access to credentials retrieved from a Vault server.
db
db/assert
Package dbassert provides a set of assertions for testing the boundary database applications.
Package dbassert provides a set of assertions for testing the boundary database applications.
db/common
common package contains functions from internal/db which need to be shared commonly with other packages that have a cyclic dependency on internal/db like internal/oplog.
common package contains functions from internal/db which need to be shared commonly with other packages that have a cyclic dependency on internal/db like internal/oplog.
db/db_test
Package db_test provides some helper funcs for testing db integrations
Package db_test provides some helper funcs for testing db integrations
db/sanitize
Package sanitize contains a set of functions that sanitizes input received from external systems before being persisted in the database.
Package sanitize contains a set of functions that sanitizes input received from external systems before being persisted in the database.
db/schema
Package schema is used to apply sql migrations to modify the state of a database instance.
Package schema is used to apply sql migrations to modify the state of a database instance.
db/schema/internal/edition
Package edition provides internal structs for the schema package for defining and organizing database migration editions.
Package edition provides internal structs for the schema package for defining and organizing database migration editions.
db/schema/internal/log
Package log provides internal structs and options for the schema package for tracking logs generated when applying migrations.
Package log provides internal structs and options for the schema package for tracking logs generated when applying migrations.
db/schema/internal/postgres
Package postgres provides an implementation of the schema.driver interface for a PostgreSQL database.
Package postgres provides an implementation of the schema.driver interface for a PostgreSQL database.
db/schema/internal/provider
Package provider provides an iterator for iterating over all of the migration statements that need to be applied.
Package provider provides an iterator for iterating over all of the migration statements that need to be applied.
db/schema/migrations
Package migrations contains the base sql statements needed to bootstrap the migration process.
Package migrations contains the base sql statements needed to bootstrap the migration process.
db/schema/migrations/oss
Package oss is used to embed the sql statements for the oss edition and registering the edition for the schema.Manager.
Package oss is used to embed the sql statements for the oss edition and registering the edition for the schema.Manager.
db/sentinel
Package sentinel allows for the use of Unicode non-characters to distinguish between Boundary defined sentinels and values provided by external systems.
Package sentinel allows for the use of Unicode non-characters to distinguish between Boundary defined sentinels and values provided by external systems.
gen/controller/api/services
Package services is a reverse proxy.
Package services is a reverse proxy.
gen/testing/event
Package event is a reverse proxy.
Package event is a reverse proxy.
host/plugin
Package plugin provides a plugin host catalog, and plugin host set resource which are used to interact with a host plugin as well as a repository to perform CRUDL and custom actions on these resource types.
Package plugin provides a plugin host catalog, and plugin host set resource which are used to interact with a host plugin as well as a repository to perform CRUDL and custom actions on these resource types.
host/static
Package static provides a host, a host catalog, and a host set suitable for hosts with a static address.
Package static provides a host, a host catalog, and a host set suitable for hosts with a static address.
iam
iam package is for identity access management of boundary.
iam package is for identity access management of boundary.
kms
oplog
oplog is a package for writing operational log (oplog) entries for the purpose of replication and verification of the data stored in the Boundary RDBMS.
oplog is a package for writing operational log (oplog) entries for the purpose of replication and verification of the data stored in the Boundary RDBMS.
oplog/oplog_test
Package oplog_test provides some gorm helper funcs for testing oplog database integrations
Package oplog_test provides some gorm helper funcs for testing oplog database integrations
oplog/store
Package store provides storage types/behavior for the oplog
Package store provides storage types/behavior for the oplog
perms
Package perms provides the boundary permissions engine using grants which are tied to IAM Roles within a Scope.
Package perms provides the boundary permissions engine using grants which are tied to IAM Roles within a Scope.
plugin
Package plugin contains other packages related to the different plugin types and any helpers related to working with non type specific plugins.
Package plugin contains other packages related to the different plugin types and any helpers related to working with non type specific plugins.
plugin/host
Package host provides a plugin type used to interface with boundary's host related resources.
Package host provides a plugin type used to interface with boundary's host related resources.
scheduler
Package scheduler allows callers to register recurring jobs on the controller.
Package scheduler allows callers to register recurring jobs on the controller.
scheduler/job
Package job provides a Job and a Run struct suitable for persisting to the repository.
Package job provides a Job and a Run struct suitable for persisting to the repository.
servers/controller/common
Package common contains types and helper functions that are used across the different packages under internal/server/controller.
Package common contains types and helper functions that are used across the different packages under internal/server/controller.
servers/worker/common
Package common contains types and helper functions that are used across the different packages under internal/server/worker.
Package common contains types and helper functions that are used across the different packages under internal/server/worker.
servers/worker/proxy
Package proxy contains a collection of proxy handlers for the worker to call once a connection has been authorized.
Package proxy contains a collection of proxy handlers for the worker to call once a connection has been authorized.
target/targettest
Package targettest provides a test target subtype for use by the target package.
Package targettest provides a test target subtype for use by the target package.
target/tcp
Package tcp provides a Target subtype for a TCP Target.
Package tcp provides a Target subtype for a TCP Target.
types/subtypes
Package subtypes provides helpers to work with boundary resource subtypes.
Package subtypes provides helpers to work with boundary resource subtypes.
ui
plugins module
sdk module
testing
controller
Package controller is a package meant for internal testing only.
Package controller is a package meant for internal testing only.
dbtest
Package dbtest provides a way to create a clean database for tests using template databases.
Package dbtest provides a way to create a clean database for tests using template databases.
vault
Package vault is a package meant for internal testing only.
Package vault is a package meant for internal testing only.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL