Merge pull request #9 from cisagov/first-commits

Initial functionality

.coveragerc

@@ -2,7 +2,7 @@
 # https://coverage.readthedocs.io/en/latest/config.html
 
 [run]
-source = src/example
+source = src/awssh
 omit =
 branch = true
 

.github/workflows/build.yml

@@ -23,12 +23,12 @@ jobs:
       - id: setup-python
         uses: actions/setup-python@v2
         with:
-          python-version: 3.9
+          python-version: "3.10"
       # We need the Go version and Go cache location for the actions/cache step,
       # so the Go installation must happen before that.
       - uses: actions/setup-go@v2
         with:
-          go-version: '1.16'
+          go-version: "1.16"
       - name: Store installed Go version
         id: go-version
         run: |
@@ -112,9 +112,6 @@ jobs:
       fail-fast: false
       matrix:
         python-version:
-          - "3.6"
-          - "3.7"
-          - "3.8"
           - "3.9"
           - "3.10"
     steps:
@@ -165,7 +162,7 @@ jobs:
       - id: setup-python
         uses: actions/setup-python@v2
         with:
-          python-version: 3.9
+          python-version: "3.10"
       - uses: actions/cache@v2
         env:
           BASE_CACHE_KEY: "${{ github.job }}-${{ runner.os }}-\
@@ -199,9 +196,6 @@ jobs:
       fail-fast: false
       matrix:
         python-version:
-          - "3.6"
-          - "3.7"
-          - "3.8"
           - "3.9"
           - "3.10"
     steps:

.pre-commit-config.yaml

@@ -109,7 +109,13 @@ repos:
     hooks:
       - id: mypy
         additional_dependencies:
+          - boto3-stubs
+          - pytest-mypy
+          - types-docopt
+          - types-requests
           - types-setuptools
+        args:
+          - --scripts-are-modules
   - repo: https://github.com/asottile/pyupgrade
     rev: v2.31.0
     hooks:

CONTRIBUTING.md

@@ -15,7 +15,7 @@ all of which should be in this repository.
 
 If you want to report a bug or request a new feature, the most direct
 method is to [create an
-issue](https://github.com/cisagov/ssm-ssh/issues) in
+issue](https://github.com/cisagov/awssh/issues) in
 this repository.  We recommend that you first search through existing
 issues (both open and closed) to check if your particular issue has
 already been reported.  If it has then you might want to add a comment
@@ -25,7 +25,7 @@ one.
 ## Pull requests ##
 
 If you choose to [submit a pull
-request](https://github.com/cisagov/ssm-ssh/pulls),
+request](https://github.com/cisagov/awssh/pulls),
 you will notice that our continuous integration (CI) system runs a
 fairly extensive set of linters, syntax checkers, system, and unit tests.
 Your pull request may fail these checks, and that's OK.  If you want
@@ -135,9 +135,9 @@ can create and configure the Python virtual environment with these
 commands:
 
 ```console
-cd ssm-ssh
-pyenv virtualenv <python_version_to_use> ssm-ssh
-pyenv local ssm-ssh
+cd awssh
+pyenv virtualenv <python_version_to_use> awssh
+pyenv local awssh
 pip install --requirement requirements-dev.txt
 ```
 

README.md

@@ -1,25 +1,75 @@
-# ssm-ssh #
-
-[![GitHub Build Status](https://github.com/cisagov/ssm-ssh/workflows/build/badge.svg)](https://github.com/cisagov/ssm-ssh/actions)
-[![Coverage Status](https://coveralls.io/repos/github/cisagov/ssm-ssh/badge.svg?branch=develop)](https://coveralls.io/github/cisagov/ssm-ssh?branch=develop)
-[![Total alerts](https://img.shields.io/lgtm/alerts/g/cisagov/ssm-ssh.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/cisagov/ssm-ssh/alerts/)
-[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/cisagov/ssm-ssh.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/cisagov/ssm-ssh/context:python)
-[![Known Vulnerabilities](https://snyk.io/test/github/cisagov/ssm-ssh/develop/badge.svg)](https://snyk.io/test/github/cisagov/ssm-ssh)
-
-This is a generic skeleton project that can be used to quickly get a
-new [cisagov](https://github.com/cisagov) Python library GitHub
-project started.  This skeleton project contains [licensing
-information](LICENSE), as well as
-[pre-commit hooks](https://pre-commit.com) and
-[GitHub Actions](https://github.com/features/actions) configurations
-appropriate for a Python library project.
-
-## New Repositories from a Skeleton ##
-
-Please see our [Project Setup guide](https://github.com/cisagov/development-guide/tree/develop/project_setup)
-for step-by-step instructions on how to start a new repository from
-a skeleton. This will save you time and effort when configuring a
-new repository!
+# awssh ☁️🔒🐚 #
+
+[![GitHub Build Status](https://github.com/cisagov/awssh/workflows/build/badge.svg)](https://github.com/cisagov/awssh/actions)
+[![Coverage Status](https://coveralls.io/repos/github/cisagov/awssh/badge.svg?branch=develop)](https://coveralls.io/github/cisagov/awssh?branch=develop)
+[![Total alerts](https://img.shields.io/lgtm/alerts/g/cisagov/awssh.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/cisagov/awssh/alerts/)
+[![Language grade: Python](https://img.shields.io/lgtm/grade/python/g/cisagov/awssh.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/cisagov/awssh/context:python)
+[![Known Vulnerabilities](https://snyk.io/test/github/cisagov/awssh/develop/badge.svg)](https://snyk.io/test/github/cisagov/awssh)
+
+This project provides a tool that simplifies secure shell connections over
+[AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html)
+(formerly known as SSM).
+
+## Pre-requisites ##
+
+- The [AWS CLI](https://aws.amazon.com/cli/) installed on your system.
+- A valid AWS profile that has permissions to start/stop SSM sessions.
+- A [`bash`](https://www.gnu.org/software/bash/) shell.
+
+## Usage ##
+
+### Setup ###
+
+1. Install the `awssh` command line utility.  One easy way to do this is
+   to run the `setup-env` script in the main directory.
+1. Define environment variables:
+   - `AWSSH_PROFILE_FILTER`: A string that will match one or more profiles
+     in your AWS configuration file that have permission to start/stop SSM
+     sessions.
+   - `AWSSH_USER`: The username to use for ssh connections over SSM.
+
+    ```bash
+    export AWSSH_PROFILE_FILTER="startstopssmsession"
+    export AWSSH_USER="lemmy.kilmister"
+    ```
+
+1. Source the [`awssh-completion.bash`](tools/awssh-completion.bash) file in
+   your `bash` environment:
+
+   ```bash
+   source tools/awssh-completion.bash
+   ```
+
+   If you skip this step, you won't get to enjoy any of that sweet, sweet
+   tab completion that will make life a lot easier for you.  Don't say we
+   didn't warn you.
+
+### Start a SSM shell session without ssh ###
+
+```console
+awssh --no-ssh my-aws-startstopssmsession-profile i-01234567890abcdef
+```
+
+### Start a SSM shell session with ssh ###
+
+```console
+awssh my-aws-startstopssmsession-profile i-01234567890abcdef
+```
+
+Tab completion can be used to autocomplete the following items as you type
+your `awssh` command:
+
+- Shared credentials file (following `-c`, `--credentials=FILENAME`), by
+  showing matching files in the `.aws` directory in your home directory
+  (e.g. `~/.aws/`)
+- AWS region (`-r`, `--region`)
+- AWS profile (`<profile>`), provided your chosen (or default) credentials
+  file contains at least one profile that matches the string specified by the
+  `AWSSH_PROFILE_FILTER` environment variable
+- AWS instance you want to open a session to (`<instance-id>`); note that
+  if your instance is tagged with a name, you can start typing that name and
+  when you tab complete, the name will be transformed into the instance ID
+  (assuming you have typed enough of the name to identify a unique instance).
 
 ## Contributing ##
 

bump_version.sh

@@ -6,7 +6,7 @@ set -o nounset
 set -o errexit
 set -o pipefail
 
-VERSION_FILE=src/example/_version.py
+VERSION_FILE=src/awssh/_version.py
 
 HELP_INFORMATION="bump_version.sh (show|major|minor|patch|prerelease|build|finalize)"
 

setup.py

@@ -1,5 +1,5 @@
 """
-This is the setup module for the example project.
+This is the setup module for the awssh project.
 
 Based on:
 
@@ -42,19 +42,19 @@ def get_version(version_file):
 
 
 setup(
-    name="example",
+    name="awssh",
     # Versions should comply with PEP440
-    version=get_version("src/example/_version.py"),
-    description="Example Python library",
+    version=get_version("src/awssh/_version.py"),
+    description="A tool that simplifies secure shell connections over AWS Systems Manager",
     long_description=readme(),
     long_description_content_type="text/markdown",
     # Landing page for CISA's cybersecurity mission
     url="https://www.cisa.gov/cybersecurity",
     # Additional URLs for this project per
     # https://packaging.python.org/guides/distributing-packages-using-setuptools/#project-urls
     project_urls={
-        "Source": "https://github.com/cisagov/ssm-ssh",
-        "Tracker": "https://github.com/cisagov/ssm-ssh/issues",
+        "Source": "https://github.com/cisagov/awssh",
+        "Tracker": "https://github.com/cisagov/awssh/issues",
     },
     # Author details
     author="Cybersecurity and Infrastructure Security Agency",
@@ -74,23 +74,25 @@ def get_version(version_file):
         # Specify the Python versions you support here. In particular, ensure
         # that you indicate whether you support Python 2, Python 3 or both.
         "Programming Language :: Python :: 3",
-        "Programming Language :: Python :: 3.6",
-        "Programming Language :: Python :: 3.7",
-        "Programming Language :: Python :: 3.8",
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
     ],
-    python_requires=">=3.6",
+    python_requires=">=3.9",
     # What does your project relate to?
-    keywords="skeleton",
+    keywords="aws ssm ssh",
     packages=find_packages(where="src"),
     package_dir={"": "src"},
-    package_data={"example": ["data/*.txt"]},
     py_modules=[splitext(basename(path))[0] for path in glob("src/*.py")],
     include_package_data=True,
-    install_requires=["docopt", "schema", "setuptools >= 24.2.0"],
+    install_requires=[
+        "boto3",
+        "docopt",
+        "schema",
+        "setuptools >= 24.2.0",
+    ],
     extras_require={
         "test": [
+            "boto3-stubs",
             "coverage",
             # coveralls 1.11.0 added a service number for calls from
             # GitHub Actions. This caused a regression which resulted in a 422
@@ -102,8 +104,16 @@ def get_version(version_file):
             "pre-commit",
             "pytest-cov",
             "pytest",
+            "types-docopt",
+            "types-requests",
+            "types-setuptools",
+        ]
+    },
+    # Conveniently allows one to run the CLI tool as `awssh`
+    entry_points={
+        "console_scripts": [
+            "awssh = awssh.awssh:main",
+            "_awssh-completer = awssh.autocompleter:main",
         ]
     },
-    # Conveniently allows one to run the CLI tool as `example`
-    entry_points={"console_scripts": ["example = example.example:main"]},
 )

src/example/__init__.py → src/awssh/__init__.py

@@ -1,9 +1,14 @@
-"""The example library."""
+"""The awssh library."""
+# Standard Python Libraries
+from pathlib import Path
+
 # We disable a Flake8 check for "Module imported but unused (F401)" here because
 # although this import is not directly used, it populates the value
 # package_name.__version__, which is used to get version information about this
 # Python package.
 from ._version import __version__  # noqa: F401
-from .example import example_div
 
-__all__ = ["example_div"]
+CREDENTIAL_DIR = Path("~/.aws").expanduser()
+DEFAULT_CREDENTIAL_FILE = Path(CREDENTIAL_DIR) / Path("credentials")
+
+__all__ = ["CREDENTIAL_DIR"]

src/example/__main__.py → src/awssh/__main__.py

@@ -1,5 +1,5 @@
 """Code to run if this package is used as a Python module."""
 
-from .example import main
+from .awssh import main
 
 main()

src/example/_version.py → src/awssh/_version.py

@@ -1,2 +1,2 @@
 """This file defines the version of this module."""
-__version__ = "0.1.0"
+__version__ = "1.0.0"