ASVS
ASVS copied to clipboard
OWASP
lowercase vs uppercase grammar (original: 6.2.1 causes capitalization inconsistency)
Other attacks in the document such as "brute force", "rainbow table", "phising" are all in lowercase but in this requirement "Padding Oracle" is all in uppercase which may cause confusion for people who never heard about it. Especially considering Oracle is a well-established company in technology field.
My proposal is to write it in all lowercase as other attack methods.
We can change this requirement, but I think we need to set some rules in place and follow proper grammar in the document.
Does anyone have some good grammar rules to point out?
ping @tghosth @jmanico @Sjord
Yes. Use a tool like Grammarly to check your grammar.
not helpful in this case, as it does not know which words are names for something and which are not.
Padding Oracle
I agree that this should be lower case, and also the following should be lower case:
- libraries do not contain Easter eggs
- This should prevent Web Cache Deception attacks.
- Verify that the application is protected against ... Formula Injection
- to prevent ... Request Smuggling
- Verify that proper certification revocation, such as ... Stapling
I think in these cases uppercase is acceptable:
- JavaScript, LaTeX, Markdown, GraphQL, WebSocket
- CSV, HTTP, SMTP, API
- Content-Type, Set-Cookie
When an abbreviation is written in full it is often capitalized. I think these also should not be capitalized:
- Server-side Request Forgery (SSRF)
- Insecure Direct Object Reference (IDOR)
Currently all requirements start with "Verify that". I would rather omit that.
The first sentence of a requirement is often pretty clear and grammatically correct. The second sentence is often problematic; written for a different audience than the first, or gives a recommendation instead of a requirement:
- Registration and forgot password functionality should also have this protection.
- Strongly consider logging only in UTC if systems are global to assist with post-incident forensic analysis.
- Permissions should still be allocated using roles.
The requirements table should not have markdown formatting, because this doesn't work if it's exported to CSV or another format. Currently the links to proactive controls are the biggest problems here, and I suggest removing them.
Thank you @Sjord :) There is an entire Internet full of every kind of grammar rules, can you also point out some good ones for me to educate myself and to follow here?
Let's focus on this issue only on the lowercase-uppercase grammar topic.
I would say we don't have markdown in our requirement texts, extra links, and mappings we have discussed (#810, #847) already a long time ago and I agree, that those must be removed. We need to wait for a "nod" from @tghosth for that (https://github.com/OWASP/ASVS/issues/810#issuecomment-645002831). (edit: I later figured out that you created a PR #1877 for that)
Other requirements we need to fix or improve case-by-case.
I think capitalization is partially subjective or a matter of taste, as opposed to a strict grammar rule that is right or wrong. There are several style guides with an opinion about capitals, and most instruct to use capitals sparingly:
- Capitalization - Microsoft Style Guide | Microsoft Learn
- Capitalization | Google developer documentation style guide
- IEEE style guide p21
- Wikipedia:Manual of Style/Capital letters - Wikipedia
There are also some existing OWASP style guides:
I think it would make sense for the ASVS or perhaps the whole of OWASP to pick an existing style guide as a base, and then add some clarifications to it. No need to reinvent the wheel.
Yes, whatever are those rules, they just need to be applied through the document.
Honestly I am happy for specific suggestions but I don't have strong opinions over this
I would like to have 2 outcomes from this:
- The entire document fine-tuned
- All change decisions documented as the ruleset for the future
@Sjord - is this something you would like to do?
Timeline-wise, maybe it makes sense to do this when we finalize the document. At the moment there is no point in putting effort into the chapter texts, only to the requirements.
I'll add that Bishop Fox publishes a cybersecurity style guide that might be of assistance. I'm open to compiling a style guide or doing grammar and style checks when ready.
Good pointer @EnigmaRosa :)
This might be interesting when we are closer to a draft :)