Web security docs for MDN
This page contains a video recording of the presentation made during the session from Breakouts Day 2024, along with a transcript. Video captions and transcript were automatically generated and may not properly translate the speaker's speech. Please use GitHub to suggest corrections.
Table of contents
See also:
Video
Transcript
Will Bamberg: Okay. So welcome to this session.
… thanks for coming. It's called web security, Doc. Nd. And the the point of it really is to present
… where we currently are on planning some new documentation for MDN. About
… web security, and to ask your feedback on where we are and where we should be going next. to put it very quickly.
… So
… my name is Will Bamberg. I'm a technical writer. I work for open web docs, which is a kind of collective of writers who work on web platform documentation of one sort or another, and most of our work takes place on as contributions to MDN, various and MDN repositories.
… yeah. So
… about the session the starting point here is recognition that we need better web security documentation on MDN. We had, though there was a workshop last year called Secure the web Forward and Florian from open web. Docs presented at that at that
… session about web security documentation, and one of the outcomes was that we would do some work to make an outline for some better docs. We could have an MDN. And we've done some of this work since then, and this is in a sense, an update on that.
… I suppose, where we are right now in open web docs, we have essentially, we have a committed project proposal. And that basically means that we are, we're kind of prepared to fund the work. We better do the work really in in 2024, like we have. But we have an approved project, which is like a vehicle for writing these docs.
… In the first half 2024
… and we have a draft outline for the work which I'm going to go through in this
… presentation. What we're looking for
… from this session really is feedback on the plan we have so far, especially sort of high level feedback. We're in pretty early stages. So we can we can get. We can accept all kinds of feedback. We're especially interested in high level feedback on the whole approach
… and the shape of the docks we've come up with so far. That's the first piece, and the second piece is, if this is going to be an ongoing project for the next few months, or we actually write this stuff we'd love to have like ongoing detailed review from
… security experts. So that's the the next piece which won't happen today, but would hopefully be happening in the kind of weeks and months to come.
… That's what we're what we're trying to get out of the session. Really?
… More meta stuff about the session. Please, mute, when you're not speaking. If you have a question or want to make comment.
… please raise your hand in zoom. I guess you couldn't do that the
… queue thing, and I ask you as well to ask a question as well. It says the hash session not being recorded, session is now being recorded, but only the presentation part, not the discussion part. I believe.
… There are notes being taken in IRC. Florian's agreed to be a scribe. So thanks for that.
… and finally, a reminder that this breakout is operated under the W3C Code of ethics and professional conduct.
… So like, I say, this starts off with that with and with an idea that we need better sketch docs. And Nbn. I think this is pretty much unarguable, like a lot of
… MDN. Reference documentation is quite often
… very good, and very often quite good.
… So things like the reference docs we have on Csp is is is good reference documentary we have on cause is good. You know.
… But the
… documentation that's more kind of guidance. Tutorial, and especially stuff that kind of
… crosses over domains. Right? So, stuff that's like about specifically can live within. Say, Http is going to be pretty good. But documentation, which crosses over from one domain into another is quite often lacking on MDN, and so over here on the left hand side. I've got basically the dock tree for
… the developer, mozilla.org slash web slash security. There's all the docs under that
… and what I say about this is that it's th. There is some good content here, but it's completely disorganized like it's it's it's it's not possible. I don't think for somebody's look at this, and really use it in a kind of systematic way to have a more secure website.
… And and and and there there are some some pages that look like they're gonna be good. There's a page like called securing your site. You think this is. This is, gonna be great, and it's not great. It's like there's a lot of missing content and a lot of content that is, there is a is a little bit kind of random
… and so I think, really, what was missing here is this kind of systematic approach. Once you know, what? What do web developers need to know to have a more secure site. And how can we help them get to that point? And that's, I think, really, what's missing an MDN. At the moment.
… And so we've done some thinking about this. And and I mean one thing, I think, which helps people is
… categorising documents. They know what kind of thing they can expect to find in a particular place. So everything isn't at all kind of mixed up together in one big
… morass. So we've got
… here. We have 4 different categories of docs we've come up with.
… Theory is
… well, I guess, fairly obviously not practical guidance. It's like things you need to understand, to make sense of other things. But it's not. It doesn't really have a kind of immediate and practical payoff.
… Now, the classic thing there is things like talking about the same origin policy like like how that gets implemented in browsers.
… and why it matters. And then there's also things about like secure design principles which we think is kind of theoretical.
… The second
… category, which is the one I'm mostly going to talk about, is practices.
… and the idea of that is, it's it's things you have to take care of. and I'll I'll go more into that later.
… And there's a category of attacks, and there's a category of tools, and I think both of those are
… moderately well served on MDN. Like tools. Especially is the kind of thing that tends to live in a particular domain, and it tends to have a lot of reference documentation for it. So like we have docs on Csp, we have docs and Sri, now that
… they're okay to? Very good, you know. So yeah, so the main thing I want to talk about here is is this top right?
… Category practices.
… And it it feels to me this is where this project would at the moment
… wants to spend most of its time, and this is where we'd write most of the docs.
… and I. So I've I've cast. I've I've characterized this as things a developer might need to take care of.
… So especially if you're doing this particular thing, then you probably need to care about these issues that will come up. And the reason I think this is useful is that it's kind of tied to what people are doing like. They know what they're doing. And so if they know if they know the things they're trying to accomplish. We can say if we're trying to accomplish those things, they don't need to worry about all of these other things, and so I think it kind of ties into their activities and their needs
… relatively, closely, which makes it a bit more accessible.
… And these these are the. These are focused on concrete practical guidance. So so the idea is, these are specific things you can do which you can understand. You know how to do them right.
… So practice? And so to that end
… the idea is, there is a list of topics underneath there which are related to specific kinds of things that a site might want to do. So if it's going to have users who sign in, if it's going to have users who provide input. To the site. If it's going to use a lot of third party software, then there are specific things you're going to have to take care of.
… And so that's the the general principle of organization here is to say, we we're going to have for the main. The most important thing is we're going to have docs for security practices, and
… possibly each of these is a separate document. Possibly some of them might split up into multiple docs. I think that's the thing which would come out as we write them.
… But that's the general idea. I'm not going to go into
… all of these right now. I have. I have slides I should like. So I can show you, I guess quickly. So we have like
… hit the authentication. The idea is like these are the kinds of things you need to cover if you're dealing with authentication. And so we have to some extent kind of fleshed out the detail of each of these topics. But I think working on this is is is for the is for the next kind of weeks and months, like figuring out exactly what fits into each of these topics is A is a more of a detailed question. Although we are interested in feedback on this right now, I think it's not my main focus today.
… one
… security practices, Doc, that I'll talk about a little more is the idea of having a security practice one. One which is.
… The idea of this is that it's things that are like.
… it's sort of it's almost like, if you don't do anything else, do this right. And and and I think the idea is these are things that are hopefully, relatively straightforward to do and have a very high payoff in terms of security.
… So
… th. This is not supposed to be an exhaustive guide, but this is like this is a a a place to kind of start from place to our foundation, from
… So this is one
… one spread practice guide. We we could have that isn't really specific to a particular thing you do, but it's like, a baseline you should establish.
… So those are. That's like a a real quick overview of where we where we are right now.
… I'm interested in
… everything people have to say about this really. Iii want discussion to be open. I've got a few points here that have come up in the course of our work. The first is obviously feedback, as I said, on the overall shape. Does it make sense to talk about this so structured, this in terms of security practices.
… Does a list of security practices?
… Seem like a sensible one to be starting off with can people see major omissions or major issues of trying to explain things like this?
… The next thing that's come up that I'm not that sure about yet is how to talk about frameworks. So I think a lot of these practices. It makes sense for people to use frameworks. Right? You know the the the answer is, really, use a reliable framework and follow what it recommends that you do.
… And I'm a little unsure how we should integrate that kind of conversation into these docs. And and and I'm interested in feedback on that. As a rule. As a rule, MDN. Doesn't talk a lot about frameworks. It tends to talk
… a lot about web standards. And
… but I think it's important to talk about frameworks here, right? So that does it
… a bit of a question now of how we're going to do this. and the last piece of this is a excuse me.
… The last piece of this is, I've called it the fear of imperfections. And the idea of that is that I
… it's it's II find it difficult to write about web security sometimes because there's a feeling that you have to be perfect, and that if you're not perfect, you should say nothing and kind of one extreme of this, I think it does actually appear in MDN. This statement, where it sort of says, if you want your site to be secure, you just need to hire somebody who knows what they're doing right. And so you just just just put put this off on a third party.
… and I'm I'm I'm I'm a bit uncomfortable with that. I think it's because I think a lot of people just won't do it. And so there's this
… issue of you know, how can we help people who
… may not be perfect, how can we help them be better?
… So again, this is question like, on the on the one hand, the the one extreme. You just don't need to give people any guidance. You just say like, get somebody else take her up for you on the other extreme, you say, do what we say, and you'll be fine, which is also not true. Right? So how do you? You know? How do we kind of
… resolve that kind of tension. I suppose you know. Where do we? How do we pitch this in terms of the docs?
… Those are 3 questions.
… but if you have any other feedback, I'm interested in that, too.
… and that's
… that's the end of my presentation. So
… I'm interested to what people have to say.