Skip to content

Commit

Permalink
Migrate readme yaml (#20)
Browse files Browse the repository at this point in the history 
* Migrate to README.yaml format
  • Loading branch information
@vadim-hleif
vadim-hleif authored Jul 6, 2018
1 parent 3ab66fb commit eb62ae3
Show file tree
Hide file tree
Showing 3 changed files with 325 additions and 62 deletions.
3 changes: 3 additions & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1,5 @@
build-harness/
Makefile.build-harness

.idea
*.iml
187 changes: 125 additions & 62 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,13 @@
# Secure Bastion with MFA [![Build Status](https://travis-ci.org/cloudposse/bastion.svg)](https://travis-ci.org/cloudposse/bastion)
<!-- This file was automatically generated by the `build-harness`. Make all changes to `README.yaml` and run `make readme` to rebuild this file. -->

This is a secure/locked-down bastion implemented as a Docker Container. It uses Alpine Linux as the base image and ships with support for Google Authenticator & DUO MFA support.
[![Cloud Posse](https://cloudposse.com/logo-300x69.png)](https://cloudposse.com)

It was designed to be used on Kubernetes together with [GitHub Authorized Keys](https://github.com/cloudposse/github-authorized-keys) to provide secure remote access to production clusters.
# bastion [![Build Status](https://travis-ci.org/cloudposse/bastion.svg?branch=master)](https://travis-ci.org/cloudposse/bastion-cloudtrail) [![Latest Release](https://img.shields.io/github/release/cloudposse/bastion.svg)](https://travis-ci.org/cloudposse/bastion-cloudtrail/releases) [![Slack Community](https://slack.cloudposse.com/badge.svg)](https://slack.cloudposse.com)

[![Docker Stars](https://img.shields.io/docker/stars/cloudposse/bastion.svg)](https://hub.docker.com/r/cloudposse/bastion)
[![Docker Pulls](https://img.shields.io/docker/pulls/cloudposse/bastion.svg)](https://hub.docker.com/r/cloudposse/bastion)
[![GitHub Stars](https://img.shields.io/github/stars/cloudposse/bastion.svg)](https://github.com/cloudposse/bastion/stargazers)
[![GitHub Issues](https://img.shields.io/github/issues/cloudposse/bastion.svg)](https://github.com/cloudposse/bastion/issues)
[![Average time to resolve an issue](http://isitmaintained.com/badge/resolution/cloudposse/bastion.svg)](http://isitmaintained.com/project/cloudposse/bastion "Average time to resolve an issue")
[![Percentage of issues still open](http://isitmaintained.com/badge/open/cloudposse/bastion.svg)](http://isitmaintained.com/project/cloudposse/bastion "Percentage of issues still open")
[![Contributions Welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg)](https://github.com/cloudposse/bastion/pulls)
[![License](https://img.shields.io/badge/license-APACHE%202.0%20-brightgreen.svg)](https://github.com/cloudposse/bastion/blob/master/LICENSE)

## Demo
This is a secure/locked-down bastion implemented as a Docker Container. It uses Alpine Linux as the base image and ships with support for Google Authenticator & DUO MFA support.

It was designed to be used on Kubernetes together with [GitHub Authorized Keys](https://github.com/cloudposse/github-authorized-keys) to provide secure remote access to production clusters.
### MFA Setup & Usage

Here's a demo of what a user experiences when setting up Google Authenticator for the first time.
Expand All @@ -26,44 +19,28 @@ Just approve the request on your mobile phone (e.g. with a thumb press on iOS) w

### Slack Notifications

Here's what it looks like when someone connects to the bastion if Slack notifications are enabled.
Here's what it looks like when someone connects to the bastion if Slack notifications are enabled.

![Demo 2](docs/slack.png)

We recommend using Slack notifications for self-reporting.
* Any time a user accesses production systems, they should reply to the slack notification to justify their remote access.
* A "buddy" should approve the login by adding a reaction (e.g. ✅).
We recommend using Slack notifications for self-reporting.
* Any time a user accesses production systems, they should reply to the slack notification to justify their remote access.
* A "buddy" should approve the login by adding a reaction (e.g. ✅).
* If no one approves the login, it should trigger an *incident response* to track down the unauthorized access.

## Help

**Got a question?**
File a GitHub [issue](https://github.com/cloudposse/bastion/issues), send us an [email](http://cloudposse.com/contact/) or reach out to us on [Gitter](https://gitter.im/cloudposse/).
---

This project is part of our comprehensive ["SweetOps"](https://docs.cloudposse.com) approach towards DevOps.

## Quick Start

Here's how you can quickly demo the `bastion`. We assume you have `~/.ssh/authorized_keys` properly configured and your SSH key (e.g. `~/.ssh/id_rsa`) added to your SSH agent.

It's 100% Open Source and licensed under the [APACHE2](LICENSE).

```bash
$ docker run -it -p 1234:22 \
-e MFA_PROVIDER=google-authenticator \
-v ~/.ssh/authorized_keys:/root/.ssh/authorized_keys
cloudposse/bastion
```

Now, in another terminal you should be able to run:
```bash
$ ssh root@localhost -p 1234
```

The first time you connect, you'll be asked to setup your MFA device. Subsequently, each time you connect, you'll be prompted to enter your MFA token.


## Usage


### Running

Refer to the [Environment Variables](#environment-variables) section below to tune how the `bastion` operates.
Expand Down Expand Up @@ -120,7 +97,7 @@ Google Authenticator is a free & open source MFA solution. It's less secure than

| ENV | Description | Default |
|-------------------|:----------------------------------------------------|:---------------------:|
| `MFA_PROVIDER` | Enable the Google Authenticator provider | google-authenticator |
| `MFA_PROVIDER` | Enable the Google Authenticator provider | google-authenticator |


##### Enforcer Settings
Expand Down Expand Up @@ -170,64 +147,150 @@ The `bastion` does not attempt to manage user accounts. We suggest using [GitHub

The `bastion` was written to be easily extensible.

You can extend the enforcement policies by adding shell scripts to `etc/enforce.d`. Any scripts that are `+x` (e.g. `chmod 755`) will be executed at runtime.
You can extend the enforcement policies by adding shell scripts to `etc/enforce.d`. Any scripts that are `+x` (e.g. `chmod 755`) will be executed at runtime.

## Thanks

- [@neochrome](https://github.com/neochrome/docker-bastion), for providing a great basic bastion built on top of Alpine Linux
- [@aws](https://aws.amazon.com/blogs/security/how-to-record-ssh-sessions-established-through-a-bastion-host/), for providing detailed instructions on how to do SSH session logging.
- [@duo](https://duo.com/docs/duounix), for providing excellent documentation
- [@google](https://github.com/google/google-authenticator-libpam) for contributing Google Authenticator to the Open Source community

## Quick Start


Here's how you can quickly demo the `bastion`. We assume you have `~/.ssh/authorized_keys` properly configured and your SSH key (e.g. `~/.ssh/id_rsa`) added to your SSH agent.


```bash
$ docker run -it -p 1234:22 \
-e MFA_PROVIDER=google-authenticator \
-v ~/.ssh/authorized_keys:/root/.ssh/authorized_keys
cloudposse/bastion
```

Now, in another terminal you should be able to run:
```bash
$ ssh root@localhost -p 1234
```

The first time you connect, you'll be asked to setup your MFA device. Subsequently, each time you connect, you'll be prompted to enter your MFA token.





## Help

**Got a question?**

File a GitHub [issue](https://github.com/cloudposse/bastion/issues), send us an [email][email] or join our [Slack Community][slack].

## Commerical Support

Work directly with our team of DevOps experts via email, slack, and video conferencing.

We provide *commercial support* for all of our [Open Source][github] projects. As a *Dedicated Support* customer, you have access to our team of subject matter experts at a fraction of the cost of a fulltime engineer.

[![E-Mail](https://img.shields.io/badge/email-hello@cloudposse.com-blue.svg)](mailto:hello@cloudposse.com)

- **Questions.** We'll use a Shared Slack channel between your team and ours.
- **Troubleshooting.** We'll help you triage why things aren't working.
- **Code Reviews.** We'll review your Pull Requests and provide constructive feedback.
- **Bug Fixes.** We'll rapidly work to fix any bugs in our projects.
- **Build New Terraform Modules.** We'll develop original modules to provision infrastructure.
- **Cloud Architecture.** We'll assist with your cloud strategy and design.
- **Implementation.** We'll provide hands on support to implement our reference architectures.


## Community Forum

Get access to our [Open Source Community Forum][slack] on Slack. It's **FREE** to join for everyone! Our "SweetOps" community is where you get to talk with others who share a similar vision for how to rollout and manage infrastructure. This is the best place to talk shop, ask questions, solicit feedback, and work together as a community to build *sweet* infrastructure.

## Contributing

#### Bug Reports & Feature Requests
### Bug Reports & Feature Requests

Please use the [issue tracker](https://github.com/cloudposse/bastion/issues) to report any bugs or file feature requests.

#### Developing
### Developing

If you are interested in being a contributor and want to get involved in developing this project or [help out](https://github.com/orgs/cloudposse/projects/3) with our other projects, we would love to hear from you! Shoot us an [email](mailto:hello@cloudposse.com).

PRs are welcome. In general, we follow the "fork-and-pull" Git workflow.
In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.

1. **Fork** the repo on GitHub
2. **Clone** the project to your own machine
3. **Commit** changes to your own branch
4. **Push** your work back up to your fork
5. Submit a **Pull request** so that we can review your changes
5. Submit a **Pull Request** so that we can review your changes

NOTE: Be sure to merge the latest from "upstream" before making a pull request!
**NOTE:** Be sure to merge the latest changes from "upstream" before making a pull request!

## Change Log
## Copyright

View our closed [Pull Requests](https://github.com/cloudposse/bastion/pulls?q=is%3Apr+is%3Aclosed).
Copyright © 2017-2018 [Cloud Posse, LLC](https://cloudposse.com)


## Thanks
## License

- [@neochrome](https://github.com/neochrome/docker-bastion), for providing a great basic bastion built on top of Alpine Linux
- [@aws](https://aws.amazon.com/blogs/security/how-to-record-ssh-sessions-established-through-a-bastion-host/), for providing detailed instructions on how to do SSH session logging.
- [@duo](https://duo.com/docs/duounix), for providing excellent documentation
- [@google](https://github.com/google/google-authenticator-libpam) for contributing Google Authenticator to the Open Source community
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

See [LICENSE](LICENSE) for full details.

Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

## License
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.

Apache2 © [Cloud Posse, LLC](https://cloudposse.com)

## Trademarks

All other trademarks referenced herein are the property of their respective owners.

## About

This project is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at <hello@cloudposse.com>

The `bastion` is maintained and funded by [Cloud Posse, LLC][website]. Like it? Please let us know at <hello@cloudposse.com>
[![Cloud Posse](https://cloudposse.com/logo-300x69.png)](https://cloudposse.com)

We're a [DevOps Professional Services][hire] company based in Los Angeles, CA. We love [Open Source Software](https://github.com/cloudposse/)!

We offer paid support on all of our projects.

We love Open Source Software!
Check out [our other projects][github], [apply for a job][jobs], or [hire us][hire] to help with your cloud strategy and implementation.

[docs]: https://docs.cloudposse.com/
[website]: https://cloudposse.com/
[github]: https://github.com/cloudposse/
[jobs]: https://cloudposse.com/jobs/
[hire]: https://cloudposse.com/contact/
[slack]: https://slack.cloudposse.com/
[linkedin]: https://www.linkedin.com/company/cloudposse
[twitter]: https://twitter.com/cloudposse/
[email]: mailto:hello@cloudposse.com

See [our other projects][community]
or [hire us][hire] to help build your next cloud-platform.

[website]: http://cloudposse.com/
[community]: https://github.com/cloudposse/
[hire]: http://cloudposse.com/contact/

### Contributors

[![Erik Osterman](http://s.gravatar.com/avatar/88c480d4f73b813904e00a5695a454cb?s=144)](https://osterman.com/)
| [![Erik Osterman][osterman_avatar]](osterman_homepage)<br/>[Erik Osterman][osterman_homepage] | [![Marji Cermak][marji_avatar]](marji_homepage)<br/>[Marji Cermak][marji_homepage] |
|---|---|

[osterman_homepage]: https://github.com/osterman
[osterman_avatar]: https://github.com/osterman.png?size=150
[marji_homepage]: https://github.com/marji
[marji_avatar]: https://github.com/marji.png?size=150

[Erik Osterman](https://github.com/osterman)


Loading

0 comments on commit eb62ae3

Please sign in to comment.