cyberark/conjur

CyberArk Conjur automatically secures secrets used by privileged users and machine identities

Conjur

Conjur provides secrets management and application 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.

• Getting Started
  • Compatibility
• Community Support
• Migrating to Conjur EE
• Architecture
  • Database
    • DATABASE_URL environment variable
    • Database initialization
  • Authenticators
  • Rotators
  • Secrets and keys
    • Important: avoid data loss
  • Account management
• Versioning
• Contributing
• License

Table of contents generated with markdown-toc

Getting Started

Please refer to our Quick Start Guide for detailed information on using Conjur Open Source for the first time, or, refer to the Conjur docs for specific guides relating to setup, integrations, administration, and more.

Compatibility

We strongly recommend choosing the version of this project to use from the latest Conjur Open_Source suite release. Conjur maintainers perform additional testing on the suite release versions to ensure compatibility. When possible, upgrade your Conjur version to match the latest suite release; when using integrations, choose the latest suite release that matches your Conjur version.

When upgrading your Conjur server running in a Docker Compose environment to the latest suite release version, please review the upgrade instructions. For any questions, please contact us on Discourse.

Community Support

Our primary channel for support is through our CyberArk Commons community here

Migrating to Conjur EE

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

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 design documentation

Rotators

Conjur makes it easy to:

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

Detailed rotator design 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 CyberArk Commons 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.

Contributing

If you’re interested in running Conjur locally and learning about how it works, please see our Contributing Guide. It includes helpful instructions for Conjur development and debugging, including:

• Development prerequisites
• Building Conjur as a Docker image
• Setting up a local development environment
• Running the test suites
• Pull request workflow
• Style guide
• Changelog maintenance

If you have any questions, please open an issue or ask us on Discourse.

License

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.

Copyright (c) 2020 CyberArk Software Ltd. All rights reserved.

conjur's Issues

Document the !deny statement

The website policy reference does not yet document !deny.

Are the Cucumber links in sidebar useful enough to be there?

https://possum-www.itci.conjur.net/

Bottom of sidebar:

It's good to know the project you're using is being tested, but I think these links clutter up the sidebar and most people would rather see a public CI job anyways.

If we want to call attention to these, is there a different place we can put them? Linked to in the README section under 'Running tests' header or something?

Links from the quick tour should open in a new tab

When a first-time user is going through the quick tour, we want them to retain context and not lose sight of their progress. If they have to hit Back to find the tour page again (and then make an effort to open the original link in a tab themselves), that's an obstacle to their learning.

It's probably fine to use the same tab for navigation elsewhere, but for the quick tour I think it's important.

Pipeline build on master auto-deploys Possum to Heroku

With this, we can probably get rid of the other build jobs such as possum_nodeb.

Installation page on possum site needs more detail

https://possum-www.itci.conjur.net/installation/

Right now it just links out to two other pages, but it really should be more filled out and explain briefly what the difference between 'server' and 'client' are. An architecture diagram would be helpful here.

Screenshot:

Recommend an analytics dashboard for KPIs

Consider auto-sending the reports to email/Slack
Okta integration would be nice

Did we do away with loading policies as security_admin?

policy load no longer requires --as-group security_admin. Is that feature gone for possum?

Should the quickstart text on cpanel be a link to the docs instead?

Screenshot:

There is some helper text though, but it doesn't really get you very far. Logged into the Conjur CLI in an ephemeral container. What if we linked to the quick tour on the possum site instead? That way we could change them independently too.

Add instructions for website development to the README

As a project contributor, I want a simple and obvious way to run the website in development mode so that I can make additions and fixes.

Container based CLI tool instructions

Tutorials give the user the option of Docker container w/ CLI or install from source. As a developer, I'm far more likely to go the docker route out of simplicity. I got stuck setting up my container based CLI because I hadn't mounted a volume so I could load policy.

Proposed Solution : update the start command to something like:

$ docker run -v $(pwd):/policies -it conjurinc/cli5

Potentially, update the documentation to include the container based CLI syntax:

# conjur policy load bootstrap /policies/conjur.yml

Code examples we want people to copy should have clipboard functionality

We have a mix of code blocks throughout the site. We should have copy-to-clipboard functionality (preferable without Flash) to make it easy for people to copypasta.

That said, I noticed that we do have some code blocks that are 'explainers', we don't want people to copy them. The copy button could signify this difference.

Confused about the multiple policy files in delegation tutorial

https://possum-www.itci.conjur.net/tutorials/policy/delegation.html

We have 3 policy files in this tutorial: conjur.yml, backend.yml, frontend.yml. Can someone help me understand why this is a good pattern? For me, I'd just like to have one policy.yml file in my project repo that defines the application's Conjur setup.

That said, there are also consumable resources like AWS keys that multiple projects may need. I think we need to add some guidance to the site on how to place policy files, if that doesn't exist already.

OpenAPI compatible APIs

Get our APIs compliant with https://www.openapis.org/ (basically an open, consortium-driven evolution of Swagger) and use their tools to build online docs for them.

Extended options are supported for listing resources

As a Possum API user, I want to be able to search, count, and paginate when I list resources.

GIVEN I pass search, count, limit, or offset
WHEN I list resources
THEN I see only the specified information

Dev notes:
Searching, counting, and pagination should work the same way they do in Conjur v4.

Create a meaningful CONTRIBUTING.md

This has to be more than just a placeholder - it has to really inform community developers on how to contribute.

Homepage is too text-heavy, needs a diagram above the fold

https://possum-www.itci.conjur.net/

See <diagram here> - @typaulhus is working on this I believe.

Custom authentication tutorial needs more specifics about accounts

The custom authentication tutorial kind of glosses over accounts.

For example, It has a reference to an account variable here:

but doesn't set it anywhere.

Later, in the example, it uses an account of myorg in the request for a URL that it says should work. The request fails, though, because the account doesn't exist.

Finally, in Client Configuration, CONJUR_ACCOUNT needs to be set before the Ruby REPL is started.

API docs for one API is available online

Using the OpenAPI tools, create API docs for one method (say, the authenticate method) and make sure it works end-to-end for readability, publishing, etc.

The docs site has an improved Conjur theme

Creation of a Conjur theme to be used on the Jekyll docs site with improved functionality and branding.

• Sass broken out into partials
• Search
• Responsive Nav
• Sidebar for sub-navigation items
• Footer
• Links to Community (Github, Slack, Twitter, etc)

Wireframes: http://8vjyzx.axshare.com/#g=1&p=home

Initial Comp

cpanel site design should match Conjur branding

If it will be public, the design should be consistent with Conjur brand, so when users come to create accounts, it is a seamless experience.

Loading a policy when your credentials are incorrect gives a cryptic error message

This happened when I had an environment variable set incorrectly (wrong username):

$ conjur policy load --replace bootstrap conjur.yml

error: 401 Unauthorized

If I was new to Conjur I might not be able to figure out what this error message is telling me (I'm not logged in). Can we implement a better error message here?

Extra html tag in tour.html page

There's an </p> tag in the "https://possum-www.itci.conjur.net/tour.html#programming-conjur" section below "Note" that should be removed.

Ruby API tutorial would be much easier with an example github project

https://possum-www.itci.conjur.net/tutorials/integrations/ruby.html

There is a lot of 'setup' in this tutorial, copy/pasting files, setting up possum environment. The time to value is too long IMO.

One solution is to have a github project that is linked with this tutorial (not sure on all the mechanics at this point). That way, someone can just clone the repo, run docker-compose up -d/similar, and get to work.

Loading a bootstrap policy documentation is confusing

I got really confused when I got to this section: https://possum-www.itci.conjur.net/tour.html#loading-the-bootstrap-policy

The first line:

To load the policy, use the CLI command conjur policy load <policy-id> <policy-file>

made me think I had to run a command, but had no idea what the policy-id should be. It might be helpful to either put bootstrap policy load command

# conjur policy load bootstrap conjur.yml

at the end of the previous section or at the top of the Loading the Bootstrap Policy section to reduce confusion.

Rename "bootstrap" policy to "root" policy

It's been suggested that "root" is a more natural name for the top-level policy, and I concur.

Should --replace be the default way to load policy?

In these tutorials so far:

• https://possum-www.itci.conjur.net/tutorials/policy/applications.html
• https://possum-www.itci.conjur.net/tutorials/integrations/ruby.html

We're always calling conjur policy load --replace .... Should --replace be the default option, instead of a flag that you have to set every time for common workflows?

Page TOC would be better as a floating sidebar on the right

For example, the TOC/prerequisites are taking up all the space above the fold for the Quick Tour

Instead, I think we should have a floating right sidebar for the page TOC, like on our current devsite. The TOC can move with the page, so it's always easy to navigate. This also removes the need for a 'back to top' button.

CLI page on devsite, for example:

Quick Tour should link out to other pages when possible

https://possum-www.itci.conjur.net/tour.html

Other than at the top and bottom, this page introduces a ton of new concepts and ideas that are doc'ed in the Reference/other sections. We should 'link up' the Quick Tour so that people don't get lost in the terms/ideas.

Document the !delete statement

The website policy reference does not yet document !delete.

jq tool should have a link when mentioned in tutorial

See the note in this section: https://possum-www.itci.conjur.net/tutorials/policy/delegation.html#delegation-concepts

So we call out jq, but there is no link to it - hurts discoverability. Many people will know what jq is, but not all. A hyperlink would fix that.

https://stedolan.github.io/jq/

PR templates exist for contribution

Subject line says it all - we need PR templates to set the expectations for contributions to the repo.

Secrets can be retrieved in batches

As a user of the Possum API, I want to be able to retrieve batches of secret values efficiently.
GIVEN I request /secrets and pass multiple ids
WHEN I read the response
THEN I get the values of the secrets I asked for

Dev notes:

This needs to be implemented a la core in Conjur 4. The /secrets route isn't a hard requirement, but the route should be mappable from the v4 route (the same way other routes are).
Tasks:
implement batch retrieval
port/write cukes

Organization name does not permit whitespace or the colon ":" character

It's currently possible to create an conjur account that includes a space, like so:

export CONJUR_ACCOUNT='Awesome Org'

This appears to work when authenticating, but causes problems further down the line, for example when trying to show a variable:

root@9317596fe079:/# conjur show variable:db/password
error: bad URI(is not URI?): https://possum-ci-conjur.herokuapp.com/resources/Awesome Org/variable/db/password

We probably want to disallow spaces in account names. If not, we should identify commands that fail when there is a space in the account name and fix them.

'Runtime Integration' link is broken on Tutorials page

https://possum-www.itci.conjur.net/tutorials/

The 'Runtime Solutions' link in the sidebar works fine.

We should name the link the same thing in both places.

"conjur policy load" throws a confusing message when passed an empty file

Steps to recreate:

1. From CLI, create an empty file called foo.yml
2. Attempt to load:

# conjur policy load foo foo.yml

Result is the following:

{
	"error": {
		"code": "validation_failed",
		"message": "policy_text is not present,policy_text undefined method `each_with_index' for nil:NilClass",
		"details": [{
			"code": "validation_failed",
			"target": "policy_text",
			"message": "is not present"
		}, {
			"code": "validation_failed",
			"target": "policy_text",
			"message": "undefined method `each_with_index' for nil:NilClass"
		}]
	}
}

Message is fine, but I don't think we should have Ruby specific errors bubbling up into error messages.

conjur policy list subcommand would be really helpful

After I had gone through and loaded policies I wanted to double-check my work (harder with no UI).
So I did conjur policy list, which isn't a command.

The command I was looking for was conjur policy list, but it's actually conjur list -i -k policy. Can we alias conjur policy list to that?

"Copy to clipboard" needed for anything the user is asked to paste from the web docs

Broken link in tour.html

Conjur Tutorials link is broken on bottom of https://possum-www.itci.conjur.net/tour.html. It looks like the issue is that the scheme needs to be https rather than http

• http://possum-www.itci.conjur.net/tutorials/ (fails)
• https://possum-www.itci.conjur.net/tutorials/ (works)

Ensure that Possum runs and reports the cucumber tests in Jenkins

I don't see Cucumber test reports in the Jenkins jobs.

Document the !revoke statement

The website policy reference does not yet document !revoke.

Extra space in Possum CPanel

In the possum-cpanel quickstart, the last step has an extra space after $:

$  conjur authn login -u admin -p 19fjyeh3kdeprx3g9bnnasz0mk31eza6yz28rbvvxed34mzf2q4th

should be:

$ conjur authn login -u admin -p 19fjyeh3kdeprx3g9bnnasz0mk31eza6yz28rbvvxed34mzf2q4th

Links in tour prerequisites section are broken

Both links here are broken: https://possum-www.itci.conjur.net/tour.html#prerequisites

Docs site has a improved/simplified "Get Started" flow.

Streamline the onboarding (Get Stated) flow for developers, so they are able to get up & running quickly with Possum.

Design for the product upgrade experience

When someone goes live with v5.x, what will be their experience upgrading to 5.x+1 and beyond?

"CLI" and "client" are used interchangeably in the web docs

We should be consistent and clear by picking one and sticking with it across the board.

Should -i be the default for listing objects with the CLI?

It seems like it should be, since the output using -i is much more human readable. What if instead we had a -v flag for verbose that spit out all the data? Then by default the command output is human-readable and you have to use -v for machines (which often don't use the CLI anyways).

Demonstrate how to use RESTCLIENT_LOG to trace REST calls from Ruby

Link-related issues on the Conjur Quick Start / Installation instructions

The following links result in a 404 or Can't Be Reached error:

Top Bar:

• Downloads
• GitHub Project

Quick Tour Page:

• API Reference
• Conjur Server
• Conjur CLI
• Runtime Integration

Tutorials Page:

• Policy

Other link issues:

The links on the nav section on the Quick Tour are in a different order than the sections on the page.

Google analytics are running on the doc site

As a Conjur member, I want insight into how users are using the site and where they fall off.
GIVEN I'm on the Conjur CE site
WHEN I navigate around
THEN my actions are tracked on Google Analytics
AND a funnel is setup to track the percentage of users who complete the tutorial.

What to do after CPanel quickstart

Once I've completed the steps in the possum cpanel quickstart, it's not clear what I should do. It might be helpful to have a link that goes back to the documentation site or opens the documentation site in a new tab.