Features July/August 2021

Cybersecurity & Documentation: Security Considerations for Authors

By Bridget Khursheed

Security is a concern for technical communicators now more than ever. Cyberattackers thrive on opportunity. For example, rogue actors were exploiting COVID-19 as soon as the pandemic started. This article examines the risks and the solutions, or at least mitigations, that technical communicators can put in place now, along with best practices for yourself and your team. I first gave this article as a TCUK 2018 presentation, but while time has passed, and specific malware has evolved and changed names, the message remains the same.

Security: The More It Changes, the More It Stays the Same

One big change is that we now know our data is valuable. It is used by everyone from social media platforms advertising to data gathering organizations voter profiling during Brexit and recent U.K. and U.S. elections. This value is exploitable because more of our lives are online. For example, in my industry (financial technology, known as “fintech”), former ING CEO Ralph Hamer said in 2017, “We want to be a tech company with a banking license.” But while current circumstances conspire to make it easier than ever to gather our data even for apparently innocent activities like targeted advertising and market research, companies may not always be aware that they are under the same level of scrutiny by bad actors.

Long-term reconnaissance using open-source intelligence (OSINT) and less legal methods, is a part of all attack preparations. And, unfortunately, there is no guaranteed protection whether your organization is tiny, has a “less interesting product,” or is a low-key charity: you may still be the entry-level practice for an apprentice hacker or a key trust component gathered for a spear phishing attack. High schools have been hacked to get access to senior executives whose children attend the schools. In the U.K., the Woodland Trust charity had its shop and systems knocked out by ransomware this past holiday season. Information security is, therefore, everyone’s business if we are going to make it work, and not just IT’s and the cybersecurity team’s concern. Consider this: it looks like the definition of information that needs to be kept safe is a little fuzzier than we might previously have thought.

So how does this affect technical communicators?

Why Your APIs and Docs Are Already a Target

The question to ask first is, what are the goals of the attackers? Money and data come first, then we could add “celebrity” in the hacker community, and even training. As we have mentioned, no company is too small to escape notice. It isn’t just software companies like health, government offices, and many more that suffer the attention of bad actors. But at the top end of global information reconnaissance, the global API attack landscape is lucrative, mature, and well-defined. The Payment Services Directive (PSD2) means that banks operating in the E.U. must now have open APIs with potentially rich pickings. But even before that, operations security (OPSec) experts like Stuart Peck at ZERODAYLABS were saying, “APIs are the first place we look.” For security experts, the API—and by extension all company documentation—is useful when preparing for an attack. OSINT is data collected from publicly available sources to be used in an intelligence context; That is, what can be viewed more or less legally.

Online documentation is so interesting because of the gems it may contain, everything from names of colleagues, email address structure, what programming language is used, implementation details, and even hardcoded passwords! If it is auto-generated and not checked, it may be that the bad actors are the first to see this. API issues blur the line between code and docs and so become the communicator’s problem, too. An example can be found in a 2019 OWASP talk given by Skip Hovsmith, Principal Engineer and VP Americas Critical Blue. He, like Stuart Peck, describes “new business opportunities” appearing as a result of public APIs. He points out that APls are well documented at a time when reverse engineering has never been easier and sums up some danger areas:

  • Structured styles like REST are often easy to guess
  • Leaky APls may disclose implementation details and error handling
  • Hidden APls may be accidentally exposed by autodoc services

We will talk about those a bit more later.

Security: What Are the Risks?

Before we get more specific, let’s take a look at what the results of this material being available to bad actors might be. We agree docs are targets, but what is the worst that can happen? Maybe we can live with it?

We hope that we catch doc issues in our review cycles over at the green end of the spectrum (that is omitted in Figure 1). We also hope after that that it’s the good actors who attack us either as part of an official pentest/security audit or bounty hunters who will let us know the problem privately so we can fix it. If it is a bad case, it costs money, prestige; sometimes all access to systems is blocked and sometimes companies never get back on their feet. This assessment of risk is what your information security team should be deciding, but don’t you want to be part of the conversation when you are the one writing the docs?

Targets and Attacks

If attacks need targets, what are they? If you are a technical communicator working in software, it is clear that offering help in hacking your product is a bad idea. But any organization in any field may be revealing more than they know, and it is a constant review process. The first step is checking your APIs for elements that give the game away. Auto-generation tools can pull in code details, company information such as names and emails—not to mention evidence of a lack of professionalism, such as documented examples online of bad language in code naming slipping through! Your APIs are objects of close scrutiny using easily available specific tools to trawl through; for example, GitHub repositories locating email forms and passwords, etc., such as truffleHog and gitrob. Other more technical vulnerabilities include:

  • Certificates–training users to click popups or accept the fact that a certificate isn’t right
  • Loosely defined or leaky data–see my Twitter example in Figure 2.
  • Type checking, assertions, root level access–are the code examples clean?
  • Endpoints, especially legacy endpoints, multiple APIs–legacy access may run under older security standards without patches and updates, so plan ahead for their upgrade
  • Cultural giveaways (we will talk more about this next)

There is a good example of how API information can be exploited by cutting and pasting tokens, courtesy of Laxman Muthiyah of thezerohack, a whitehat who received a $12,500 bug bounty for reporting this. From an attacker point of view, this shows that relentless attention to detail pays well—will your docs stand up to it?

Other attack examples are found in Table 1.

Is security already a consideration for your API? Research has shown it is not usually a priority. In an analysis paper by Murphy, Alliyu, Macvean, Kery, and Myers (2017), security came in eleventh  out of 27 categories; Documentation was even lower at fifteenth.

Usually security only jumps up the agenda when things start to fail, although data protection legislation, such as GDPR, shows that people can take data security seriously. Not everybody, though: a U.K. Conservative Party 2018 conference app accidentally released all their MPs’ phone numbers.

Best Practices

So, security is on our agenda. Here’s some things we can do immediately:

  • For developers/security policy, include:
    • Writing restrictions like a least privilege policy
    • Secure authentication
    • Regular security audit/PEN test
  • For API documentarians, include:
    • OPSEC obfuscation like hiding or disguising stuff
    • Abstraction (no examples from own company culture, multiple code examples, don’t specify the source code language)
    • Hide data specifics where possible (no passwords obviously, but also pseudocode, obscure GETs examples, email format, etc.)
  • For everyone:
    • Backup files (check for inappropriate content)
    • Watch out for features that train users to be less secure
    • Software error analysis
    • Handle auto-generation with care
    • Learn code
    • Become cybersecurity aware (attend your local security meetup)
    • Review standards like ISO 27001, NIST, and PCI-DSS
    • Training in API security and social engineering


The good news is that security is a fun world to get involved in.

Conclusion: What You Can Do Next?

My main goal is to see technical communicators as an integral part of cybersecurity strategy and practice. My experience has shown that we have the skills, energy, and robust professionalism to communicate and ensure standards are met. How you proceed depends a little on where you sit, but here are three possibilities:

  1. I would recommend that documentation managers locate their Corporate Information Security Policy (CISP) immediately and take a long hard look at it (if you haven’t already done this).
  2. Make yourself part of the security conversation over the whole company and develop explicit documentation security strategy. For communicators, be scrupulous—you may yourself be a target as you may have unusual access levels to code; avoid giving too much away via your personal channels and follow documentation best practices.
  3. Finally, a note on freelancers or if you work remotely as this now has become the norm: Create your own CISP (there are templates available and you can perform a regular security audit of your systems and monitor risk, such as with email).

Let’s start building a more secure world!



BRIDGET KHURSHEED (poetandgeek@gmail.com) works as global documentation manager in a leading fintech. Her paper, “Microtargeting or Microphishing? Phishing Unveiled,” is published in Trust, Privacy and Security in Digital Business 17th International Conference, TrustBus 2020, Bratislava, Slovakia, September 14-17, 2020 (Springer). She is also an award-winning poet and spoken word performer.



BBC News. 2018. “Conservative Party Conference app Reveals MPs’ Numbers.” Accessed 22 May 2021. https://www.bbc.co.uk/news/uk-politics-45693143.

Ferbrache, David. n.d. “Rise of Ransomware During COVID-19: How to Adapt to the New Threat Environment.” KPMG. Accessed 21 May 2021. https://home.kpmg/xx/en/home/insights/2020/05/rise-of-ransomware-during-covid-19.html.

Hovsmith, Skip. 2019. “Preventing Mobile App and API Abuse.” OWASP AppSecCali (YouTube video). Accessed 21 May 2021. https://www.youtube.com/watch?v=QEW2AnEhfjs.

Murphy, Lauren and Alliyu, Tosin, et al. 2017. “Preliminary Analysis of REST API Style Guidelines.” PLATEAU’17. Accessed 21 May 2021.

Muthiyah, Laxman. 2021. “Deleting Any Photo Albums – How I Hacked Your Facebook Photos.” The Zero Hack. Accessed 21 May 2021.

Download the July/August 2021 PDF

2020 PDF Downloads