Security/Security Note Process

This page describes the process that should be followed for writing and publishing an OpenStack Security Note (OSSN). This page is intended to be used by members of the OpenStack Security Project.

For many members of the Security Project an OSSN will be their first time contributing to the OpenStack community using the standard tools and processes. Contributing to the OpenStack Security Note repository counts as active technical contribution in OpenStack, earning authors discounted access to OpenStack summits and the prestige of being recognised as contributing to the security of the world's largest, fastest moving Open Source project.

What is an OSSN
OpenStack has two mechanisms for communicating security information with downstream stakeholders, "Advisories" and "Notes". A Security Advisory (OSSA) is created to deal with severe security issues in OpenStack for which a fix is available - OSSA's are issued by the OpenStack VMT. We created the Security Note process for everything that doesn't qualify as an advisory, that's to say security issues that can't be fixed, design issues, deployment and configuration vulnerabilities.

Readers can learn more about the OSSA process and the VMT at https://security.openstack.org/vmt-process.html.

Process
Typically a third party will file a security bug in OpenStack via Launchpad. If the VMT decides that it might be valid but doesn't qualify for an OSSA they will add the "OpenStack Security Notes" team to the "also affected" section of the bug. Launchpad bugs can affect multiple teams, adding the Security Notes team to the bug is the primary way we are notified that there is an issue we need to address.

Bug Reported via Launchpad => Bug marked as effecting "OpenStack Security Notes => Bug accepted by the OSSP => Bug written and submitted to Gerrit for review => Note published via email and to the OpenStack wiki

Reviewing Bugs
The list of bugs requiring OSSNs to be written is maintained here: https://bugs.launchpad.net/ossn and should look similar to the list below



Bugs have a number of different status and the labels that Launchpad uses are geared more towards code development than documentation, however interpret the different statuses as follows:

There are additional statuses that can be applied to a project including "Incomplete, Opinion, Invalid, Triaged, Fix Committed" - the Security Project does not currently use these tags for managing Security Notes. If you see a note with one of these tags you should raise the issue on IRC or via the mailing list.

Writing
When writing a new Security Note, you should ensure that the target audience will be able to clearly answer the following questions once they have read the Security Note:


 * What is the issue?
 * Is my deployment affected?
 * What are the ramifications if my deployment is affected?
 * What can I do to correct or avoid the issue?

To ensure that the Security Note is technically correct, you should reach out to the developers involved if any clarification is needed. Much of the required technical information is usually in the Launchpad bug already, but additional information is often needed to produce a thorough Security Note.

You should also check the new Security Note for the following issues:


 * Correct spelling
 * Proper grammar
 * Avoid using acronyms (or define them when first used in the Security Note)

Number Assignment
When you begin to write a new Security Note, the first thing you should do is assign the next available OSSN number to your note. This is done in the Security Note publishing area on the wiki. Add a placeholder with the proposed title of your new Security Note using the next available number and append (work in progress) to it. This should look similar to the following example:


 * OSSN-1234 - My new Security Note (work in progress)

Save the page, then click the link you just added, to create a new page. Paste in the title of the OSSN and a link to the launchpad bug, then save the page.

Templates
The OpenStack Security Notes are kept in the Security Docs repository, which contains a template to aid in the creation of new Security Notes.

The template is in the format used for publishing to the OpenStack mailing lists. The line length should be limited to 72 characters with the exception of example snippets of configuration files or long links in the Contacts / References section. This will prevent problems with line wrapping messing up the formatting that can occur with popular PGP mail client software. The template format is also what we use for the Security Notes that we push to the git repository.

Testing
If the new Security Note is documenting a workaround, it is important that it is actually tested to ensure it works. If you need help in testing, you can reach out to the developers in the original Launchpad bug as well as other members of the OpenStack Security Group.

Reviewing
The Gerrit review system is used to review new Security Notes. It is recommended that you read over the Development Workflow if you are not already familiar with it. Do not hesitate to reach out to authors of released notes if you want to be guided through the process.

In order to link the review to the associated Lauchpad bug, you should use the Closes-bug tag in your commit message. The details on using this tag are described on the Git commit messages page.

The OpenStack Security Notes source repository is available at http://git.openstack.org/cgit/openstack/security-doc/

A Security Note will need to be reviewed by two members of the OpenStack Security Note Core group to be merged. It is also a good idea to add the PTL from any projects related to the Security Note as a reviewer.

Publishing
Once a Security Note has been approved by the appropriate reviewers, it is ready to be published. Security Notes are published to the OpenStack wiki and the OpenStack mailing lists.

Wiki
Before publishing a Security Note to the mailing lists, it should be published on the OpenStack wiki. This allows the e-mail version of the Security Note to contain a link to the wiki that is immediately accessible. Each Security Note gets it's own wiki page, which is then linked to from the Security Notes wiki page. The new Security Note wiki page location should be OSSN/OSSN-number. The numbering scheme is simply a 4 digit integer that we increment when a new OSSN is published. You can look at the previously posted Security Notes to see what the next free number is.

When publishing a Security Note to the OpenStack wiki, you should use proper wiki markup to improve formatting and aid readability. It is recommended that you look at the previously published Security Notes to see examples of how markup is used for formatting.

Mailing Lists
Once a Security Note has been published on the wiki, it should be sent to the following mailing lists:


 * openstack-discuss@lists.openstack.org
 * openstack-announce@lists.openstack.org

The e-mails should be signed, and the subject should be in the form of [OSSN number] Title. The body of the e-mail should use the format from the template above.

Post-mortem Tasks
Once a Security Note has been published, it is a good idea to see if the OpenStack Security Guide or Security Guidelines could be improved to help prevent issues similar to the issue form the Security Note.