Security Guide should contain meta-data about content that requires regular review

Bug #1432692 reported by Michael McCune
6
This bug affects 1 person
Affects Status Importance Assigned to Milestone
OpenStack Security Guide Documentation
Confirmed
Wishlist
Aastha Dixit

Bug Description

The security guide carries many examples for the services it covers. These examples provide a wide range of configurations and sample implementation data which can become outdated as projects grow. To address this issue the security guide should contain meta-data to aid in locating all the sections that will need to be reviewed as projects release new versions.

Given the wide variance of example data in the guide, the effort to identify and mark the sections for review should be undertaken by project specialists who understand the changes that might be occurring to the data. These should be opened as separate bugs against those sections, and a global style for meta-data should be conformed to while marking the sections.

There are a few options for the implementation of the meta-data depending on the needs of the review group. A simple approach would be to add inline comments in the sections marked for review, these comments would contain a keyword which could then be collated with a tool like "grep". In this manner a reviewer could gather all the sections for review and address them individually. This approach would be simple to implement and would only require that a reviewer be familiar with common search tools to locate all the marked sections.

A more complicated approach would be to create a debug type option in the build file which would allow a reviewer to create a version of the guide with a special index containing all the locations marked for review. This approach might be slightly heavy for the nature of this work as it would require creating a secondary build path and potentially a different root document for that build. The advantage of this approach would be a simple document providing an index to all the necessary sections.

Tags: sec-guide
tags: added: sec-guide
N Dillon (sicarie)
Changed in openstack-manuals:
status: New → Confirmed
Bryan D. Payne (bdpayne)
Changed in openstack-manuals:
importance: Undecided → High
importance: High → Medium
Tom Fifield (fifieldt)
Changed in openstack-manuals:
importance: Medium → Wishlist
Ian Cordasco (icordasc)
affects: openstack-manuals → ossp-security-documentation
Changed in ossp-security-documentation:
assignee: nobody → Aastha Dixit (aastha-dixit)
To post a comment you must log in.
This report contains Public information  
Everyone can see this information.

Other bug subscribers

Remote bug watches

Bug watches keep track of this bug in other bug trackers.