I have summarized existing proposals, and I have replied to some of them:

On 30. 07. 20 1:02, Gabe Alford wrote:

...

- Rename description, rationale to html_description, html_rationale.
Reason: We could start to introduce Markdown input, and doing it this
way would allow us to do it gradually. We probably want to have
html as
a canonical form, but we could offer more possibilities for
content authors.

I don't think changing keys like this makes sense or adds value, and in fact, will make things more confusing. Just supporting markdown in the text would better and easier for people to understand.

Jan also isn't in favor of changing keys. I think that we can shift to markdown without changing keys only if we convert existing HTML markup to md at the same time. And I think that this can be feasible.

There are the following problems with preserving key names and introducing new input type:

1. Autodetection of HTML vs MD isn't trivial: Markdown can contain HTML tags - consider e.g. XCCDF value substitutions in an otherwise markdown rule description. 2. Blank lines have some significance in markdown, but not at all in HTML, so if we start processing existing tag-less text as markdown, the text layout may change significantly.

Technically, processing text as markdown is extremely easy to implement, it would just require to add a new project dependency.

- Restructure project's folder structure - right now, the list of
products is really long, which makes the project page too long.
Having
products in a separate directory would also allow us to get a list of
supported products programmatically from the filesystem.

I really don't want to do this again. Not in favor, and there is nothing preventing getting the list programmatically right now.

FTR, Jan is not in favor of this either. But when we ask ourselves a question why could it be that a project is perceived as complex, isn't this one of the first oddities one comes across? That linux_os is a container of rules, but rhel7 is a product? That ssg is not a product, but a Python package? Neither cmake is a product, but support for the build system, along with build-scripts? That applications/openshift is a container of rules much like linux_os, just being located elsewhere? And did you know that we now have an ocp-resources folder in the root directory?

I think that a folder structure would make things more approachable, and that moving just products wouldn't cause a big pain - the only thing that is likely to be used by others is one or two profile files in the product they are interested in.

- Put macros where they belong. We have plenty of boilerplate in the
project, and macros can keep the code readable and free of
duplicates.
Moreover, if people use a macro to e.g. instantiate an XCCDF
variable,
we can change the underlying implementation without breaking the
public API.

Answering a bit to myself, Jan also supports this, and it is not really breaking.

Similarly, items proposed by Jan s.a speeding the build up and replacing shared remediation functions with macros aren't breaking either and can be done gradually.

Vojta's item, reorg of templates, could break the internal API, but as we got zero complaints about our last template reorg, that proves that nobody else cares about how templates are implemented, so that one is not a breaking change either.

Now Gabe's items:

• Merging platform and prodtype together

That's IMO a great candidate - it can break things, but this duality is indeed very confusing. It was also proposed by Jan

• getting rid of jinja in rules and using the industry standard of

tailoring to increase readability

I don't understand this one.

First of all, what is meant by "industry standard of tailoring"?

And what is the problem of having jinja in rules? As we have templated rules, it is obvious that there will be a lot of repetition in description, rationale and OCIL, and jinja is a good way how to avoid copy-pasting.

• Divorce the content from the build system like Chef Inspec, Ansible,

and other security tooling that is coming from the government.

Decoupling the content from the build system is also proposed by Jan, and I am on board. I have problems understanding the precise meaning of the second part of the sentence "... like Chef Inspec, ... and other tooling". What is meant by that? That we should be able to build not only datastreams, but e.g. Ansible playbooks?

• Feedback from many consultants and SAs is that things need to be

made easier and simpler. That it's too hard to do anything.

We could have various ideas how to improve this, but the really serious way how to address this would be to conduct a UX study, and then allocate a considerable amount of time to address findings. Consultants and SAs should go through the SecurityLabs self-paced training before trying to do anything serious in the project, that will save them quite a lot of time.

• Moving all product configurations necessary to add a new product

from code to product.yml

I am totally on board as well. I wouldn't see it as a breaking change though.

Dne 30. 07. 20 v 9:16 Jan Cerny napsal(a):

Hi Matěj,

Thank you very much for opening this topic.

Please find responses inline.

On Wed, Jul 29, 2020 at 5:59 PM Matej Tyc matyc@redhat.com wrote:

...

The PR https://github.com/ComplianceAsCode/content/pull/5606 introduced a large number of changes that may break patches, but those changes were much needed in the project. So I think that we should use this opportunity to introduce more changes, so we introduce only one pair of versions between which things could break, as opposed to breaking many times in a row in the future.

In general I would like to reduce breaking changes to minimum.

...

So what I think we could consider?

• Rename description, rationale to html_description, html_rationale.

Reason: We could start to introduce Markdown input, and doing it this way would allow us to do it gradually. We probably want to have html as a canonical form, but we could offer more possibilities for content authors.

I like the idea of using Markdown instead of HTML. However, I think that renaming the keys will make the rule.yml format less understandable. I think everyone understands `description` and `rationale` intuitively. But having `html_description` and `description` at the same time will confuse people. We should keep only `description` and `rationale`. I think it's possible to support HTML and Markdown at the same time and the build system could detect the format automatically.

What about possible more future formats? Is it really that trivial to distinguish between markdown and html?

• Restructure project's folder structure - right now, the list of

products is really long, which makes the project page too long. Having products in a separate directory would also allow us to get a list of supported products programmatically from the filesystem. Do I understand it well that the concern is that the product directories are all located in the project's root directory? I don't think this is a problem. I admit that 67 items in the root directory can't be skimmed in a second, but it doesn't cause any big trouble. People usually know which product they want to work with and they do `cd product_name` right away. I'm against this change. The community members have their patches that will all break because all the paths will change. The fact that the project page looks long doesn't justify such a big change. And you can get the list of products programmatically even in the current layout by searching for all directories containing product.yml.

...

• Put macros where they belong. We have plenty of boilerplate in the

project, and macros can keep the code readable and free of duplicates. Moreover, if people use a macro to e.g. instantiate an XCCDF variable, we can change the underlying implementation without breaking the public API.

I like this proposal.

...

Most of these changes is just about crafting and running a sed command, plus comparing the result before and after - I have in mind large-scale changes that don't require a large amount of time to perform.

You have proposed putting macros where they belong which will involve manual work.

...

What do you think? Do you have other suggestions you would add to the list?

I have some ideas, but most of them require a larger amount of time to perform.

• Continue with decommissioning Bash remediation functions in favor of

Jinja macros, because the mechanism of including the shared Bash functions is troublesome.

• Decouple content from the build system.
• Speed up the build.
• Unify platform assignment. This is now solved by a combination of

prodtype, platform and file name. I find this complex.

We were also talking about restructuring templates a bit, e.g. creating a folder for each template and putting there template files together with a Python script which would perform eventual data manipulation. It would make everything more clear. The need of modifying large Python file templates.py would go away. I believe it shouldn't break anything, it will require change in build system. I actually started working on it a bit but I didn't get far.

Regards

...

---

scap-security-guide mailing list -- scap-security-guide@lists.fedorahosted.org To unsubscribe send an email to scap-security-guide-leave@lists.fedorahosted.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedorahosted.org/archives/list/scap-security-guide@lists.fedor...