Contents

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.

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.

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.

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.

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.

As this page and the scripts can be modified by anyone, take care to inspect all code before running it.

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.

#!/usr/bin/env pythonimportsysimportcodecsimportosimportkconfiglibdefget_sysctl_opts(kern_src_dir):""" Returns a dictionary of sysctl variables related to grsecurity. Parameters: kern_src_dir (string) Absolute path to a kernel source directory (e.g. /usr/src/linux-3.2.48.) The key of each item is the name of a kernel configuration symbol (e.g. GRKERNSEC_SYMLINKOWN) and the value is a list of sysctl variable names (e.g. [enforce_symlinksifowner, symlinkown_gid]). """file_name=os.path.join(kern_src_dir,"grsecurity","grsec_sysctl.c")options={}withopen(file_name,'r')asf:cur_symbol=Noneforlineinf:ifline.startswith("#ifdef"):start=line.find("GRKERNSEC")cur_symbol=line[start:].strip()options[cur_symbol]=[]elifline.startswith("#endif"):ifcur_symbolinoptions:options[cur_symbol].sort()cur_symbol=Noneifcur_symbolisnotNoneandline.find(".procname")>=0:a=line.find('"')+1b=line.rfind('"')sysctl_var=line[a:b].strip()options[cur_symbol].append(sysctl_var)returnoptionsdefget_categorized_sysctl_opts(sysctl_opts):""" Returns a list of lists or tuples. Parameters: sysctl_opts (dict) Dictionary of sysctl variables. This would be the return value of get_sysctl_opts(). Each index in the returned list specifies a category. The categories are [0] Audit/logging variables [1] Chroot variables [2] Network variables [3] Misc. variables The categorization is based on the name of the sysctl variable, and is not entirely accurate. But it's "good enough." Each category consists of a list of tuples. The first element of a tuple is the name of a kernel configuration symbol (e.g. GRKERNSEC_SYMLINKOWN) and the second element is a sysctl variable that is related to that symbol. If a symbol is related to more than one sysctl variable, the list will contain multiple tuples that have the same first element. """audit_opts=[]chroot_opts=[]net_opts=[]other_opts=[]foriteminsysctl_opts.iteritems():foroptinitem[1]:ifopt.find("audit")>=0oropt.find("log")>=0:audit_opts.append((opt,item[0]))elifopt.find("chroot")>=0:chroot_opts.append((opt,item[0]))elifopt.find("socket")>=0oropt.find("ip")>=0:net_opts.append((opt,item[0]))else:other_opts.append((opt,item[0]))audit_opts.sort()chroot_opts.sort()net_opts.sort()other_opts.sort()all_opts=[audit_opts,chroot_opts,net_opts,other_opts]returnall_optsdefwrite_wikified_sysctl_opts(kern_src_dir,out_file_name):""" Writes a categorized list of sysctl variables wrapped in MediaWiki links constructs. Parameters: kern_src_dir (string) Absolute path to a kernel source directory (e.g. /usr/src/linux-3.2.48.) out_file_name (string) Path and file name or just the file name of the output file. The links point to anchors on the Grsecurity and PaX Configuration Options page. The links are written in alphabetical order by the sysctl variable. """sysctl_opts=get_sysctl_opts(kern_src_dir)categorized_opts=get_categorized_sysctl_opts(sysctl_opts)kconfig_path=os.path.join(kern_src_dir,"security","Kconfig")conf=kconfiglib.Config(kconfig_path,kern_src_dir)link_fmt="* [[Grsecurity/Appendix/Grsecurity_and_PaX"\
"_Configuration_Options#{0}|{1}]]\n"withcodecs.open(out_file_name,'w',"utf-8")asf:f.write("Category: Audit/logging\n")foroptincategorized_opts[0]:symbol=conf.get_symbol(opt[1])prompt=get_prompt(symbol)f.write(link_fmt.format(prompt,opt[0]))f.write("\nCategory: Chroot\n")foroptincategorized_opts[1]:symbol=conf.get_symbol(opt[1])prompt=get_prompt(symbol)f.write(link_fmt.format(prompt,opt[0]))f.write("\nCategory: Network\n")foroptincategorized_opts[2]:symbol=conf.get_symbol(opt[1])prompt=get_prompt(symbol)f.write(link_fmt.format(prompt,opt[0]))f.write("\nCategory: Miscellaneous\n")foroptincategorized_opts[3]:symbol=conf.get_symbol(opt[1])prompt=get_prompt(symbol)f.write(link_fmt.format(prompt,opt[0]))defget_prompt(item):""" Return the first prompt text of the specified symbol or choice. Parameters: item (Kconfiglib.Symbol or Kconfiglib.Choice) The object whose prompt is to be returned. Kconfiglib does not expose the prompt(s) of a Symbol or Choice. They have to be extracted from the string representation of a Symbol object. This function only returns the first prompt. There may be more prompts and they may or may not be identical. """s=str(item)prefix="Prompts:"i=s.find(prefix)prompt=Noneifi>=0:a=s.find('"',i+len(prefix))+1b=s.find('"',a)prompt=s[a:b]returnpromptdefwrite_wikified_item(f,sysctl_opts,item,level):""" Write the given Kconfiglib.Item in the specified file. Parameters: f (file) Output file object open for writing. sysctl_opts (dict) Dictionary of sysctl variables. This would be the return value of get_sysctl_opts(). item (Kconfiglib.Item) Item that should be formatted. level (integer) Heading level (number of '=' characters before and after a heading). Items are hierarchical and this function will increment the level when it calls itself recursively to process child Items. This function wraps certain properties of item and related content from sysctl_opts in MediaWiki markup and writes the output to the specified file object. If item is a Menu, it is formatted as a heading and its child Items are iterated and formatted. If item is a Choice, its prompt text is formatted as a heading and help text as preformatted text. If item is a Symbol, its prompt text is formatted as a heading, name as teletype text, help text as preformatted text and all related sysctl options as intended lines below a sort of heading that's regular unformatted text. """heading_fmt="\n{0}{1}{0}\n"symbol_fmt="<tt>{0}</tt><br/>\n"help_fmt="<pre>{0}</pre>\n"sysctl_vars_heading="Related sysctl variables:<br/>\n"sysctl_var_fmt=":<tt>kernel.grsecurity.{0}</tt>\n"ifitem.is_menu():iflevel>1:f.write(heading_fmt.format("="*level,item.get_title()))forsubiteminitem.get_items():write_wikified_item(f,sysctl_opts,subitem,level+1)ifitem.is_choice():f.write(heading_fmt.format("="*level,get_prompt(item)))help_text=item.get_help()ifhelp_textisnotNoneandlen(help_text)>0:f.write(help_fmt.format(help_text.strip()))forsubiteminitem.get_items():write_wikified_item(f,sysctl_opts,subitem,level+1)ifitem.is_symbol():name=item.get_name().strip()prompt=get_prompt(item)help_text=item.get_help()ifpromptisnotNoneandlen(prompt)>=3:f.write(heading_fmt.format("="*level,prompt))f.write(symbol_fmt.format(name))ifnameinsysctl_opts:opt_list=sysctl_opts[name]ifopt_listisnotNoneandlen(opt_list)>0:f.write(sysctl_vars_heading)foroptinsysctl_opts[name]:f.write(sysctl_var_fmt.format(opt))ifhelp_textisnotNoneandlen(help_text)>0:f.write(help_fmt.format(help_text.strip()))defwrite_wikified_kconfig(kern_src_dir,out_file_name):""" Create a MediaWiki-formatted version of the Kconfig file found in the kern_src_dir/security/ directory and write the output to the given file. Parameters: kern_src_dir (string) Absolute path to a kernel source directory (e.g. /usr/src/linux-3.2.48.) out_file_name (string) Path and file name or just the file name of the output file. """security_kconfig=os.path.join(kern_src_dir,"security","Kconfig")conf=kconfiglib.Config(security_kconfig,kern_src_dir)ifconfisnotNone:formenuinconf.get_menus():ifmenu.get_title()=="Grsecurity":withcodecs.open(out_file_name,'w',"utf-8")asf:sysctl_opts=get_sysctl_opts(kern_src_dir)write_wikified_item(f,sysctl_opts,menu,1)break# kern_src_dir is expected to be an absolute path to the kernel# source directory (e.g. /usr/src/linux-3.2.48).kern_src_dir=sys.argv[1]ifkern_src_dirisnotNoneandlen(kern_src_dir)>0:write_wikified_kconfig(kern_src_dir,"Grsecurity_and_PaX_Configuration_Options.wiki")write_wikified_sysctl_opts(kern_src_dir,"Sysctl_Options.wiki")