Difference between revisions of "Security/Security Note Process"

Revision as of 00:13, 30 May 2014

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 Group.

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)

Templates

The OpenStack Security Notes repository contains templates to aid in the creation of new Security Notes.

The email-template.txt template should be 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 e-mail template is also the format that we use for the Security Notes that we push to the git repository.

There is also a wiki-template.txt template that can be used for publishing a Security Note to the wiki. Once a Security Note is reviewed, you can use this template to format the Security note in wiki markup for publishing.

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 Gerrit workflow if you are not already familiar with it.

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

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.

A template for publishing a Security Note on the OpenStack wiki with the proper wiki markup is available in the OpenStack Security Notes repository. It is a good idea to preview your wiki page first to see if any additional wiki formatting can be done to improve readability.

Mailing Lists

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

• openstack-dev@lists.openstack.org
• openstack@lists.openstack.org

The e-mails should be signed, and the subject should be in the form of [OSSG][OSSN] OSSN 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.