Add a way to include other files besides components, standards, and certifications.

[DavidEBest]

Currently, there's no way to include other files when getting all components, certifications, and standards. Would like to have an includes section in the yaml for misc data.

This will fix some broken links in the gitbook

[afeld]

@jcscottiii Do you have a branch for this? No pressure...just curious.

[mogul]

Example: Search for "diagram" in https://compliance.cloud.gov/system_documentation/system-description.html

[afeld]

Let's investigate if there's a workaround for this that requires little to no code/example changes, e.g. "put all required assets in the markdowns/ folder" or just giving instructions of "we don't support embedding assets...use links instead". Leaning towards the latter since embedding in a Word doc could get complicated.

[jcscottiii]

There's two parts missing:

1. Inclusion of the files into the opencontrols workspace
   • The code for including the files from moving to artifacts https://github.com/opencontrol/compliance-masonry/blob/3d62b3e6c9b7cf3a1165dc63d13baf83b13f957e/src/renderers/certifications_to_gitbook.py#L26
2. Rendering of the included files
   • The code about rendering images from the python days https://github.com/opencontrol/compliance-masonry/blob/3d62b3e6c9b7cf3a1165dc63d13baf83b13f957e/src/renderers/certifications_to_gitbook.py#L47

[jcscottiii]

There are 2 cases for inclusion that happen. 1) Inclusion of files that are next to the component.yaml and 2) Inclusion of completely different folders (e.g. BDD in https://github.com/opencontrol/cf-compliance)

1) Inclusion of files local to component.yaml

Currently, given a component (e.g. UAA) has the following files in the directory:

UAA
|
|- component.yaml
|- auth-diagram.png

Both files will be included into the components folder in the opencontrols workspace already. It makes it easier for renderers will take the component.yaml and create the appropriate media because the pictures are right next to it. That's the easy case.

2) Inclusion of completely different folders

This doesn't currently happen. Looking at https://github.com/opencontrol/cf-compliance, there's a BDD folder and it's not included.

This following line uses BDD but the link would be broken. https://github.com/opencontrol/cf-compliance/blob/8b76705b9e7d62d77f3d09831822121f69addc45/CloudController/component.yaml#L134

The proposed solution is to add an includes section to the opencontrols.yaml

Then when it comes to rendering, it will do like the old python code and prepend an includes folder to the path when making the image/URL path because it knows all local files should be there.

Conclusion

Well, since I'm putting files in includes in step 2 but not step 1, that will complicate search logic for resources for the renderers so I propose that we add ALL extra local files to the proposed includes folder.

In the end, part of your opencontrol.yaml will look like:

includes:
  - BDD # path will be "includes/BDD"
  - UAA/auth-diagram.png # path will be "includes/auth-diagram.png"

Why be so explicit about what you're including and not letting things next to component.yamls be automatically copied into the includes folder? Because that's magic and rather be explicit....

[afeld]

@jcscottiii Thoughts about my comment above? I want to be very careful about us over-promising anything with this feature. With Word docs as a common format for system security plans, we can't (easily) do anything with included files. Even embedding images could be tricky. Therefore, it feels safer to me to punt on it (for now) and tell people to use external URLs. Thoughts?

/cc https://github.com/opencontrol/schemas/issues/13

[jcscottiii]

@afeld I agree that the latter of the two would work and be the cleanest. (The former would require code changes because inherited markdowns are not included right now)

It brings about another problem about hosting those assets but you know ¯(ツ)/¯ not on us now lol. But a great alternative would just have people host it in their repos and point to the raw links.

[afeld]

a great alternative would just have people host it in their repos and point to the raw links

Yeah, that seems like the easiest thing for now, though I could be convinced that we should try and figure this out for images, at least. How do you want to proceed?

[jcscottiii]

I created a new issue to research it: https://github.com/opencontrol/fedramp-templater/issues/19

We need to create a how-to-use or FAQ for the component.yaml. In that, we could say for now, "If you want to use images, just use the link to them. We are currently researching on improving this via research on this issue.."

I can create this.

[afeld]

Another relevant issue: https://github.com/18F/cg-compliance/issues/166. @brittag mentions there that architecture diagrams aren't readable shoved into a table cell in a Word doc, so these would need to be provided as an attachment or a link anyway.