CSP source expression syntax

[wbamberg]

(This is an expanded version of mdn/content#35947 (comment), which I thought deserved wider consideration.)

I've been doing some work on CSP lately, and have some suggestions for how we document CSP source expressions.

Background

CSP consists of a number of directives, each of which controls some aspect of the security policy. Each directive has its own syntax. The biggest group of directives are the fetch directives, which control the resources - images, fonts, scripts, stylesheets, workers, etc - that a document may load.

According to the spec, fetch directives all have the same syntax: https://w3c.github.io/webappsec-csp/#grammardef-serialized-source-list. This is: either the keyword value 'none', or one or more source expression values, which can take various forms.

History

Obviously, we need to document the source expression values that each directive may take. Back in the days of the {{page}} macro:

• the script-src* and style-src* pages transcluded their content from default-src
• the other directives transcluded their content from connect-src

Then through mdn/content#5732 and mdn/content#11185, we ended up factoring the source value syntax into a single separate page: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/Sources. All fetch directives (plus a couple of other directives that have the same grammar) point to this page for the syntax. For example: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/font-src#source-expression-list .

Although I advocated for this at the time, I didn't understand fetch directive syntax very well and now I think this was a mistake.

Problems

Although per spec, source expressions all have the same syntax, in practice they don't: although you are allowed to use, say, unsafe-hashes in a connect-src directive, it won't have any effect. See for example w3c/webappsec-csp#22 for a similar question.

So I think listing all source expression values as valid values for all fetch directives is confusing: it makes the syntax seem more complex than it really is, while forcing developers to understand that depending on the directive they're looking at, many of the listed values aren't actually applicable.

I've tried to look at this systematically in https://docs.google.com/spreadsheets/d/1UtOEWR4j-lxClWwbxOMLEjFwIBnSgO0L9x-VXgKHiCc/edit?gid=0#gid=0: columns are source expression values, and rows are fetch directives.

As far as I can tell:

• For all fetch directives except default-src, script-src*, and style-src*, the only effective values are <host-source>, <scheme-source>, and 'self'

• default-src can accept any values

• script-src can accept any values, and script-src-elem can accept any values except unsafe-hashes

• style-src and style-src-elem can accept the same values as their script-src* counterparts, except they cannot accept unsafe-eval, wasm-unsafe-eval, or inline-speculation-rules.

• script-src-attr and style-src-attr can only accept unsafe-inline, unsafe-hashes, and report-sample

Proposal

My proposal is something like:

1. have a complete list of all source expression values in the main CSP reference page (perhaps under https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directives). This would give us a place to explain in enough detail things like the syntax of a hash source expression.
2. in each fetch directive page, list only the source expression values relevant to that directive, and for each of these values, link to the relevant bit of (1) for all the details

[pransh15]

Interesting proposal, @wbamberg. Thanks for writing, and sharing with all of us! Hope this will be discussed in the Content call next Monday. 👍

[wbamberg]

Thanks for the suggestion! The next content call is a holiday where I am, and it's not in a good timezone for some people that I'd hope might have input. So I'd love to see feedback in this thread.

[hamishwillee]

As per mdn/content#35947 (comment) I agree that what we do not doesn't work - the sources are too separated from where they are used and so context is lost. We can solve this either by choosing to duplicate content, or link as you are suggesting. Duplicating is best for readers, linking is best for maintainers. Either is better than what is there now.

I am not sure about having the sources in the directive page vs in default-src. I kind of like the default-src since it can take all the arguments anyway, that means you don't have to link elsewhere for more information in that page.
The arguments for the fetch directives page are that

• this is already a large page so you're not making it much more complicated.
• you can get a flavour for what is available without cluttering any of the lower pages.
• We can provide more targeted advice in default-src - i.e. take the time to make the point that not all values are used as default for all directive types, and recommend especially recommend that if script-src is not overridden that hashes are used here.

If it were entirely up to me, I would be inconsistent and do limited duplication on the cases where we have only a few options.
So:

• For script-src-attr and style-src-attr I would duplicate unsafe-inline, unsafe-hashes, and report-sample
• Probably for all fetch directives except default-src, script-src*, and style-src*, I would duplicate <host-source>, <scheme-source>, and 'self , and none - it is quite a lot of duplication, but they should never be different, and it saves readers having to jump around.

[wbamberg]

Thanks for this response!

As per mdn/content#35947 (comment) I agree that what we do not doesn't work - the sources are too separated from where they are used and so context is lost. We can solve this either by choosing to duplicate content, or link as you are suggesting. Duplicating is best for readers, linking is best for maintainers. Either is better than what is there now.

I am not sure about having the sources in the directive page vs in default-src. I kind of like the default-src since it can take all the arguments anyway, that means you don't have to link elsewhere for more information in that page. The arguments for the fetch directives page are that

• this is already a large page so you're not making it much more complicated.

• you can get a flavour for what is available without cluttering any of the lower pages.

• We can provide more targeted advice in default-src - i.e. take the time to make the point that not all values are used as default for all directive types, and recommend especially recommend that if script-src is not overridden that hashes are used here.

Yes, I'm also not sure which is best here. Perhaps I will pick an option and see what it looks like. I think documenting the values in https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy#fetch_directives feels "cleaner", and makes the directive pages more consistent.

If it were entirely up to me, I would be inconsistent and do limited duplication on the cases where we have only a few options. So:

• For script-src-attr and style-src-attr I would duplicate unsafe-inline, unsafe-hashes, and report-sample

• Probably for all fetch directives except default-src, script-src*, and style-src*, I would duplicate <host-source>, <scheme-source>, and 'self , and none - it is quite a lot of duplication, but they should never be different, and it saves readers having to jump around.

That means that in most cases we choose duplication, which I agree with. The only cases where we would not are:

• script-src, where we can just say "takes the same values as default-src"
• script-src-elem, where we could say "takes the same values as script-src, except unsafe-hashes"
• style-src, which is a bit awkward because there are quite a few omissions, when compared with default-src
• style-src-elem, where we could say "takes the same values as style-src, except unsafe-hashes"

...so I might be tempted to duplicate style-src as well.

[hamishwillee]

...so I might be tempted to duplicate style-src as well.

Yes! The less we have to say in each of these pages and the less we have to out-link the better.

[bsmth]

Thanks, both. Another +1 from me for some selective duplication in the sub pages for the benefit of readers.

I'm also not sure which is best here. Perhaps I will pick an option and see what it looks like.

This is a good idea, I think we'll get a feel for it on a PR, but the proposals are already sounding like a great improvement, IMO.

[wbamberg]

Filed mdn/content#36792 for this.

[bsmth]

Looking great, well done