Grsecurity/How to Contribute

The easiest way to contribute is to enhance existing content by correcting misspelled words or restructuring sentences or paragraphs to make them more readable. You are also very welcome to add new content by expanding pages that are under development or by adding completely new pages if your text doesn't fit any of the other pages. As grsecurity is being actively developed and features are added and removed, help with keeping the content up to date is much appreciated.

On this page you will find background on why a particular structure was chosen for the book, who this book is for, and what style and formatting should be used.

Book Structure
The book's structure follows the original documentation of the grsecurity project that had three main chapters: Installation, Configuration and Specification, and Using gradm and the Learning Mode. Configuration and Specification was retitled as Policy Configuration. Using gradm and the Learning Mode was retitled as Administration and was also moved before the Policy Configuration, because you must know how to manage grsecurity before you configure the policy. This is how we ended up with the core structure: Installation, Administration, Policy Configuration.

Target Audience
The book is meant for people who are capable of solving hardware and software problems of varying complexity on their own and who actually read the manual. They know their way around their favorite Linux distribution and are familiar with configuring and building software from source.

Objectives
The purpose of this book is to provide comprehensive, reliable, and up-to-date documentation of grsecurity and related tools. In addition to teaching how to do something, the book provides information about best practices and common pitfalls learned in practice. This is the main objective.

Each chapter has additional objectives that define what the reader should know after they've read it. These objectives were defined after most of the book's core content was in place, so at the time of writing some chapters might not fulfill all of their objectives.

Introduction - The reader must learn on a basic level what grsecurity is, what are its goals and how those goals are realized. If they do not belong to our target audience they should still get a rough idea of what grsecurity is about.

Installation - The reader must learn:
 * Where to get grsecurity, its administration tool gradm and the Linux kernel source.
 * How to verify the authenticity of each package.
 * How to apply the grsecurity patch properly.
 * How to configure grsecurity's kernel configuration options (this includes PaX settings) and what they need to consider before doing so.
 * How to build and install a grsecurity-enabled kernel using their chosen distribution's tools.

Administration - The reader must learn:
 * How to install gradm, the administration tool.
 * How to use gradm and especially the learning mode.
 * How to configure grsecurity's features at runtime.
 * What other useful tools are available, where to get them, and how to install and use them.
 * How to troubleshoot application incompatibilities and problems with grsecurity.

Policy Configuration - The reader must learn:
 * What an RBAC system is and is not, what it can provide when properly configured.
 * What makes a secure policy.
 * The policy structure and rules; they must be familiar with every configuration element and their parameters and configuration inheritance.

Reporting Bugs: The reader must learn how to report bugs; what information is required, how to gather it, and where to send the reports.

Style and Conventions

 * Headers should be title cased.
 * Use the &lt;pre&gt; tag to display long commands, example program output, and file contents.
 * Use the XWarning template when you need to point out an important security consideration or a possibly dangerous operation. It is easier to spot than the classic Warning template when scrolling.
 * Use the Info template when you need to point out something that's related to the surrounding text.
 * The name grsecurity should be written in lowercase and without special formatting unless it begins a sentence. This is how it is written on the grsecurity website.

Formatting
Note: This is still a work in progress, and will change in the future. It will be finalized soon.  Italic Used for file and directory names. Boldface Used for occasional emphasis, such as when introducing a new term. Constant Width Used in text for program and command names. Blocks of pre-formatted text is used in examples show what commands to execute and what their output should be. 

Generating Content Automatically
Some content in this book can be generated automatically from grsecurity's source files. Scripts and programs that do this are listed here. Fixes and improvements to any of the scripts and programs are welcome, as are complete rewrites.

Grsecurity and PaX Configuration Options and Sysctl Options
Below is a Python script that outputs two files, one with content for the Grsecurity and PaX Configuration Options page and another for the Sysctl Options page.

The script takes an absolute path to the kernel source patched with grsecurity as input, reads the grsecurity/grsec_sysctl.c, security/Kconfig, and grsecurity/Kconfig files, and outputs two files named Grsecurity_and_PaX_Configuration_Options.wiki and Sysctl_Options.wiki. The contents of Grsecurity_and_PaX_Configuration_Options.wiki can copied as they are to the wiki. Sysctl_Options.wiki only contains categorized lists of links that can be shown in the table on the Sysctl Options page. The links in the Sysctl_Options.wiki file point to anchors on the Grsecurity and PaX Configuration Options page, so the contents of these two files are linked.

The script uses Kconfiglib by Ulf Magnusson for reading the Kconfig files.

Feel free to replace the script with a Perl one-liner or a single command line.