README.md

Providence

Providence is a system for code commit & bug system monitoring. It is deployed within an organization to monitor code commits for security (or other) concerns, via customizable plugins. A plugin performs logic whenever a commit occurs.

Cool Stuff

• Build plugin to run a something everytime a commit happens
• Empire contains some useful tools for credential management
• Find our slides from our AppSec presentation here

Requirements

python2.7
postgresql 9.4+

Steps: Local install with pip and virtualenv

1. OS X Prerequisites

• Homebrew (http://brew.sh)
• XCode (once installed, open up and accept license)
• Xcode Command Line Tools (from Terminal.app) xcode-select --install

2. Setup Postgresql on your server

3. Setup the Database

Create a database named 'providence'

4. Checkout Providence and Submodules

git clone https://github.com/Salesforce/Providence --recursive
cd Providence

5. Install the VirtualEnv in your Providence Directory & Install Dependencies

Linux

sudo apt-get install python-pip python-virtualenv

OS X

sudo easy_install virtualenv
brew install swig postgresql wget 

Configuration On All Systems

virtualenv venv
source venv/bin/activate
pip install -r requirements.txt

For OSX users, you may have issues installing the cryptography dependency. If the above steps fail due to the cryptography module, update your pip to the latest version in virtualenv

pip -V
pip 7.1.2 from /Users/joe_smith/Desktop/Providence/venv/lib/python2.7/site-packages (python 2.7)
(upgrade pip to latest)
pip install --upgrade pip

See https://cryptography.io/en/latest/installation/ if upgrading pip does not solve the problem

If you need to deactivate the virtualenv just type deactivate

If you would like to use Perforce monitoring

(follow steps above, make sure you have run 'source venv/bin/activate')
pip install p4python

6. Configuration

The config.json.example file contains the settings for which to run Providence with.

credentials_file

Name of the credential storage file. There should be no need to modify this.

logging

Format of the Providence.log logging file. Change the loglevel if the log file is too large

postgresql

Edit this section to point to your Postgres server. credential-identifier is the name used in credentials.json for the Postgres username and password.

repos

Edit this section to point to the repositories you want to monitor with Providence. Github (including Enterprise) and Perforce are currently supported.

{
    "type": "(github or perforce)",
    "name": "(name used by Providence, not the actual repo name)",
    "server": "(server URL)",
    "owner": "(github only - owner)",
    "directory": "(directory of the repo)"
  }

cron

watcher_interval sets the time in minutes between each scheduled processing, for watcher plugins.

7. Adjust which plugins you want to run

Enable plugins in your new config.json file, several examples are listed in the example file.

pmd_path

If using the PMD plugin, fill out the full directory to run.sh file for your PMD installation.

8. Generate a Credentials Key

dd if=/dev/urandom bs=32 count=1 2>/dev/null | openssl base64

This key can be stored in the environmental variable $CREDENTIAL_KEY or entered when Providence is first run. It's highly recommended you don't keep the key on the same server as the credentials.json file, and use something like LastPass for keeping it safe.

9. Entering Credentials

When you start up Providence it will try to connect to the repositories set up in config.json, and ask you for credentials that aren't found. Alternatively you can edit the credentials.json file yourself (useful if one github account works for several repositories).

Manually create the credentials file.

You can encrypt a passwords using the command:

python Empire/creds/encrypt-cred.py

copy credentials.json.example to credentials.json and update it as needed:

{    
   "plsqlcreds": {
        "type":"password",
        "username":"<username>",
        "password":"<password or fernet-encrypted password>"
   },
   "github": {
        "type":"password",
        "username":"<myusername>",
        "password":"<my password or fernet-encrypted password>"
    }
}

10. Run Providence!

python providence.py