README.md

Cerberus

The Cerberus API is a cloud native, scalable Springboot application that can securely store application properties and files with robust auditing features.

Cerberus has an accessible user interface that offers teams there own self service portal for mapping various principals (Users and Applications) to what we call a Safe Deposit Box.

Safe Deposit Boxes can store properties (k,v pairs, json blobs, etc) and files (certificates, private key files, etc).

Cerberus has a robust versioning and audit features built in, so you can see who is doing what and revert data in an SDB if needed.

To learn more about Cerberus, please visit the Cerberus website.

Getting Started for local development

Configure Cerberus

Cerberus will look in ~/.cerberus/ for additional springboot configuration. You can configure a cerberus-local.yaml file there that has your local specific conf.

See the configuration section for details on required and optional configuration.

Start Mysql

You need to configure and run MySQL locally

MySQL Version 5.7 is required to run the application locally.

To get MySQL setup on OS X:

$ brew install [email protected]
$ mysql.server restart
$ mysql_secure_installation

You'll need to create a database and user for it. Run the following SQL against your mysql database:

CREATE DATABASE IF NOT EXISTS cms;

CREATE USER 'cms'@'localhost' IDENTIFIED BY '<YOUR DB PASSWORD HERE>';

GRANT ALL ON cms.* TO 'cms'@'localhost';

Ensure that you have AWS Credentials available

Ensure Credentials are available as outlined in the AWS Java Credentials page, we use the default provider chain.

For local development you can use a tool such as gimme-aws-creds

$ gimme-aws-creds --profile cerberus
Using password from keyring for [email protected]
Multi-factor Authentication required.
token:software:totp( GOOGLE ) : [email protected] selected
Enter verification code: 111111
writing role arn:aws:iam::111111111111:role/cerberus.admin.role to /Users/jfiel2/.aws/credentials

Start Cerberus

Cerberus is a Spring boot application and this project makes use of the Springboot gradle plugin. You can start cerberus with gradle

./gradlew cerberus-web:bootRun

You can start it with a remote debugger

./gradlew cerberus-web:bootRun --debug-jvm

You must build the dashboard once and after you make changes

./gradlew cerberus-dashboard:buildDashboard cerberus-web:bootRun

We have also including 2 convenience scripts that are nice because they give you pretty colors

./run.sh

This script builds the jar and starts the application listening but not breaking for a remote debugger on port 5006

./debug.sh

This script builds the jar and starts the application stopping automatically before spring initializes and waits for a remote debugger to attach on port 5006

Configuration

Take a look at the master configuration, which contains all the available options and default values. A reasonable approach would be to copy this file and place it ~/.cerberus/cerberus-${envName} and remove the default values you do not wish to override and configure any options you desire.

Remember that this is a Springboot app, so when you deploy it you can configure it like so.

LOG_DIR=/var/log/cerberus
LOG_OUT=${LOG_DIR}/stdout.log
LOG_ERR=${LOG_DIR}/stderr.log

# configure the jvm by using export JVM_BEHAVIOR_ARGS
. /path/to/some/file/that/does/advanced/jvm/config/

APP_SPECIFIC_JVM_ARGS="\
-Dspring.profiles.active=prod \
-Dspring.config.additional-location:/opt/cerberus/ \

java -jar \
    ${JVM_BEHAVIOR_ARGS} \
    ${APP_SPECIFIC_JVM_ARGS} \
    /opt/cerberus/cerberus-web.jar > ${LOG_OUT} 2> ${LOG_ERR}

In the above when the app starts it will look in the classpath and /opt/cerberus/ for cerberus.yml|yaml, cerberus-prod.yml|yaml

First Secrets

You need to configure the first secrets, AKA the secrets that Cerberus needs to run. When Cerberus was first released AWS Secrets Manager didn't exist, so we rolled out a solution based on encrypting props files with KMS and storing them in S3 and downloading and decrypting them at runtime and merging the props in Guice.

With the new Springboot based Cerberus (Phoenix) you can use Kork-Secrets and AWS Secrets Manager.

You can upload a binary file such as a cert via the following:

aws secretsmanager create-secret --name ${ENV}-cms-ssl-cert --secret-binary fileb://path/to/your/ssl/cert.pfx

Update the cert in the future via the following:

aws secretsmanager update-secret --secret-id arn:aws:secretsmanager:us-west-2:111111:secret:${ENV}-cms-ssl-cert-xxxxx --secret-binary fileb://path/to/your/ssl/cert.pfx

Once uploaded you can reference the first secrets in the config yaml like this

security.requireSsl: true
server.ssl:
  keyStore: encryptedFile:secrets-manager!r:some-region!s:${ENV}-cms-ssl-cert
  keyStorePassword: encrypted:secrets-manager!r:some-region!s:some-secret!k:some-key

License

Cerberus Management Service is released under the Apache License, Version 2.0