:man| Alphabetical   Categories   About us 
 
SDOC (7) | Miscellanea | Unix Manual Pages | :man▋

NAME

sdoc - guide to adding security considerations sections to manual pages

CONTENTS

Description
Where to Start
Where to Stop
Examples
See Also
History
Authors

DESCRIPTION

This document presents guidelines for adding security considerations sections to manual pages. It provides two typical examples.

The guidelines for writing
.Fx manual pages in groff_mdoc(7) mandate that each manual page describing a feature of the
.Fx system should contain a security considerations section describing what security requirements can be broken through the misuse of that feature. When writing these sections, authors should attempt to achieve a happy medium between two conflicting goals: brevity and completeness. On one hand, security consideration sections must not be too verbose, or busy readers might be dissuaded from reading them. On the other hand, security consideration sections must not be incomplete, or they will fail in their purpose of instructing the reader on how to avoid all insecure uses. This document provides guidelines for balancing brevity and completeness in the security consideration section for a given feature of the
.Fx system.

Where to Start

Begin by listing those general security requirements that can be violated through the misuse of the feature. As described in the FreeBSD Security Architecture (FSA), there are four classes of security requirements:
integrity (example: non-administrators should not modify system binaries),
confidentiality (example: non-administrators should not view the shadow password file),
availability (example: the web server should respond to client requests in a timely fashion), and
correctness (example: the ps program should provide exactly the process table information listing functionality described in its documentation - no more, no less.)

The FSA contains a list of integrity, confidentiality, availability, and correctness requirements for the base
.Fx system. Many commands, tools, and utilities documented in sections 1, 6, and 8 of the manual are partly responsible for meeting these base system requirements. Consequently, borrowing entries from the list in the FSA is a good way to begin the list of requirements for these commands, tools, and utilities.

Complex servers and subsystems may have their own integrity, confidentiality, availability and correctness requirements in addition to the system-wide ones listed in the FSA. Listing these additional requirements will require some thought and analysis. Correctness requirements will most often deal with configuration issues, especially in cases of programs that can load modules containing arbitrary functionality during run-time.

For low-level features, such as the individual functions documented in sections 2, 3, and 9 of the manual, it is generally sufficient to proceed with only a single correctness requirement: simply that the function behaves as advertised.

A good security considerations section should explain how the feature can be misused to violate each general security requirement in the list. Each explanation should be accompanied by instructions the reader should follow in order to avoid a violation. For the sake of brevity, assume the reader is familiar with all of the concepts in the FSA. When referencing potential vulnerabilities described in the Secure Programming Practices manual page, sprog(7), likewise cross-reference that document rather than replicating information. Whenever possible, refer to this document rather than reproducing the material it contains.

Where to Stop

Security problems are often interrelated; individual problems often have far-reaching implications. For example, the correctness of virtually any dynamically-linked program is dependent on the correct implementation and configuration of the run-time linker. The correctness of this program, in turn, depends on the correctness of its libraries, the compiler used to build it, the correctness of the preceding compiler that was used to build that compiler, and so on, as described by Thompson (see SEE ALSO, below).

 
Created by Blin Media, 2008-2013