<h1 align="center">Basti</h1> <div align="center"> <a href="https://www.npmjs.com/package/basti"> <img alt="NPM Package" src="https://img.shields.io/npm/v/basti?color=blue"> </a> <a href="https://www.npmjs.com/package/basti"> <img alt="NPM" src="https://img.shields.io/npm/dt/basti"> </a> <a href="https://github.com/basti-app/basti/blob/main/LICENSE"> <img alt="GitHub" src="https://img.shields.io/github/license/basti-app/basti"> </a> </div> <br/> <div align="center"> <a href="https://github.com/basti-app/basti">Basti</a> <em>(from <a href="https://en.wikipedia.org/wiki/Bastion_host"><strong>Basti</strong>on Host</a>)</em> is a CLI tool for securely accessing your DB instances and other AWS resources in private networks at almost no cost. <br/> <br/> 💵 <em>No idle costs.</em> 🔑 <em>No SSH keys.</em> 🔒 <em>Fully IAM-driven.</em> </div> <br/> <div align="center"> <img alt="Demo" src="https://user-images.githubusercontent.com/45905756/211385579-3ac54ad5-7c90-4b68-9b22-239f4b26ad61.gif"> </div> <br/>

💡 Why Basti?
⚙️ How it works
💻 Installation
🏄 Basic usage
🧶 Reference documentation
💠 Custom connection targets
🎛️ Advanced initialization options
🦾 Automatic mode
📝 Configuration file
💫 Infrastructure as code (IaC)
🏢 Basti in teams and organizations
🔐 Security
❤️ Development
- Build
- Run
- Test
License

<br/>

💡 Why Basti?

With Basti, you can securely connect to RDS, Aurora, Elasticache, or any other AWS resources in private VPC subnets from a local machine or a CI/CD pipeline almost for free!

AWS Session Manager is a fantastic tool! But Basti makes it even better:

🦾 With Session Manager, you need to oversee an EC2 bastion instance for connecting to managed resources such as RDS or Elasticache. Basti handles bastion instance setup, shutdown, and updates for you!
💅 Basti provides a convenient way to store and reuse connection configuration across your team.
📶 Basti improves stability of the Session Manager sessions by automatically restarting failed or expired sessions.

⚙️ How it works

🏰 Basti sets up a so called bastion EC2 instance in the connection target's VPC.
🧑‍💻 The bastion instance is used with AWS Session Manager port forwarding capability to make the target available on your localhost.
💵 Basti takes care of keeping the bastion instance stopped when it's not used to make the solution cost as low as ≈ 0.01 USD per hour of connection plus ≈ 0.80 USD per month of maintaining the instance in a stopped state.
🔒 Security completely relies on AWS Session Manager and IAM policies. The bastion instance is not accessible from the Internet and no SSH keys are used.

💻 Installation

Using homebrew

brew install basti

Using npm

npm install --global basti

Other, NodeJS-independent, installation options are coming soon!

🏄 Basic usage

Basti uses AWS SDK and relies on credentials to be configured in your system. You can use any of the methods supported by AWS SDK to configure credentials.

💡 You can expect Basti to work if you can use AWS CLI in your terminal.

☝️ Initialize connection target

First, initialize your connection target. It could be an RDS instance, an Elasticache cluster or any other target residing in a VPC. The following command will set up all the infrastructure required to start a connection. You only need to do this once.

basti init

You will be prompted for a target to initialize and a public VPC subnet to create the bastion EC2 instance in.

✌️ Connect to the target

Now, you can start the connection. This command will establish a secure port forwarding session and make the target available on your localhost.

basti connect

You will be prompted for the target to connect to as well as the local port to forward the connection to.

🎉 Use the target on localhost

Finally, you can use the target same way as it was running on your localhost and port you specified in the previous step.

psql -h localhost -p 5432

💡 psql, the PostgreSQL client, is used as an example here. Basti can be used to connect to any type of database or other services as long as the communication is done over TCP.

Cleanup (optional)

You can remove all the resources created by Basti in you AWS account.

basti cleanup

The list of resources will be displayed and you will be prompted to confirm the cleanup.

🧶 Reference documentation

Please, refer to the reference documentation for the full description of Basti CLI options and the configuration file.

💠 Custom connection targets

Basti provides first class support for RDS instances, Aurora clusters, and Elasticache clusters. However, you can use Basti to connect to any other target in your AWS VPC (e.g. DocumentDB instance, EC2 instance, etc.).

To connect to a custom target, select the Custom option when prompted for a target to initialize or connect to. You will be prompted for the target's VPC, IP address and port.

🤝 Feel free to open an issue or a pull request if you want to extend the list of natively supported targets

🎛️ Advanced initialization options

The basti init command has a number of advanced options that can be used to customize the bastion instance and other resources created by Basti.

💡 Please, refer to the reference documentation for the full list of options.

Resource tags

You can specify tags to be applied to the bastion instance and other resources created by Basti. This can be done in three ways:

By entering the tags in the advanced options section of the interactive mode.
By passing the --tag option. This option accepts tag name and value separated by an equal sign. For example, --tag Project=my-project This option can be used multiple times to specify multiple tags.
By passing the --tags-file option. This option accepts a path to a JSON file with tags. The option can be used multiple times to specify multiple files.

Example of a tags file:

{
  "Project": "my-project",
  "Environment": "production"
}

Tags with the same name will be overwritten in the order they are specified. Tags specified with the --tag option will always overwrite tags specified in the tags file.

💡 If your tags contain special characters, it might be easier to use interactive mode or the --tags-file command than escaping the characters in the --tag option.

Bastion instance type

You can specify the EC2 instance type to be used for the bastion instance using the --bastion-instance-type option or by entering it in the advanced options section of the interactive mode. The default instance type is t2.micro, but it's subject to change in the future.

Assign public IP address

By default, the bastion instance is created with a public IP address to enable seamless outbound-only connection to AWS services from a public VPC subnet. Please, refer to the AWS documentation for more details on the Session Manager requirements.

You can disable the public IP address using the --bastion-assign-public-ip false option or in the advanced options section of the interactive mode.

☝️ When the public IP address is disabled, you will need to manually ensure that the AWS Session Manager connectivity requirements are met. This can be done with the help of VPC endpoints, NAT gateways, or other means.

💡 Disabling public IP address can be useful when setting up the bastion instance in a private subnet.

🦾 Automatic mode

Using interactive mode is convenient when you're getting used to Basti. However, in Continuous Integration and Continuous Delivery (CI/CD) pipelines, you will probably want to disable interactivity and pass all the options as command line arguments:

basti connect --rds-instance your-instance-id --local-port your-port

Use basti <command> --help to see all the available options for basti connect and other commands.

To continue executing the script after the connection is established, you can use Basti in conjunction with the [wait-

Basti

Install / Use

README

Table of contents