Skip to content

Latest commit

 

History

History
204 lines (144 loc) · 8.78 KB

install.adoc

File metadata and controls

204 lines (144 loc) · 8.78 KB
Raw

🛠 🔐💥 KeyNuker Installation

Table of Contents

Requirements overview

  • Apache OpenWhisk — these docs assume you are using OpenWhisk on hosted Bluemix

  • CouchDB REST API compatible database — these docs assume you are using Cloudant on hosted Bluemix

  • An AWS account in the organization you want to monitor, with permissions to create IAM users

  • Github account and access token

  • Go 1.8 and Python 2.x installed locally

Signup for Bluemix free tier

  1. Signup for the IBM Bluemix cloud — the free tier is good enough to get things running.

  2. Download and install the OpenWhisk CLI

It’s also possible to get this running locally using the Open Source version of OpenWhisk, but there aren’t instructions for that yet.

IAM Setup

There are two ways to setup IAM Access to enable KeyNuker to pull in the latest AWS Access Keys from the AWS account(s) you want to protect:

  1. Direct: Setup an IAM User on the AWS target account, assign permissions, generate an Access Key and bake into KeyNuker parameters

  2. AssumeRole: This requires two separate AWS accounts. KeyNuker will have a user in the "initiating" AWS account, and each account you want to monitor will need to have a special role to allow that separate account to access it.

Direct: Create AWS user with minimal IAM permissions

In the AWS web admin UI, create a new IAM user called KeyNuker with only Programmatic access and assign that user the following policy:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1499788629000",
            "Effect": "Allow",
            "Action": [
                "iam:DeleteAccessKey",
                "iam:ListAccessKeys",
                "iam:ListUsers"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}
Note
 the most up-to-date version of this policy is in docs/keynuker-iam-user-policy.yml

Then under Security credentials, click the Create access key button to create a new AWS Access Key and Secret, which you should use to set the environment variable KEYNUKER_TARGET_AWS_ACCOUNTS as described below

Or to do the same steps via the CLI:

$ cd /path/to/keynuker
$ aws cloudformation create-stack --stack-name KeyNukerIAMAccess --template-body file://docs/cloudformation/keynuker-iam-user-policy.yml --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM
$ aws cloudformation describe-stacks --stack-name KeyNukerIAMAccess --query 'Stacks[0].Outputs[?OutputKey==`AwsAccessKey`].OutputValue' --output text
$ aws cloudformation describe-stacks --stack-name KeyNukerIAMAccess --query 'Stacks[0].Outputs[?OutputKey==`AwsSecretAccessKey`].OutputValue' --output text

AssumeRole: Add a role/policy with cross-account STS AssumeRole ability

Generate a github access token

Login to github and go to generate an access token. The only permission needed is the read:org (Read org and team membership) permission. You should be logged in as a user that is a member of the Github organization(s) that you want to monitor user activity for.

You should set this in an environment variable called KEYNUKER_GITHUB_ACCESS_TOKEN

Decide which github orgs you want to monitor, and set the KEYNUKER_GITHUB_ORGS environment variable accordingly. If you want to monitor non-public users on those orgs (highly recommended), your KEYNUKER_GITHUB_ACCESS_TOKEN will need to be owned by a user that is a member of those github orgs.

Create a CouchDB compatible database

Cloudant

In the bluemix web console:

  • Create a new Cloudant service

  • Create a db named keynuker. Set the KEYNUKER_DB_NAME environment variable to keynuker

  • Click the API button to get the API URL, and set the host part of the url to KEYNUKER_DB_HOST. This should not include the leading http or https.

  • Click the database name to go to the dashboard for that database

  • Go to the Permissions section and Generate API key

  • Save the Key to the KEYNUKER_DB_KEY environment variable, and the Password to the KEYNUKER_DB_SECRET_KEY environment variable

Alternatively, you should be able to use your own self-hosted Apache CouchDB or Couchbase Sync Gateway (which has a REST API that is mostly compatible with Apache CouchDB)

Environment variables

This is the full list of environment variables you should have set from the above steps. These will be used by the commands in this document, such as install.py

Table 1. Environment variables
Variable Example Description

KEYNUKER_ORG

default

The keynuker org (multi-tenancy). Set this to "default" unless you are trying to juggle multiple environments.

KEYNUKER_DB_KEY

jhh343234jkk

DB access key

KEYNUKER_DB_SECRET_KEY

7a789888djhh343234jkk

DB secret access key

KEYNUKER_DB_HOST

787877rrr-021d-42dc-6c65-gjhg775b2ef-bluemix.cloudant.com

DB hostname

KEYNUKER_DB_NAME

keynuker

DB name

KEYNUKER_TARGET_AWS_ACCOUNTS

'[{"AwsAccessKeyId": "", "AwsSecretAccessKey": ""}]' or '[{"TargetAwsAccountId": "01234", "TargetRoleName": "KeynukerAccess", "AssumeRoleExternalId": "yourexternalid"}]'

AWS Access Key ID and secret of AWS account(s) being monitored, only needs limited IAM permissions

KEYNUKER_INITIATING_AWS_ACCOUNT

'{"AwsAccessKeyId": "", "AwsSecretAccessKey": ""}'

This is specifically needed when using STS AssumeRole for Cross Account access, otherwise set it to a blank string. AWS Access Key ID and secret of AWS account(s) created in the Add a role/policy with cross-account STS AssumeRole ability instructions under "Initiating AWS Account"

KEYNUKER_GITHUB_ACCESS_TOKEN

902dcb6f5386e9f3ba

Github access token which has the :org read permission

KEYNUKER_GITHUB_ORGS

'["acme", "acme-labs"]'

The list of github orgs you would like to monitor. The quoting is important: outer quotes as single quotes, inner quotes as double quotes

KEYNUKER_GITHUB_USERS

'["defunkt", "torvalds"]'

The list of individual github user logins you would like to monitor, which is appended to the users found from the KEYNUKER_GITHUB_ORGS lookup (if any). The quoting is important: outer quotes as single quotes, inner quotes as double quotes

KEYNUKER_GITHUB_ENTERPRISE_API_URL

https://github.your.co

Only needed for Github Enterprise users. Set this to point to your custom Github URL. Defaults to "", which will connect to https://api.github.com.

KEYNUKER_MAILER_API_KEY

key-82ea6cfe7dc69f6c

The Mailgun API key for notifications. At the moment, mailgun is the only option for outgoing mail. Please open an issue if you need a different option. You can find the mailer (Mailgun) API keys in the Maigun Web Admin For MAILERAPIKEY use the value in Active API Key and for MAILERPUBLICAPIKEY use Email Validation Key

KEYNUKER_MAILER_PUBLIC_API_KEY

pubkey-e9ceff19d2749

The Mailgun public api key.

KEYNUKER_MAILER_DOMAIN

sandboxc66.mailgun.org

The Mailgun domain.

KEYNUKER_EMAIL_FROM_ADDRESS

you@your.org

The FROM address for email notifications about nuked keys

KEYNUKER_ADMIN_EMAIL_CC_ADDRESS

admin@your.org

The email address of the Sys. Admin to CC on all email notifications about nuked keys. If the "leaker" cannot be idenitifed via the github commit, this will be the only recipient of notifications.

KEYNUKER_INSTALL_USE_DOCKER_SKELETON

false

Whether to build action.zip for use with re-usable DockerSkeleton docker image, or to build a custom docker image per-action, which requires more environment variables to be set (search for "docker" in install.py). Defaults to true.

Install KeyNuker to OpenWhisk

Get the code

$ go get -u -v -t github.com/tleyden/keynuker

Run install.py

The install.py script will do the following things:

  1. Build Go binaries from source

  2. Package binaries into action.zip files that are used by the executing docker container (search install.py for --docker for details)

  3. Create (or recreate) all of the OpenWhish actions, triggers, and rules

$ cd $GOPATH/src/github.com/tleyden/keynuker/
$ python install.py --bluemix

Congrats! KeyNuker is now installed. You can do a quick verification by running wsk action list, which should return a list of actions:

$ bx wsk action list
actions
/yourusername_dev/github-user-events-scanner-nuker                     private sequence
/yourusername_dev/fetch-aws-keys-write-doc                             private sequence
etc ...

To further verify your setup, continue on to Verifying your installation