Documentation & Reporting
Table of Contents
- Collaboration Tools
- De/Briefing & Presenting
- Penetration Testing Collaboration
- Video Documentation
To Do: * Add Note taking methods
- How I read a research paper
- Start with the first two links, and go from there. They’re both great resources to writing technical documentation, the first being a beginners guide and the second being a general guide that beginners can understand.
- Politics and the English Language - George Orwell
- Tips for Writing Better Infosec Job Descriptions
- Learning the Ropes 101: Stay Beautiful, Stay Verbose
- Three parter from jacobian.org:
- The Ultimate Workflow for Writers Obsessed with Quality - Rob Hardy
How To Write Like It’s Your Job - Bria Hughes(BSidesSF2020)
- Good presentation on increasing your general writing ability.
- Writing a Paper
- Writing Types of User Documentation
- The 7 Rules for Writing World Class Technical Documentation
- Teach Technical Writing in Two Hours per Week
- Learn Technical Writing in Two Hours per Week - Norman Ramsey
- Microsoft Writing Style Guide
- Notes on Technical Writing - Marcus Kazmierczak
- SANS 10 Cybersecurity Writing Mistakes(Videos)
- Writing Tips for IT Professionals - Lenny Zeltser
Tech Writing Handbook - Kyle Wiens, Julia Bluff(iFixit)
- This handbook will teach you how to create everything from manuals to work instructions. We’ll help you avoid the most common pitfalls of tech writing, from poor planning to outdated publishing.
Technical Writing Courses - Google
- "This collection of courses and learning resources aims to improve your technical documentation. Learn how to plan and author technical documents. You can also learn about the role of technical writers at Google."
Learning Technical Writing Using the Engineering Method - Norman Ramsey(2016)
- "This booklet explains how to study technical writing in the context of a weekly group. If nothing else, a group will show you that you are not alone in your difficulties. Problems you may have are problems that others also have, and you can find similar problems even in published papers. But we do not emphasize problems; instead we emphasize useful principles and practices—engineering heuristics—that you can learn to apply to your own manuscripts."
Software Design Documentation/Functional Specifications
- Islandora Software Design Documents
- Painless Functional Specifications – Part 1: Why Bother? - JoelonSoftware
whattimeisit.com - JoelonSoftware
- Functional Specification Example
Controlling Your Environment Makes You Happy - JoelonSoftware
- Should be read in conjunction with the above link.
- Why Writing Software Design Documents Matters - Chris Fox
- How to Write an Effective Design Document - Scott Hackett
How to write a good software design doc - Angela Zhang
- Be sure to read the first comment by John Rote
- Taking Notes
- tool for syncing your markdown documentation with Atlassian Confluence pages.
Note Taking/Management Software
leaps - shared text editing in Golang
- Leaps is a service for hosting collaboratively edited documents using operational transforms to ensure zero-collision synchronization across any number of editing clients.
- Anno is a local, browser-based user interface on top of Markdown files in a given directory. It makes writing, organizing, and searching through those files easy. That's it. There are many benefits to this approach:
- Zim is a graphical text editor used to maintain a collection of wiki pages. Each page can contain links to other pages, simple formatting and images. Pages are stored in a folder structure, like in an outliner, and can have attachments. Creating a new page is as easy as linking to a nonexistent page. All data is stored in plain text files with wiki formatting. Various plugins provide additional functionality, like a task list manager, an equation editor, a tray icon, and support for version control.
- Dnote is a lightweight personal knowledge base. The main design goal is to keep you focused by providing a way of swiftly capturing new information without having to switch environment. To that end, you can use Dnote as a command line interface, browser extension, web client, or an IDE plugin.
- Joplin is a free, open source note taking and to-do application, which can handle a large number of notes organised into notebooks. The notes are searchable, can be copied, tagged and modified either from the applications directly or from your own text editor. The notes are in Markdown format.
- leaps - shared text editing in Golang
- Diagramming Tools
- Ronn builds manuals. It converts simple, human readable textfiles to roff for terminal display, and also to HTML for the web. The source format includes all of Markdown but has a more rigid structure and syntax extensions for features commonly found in manpages (definition lists, link notation, etc.). The ronn-format(7) manual page defines the format in detail.
- Zeal is a simple offline documentation browser inspired by Dash.
Public penetration testing reports
- Curated list of public penetration test reports released by several consulting firms and academic security groups
- Penetration tests done by cure53, good examples of how a report should be done.
- Offensive Security 2013 Demo report
- Public penetration testing reports
Writing a Penetration Test Report
- Writing a Penetration Testing Report by SANS
- Penetration Testing Execution Standard section on Reporting
- Tips for Creating an Information Security Assessment Report Cheat Sheet
- HowTo: Write pentest reports the easy way
- The Penetration Testing Report - websecuritywatch
- Excellent blog post breaking down the various parts, a must read
- Your Reporting Matters: How to Improve Pen Test Reporting - Brian B. King
- LTR101: Writing or Receiving Your First Pentest Report - Andy Gill
Hack for Show, Report for Dough - Brian B. King(WWHF 2018)
- The fun part of pentesting is the hacking. But the part that makes it a viable career is the report. You can develop the most amazing exploit for the most surprising vulnerability, but if you can't document it clearly for the people who need to fix it, then you're just having fun. Which is fine! But if you want to make a career out of it, your reports need to be as clear and useful as your hacks are awesome. This talk shows simple techniques you can use to make your reports clear, useful, and brief. You'll see some before-and-after examples of a bad report made good, with clear explanations of what makes the difference. Those things will be useful no matter what tools you use to create reports. Then, if we have time, we'll look at some Microsoft Word hacks that will save you time and improve consistency.
- Hack for Show, Report for Dough - Brian B. King(WWHF 2018)
Tools that can help
I <3 Reporting -
- Reporting Tips for Penetration Testers
- I <3 Reporting -
- Writing an Request for Proposal
- Report Examples/Samples
Writing Technical Documentation
- The Elements Of Style: UNIX As Literature - Thomas Scoville
- What nobody tells you about documentation - Daniele Procida
Minimalism - Hans Van Der Meij
- Writeup on the 'Minimalist' approach to technical documentation
- wordy is not a grammar checker. Nor is it a guide to proper word usage. Rather, wordy is a lightweight tool to assist you in identifying those words and phrases known for their history of misuse, abuse, and overuse, at least according to usage experts.
- A collection of simplified and community-driven man pages.
CyberSecurity Style Guide Dictionary file(cyber.dic)
- This is the companion dictionary of the Cybersecurity Style Guide. The cyber.dic dictionary file can be added to your word processor to augment its standard spellcheck list. This is a resource for anyone who regularly writes about tech and is not a fan of the red underline that plagues any highly technical document.
Scanning reports to tabular (sr2t)
- This tool takes a scanning tool's output file, and converts it to a tabular format (CSV, XLSX, or text table). This tool can process output from the following tools: Nmap (XML); Nessus (XML); Nikto (XML); Dirble (XML); Testssl (JSON); Fortify (FPR)
- CaptureIT can generate GIFs of both the actively selected window or your entire desktop
- Peek makes it easy to create short screencasts of a screen area. It was built for the specific use case of recording screen areas, e.g. for easily showing UI features of your own apps or for showing a bug in bug reports. With Peek, you simply place the Peek window over the area you want to record and press "Record". Peek is optimized for generating animated GIFs, but you can also directly record to WebM or MP4 if you prefer. Peek is not a general purpose screencast app with extended features but rather focuses on the single task of creating small, silent screencasts of an area of the screen for creating GIF animations or silent WebM or MP4 videos. Peek runs on X11 or inside a GNOME Shell Wayland session using XWayland.
- Debriefing Facilitation Guide: Leading Groups at Etsy to Learn from Accidents - Etsy
- Presentation Tips for Technical Talks - SheHacksPurple
Make your PowerPoint presentations accessible to people with disabilities - support.office.com
- This topic gives you step-by-step instructions to make your PowerPoint presentations accessible to people with disabilities.
- Kvasir is a vulnerability / penetration testing data management system designed to help mitigate the issues found when performing team-based assessments. Kvasir does this by homogenizing data sources into a pre-defined structure.
- Dradis is an open source collaboration framework, tailored to InfoSec teams.
- Faraday introduces a new concept (IPE) Integrated Penetration-Test Environment a multiuser Penetration test IDE. Designed for distribution, indexation and analysis of the generated data during the process of a security audit. The main purpose of Faraday is to re-use the available tools in the community to take advantage of them in a multiuser way.
- Lair is a reactive attack collaboration framework and web application built with meteor.
- DART is a test documentation tool created by the Lockheed Martin Red Team to document and report on penetration tests, especially in isolated network environments.
- Serpico is a penetration testing report generation and collaboration tool. It was developed to cut down on the amount of time it takes to write a penetration testing report.
- Vulnreport is a platform for managing penetration tests and generating well-formatted, actionable findings reports without the normal overhead that takes up security engineer's time. The platform is built to support automation at every stage of the process and allow customization for whatever other systems you use as part of your pentesting process.
- sh00t is a task manager to let you focus on performing security testing. Provides To Do checklists of test cases and helps to create bug reports with customizable bug templates
Video Recording/Visual Documentation
Open Broadcaster Software OBS
- Open Broadcaster Software is free and open source software for video recording and live streaming. Cross Platform, Windows/OsX/Linux
- This application will make a screenshot of the desktop. If the desktop consists of multiple monitors, it should still work fine. However it has only been tested with a dual monitor setup. The windows project has the added functionality of sending the screenshot to a server of your choosing.
- Record terminal sessions and have the ability to replay it
- A tiny chrome extension to record and replay your web application proof-of-concepts. Replaying PoCs from bug tracker written steps is a pain most of the time, so just record the poc, distribute and replay it whenever necessary without much hassle.
- kap * An open-source screen recorder built with web technology
- UEFI DXE driver to take screenshots from GOP-compatible graphic console
- ScreenToGif allows you to record a selected area of your screen, edit and save it as a gif or video
- Open Broadcaster Software OBS
- Sample/Template Documents
- OWASP Vulnerability Disclosure Cheat Sheet
- NCSAM: Coordinated Vulnerability Disclosure Advice for Researchers
- Protecting Your Sources When Releasing Sensitive Documents
- Good comparison of various forms of disclosure
- Threatbutt irresponsible disclosure policy
- The CERT Guide to Coordinated Vulnerability Disclosure - Allen Householder
- Dealing with the press/journalists:
Selling 0-Days to Governments and Offensive Security Companies - Maor Shwartz(BHUSA2019)
- Selling 0-days is a fascinating process that not a lot of people are familiar with. This talk will discuss a vulnerability brokerage company called Q-recon and provide a glimpse of how this market works. In the presentation, questions will be answered from three different angles: researcher, broker and client
- Selling 0-Days to Governments and Offensive Security Companies - Maor Shwartz(BHUSA2019)