search

OWASP / wstg

The Web Security Testing Guide is a comprehensive Open Source guide to testing the security of web applications and web services.
https://owasp.org/www-project-web-security-testing-guide/
Creative Commons Attribution Share Alike 4.0 International
6.98k stars 1.3k forks source link

Properly order document sections #253

Open victoriadrake opened 4 years ago

victoriadrake commented 4 years ago

What's the issue?

The WSTG has a legacy layout that doesn't account for some new sections and tests. I think section 4 itself has become an unnecessary layer, and the test types can be surfaced by a step for easier navigation of the guide. Article titles would benefit from the removal of redundant words, like "Testing of."

How do we solve it?

Reorder sections into a more sensible and futureproof format. I propose alphabetical by major sections, then minor articles. This issue is intended to invite feedback and work on the ordering collaboratively.

For ease of work, I will submit the proposed ordering as a TOC file (#254), which if approved, should replace documet/README.md

TODO:

ThunderSon commented 4 years ago

We need to take into consideration how other projects are setting this up, which could allow for an easier process to migrate if something was to happen. As discussions are erupting as well with the ASVS team in order to make it easier for the mapping between the 2 projects, I think we need to properly discuss this and visualize a structure that could allow us to easily map ASVS to WSTG, if it was to help. @kingthorin and @rejahrehim your input is highly required. V is already in this conversation 😄

kingthorin commented 4 years ago

Hmmm I'm not entirely sure about the alpha ordering.

Dropping chapter identifiers could be fine, but then we also need to drop figure numbering (which is probably fine, but we should agree and be sure).

I think dropping test identifiers is a mistake though (as that's the most simple mechanism by which projects can cross-reference each other's content) and will cause confusion as far as renumbering existing scenarios to match alpha sorting [perhaps we accept that, but we shouldn't do it without thought and perhaps community input (twitter poll??) ].

victoriadrake commented 4 years ago

Dropping chapter identifiers could be fine, but then we also need to drop figure numbering (which is probably fine, but we should agree and be sure).

I think dropping test identifiers is a mistake...

I didn’t think we’d drop either of those; sorry, I scattered my info between the issue and the PR. I’ve updated my issue comment to include everything now. For clarity, the chapter and section numbers should be added in after we’ve settled the ordering (since they will have grown) and same for the test IDs.

patrickceg commented 4 years ago

Syncing with ASVS is definitely a good idea, although I'm worried it won't make sense in a lot of cases. Examples

ThunderSon commented 4 years ago

Those are valid points. Requirements can map to multiple test scenarios, the opposite can happen as well. Requirements are the lowest level in the chain, so I'd expect more from that side. No need to mimic the structure. The structure won't bother anyone. It could assist, and you raised important points to it. I think we'll be able to finalize how this links in 2 weeks if we keep these discussions up 😄

victoriadrake commented 4 years ago

Besides the possibility of sections in WSTG or ASVS moving around in the future, I don't think attempting to match up section numbers with the other guides would be helpful. I worry it will be more confusing than convenient, to @patrickceg's point.

I think the most helpful we could be for creating mappings is just to mention related sections of ASVS in the text of the WSTG, where appropriate.

patrickceg commented 4 years ago

I think the most helpful we could be for creating mappings is just to mention related sections of ASVS in the text of the WSTG, where appropriate.

I was thinking about that, and my idea was another project that just maintains a graph (the discrete mathematics graph https://en.wikibooks.org/wiki/Discrete_Mathematics/Graph_theory#Introduction ) that maps various section or article IDs (OWASP WSTG, OWAS MSTG, OWASP ASVS, Cheat Sheet, OWASP Top 10, CWE, SANS top 25, whatever else comes out next week). The linker project would then have a bunch of interfaces to answer queries including:

I reiterate that's a completely separate project: I'm sure even keeping something like that in sync will be a job on its own.

ThunderSon commented 4 years ago

It is a project currently being studied @patrickceg 😄 I will DM you about it. @victoriadrake let's say we're moving the current structure numbering, what would we use? I am looking into a friendlier way than having <section-number>_<name><test-id>. What would be a neat way to do this? I would love to keep the test structure though, it helps to have unique URLs for tests for references, instead of having 10 tests under one markdown file.

kingthorin commented 4 years ago

The layout has been agreed upon in: https://github.com/OWASP/wstg/pull/254 as follows:

WSTG Table of Contents

github-actions[bot] commented 4 years ago

Please comment if you are still working on this issue, as it has been inactive for 30 days. To give everyone a chance to contribute, we are releasing it to new contributors.

rejahrehim commented 3 years ago

Can we take this forward? We have to make changes in the build scripts accordingly. Need this to be done for Json generation too. @kingthorin @ThunderSon @victoriadrake

kingthorin commented 3 years ago

This one is a bit difficult since it introduces what one might call "breaking changes" as far as where things are located and how they're numbered/sequenced.

I'm personally fine with breaking things in a minor release, however, I understand if others are against that.

patrickceg commented 3 years ago

I'm on the camp of break things whenever the value to the project is worth it because versions and version control systems exist. Place a note on the README that the big section reorg happened between version X and Y. They can always go back by tags or by using the older PDF version.

As a user, I just expect everything to break every release: I've been like that since I started using Android devices... (😁 is there anything in tech that doesn't have breaking changes every time? I think the closest thing for me that doesn't break often on updates is Debian Linux).

It's similar to why you won't want your Dockerfile to reference ubuntu:latest unless you know you'll be in there fixing the build every so often. We have tags on this repository, so for the people who want to link to something less in flux, they can use the tag.

rejahrehim commented 3 years ago

This one is a bit difficult since it introduces what one might call "breaking changes" as far as where things are located and how they're numbered/sequenced.

I'm personally fine with breaking things in a minor release, however, I understand if others are against that.

We are planning for the next big release (V5). Right ? So, We have to do this anyway.

kingthorin commented 3 years ago

The next milestone is currently 4.2.

victoriadrake commented 3 years ago

If we need this reorg, can we go straight to v5?

kingthorin commented 3 years ago

We could delay longer and plan for that I suppose. That’d be fine with me.

ThunderSon commented 3 years ago

Sure, we'd need to make a greater push to give v5 more value to its name :) Let's see what we can manage to do.