Cobalt Core Contributors Program Lessons Learned

To enhance our documentation with fewer resources, we’d like to get help from our community. Our Pentest community includes many people who know how to “educate” our customers on “best” security practices.

We’ve completed our “first” sprint, we’ve published our first doc contributions from our pentesters (as of Aug 19), in Best Practices. We’ve discussed our lessons learned in the Cobalt Core Slack, in an internal channel. We’ve laid out these lessons learned here:

Themes:

• Our pentesters had difficulty gearing their work to our intended audience. We were not specific about this audience.

• They need substantive examples of active voice

• They want confirmation for references / sources

• They think we need to “dumb down” articles

We plan to address the “lessons learned” in the following ways:

Discuss our target persona, Berry Busy.

• Startup developer

• 1+ years of experience

• Graduate of software “bootcamp”

• Learns about security via Stack Overflow

• Not “dumbing down” per se, but we’re teachers

Include a recommended “Markdown Cheatsheet”

• Shorter Cheatsheet

• Microsoft Cheatsheet

• Markdown lint tool

Create examples of “Active Voice”

• Start with Google Tech Writing course description of Active Voice

• Take examples from each article. Compare passive voice with active voice

Original Article PR	Updated Article PR	Reasoning
Input validation is a very important aspect of writing secure code	To create secure software, you need code that checks user input	Point to the reader. Specify what they needAvoid most “adverbs” like “very” and “Important”. We want our docs to stand on their own
If an application fails to properly validate untrusted user input, it might lead to security vulnerabilities such as:	Without such checks, you could see security vulnerabilities such as:	Use content from previous sentencePoint to the reader
Business Logic flaws, Denial of Service, Injection flaws, and such.	Business Logic flawsDenial of Service attacksInjection flaws	Bulleted lists are always easier to read than “inline lists”

Original Article PR	Updated Article PR	Reasoning
Security misconfigurations are failures to implement necessary security controls in any software component.	Move to new section (Description)	Content is beyond an introduction
Usually, these are the mistakes done while moving the code from development to the production environment.		Content too general and specific. Moving from the dev to production environment should not automatically lead to mistakes (and if so, we’d need specific examples)
OWASP has categorized security misconfiguration as a separate category A05:2021.	OWASP includes security misconfiguration in their Top 10 Web Application Security Risks (2021)	Readers won’t recognize “A05:2021”
These misconfigurations could lead to sensitive information disclosures and in some cases can also lead to data or system compromise.	Misconfigurations may lead to:Disclosure of sensitive informationData or system compromise	Bulleted lists are easier to read

Original Article PR	Updated Article PR	Reasoning
Server-Side Request Forgery (SSRF) is a server-side security vulnerability that allows a malicious actor (attacker) to make arbitrary requests from the application’s server.	No change.	It’s a good declarative statement. While it’s passive voice, it’s OK to set up definitions in passive voice
SSRF, given its impact and likelihood, has been rated at 10th position in the OWASP Top 10 (2021) vulnerabilities.	SSRF is ranked 10th in the OWASP Top 10 Web Application Security Risks (2021) based on its impact and likelihood.	Moved before “Description”. It’s a good intro statement that describes the importance of SSRF
Praise: Love the bulleted list	Slight modification, to help readers put the bulleted list in categories	************