Web/Security reorganization

[wbamberg]

This post is to propose a new organization for the docs under Web/Security. There is more stuff we might end up with there, but this is the initial set.

• Threat modelling for developers

  A single page that outlines in practical terms the kinds of things a website might be doing that make it a potential target for specific sorts of attacks. For example: if you have signed-in users, and use cookies to authorize state-changing requests (for instance form a form) then you're potentially a target for CSRF attacks.

• Fundamental security practices checklist

  A single page that lists the basic things a developer should consider doing, to secure their site. Things like: using HTTPS, setting sensible cookie attributes, restricting framing. This would point to separate docs, mostly under "Defenses", for more detail.

• Theory

  A directory of pages, each of which describes some theoretical aspect of web security. These pages don't generally map to anything particular a developer is going to do, but are background conceptual knowledge that they need. The canonical page is the one on same-origin policy, but the current pages on TLS and secure contexts might also fit there. These are what Diataxis calls Explanation.

• Attacks

  A directory of pages, each outlining a type of attack that a website might be vulnerable to. This section would include things like: XSS, CSRF, Clickjacking. Each of these pages is split into two sections, the first describing the attack and the second describing defenses. Most of this is in place: https://developer.mozilla.org/en-US/docs/Web/Security/Attacks. From a Diataxis point of view, these are a bit more like How-to guides, but are probably more conceptual and high-level than most how-tos. So they're a bit of a blend between Explanation and How-to.

• Defenses

  A directory of pages, each outlining a defense. This section would include things like: using HTTPS, using fetch metadata, setting SameSite, SRI, framing protection. I wasn't originally planning to have this, but as I've worked through the attacks it's clear that there's a many-many relationship between attacks and defenses - for example, framing protection is a defense against several attacks. So I'm getting quite a bit of duplication in the "defenses" section of the "attacks" doc. So it might be better to document defenses standalone, and then point there from "attacks".

  One question: why are some things, like "Using fetch metadata", here under Defenses, and others, like "Using CSP", under HTTP? I don't have a good answer to this.

Another question is, what happens to the existing pages under Web/Security? I'll deal with this in a follow up.

[pransh15]

Hi @wbamberg, thanks for submitting this proposal. I like this idea, let's see what everyone has to say. I'll share it with the team to see if they have any thoughts they would like to share here.

[dipikabh]

Thanks for putting this together, @wbamberg. I think some sort of grouping would certainly help give clearer direction to developers, instead of our current listing of all the guides.

I'm trying to visualize how this would pan out and have a few clarifying questions:

• It looks like we'll be creating more landing pages that would link to many of the same underlying content pages. Is that correct? For example, "Fundamental security practices checklist" feels quite similar to "Defenses", but is it meant to approach the topic from a different angle?
  As you've mentioned, the single-page checklist would link out to pages under "Defenses". Would it make sense to position the checklist as an overview (almost a cheat sheet) within the "Defenses" section, rather than as a separate top-level item?
• How do our existing Practical security implementation guides fit in the proposed structure? These feel very much on the lines of "how-to" guides. So there may be room for both "Guides" and "How-to" under "Security".

If you can map our existing pages under each of these sections, it might help with understanding the proposed structure better.

[dipikabh]

I think it's better for discovery for it to be a separate page.

My bad. By "section" in ""Defenses" section", I was really referring to the "Defenses" folder.
I might be off here but maybe you're probably not proposing a folder for each of those bullet points, which is how I was looking at it.

They will cease to exist

From what I remember, the Practical guides were added at the time Observatory was added to MDN (Tools > HTTP Observatory), so there might be links from that tool to these guides.
@chrisdavidmills can probably chime in more here.

[wbamberg]

I think it's better for discovery for it to be a separate page.

My bad. By "section" in ""Defenses" section", I was really referring to the "Defenses" folder. I might be off here but maybe you're probably not proposing a folder for each of those bullet points, which is how I was looking at it.

Oh I see, yes. I was confused because in this proposal I had "Defenses" as a directory containing multiple pages (like "Attacks"), but having talked things over a bit with @hamishwillee I'm now experimenting with making it a single page.

They will cease to exist

From what I remember, the Practical guides were added at the time Observatory was added to MDN (Tools > HTTP Observatory), so there might be links from that tool to these guides. @chrisdavidmills can probably chime in more here.

That's right, that is where most of these guides come from (though I'm not sure where the form autocompletion guide came from - it was added in the same PR (mdn/content#33793) but I don't see it in the Observatory docs (https://infosec.mozilla.org/guidelines/web_security.html). But I will make sure any links from the Observatory end up somewhere sensible.

[chrisdavidmills]

That's right, that is where most of these guides come from (though I'm not sure where the form autocompletion guide came from - it was added in the same PR (mdn/content#33793) but I don't see it in the Observatory docs (https://infosec.mozilla.org/guidelines/web_security.html). But I will make sure any links from the Observatory end up somewhere sensible.

@wbamberg @dipikabh as long as the links from HTTP Observatory still point to/redirect to equivalent information sources, I think we are OK. Let's do a check around the time you come to do these deletions/redirects.

The Form autocompletion guide has nothing to do with Observatory. When I originally did a bunch of restructuring of the security section, it was one pre-existing guide that I felt we should keep, but didn't really know what to do with, so I ended up putting it there, as it seemed like a practical guide of sorts.

I don't have a strong opinion about it. If you want to put it somewhere else, or even remove it, I'm cool with that.

[wbamberg]

Let's do a check around the time you come to do these deletions/redirects.

I'm more than happy to ask you to review and PRs that touch these pages.

didn't really know what to do with, so I ended up putting it there, as it seemed like a practical guide of sorts.

Do you think we could find a home for it somewhere in the LA Forms pages?

[chrisdavidmills]

Let's do a check around the time you come to do these deletions/redirects.

I'm more than happy to ask you to review and PRs that touch these pages.

Yup, sounds good.

didn't really know what to do with, so I ended up putting it there, as it seemed like a practical guide of sorts.

Do you think we could find a home for it somewhere in the LA Forms pages?

I think this would be a reasonable place for it, yes. Especially given that we are probably going to move the LA forms module out of the LA into its own dedicated module, as it is really too advanced for an LA module.