Browsable hosted pragmatic example site for compliance-masonry

[aegershman]

In order to provide quicker comprehension for users considering compliance-masonry, a browsable holistic/pragmatic example site presented alongside compliance-masonry (possibly https://github.com/opencontrol/freedonia-compliance) could be generated and hosted.

This way folks could get an immediate hands-on demonstration without having to stitch together an example themselves to see how compliance-masonry lays things out and how it benefits them / their organization(s). This could be hosted as a static site on github pages.

Apologies if this issue is more appropriate in a different repository; it felt right to post it here in the core repo for compliance-masonry, even if an example site were hosted elsewhere (again, freedonia maybe...? though it'd be nice if the examples were fairly pragmatic and close to what would actually be used for managing/submitting compliance documentation for nist/fedramp/hitrust/soc2/etc. certification... not to discount the FredRAMP certification)

Thanks for folks' time and consideration 👍

[pburkholder]

Hi Aaron,

So, Freedonia readme gets you to this:

visit your HTML SSP at http://localhost:4000

So you'd like to see something like freedonia.app.cloud.gov that actually hosts that content?

Or are you wanting an example that takes Freedonia a few steps farther toward what's really needed for compliance, e.g. filling out a FedRAMP templated SSP?

--Peter

[redhatrises]

Also, one can argue that https://github.com/opencontrol/freedonia-compliance is a browseable example

[pburkholder]

Also, Gabe (@redhatrises) could you email me if you have time to chat about what's working well for getting from structured content to OSCAL? I could use some help at cloud.gov before I waste time in blind alleys. (My email is in my GitHub profile)

[redhatrises]

@pburkholder email sent

[aegershman]

@pburkholder yes, to clarify I mean a built browsable clickable demo site; there's the pdf output there (https://github.com/opencontrol/freedonia-compliance/blob/master/assets/example.pdf) but it's a bit buried in the readme, and why not have it in static site format so the linking / browsing / searching is more accessible.

Building freedonia locally requires getting the cli, setting up a workspace, (not to bad so far), and then having to figure out how to build the site locally with gitbook which is deceptive because gitbook-cli seems to have stopped working on npm many versions ago (see https://github.com/GitbookIO/gitbook-cli/issues/74 and https://github.com/GitbookIO/gitbook-cli/issues/68 and so-on; it'll barf errors everywhere when you try to gitbook build/serve), so you have to use docker (as per this example) to run gitbook using these commands

# to host for localhost:4000
docker run --rm -it -p 4000:4000 -v "$PWD/exports":/srv/gitbook fellah/gitbook:2.6.7

in my opinion that's a lot of pain just to get to a point of evaluating what the end-result site looks like (besides the pdf output of course, which honestly is nice)

but since the built gitbook is a static site, it could be built with gitbook (using docker) with

# assuming you want to build site assets into /docs folder
docker run --rm -it -v "$PWD/exports":/srv/gitbook -v "$PWD/public":/srv/html fellah/gitbook:2.6.7 gitbook build . /srv/html

And then using github pages to host the site. For free 😲 which, as a sidenote, could then double as a value-add demonstration of not requiring an active server to host auditing and compliance documentation.

/cc both @redhatrises @pburkholder I suppose this issue is more appropriate to have in the freedonia repository; but-- as it stands, the freedonia example is too convoluted and lacking substance (sorry freedonia) to be able to really demonstrate why it's worth investing in. It needs more content with actual answers for controls; even something like the generated-system.yml in this example-pipelines/output would be good, because those examples are relatable and feel like reasonable guideposts for teams who'd be interested in using this to structure answers to their questions https://github.com/opencontrol/example-pipelines/blob/master/output/generated-system.yml -- and it doesn't really show how "dependencies" for other systems can be used, setting up inheritance for shared-responsibilities, or, the biggest for me personally, the value-add of using opencontrol as a way to set up separations of responsibility between "platform" (cloud foundry) and "application teams" who can inherit answered controls. And unfortunately many of the other real examples don't seem to be active (such as https://github.com/18F/epa-notice/blob/master/opencontrol.yaml https://github.com/Mirantis/compliance https://github.com/cloud-gov/cg-compliance/tree/opencontrol (rip) and so on)

EDIT: the redhat opencontrol doc seems like a solid maintained example https://github.com/ComplianceAsCode/redhat

I realize these are kind of two separate issues: one about having built static site to browse, and another about the actual content of that site. Maybe it'd be more appropriate to have that in freedonia. In either case, I'm more than happy to submit issues and PRs to enhance existing demonstrations with more content to demonstrate the value-add, if there was interest.

with all this said, what're your thoughts on it?