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 Group.
Contents
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-dev@lists.openstack.org
- openstack@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.
