Add ReqView format as generated output

[rfricz]

We’ve written the code to generate the ASVS as a document template for ReqView requirements management tool. The added value is that you can customize and trace security requirements throughout the product development lifecycle.

The intended usage of this document template is to define and implement security requirements comprehensively as described at OWASP Top Ten Proactive Controls 2018 – C1: Define Security Requirements. The user would link the ASVS security requirements to User Stories (Needs), Use/Misuse Cases, SW Requirements Specification (SRS), Risks, Tests etc.

We’ve incorporated the ASVS document in the Example project included in ReqView webapp. Detailed information about the template can be found at ReqView documentation.

ReqView makes managing ASVS requirements really convenient:

• You can find all the explanatory text (Control Objectives, Glossary, References etc.) that applies to the currently focused section, chapter or requirement in the Instructions pane (resolves Machine parseable format does not include informative text #821 in a way).
• The CWE and NIST § columns show clickable links to the corresponding items – no manual searching like when using the PDF version.
• Apart from L1/2/3 columns that are displayed just like in the md docs, you can use additional attributes for easier workflow.
• You can switch between user role based Manage view, Traceability view and dedicated Compliance views with predefined per-level filters and additional Owner, Compliance Status and Evidence columns useful to both assessors and people responsible for compliance.
• You can trace ASVS requirements using custom traceability matrix, see the image below.
• You can export fully customizable documentation in HTML, DOCX, XLSX, PDF, ReqIF, or any custom text format.

ReqView data format is open, JSON-based and documented by JSON schemas. It’s also similar to the JSON that you already generate.

[elarlang]

Hi.
however useful the tool is, personally I don't think that the ASVS as a free and open-source project should add an output format for the commercial tool. This can be used on the tool side as an adapter.

My opinion applies to any tool, I think the standard should only handle the content for the standard and provide general (static) output formats.

I leave the issue open to get feedback from other leads, ping @tghosth @vanderaj @jmanico @danielcuthbert

[rfricz]

We tried to just adapt first, but markdown source is not very adaptable into an app and the generated JSON is too stripped-down. Modifying the JSON generator was the only way to keep all the important information and structure. The output is also static, general and easily processable by any tool or script. I think it makes ASVS more accessible and useful.

Could you please explain the reasons why it shouldn’t be added? What are the downsides?

[elarlang]

Could you please explain the reasons why it shouldn’t be added? What are the downsides?

I feel I already said everything I had to say. So I'll leave it for others to have some opinions on it.

I agree that the markdown is not a friend for apps, as it is not strongly structured data. This is also a problem for the development or export of the chapter texts - it expects a certain format, but there is no guarantee that the markdown is or will be written that way. This is also one of the reasons, why #821 is stuck.

Personally, I think that we should not develop it in markdown as it causes so many problems and bottlenecks, but till there are no resources to build or adapt any technical solution for that, we keep using what we have.

[tghosth]

Hi @rfricz, I appreciate the interest in ASVS but I don't think we will be able to accept this PR and I am going to close it for now. I appreciate this may be disappointing but there are a couple of issues here and at the end of this comment I have another idea that might be helpful for you.

---

However useful the tool is, personally I don't think that the ASVS as a free and open-source project should add an output format for the commercial tool.

I am inclined to agree with this perspective. Whilst the ReqView data format may be open, it does seem to be designed specifically to fit with the way that ReqView works and seems less likely to be useful for other purposes.

---

Could you please explain the reasons why it shouldn’t be added? What are the downsides?

Anything that is committed into this repo becomes our responsibility to own and maintain and the current mechanisms are already not ideal. This would be a quite complex addition to an already not ideal situation and if we make a change to the MD files tomorrow and suddenly the output export script stops working because of this format, that is now our immediate problem to debug and fix.

I think the best option would be to keep this for yourselves in a fork or a separate repo and just reference back to the parent repository.

---

If you are interested, we maintain a list of ASVS users here: https://owasp.org/www-project-application-security-verification-standard/#div-asvsusers

You could add an entry for ReqView saying something like:

• ReqView - "We use the ASVS as part of the Example project included in the ReqView webapp"

If you are interested, you can PR that in here: https://github.com/OWASP/www-project-application-security-verification-standard/blob/master/tab_asvsusers.md

[rfricz]

I understand the potential maintenance issues, we can keep it separate. However, the CycloneDX format is very specific and it is included.

Thanks for your consideration and for pointing to the ASVS Users page, I’ll add a PR to it.