Doc

  • Launchpad entry: none yet

  • Created: 2006-08-02 by JohnMoser

  • Contributors: JohnMoser

  • Packages affected:

Summary

This spec defines a documentation aspect of the Ubuntu Hardened Team specified in HardenedUbuntu: The Ubuntu Hardened Documentation Team.

Rationale

Security is a function of the developers' and the end users' understanding of the system. If the developers do not make a secure system, the end user is exposed to risks he can't fix; and if the end user does not know how to use the system, he will open up unnecessary security holes with bad configuration. It is therefor security-critical that good documentation exist for both the developers and the end user specifically relating to security.

Use cases

There are several.

Developer:

  • A new Ubuntu Hardened Audit Team member reads the Ubuntu Hardened Developer's Guide and begins to use scanelf to locate and fix TEXTRELs and executable stacks.

  • A user interested in security reads the Ubuntu Hardened Developer's Guide and begins to toy with elfsh and flawfinder, and crawl bugtraq. He eventually earns a spot on the Ubuntu Hardened Source Code Auditing Team and also helps the Ubuntu Hardened Vulnerability Team quite frequently.

  • An end user is using Ubuntu as his development platform. He reads the Ubuntu Hardened Developer's Guide and finds information on writing secure code, auditing his own code, preventing executable stacks, and avoiding or removing TEXTRELs.

End User:

  • Alice wants to use the hardened Ubuntu kernel instead of the stock. She reads the Ubuntu User's Guide section on security and learns how to properly use the grsecurity learning mode to develop policy for her system.

  • Bob wants to install openssh-server. The description points him to a section in the Ubuntu User's Guide; he finds documentation about disabling remote root log-in.

Scope

The scope of the documentation includes the following:

  • Developer documentation
    • Preface
      • Explanation Ubuntu security policies and responsible disclosure practices
      • Explanation of several common security attacks and concerns

      • Detailed descriptions of each security feature including address space randomization, GccSsp, PositionIndependentExecutables, and mandatory access control systems

        • Descriptions of what security concerns each security feature mitigates, including example exploits where possible
        • Details of the mechanism employed to correct these concerns
        • Explanation of the general impact this has on what programs can do, if any
    • Ubuntu Hardened Audit Team documentation
      • Regression test suites for each security feature and instructions on using them
      • Guide for locating and removing executable stacks
      • Guide for locating and removing ELF TEXTRELs

      • Guide for fixing code that refuses to compile PIC to create PositionIndependentExecutables

      • Guide for fixing programs that depend on bad MemoryProtections

    • Ubuntu Hardened Configuration Team documentation
      • Explain the basic configuration issues that may arise
        • Default configurations supplying known user names and passwords
        • Default configurations enabling features that aren't commonly used

        • Default configurations that are generally wrong (i.e. sharing all directories, allowing NULL encryption...)

    • Ubuntu Hardened Kernel Team documentation
      • List different available security patches used in the Ubuntu Hardened Kernel
        • Explain who created each security patch and how to get in touch with them
        • Explain what each patch does and why it's used
      • Describe the order in which patches get stacked, based on which are most likely to eventually make Ubuntu stock kernel inclusion
        • Vulnerability patches first, these definitely have to go to the stock kernel ASAP and should probably never be solely in the Hardened kernel
        • Non-invasive patches next, in order based on opinions the Kernel team has voiced about inclusion in the Ubuntu stock kernel
        • Patches with no chance of inclusion in the Ubuntu stock kernel last
    • Ubuntu Hardened Source Code Auditing Team documentation
      • Explanation of how the Source Code Auditing Team interacts with other teams
      • Explanation of how the Source Code Auditing Team interacts with other distributions and upstream projects
      • Descriptions of various security issues that can be found in code written in various programming languages
      • Guides for using auditing tools to supplement manual auditing

        • Source code auditing tools such as rats and flawfinder

        • Binary debugging tools such as elfsh and gdb

    • Ubuntu Hardened Toolchain Team documentation

      • Documentation for each of the security features of the current gcc toolchain

        • Descriptions of what security concerns each security feature mitigates, including example exploits where possible
        • Details of the mechanism employed to correct these concerns
        • Explanation of the general impact this has on what programs can do, if any
        • Switches required to turn it on and off

      • Guide to gcc specs file hacking

    • Ubuntu Hardened Vulnerability Team documentation
      • Explanation of the common classes of security vulnerabilities
      • List of various sources of new vulnerability information
      • Policies and procedures for releasing USNs
      • Methods for contacting other distributions and upstream
  • User documentation
    • Applying patches

      • Using update-notifier

      • Enabling automatic security updates
    • Secure passwords
      • General password guidelines

      • Enabling pam secure password features

    • PGP encryption
      • Functions of PGP encryption
        • Digital signatures
        • Encryption
      • Uses for PGP encryption
        • E-mail

        • Instant Messaging using gaim plug-ins (which are unfortunately out of date)

      • Installing and configuring Seahorse
      • Generating or importing a PGP key

      • Using your PGP key in various applications such as Evolution, Thunderbird, Nautilus, gaim

    • AutomatedProblemReports

      • Description of Ubuntu's crash reporter
        • What data it collects
        • How to enable automatic reporting
        • Advantages to automatic crash reporting
      • Explanation of sensitive data
        • Which data is not automatically sent
        • How to review and send this data after a crash
    • Ubuntu security features

      • GccSsp

      • Address space ranodmization

      • glibc heap corruption and double-free() detection

      • Hardened kernel
      • Mandatory access control policies

Note that the scope is easily flexible and must change based on current technology, software, and Ubuntu policy.

Design

The developer's documentation will contain information for Ubuntu Hardened developers for all teams.

The user's documentation will contain basic, need-to-know information as well as a description of all Ubuntu security features.

The user's documentation should come in two flavors, possibly in the same documentation set:

  • Basic. Basic, need-to-know information in very friendly language. This needs to get the user to the "if something breaks I can click this button to fix it" point. Major technical details not needed for risk analysis by Joe User on his personal non-business machine can be left out; and our run-through of basic security features can be very brief and lightweight.

  • Advanced. Technical run-down in moderate detail to describe the theory and functionality of each of our security measures. Includes enough information to perform a risk-analysis of using Ubuntu and of disabling or altering any security policies in it; but also includes all of the basic "this is how you turn these things on and off" information in an easy-to-find manner. Security engineers are still people, the job is easier when the manual pretends to be For Dummies(TM).

Implementation

A LOT of documentation needs to be written.

Code

Data preservation and migration

Unresolved issues

Doc team should probably have documentation too, for style and formatting.

BoF agenda and discussion

CategorySpec

HardenedUbuntu/Doc (last edited 2008-08-06 16:38:19 by localhost)