SSH Key Enforcer for BitBucket Server

What it do..

Layers additional controls over Bitbucket's SSH key features that enforce the stronger controls required in an enterprise environment.

Features

• Blocks any keys being added directly to Projects or Repositories

• All keys must be created for specific users (system or human), and inherit their access.

• Blocks upload of existing keys and generates new RSA 2048 bit keys for the user.

• User can download public and private key pair, and regenerate as needed.

• Special users designated by a Group may add keys directly, additionally a dedicated ID may be named as "bamboo". This supports the current Bamboo/Stash integration which generates user keys when repositories are created in bamboo. This Group and User should only be granted to admins or system accounts that provision pipelines.

• Enforces Key expiration policy

• To mitigate risk, all user keys are expired after N days(configurable), and users are notified via email to re-generate a new pair.

Rules

Key Types

The system recognize multiple key types. (See SshKeyPairEntity.KeyType enum for latest)

• USER: A key generated by the plugin on user behalf via UI or API.
• BAMBOO: A key presented to stash by a user name matching the configured 'bambooUser'. This is intended to allow a system ID used in pipeline provisioning to establish a link between Bamboo and Stash.
• BYPASS: A key presented to stash by a user in the configured 'authorizedGroup'. This group is intended to allow a human admins who may manually establish a link between Bamboo and Stash, or have other lifecyle use that is managed external to this plugin.

Key Limits

Any given user will be allowed:

• 1 active USER key, new replace the old
• Unlimited BAMBOO types allow only a single active Key per user. New ones are added, not replaced.
• Unlimited BYPASS types allow only a single active Key per user. New ones are added, not replaced.

Key Rotation

USER is only key type currently rotated. BAMBOO requires code changes in bamboo's StashRepository implementation to support automatic re-generation (see issue #8). BYPASS keys are intentionally avoided with the assumption they are only enabled/authorized when an external system is in place to manage those keys.

Admin Config

Admins may update the values capture in JSON below via /rest/enterprisessh/1.0/config

{
  "authorizedGroup": "admins",
  "bambooUser":"bamboolinker",
  "daysToKeepUserKeys": 30,
  "daysToKeepBambooKeys": 365,
  "millisBetweenRuns": 86400000,
  "internalKeyPolicyLink":"https://someplace.com/page"
}

NOTE: daysToKeepBambooKeys is not currently enforced - See Issue #8

NOTE: Set any property to 0/null to disable

License

Copyright 2015 Liberty Mutual Insurance

Licensed 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

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

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.

Contributing

Prerequisites

First install and run Docker locally

• Mac Instructions
• Windows Instructions

Running Locally

• Faster start, single instance $ atlas-run --testGroup default
• Slower start, testing Data Center $ mvn docker:start && atlas-run --testGroup clusterTestGroup

Testing Locally

• Testing against Data Center cluster $ atlas-integration-test -DtestGroups=clusterTestGroup
• Testing against single server instance $ atlas-integration-test -DtestGroups=default

Reloading Plugin Changes to Save Time

If one of the two test groups is already running locally you may save time and reload any plugin changes by opening a separate terminal in the project root directory and running $ atlas-package -DskipTests

Ex.

1. Start cluster $ mvn docker:start && atlas-run --testGroup clusterTestGroup
2. Make a code change and run $ atlas-package -DskipTests to load the new plugin jar without restarting the application

Troubleshooting

• When database does not get cleaned up properly after shutting down clusterTestGroup, run $ mvn docker:stop
• When starting clusterTestGroup throws address already in use exception, try changing the port in the pom. Ex. change http port of second node to 7991 and restart cluster

SSH Key Enforcer for Stash is built using Atlassian SDK, here's some info on that...

Here are the SDK commands you'll use immediately:

• atlas-run -- installs this plugin into the product and starts it on localhost
• atlas-debug -- same as atlas-run, but allows a debugger to attach at port 5005
• atlas-cli -- after atlas-run or atlas-debug, opens a Maven command line window: - 'pi' reinstalls the plugin into the running product instance
• atlas-help -- prints description for all commands in the SDK

Full documentation is always available at:

https://developer.atlassian.com/display/DOCS/Introduction+to+the+Atlassian+Plugin+SDK