CyberArk Conjur automatically secures secrets used by privileged users and machine identities
Permalink
Failed to load latest commit information.
.github Pull this PR template in line with our default templates Aug 31, 2018
Contributing_OSS updated PDF of Contributor Agreement (#405) Oct 2, 2017
apidocs Make authentication more obvious in the API documentation Aug 22, 2018
app WIP: K8s refactor 642 (#696) Sep 19, 2018
aws/cloudformation Add a CloudFormation template for Conjur CE (#314) Sep 5, 2017
bin Configurable Export Archive Filename (#661) Aug 13, 2018
ci authn-k8s authenticator expects a URL-escaped client cert (#730) Sep 10, 2018
config Conjur CA Services (#689) Aug 31, 2018
contrib Add frozen string literal magic comment everywhere Jul 5, 2018
cucumber WIP: K8s refactor 642 (#696) Sep 19, 2018
db Improve large policy initial load performance (#674) Aug 22, 2018
dev Moving Linting/Static Analysis/Vulnerability Scanning to Code Climate ( Jul 11, 2018
distrib fix rewriting of /api and / so they're not URL-decoded Jun 26, 2018
docs Improve Subject Name handling for Conjur CA certificates (#712) Sep 11, 2018
engines/conjur_audit CIDR Authentication Restriction for Users and Hosts (#616) Jul 11, 2018
lib WIP: K8s refactor 642 (#696) Sep 19, 2018
run response to PR review; gets authn_local cukes working in Jenkins Dec 8, 2017
spec WIP: K8s refactor 642 (#696) Sep 19, 2018
.codeclimate.yml Restore rubocop config (#668) Aug 28, 2018
.dockerignore Adds suggestion to generate apidocs & updates .dockerignore Aug 30, 2017
.gitignore WIP create conjur v5 k8s authenticator (#619) Jul 11, 2018
.irbrc Add frozen string literal magic comment everywhere Jul 5, 2018
.overcommit.yml Disable style todo files when using overcommit Jul 5, 2018
.project initial commit Jun 28, 2016
.pryrc Add frozen string literal magic comment everywhere Jul 5, 2018
.reek.yml Conjur CA Services (#689) Aug 31, 2018
.rubocop.yml Restore rubocop config (#668) Aug 28, 2018
.rubocop_settings.yml Tooling: Ignore specs in Metrics/BlockLength Aug 9, 2018
.rubocop_todo.yml Restore rubocop config (#668) Aug 28, 2018
.simplecov Change simplecov config to not balk on missing env Jun 21, 2018
CHANGELOG.md Raise an error if a host factory policy definition doesn't include an… Sep 19, 2018
CODE_OF_CONDUCT.md Renamed CoC Apr 19, 2018
CONTRIBUTING.md Update Contributing (#396) Sep 29, 2017
Dockerfile k8s authenticator gets client cert from HTTP_X_SSL_CLIENT_CERTIFICATE… Aug 17, 2018
Dockerfile.fpm Update debian package to use Ruby 2.5 instead of 2.2 (#556) Jun 4, 2018
Dockerfile.test Be specific about which Conjur image targeting during build/test/push… Dec 4, 2017
Gemfile WIP: K8s refactor 642 (#696) Sep 19, 2018
Gemfile.lock WIP: K8s refactor 642 (#696) Sep 19, 2018
Jenkinsfile v1.1.2 Aug 22, 2018
LICENSE.md Update license to LGPL (#630) Jul 13, 2018
NOTICES.txt Adding additional libraries to NOTICES.txt Aug 29, 2017
Procfile add Procfile and config/puma.rb May 5, 2017
README.md Update README.md Aug 29, 2018
Rakefile Add frozen string literal magic comment everywhere Jul 5, 2018
STYLE.md Adds a style guide (#311) Aug 30, 2017
VERSION v1.2.0 Sep 7, 2018
VERSION_APPLIANCE CON-3523 build a Possum deb Oct 14, 2016
build.ps1 Improve Development flow (#528) Apr 23, 2018
build.sh Improve Development flow (#528) Apr 23, 2018
config.ru Add frozen string literal magic comment everywhere Jul 5, 2018
cucumber.yml Rename and cleanup world and env files Jul 11, 2018
debify.sh CON-3523 build a Possum deb Oct 14, 2016
docker-compose.yml CONJ-4525 Remove docs from conjur repo (#502) Dec 13, 2017
migrate.sh Revert these files to the master versions May 4, 2018
package.sh Update debian package to use Ruby 2.5 instead of 2.2 (#556) Jun 4, 2018
publish.sh Use VERSION file instead of git tag to set versions Dec 11, 2017
push-image.sh Fix docker image tagging and pushing (#694) Aug 22, 2018
release v1.1.2 Aug 22, 2018
sample_policy.yaml Add rotation feature with postgresql rotator Jun 11, 2018
secrets.yml CONJ-4525 Remove docs from conjur repo (#502) Dec 13, 2017
version_utils.sh Fix docker image tagging and pushing (#694) Aug 22, 2018
website-policy.yml use summon for building website, use conjurops v2 variables Jun 15, 2017

README.md

Conjur

Issues ready for work Issues in progress

Conjur on DockerHub Conjur on Quay.io Anchore Image Overview

Join Conjur Slack Follow Conjur on Twitter

Conjur provides secrets management and machine identity for modern infrastructure:

  • Machine Authorization Markup Language ("MAML"), a role-based access policy language to define system components & their roles, privileges and metadata
  • A REST web service to:
    • manage identity life cycles for humans and machines
    • organize and search roles and data in your secrets infrastructure
    • authorize access to resources using a sophisticated permission model
    • store secrets and make them available securely
  • Integrations throughout the cloud toolchain:
    • infrastructure as a service (IaaS)
    • configuration management
    • continuous integration and deployment (CI/CD)
    • container management and cloud orchestration

Note: our badges and social media buttons never track you.

Community Support

Our primary channel for support is through our Slack community. More here: community support

Migrating to Conjur EE

Migrating data from Conjur Open Source to Conjur EE is simple using our migration guide

Development

We welcome contributions of all kinds to Conjur. See our contributing guide.

Prerequisites

Before getting started, you should install some developer tools. These are not required to deploy Conjur but they will let you develop using a standardized, expertly configured environment.

  1. git to manage source code
  2. Docker to manage dependencies and runtime environments
  3. Docker Compose to orchestrate Docker environments

Build Conjur as a Docker image

It's easy to get started with Conjur and Docker:

  1. install dependencies (as above)

  2. clone this repository

  3. run the build script in your terminal:

    $ ./build.sh
    ...
    Successfully built 9a18a1396977
    $ docker images | grep conjur
    conjurinc/conjur latest a8229592474c 7 minutes ago 560.7 MB
    conjur           latest a8229592474c 7 minutes ago 560.7 MB
    conjur-dev       latest af98cb5b2a68 4 days ago    639.9 MB

Set up a development environment

The dev directory contains a docker-compose file which creates a development environment with a database container (pg, short for postgres), and a conjur server container with source code mounted into the directory /src/conjur-server.

To use it:

  1. Install dependencies (as above)

  2. Start the container (and optional extensions):

    $ cd dev
    $ ./start
    ...
    root@f39015718062:/src/conjur-server#

    Once the start script finishes, you're in a Bash shell inside the Conjur server container.

    After staring Conjur, your instance will be configured with the following:

    • Account: cucumber
    • User: admin
    • Password: Run conjurctl role retrieve-key cucumber:user:admin inside the container shell to retrieve the admin user API key (which is also the password)

LDAP Authentication

To enable a user to log into Conjur using LDAP credentials, run start with the --authn-ldap flag:

$ cd dev
$ ./start --authn-ldap
...
root@f39015718062:/src/conjur-server#

The --authn-ldap flag will:

  • Start an OpenLDAP container.
  • Load a user alice with the password alice into the LDAP server.
  • Load a policy authn-ldap/test, that grants alice the ability to authenticate via http://localhost:3000/authn-ldap/test/cucumber/alice/authenticate with the password alice.
  1. Run the server

    root@f39015718062:/src/conjur-server# conjurctl server
    <various startup messages, then finally:>
    * Listening on tcp://localhost:3000
    Use Ctrl-C to stop

    The conjurctl server script performs the following:

    • wait for the database to be available
    • create and/or upgrade the database schema according to the db/migrate directory
    • find or create the token-signing key
    • start the web server

    If you are going to be debugging Conjur using pry.byebug, you may choose to start the web server by calling rails server -b 0.0.0.0 webrick instead of conjurctl server. This will allow you to work in the debugger without the server timing out.

  2. Validate authentication using the username alice with the password alice:

$ curl -v -k -X POST -d "alice" http://localhost:3000/authn-ldap/test/cucumber/alice/authenticate
  1. Cleanup

    $ ./stop

    Running stop removes the running Docker Compose containers and the data key.

Development CLI

As a developer, there are a number of common scenarios when actively working on Conjur. The ./cli script, located in the dev folder is intended to streamline these tasks.

$ ./cli --help

NAME
    cli - Development tool to simplify working with a Conjur container.

SYNOPSIS
    cli [global options] command [command options] [arguments...]

GLOBAL OPTIONS
    --help                                    - Show this message

COMMANDS

    exec                                      - Steps into the running Conjur container, into a bash shell.

    key                                       - Displays the admin user API key

    policy load <account> <policy/path.yml>   - Loads a conjur policy into the provided account.

Step into the running Conjur container

$ ./cli exec

root@88d43f7b3dfa:/src/conjur-server#

View the admin user's API key

$ ./cli key

3xmx4tn353q4m02f8e0xc1spj8zt6qpmwv178f5z83g6b101eepwn1

Load a policy

$ ./cli policy load <account> <policy/path/from/project/root.yml>

For most development work, the account will be cucumber, which is created when the development environment starts. The policy path must be inside the cyberark/conjur project folder, and referenced from the project root.

Testing

Conjur has rspec and cucumber tests.

RSpec

RSpec tests are easy to run from within the conjur server container:

root@aa8bc35ba7f4:/src/conjur-server# rspec
Run options: exclude {:performance=>true}

Randomized with seed 62317
.............................................

Finished in 3.84 seconds (files took 3.33 seconds to load)
45 examples, 0 failures

Cucumber

Cucumber tests require the Conjur server to be running. It's easiest to achieve this by starting Conjur in one container and running Cucumber from another. Run the service in the conjur server container:

root@aa8bc35ba7f4:/src/conjur-server# conjurctl server
...
* Listening on tcp://localhost:3000
Use Ctrl-C to stop

Then, using the dev/cli script, step into the Conjur container to run the cukes:

$ ./cli exec
...
root@9feae5e5e001:/src/conjur-server#

Run all the cukes:

There are three different cucumber suites: api, policy, and authenticators. Each of these can be run using a profile of the same name:

root@9feae5e5e001:/src/conjur-server# cucumber --profile api               # runs api cukes
root@9feae5e5e001:/src/conjur-server# cucumber --profile policy            # runs policy cukes
root@9feae5e5e001:/src/conjur-server# cucumber --profile authenticators    # runs authenticators cukes

Run just one feature:

root@9feae5e5e001:/src/conjur-server# cucumber --profile api cucumber/api/features/resource_list.feature

Architecture

Conjur is designed to run in a Docker container(s), using Postgresql as the backing data store. It's easy to run both Conjur and Postgresql in Docker; see the demo directory for an example.

Database

DATABASE_URL environment variable

Conjur uses the DATABASE_URL environment variable to connect to the database. Typical options for this URL are:

  • Local linked pg container
  • External managed database such as AWS RDS.

Database initialization

Conjur creates and/or updates the database schema automatically when it starts up. Migration scripts are located in the db/migrate directory.

Authenticators

Conjur makes it easy to:

  • Enable and disable built-in authenticators
  • Secure access to authenticators using policy files
  • Create custom authenticators

Detailed authenticator documenation

Rotators

Conjur makes it easy to:

  • Rotate variables regularly using built-in rotators
  • Create custom rotators

Detailed rotator documenation

Secrets and keys

Main article: Conjur Cryptography

Conjur uses industry-standard cryptography to protect your data.

Some operations require storage and management of encrypted data. For example:

  • Roles can have associated API keys, which are stored encrypted in the database
  • the authenticate function issues a signed JSON token; the signing key is a 2048 bit RSA key which is stored encrypted in the database

Data is encrypted in and out of the database using Slosilo, a library which provides:

  • symmetric encryption using AES-256-GCM
  • a Ruby class mixin for easy encryption of object attributes into the database
  • asymmetric encryption and signing
  • a keystore in a Postgresql database for easy storage and retrieval of keys

Slosilo has been verified by a professional cryptographic audit. Ask in our Slack community for more details. (You can join here.)

Important: avoid data loss

When you start Conjur, you must provide a Base64-encoded master data key in the environment variable CONJUR_DATA_KEY. You can generate a data key using the following command:

$ docker run --rm conjur data-key generate

Do NOT lose the data key, or all the encrypted data will be unrecoverable.

Account management

Conjur supports the simultaneous operation of multiple separate accounts within the same database. In other words, it's multi-tenant.

Each account (also called "organization account") has its own token-signing private key. When a role is authenticated, the HMAC of the access token is computed using the signing key of the role's account.

Accounts can be listed, created, and deleted via the /accounts service. Permission to use this service is controlled by the built-in resource !:webservice:accounts. Note that ! is itself an organization account, and therefore privileges on the !:webservice:accounts can be managed via Conjur policies.

Versioning

Starting from version 0.1.0, this project follows Semantic Versioning.

Changelog maintenance

The changelog file is maintained based on Keep a Changelog guidelines.

Each accepted change to the Conjur code (documentation and website updates excepted) requires adding a changelog entry to the corresponding Added, Changed, Deprecated, Removed, Fixed and/or Security sub-section (add one as necessary) of the Unreleased section in the changelog.

Bumping the version number after each and every change is not required, advised nor expected. Valid reasons to bump the version are for example:

  • enough changes have accumulated,
  • an important feature has been implemented,
  • an external project depends on one of the recent changes.

Cutting a release

  • Examine the changelog and decide on the version bump rank (major, minor, patch).

  • Change the title of Unreleased section of the changelog to the target version.

    • Be sure to add the date (ISO 8601 format) to the section header.
  • Add a new, empty Unreleased section to the changelog.

    • Remember to update the references at the bottom of the document.
  • Change VERSION file to reflect the change. This file is used by some scripts.

  • Commit these changes. Bump version to x.y.z is an acceptable commit message.

  • Tag the version using eg. git tag -s v0.1.1. Note this requires you to be able to sign releases. Consult the github documentation on signing commits on how to set this up.

    • git will ask you to enter the tag message. These will become the release notes. Format should be like this (note the subject line and message):

      Version x.y.z
      
      This is a human-readable overview of the changes in x.y.z. It should be a
      consise, at-a-glance summary. It certainly isn't a direct copy-and-paste
      from the changelog.
      
  • Push the tag: git push vx.y.z (or git push origin vx.y.z if you are working from your local machine).

  • Create a pull request to have the release acked and merged.

Deleting and changing tags should be avoided. If in any doubt if the release will be accepted, before creating a tag push the (VERSION and CHANGELOG) changes in a branch and ask for approval. Then create and push a tag on master once it's been merged.

Licensing

The Conjur server (as in, the code within this repository) is licensed under the Free Software Foundation's GNU LGPL v3.0. This license was chosen to ensure that all contributions to the Conjur server are made available to the community. Commercial licenses are also available from CyberArk.

The Conjur API clients and other extensions are licensed under the Apache Software License v2.0