Writing a security advisory

Have you ever written a security advisory? Be ready to write the most fraught and demanding document in your life! I’ve been writing them off and on for three years now. The first was a huge challenge. Since then, each one has been interesting in its own way and I’ve learned an enormous amount.

If you’re as lucky as I was, you’ll have an expert to help you with the first few security advisories you have to write. Dave O’Flynn knows a lot about application security. He spent a fair bit of time explaining severity levels, designing our security advisories and walking me through the accepted and expected ways of communicating vulnerabilities and fixes to customers. Thank you Dave!

So I decided to share my experiences by writing this blog post. It’s been brewing for months. My inbox and my dressing-table have been collecting notes of all shapes and sizes. It’s going to be a long one, and a goodly mix of opinion and fact. Grab a cuppa. I hope you enjoy it. 🙂

Please note that the opinions here are my own, and not necessarily shared by the company I work for. Comments welcome!

What is a security advisory?

It’s a document letting customers know that you have found a security vulnerability in your product or that someone else has found it for you. It also tells customers how to fix the problem. A security vulnerability, also called a security flaw or security hole, is a bug in the application that malicious users (hackers) could exploit to gain access to your customers’ data or network. The best known and most-frequently occurring security vulnerabilities in web applications are cross-site scripting (XSS) flaws.

In most cases, you would issue the security advisory at the same time as you provide the patch or upgrade that fixes the flaw. If necessary, you may issue the security advisory even before the patch is ready, and tell people how to minimise or prevent their exposure to attack until the fix is ready.

Here’s an example of the most recent security advisory I’ve written. It announces a number of flaws found and fixed, all XSS flaws. Here’s another security advisory, with a number of different types of vulnerability in one single advisory. This third security advisory is much simpler, describing just a single flaw.

Why do I say “fraught”?

Writing a security advisory

A kookaburra looking warm and fuzzy

People are going to lose some of that warm fuzzy feeling about your application when you issue a security advisory. That’s especially true of customers who haven’t been aware of security holes in other applications up to now, and who are not used to the advisory and patch procedures. As technical writers, it’s our job to help customers feel safe by letting them know the company takes security seriously. In a nutshell, we want to tell them:

Someone finds a hole, we fix it, and we let you know so that you can upgrade or patch your systems before any hacker can take advantage of the flaw.

What other aims do we have? Ah, well, this is where things get complicated.

On the one hand we want to tell our customers as much as possible, so that they can make their decisions about whether and when to upgrade or patch their systems. What type of security flaw are we announcing and how can they fix it? Are they vulnerable to attack if their site is open to staff only, for example? What about if it’s behind a firewall? What is the worst case scenario if they are attacked?

On the other hand, we want to protect people from hackers. If we publish too much information about a vulnerability, that may be an invitation to a hacker to jump in before customers have time to upgrade.

People have, ahem, strong feelings on this topic. You’ll probably find polarised opinions even within your own company, let alone amongst your customers. It’s fraught, uh, fun… well, let’s say it’s a very interesting path you’ll take to determine just how much detail to reveal in your security advisory and when to reveal it.

Personally, my thoughts are:

  • Tell everyone.
  • Tell them everything except the exact details of the attack vector. In other words, tell them the severity level of the flaw and which areas of the application are vulnerable, but not exactly how to script an attack.
  • Tell them as soon as you have a fix available. Moreover, if the vulnerability has already been exploited, meaning that someone has already hacked the software in anger, then tell everyone immediately.
  • If possible, give people advance warning a week or so before the actual advisory and patch are released, letting them know that a security advisory is in the offing. They will be able to set aside time to upgrade or patch their systems when the details are released.

People can then make decisions about limiting access to their sites, blocking all but known IP addresses, or even taking the site down until they can apply the fix.

Because guess what, hackers share information behind the scenes. They can be malicious or just ignorantly mischievous, and they will not wait politely for us or our customers to get our ducks in a row.

Why do I say “demanding”?

A security advisory is also one of the most work-intensive and time-consuming documents you will ever have to write. There are few words in a security advisory, but each word carries a lot of weight and consequences for your customers. What’s more, everyone in the company has an opinion on each word. And even more, as technical writer you’ll probably find that you have to wring each detail out of the development team and cajole them into doing extra work.

No matter if your internal procedures say it’s the responsibility of the development team to decide the severity level of a flaw. No matter if it’s the product manager’s responsibility to determine the patch policy. When push comes to shove, it’s the technical writer who ensures that every detail of the security advisory is complete and correct.

You need to know exactly which versions of the product are vulnerable to the security flaw. This could mean delving into the code going years back.

You need to know the exact details of the patches available, which versions of the product they will fix, where people can get them and how they can install them. For the development team, it’s very time-consuming to create the patches to fix earlier releases for those customers who can’t upgrade. Be sure to start asking for the details early. You’ll find that your questions drive the development team to start looking at patches early enough to meet the release deadline.

You need to know the exact details of the flaw, so that you can be comfortable with the severity level assigned to each one. Often the bugs are highly technical. Be sure to get at least two opinions on the severity level. In many cases, the severity level determines your communication policy. For example, you may issue advance warnings for “critical” severity levels only, or you may build patches for “critical” and “high” severity levels only.

The content of a security advisory

Dave and I based the design of the security advisories on those by other well-known and respected web development companies and security-focused sites. We came up with the following sections for each vulnerability:

  • Vulnerability Type
  • Severity
  • Risk Assessment
  • Vulnerability
  • Risk Mitigation
  • Fix
  • Acknowledgement of the reporter

The vulnerability type is a well-recognised classification of the vulnerability. Examples are XSS, XSRF, privilege escalation.

The severity level is a rating of the potential impact and ease of exploitation of the vulnerability, based on our published criteria, allowing us to rank the severity as critical, high, moderate or low.

The risk assessment includes information about the type of data a hacker might be able to access, the worst case scenario, and the kind of deployment scenario or security setup which is at risk. The purpose of this section is to give our customers enough information to make their own decisions about when to upgrade, whether to apply a patch, and whether to shut down public access to their data until the fix is implemented.

The vulnerability section describes the location or area of the application that is affected by the vulnerability, such as the affected macro, URL or screen. It also says which versions of the application are vulnerable, and links to the JIRA issue where the bug is tracked.

The risk mitigation section tells customers what they can do to minimise their exposure to malicious attack, especially if they are not in a position to upgrade immediately

The fix section tells customers what they can do to fix the problem permanently. Usually, this will be a recommendation to upgrade to the latest version of the application. In addition, we describe how to apply patches if supplied.

We also acknowledge the reporter, that is the person who reported the vulnerability, if it was someone outside the company and only if the reporter has indicated that they would like to be acknowledged.

For convenience, here are the links to some of our recent security advisories again. Here’s the most recent security advisory I’ve written. It announces a number of flaws found and fixed, all XSS flaws. Here’s another security advisory, with a number of different types of vulnerability in one single advisory. This third security advisory is much simpler, describing just a single flaw.

Technical and product management review

Give the developers and product managers time to stew. 🙂

Heh, as technical writers we’re very aware of the importance of the review phase for a technical document. For a security advisory, I’ve found that this phase is even more crucial. It’s a good plan to set aside a week or so. Technically, security bugs can be complex. From a product management point of view, they can be even more complex. I’ve found that if I start badgering people for a review early, it gives them the time they need to let their ideas and concerns stew, to consider and re-consider all aspects of the security fix and of the security advisory.

As is so often true in technical writing, you’ll find that your questions prompt the development team to look at the bug (the security flaw, in this case) and the fix in a new light. Your concerns about crafting a good advisory will also prompt product management to think in different ways about the impact on the customers. Getting started early will help the development team meet their release deadline, as well as being essential for you to meet yours.

So, if you get started early, that will reduce the “fraughtness”? Heh again. No, probably not, because your questions will lead to changes, and you’ll need to keep adjusting the advisory and other communications until everything is just right. But at least you’ll feel that you’re on top of and driving the fraughtness rather than swamped and driven by it.

Advance warning

An “advance warning” is a message sent to customers warning them that a security advisory is in the offing. Not all companies issue advance warnings. The policy may be to issue an advance warning for any upcoming security advisory, or for critical vulnerabilities only, or not at all.

If you do issue an advance warning, you would publish it a while before the actual security advisory itself is released. We’ve decided that a week is a good period. It gives system administrators time to decide whether they need to do an upgrade or patch and to schedule the downtime if necessary.

The wording and content of the advance warning need careful consideration, just like the security advisory itself. Our aim is to inform and protect our customers. We need to give them enough information to make their decisions, but we must not give hackers enough information to track down the vulnerability itself before we issue the fix.

What you might put into an advance warning:

  • The approximate date on which you plan to release the security advisory and fix, such as: “currently scheduled for release in the middle of next week”.
  • The type of security flaw you will be announcing, its severity level and a generic risk assessment.
  • Advice on how to prepare for the security advisory and fix.
  • Advice on mitigation strategies.

Here’s a recent example of an advance warning.

Known communication channels

We need to tell people what our policy is, both the policy on security advisories and the policy on advance warnings. That way, system administrators know what they’ll be told and when they’ll be told it, and they can base their planning on that knowledge. People also need to know where the security advisories will appear, such as in the discussion forums, on an email list or on a wiki page that people can subscribe to.

We publish our security policies as part of the technical documentation on the wiki. For example, the security advisory publishing policy, the security patch policy and the way we determine severity levels.

Zero-day attacks

“Zero-day attacks” are a special case, and they affect your disclosure policy and patch policy. They’re also sometimes called “zero-hour” or “day zero” attacks.

A zero-day attack is a previously unknown and unpublicised vulnerability that has now been exploited by a hacker. It’s called “zero-day” because the attack happens before the first day that the application developer knows about it – and so, it happens on “day zero”.

How does this affect your communication policy? If you suffer a zero-day attack, the common understanding is that you will announce the vulnerability as soon as you hear it has been exploited, even if you do not yet have a fix for it. If you do not announce it, you run the risk that your customers will be attacked by hackers, who are sharing the information about the vulnerability, and the customers will not have a chance to protect themselves.

Here are a couple of examples:

Some interesting sites

  • Web Application Exploits and Defenses, a codelab from Google Code University. The codelab is based on an example application called Gruyere, “a small, cheesy web application that allows its users to publish snippets of text and store assorted files”. Gruyere is rife with security holes, including XSS and XSRF vulnerabilities. You get to be the hacker. The codelab gives you your own instance of Gruyere, and a set of tutorials to help you find the security vulnerabilities. It demonstrates the principles behind the various types of vulnerability. I’m told it should take approximately 4 hours to complete the set of exercises. I haven’t done it myself.
  • ZDNet‘s Zero Day blog with the latest news in security-related research, vulnerabilities, threats and attacks.
  • The Cross-Site Scripting (XSS) FAQ at cgisecurity.com.
  • CERT’s advisory on Malicious HTML Tags Embedded in Client Web Requests.
  • The Alphabet Soup of Software Security Guidelines, an informative and entertaining post by Todd Landry on >kloctalk.

Fraught and demanding? Yes, but…

I hope this post may be useful to someone who is in the enviable position of having to write a security advisory. Yes, I really do mean “enviable”. Though they may be fraught and demanding, they’re also one of the most interesting documents you’ll ever write. 🙂 I’d love to hear your experiences of writing such documents, and your ideas and opinions on what they should reveal. How much influence does the technical writer have over the procedure and the content? In my experience, a lot, because we quickly become the ones who know most about it!

Security Advisory for Flash Player, Adobe Reader and Acrobat

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 8 August 2010, in technical writing and tagged , , , , , , . Bookmark the permalink. 7 Comments.

  1. Great post!

    It might be worth adding http://www.owasp.org/ to your list of interesting sites. The “The Open Web Application Security Project” is a not-for-profit organisation dedicated to visible application security.

    • Brilliant, thanks Peter! Especially interesting are their Top 10 security risks for 2010. I really like their philosophy: “Our mission is to make application security visible, so that people and organizations can make informed decisions about true application security risks. Everyone is free to participate in OWASP and all of our materials are available under a free and open software license.”
      Cheers, Sarah

  2. I would first like to say that ‘Writing a Security Advisory’ provides a lot of great insight from @ffeathers on writing a well-constructed security advisory while mindful of the fact that readers of this blog post might not know what a security advisory is or how to write one, but could have done a better job of sharing their experiences as they stated as the intention of writing the piece. Having a vague concept of what a security advisory is, I was pleased to find very detailed descriptions as well as necessary steps to writing one and it sounds like it would be an interesting task if I was ever in a situation to write one myself. While it might seem hard for a company to admit that a product they have spent lots of time and effort in creating now has a flaw, I have a sense that a good technical writer can put the company at some kind ease by creating a very good, easy-to-understand, security advisory for the general public but also craft it in a way that any hackers out there will not be able to jump to conclusions as to the patch or upgrade that will have to be created to solve said problem. Still I felt that @ffeathers could have done a better job to put a personal touch to this as opposed to providing general examples. While the security advisory is, from my understanding anyway, not just to re-assure clients, stockholders, board members, etc., but can also to provide the company with some transparency as to why the problem was caused in the first place and that everything is being done to fix it, it would have been helpful to see some best practices in what has worked and not worked through their experiences. Also, in detailing the benefits of creating ‘advance warnings,’ @ffeathers shows how this can be even more beneficial to those who are using a product and might already be affected by vulnerability. Assuming that the writer of this piece does their job well, the subsequent security advisory will be welcomed and possibly better-received than if there was no previous warning as to what was to come. This is probably the best case scenario. Has @ffeathers been fortunate enough to have this experience? If so, how did it help them to frame their follow-up security advisory? No company wants to experience ‘zero-day attack’ where the vulnerability is publicized by a hacker and the company is now faced with a very real threat to themselves and to their clients. In providing some great, key examples of this readers and potential security advisory writers can understand best practices in how to deal with this type of situation. By advising to ‘own’ the attack and announce that a fix is on the way is great advice and can possibly open up the conversation as to how the hacker found the vulnerability before the company itself. Still, it would have been nice to know what @ffeathers did in a situation like this. What was that like and were there any arguments within the company as to how to best handle the situation? What was their job like as the person writing the security advisory, where the product and potential the company has been compromised? Overall, while providing some very helpful advice and key terms, I think @ffeathers spent more time describing situations and providing a vocabularly lesson than putting their own experiences into the post. I would have loved to hear how they were able to address the different situations of security advisory writing and maybe how they felt about them afterwards.
    I chose this blog because it seemed to have a lot of great insight for technical writers on a wide variety of topics. While this particular post was not something I had much knowledge about, I still felt good about my comment because I was able to comment on the author’s writing, the blogs usefulness, and what I found to be most helpful.

    • Hallo Leigh

      Thank you for your review of my blog post. From the style and tone of your comment, I’m guessing it was part of an assignment in a study course, perhaps in technical communication or blogging. 

      You make some good points. A great place to see the potential for emotional involvement in and possible consequences of a security breach and  subsequent security advisory, is the blog post I linked to above:

      The principal aim of my technical writing blog is to give other tech writers and other people real information about various aspects of tech writing. I like to add a bit of myself to the posts too, and often something about trees. I’m always glad when people enjoy a post, and even more pleased when they tell me what they think. 

      Good on ya! 🙂

  1. Pingback: Tweets that mention Writing a security advisory « ffeathers — a technical writer’s blog -- Topsy.com

  2. Pingback: How to write a security advisory « CyberText Newsletter

  3. Pingback: links for 2010-08-08 « Ex Orbite

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: