cyberark / conjur Goto Github PK

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.

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

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.

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.

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.

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.

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.

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.

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

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:

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

The website policy reference does not yet document !delete.

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

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

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.

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

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

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?

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.

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/

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.

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?

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)

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

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

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

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.

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

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.

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

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.

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:

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

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

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

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

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.

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?

The website policy reference does not yet document !revoke.

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).

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

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.

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

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.

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.

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?

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.

The website policy reference does not yet document !deny.

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.