What Not to Document and Why_ (North Bay Python 2024)

We’re hopefully all on board with writing documentation for our projects. However, especially with the rise of supply-chain attacks, there are some aspects of our projects that we really shouldn’t document, and should instead remediate as vulnerabilities. If we do document these aspects of a project, it may help someone compromise the project itself or our users. In this talk, you will learn why some aspects of documentation may help attackers more than users, how to recognize those aspects in your own projects, and what to do when you encounter such an issue.

These are slides as presented at North Bay Python 2024, with one minor modification to add the URL of a tweet screenshotted in the presentation.

1. What Not to Document and Why?
Don’t Help Hackers by Highlighting Risks
Margaret Fero
@MaggieFero(@hachyderm.io)
For North Bay Python 2024

2. Overview
Case Study: The 0Day Docs Caused
Overview of Some Common Vulnerabilities in Docs
What to Watch Out For
What if it’s in somebody else’s docs?
Review

3. Case Study
The 0day Docs Caused

4. Quick Terminology Overview
A person trying to
use your system to
cause harm, real
or simulated
Attacker Vulnerability
A way that an
attacker could
cause harm
0day /
Zero Day
A vulnerability
publicized or
exploited without
prior warning to
the development
team, named for
the 0 days of
advance notice

5. In late 2019, a
Security Researcher
Got Stuck
●SwiftOnSecurity got
stuck
●They read the docs!
●Very normal, good
job adhering to best
practices
https://twitter.com/SwiftOnSecurity/status/1202034106495832067

6. Within an hour...
Another researcher
responded!

7. This ended up CVE-2019-15006.
Oops.

8. CVE-2019-15006
●Affected: Everyone who used the Confluence Previews plugin in
Confluence Server or Confluence Data Center
●Potential Impact: An attacker could see files that were edited, edit files, and
possibly access user information
●Time to patch this before public disclosure: 0 days

9. What went wrong here?
●Almost no security issue has one single root cause
●Software
●Documentation
●Researchers

10. Common Vulnerabilities in Docs
Authentication, Authorization, and Disclosure! Oh my!

11. URLs Used in Authorization
Users Get
●A URL to Allowlist
●A better understanding
of how you handle
Authorization
Attackers Get
●A high-value target
point

12. Common Examples
●Secret Admin Console
●Alternate versions of pages
Example: old.reddit.com
●Unpublished pages (like testing or dev)

13. Default Passwords/Keys
Users Get
●The key they need to
set up, and change it if
desired
Attackers Get
●The key that
almost-every user is
definitely still using

14. Common Examples
●IoT devices, especially cameras and networked printers
●Routers and other equipment
●SaaS products given as employee benefits

15. Password Requirements
Users Get
●A clear outline of what
criteria your password
must meet
Attackers Get
●Exact regex criteria for
faster, easier
bruteforcing and other
password attacks
●A way to reduce the
solution space
●Often, information
about your tech stack

16. Common Examples

17. Any Setting You Don’t Recommend
Users Get
●Curious about what it
does
●A desire to try it out
and see if it’s really as
bad as you made it
sound
Attackers Get
●A strong hint that you
can get unexpected
behavior by playing
with this now-shiny
new toy

18. Common Examples
●Configurable page limits over a certain value
●Anything that “may cause a crash”
●Anything you’re thinking about putting a security warning on

19. How Will I Know?
Signs and signals that you might have a problem

20. “Not Recommended”

21. Insider Information

22. Concepts You Don’t Fully
Understand

23. What if it’s in somebody else’s docs?
You can still try to help!

24. security.md
Information about how
the repository owner
would like to receive
security reports

25. ●Try not to exaggerate or downplay the severity
●Mention who’s affected
●Be polite and kind
●Include any information you have about the fix; if it’s easy, providing a patch
in the email upfront is often very much appreciated
How To Approach That Email

26. In Conclusion
Here’s a review of what we covered!

27. When In Doubt, Call It Out
●Some things that turn up in your docs are signs of a security vulnerability
●If something feels fishy in a document, ask a teammate, the maintainer, or if
you’re a solo maintainer, a trusted peer
●Security is always a team effort
●Note that none of these vulnerabilities are fixed by just not documenting!

28. Thank you!
https://linktr.ee/MaggieFero