- <sect id="bpp-debian-security-audit">
- <heading>Best practices for security review and design</heading>
-
-<p>When you are packaging software for other users you should make a
-best effort to ensure that the installation of the software, or its
-use, does not introduce security risks to either the system it is
-installed on or its users.</p>
-
-<p>You should make your best to review the source code of the package and
-detect issues that might introduce security bugs. The programming bugs
-which lead to security bugs typically include: <url
-id="http://en.wikipedia.org/wiki/Buffer_overflow" name="buffer
-overflows">, <url
-id="http://en.wikipedia.org/wiki/Cross_site_scripting" name="format
-string overflows">, <url
-id="http://en.wikipedia.org/wiki/Cross_site_scripting" name="heap
-overflows"> and <url
-id="http://en.wikipedia.org/wiki/Cross_site_scripting" name="integer
-overflows"> (in C/C++ programs), temporary <url
-id="http://en.wikipedia.org/wiki/Symlink_race" name="symlink race
-conditions"> (in scripts), <url
-id="http://en.wikipedia.org/wiki/Directory_traversal" name="directory
-traversal"> and command injection (in servers) and <url
-id="http://en.wikipedia.org/wiki/Cross_site_scripting"
-name="cross-site scripting">, and <url
-id="http://en.wikipedia.org/wiki/Cross_site_scripting" name="SQL
-injection bugs"> (in the case of web-oriented applications).</p>
-
-<p>Some of these issues might not be easy to spot unless you are an
-expert in the programming language the program uses, but some security
-problems are easy to detect and fix. For example, finding temporary
-race conditions in the source code can easily be done by running
-<tt>grep -r "/tmp/" .</tt> in the source code replace
-hardcoded filenames using temporary directories to calls to either
-<prgn>mktemp</prgn> or <prgn>tempfile</prgn> in shell
-scripts, <manref name="File::Temp" section="3perl"> in Perl scripts,
-and <manref name="tmpfile" section="3"> in C/C++. You can also use
-<url id="http://www.debian.org/security/audit/tools" name="specific
-tools"> to assist to the security code review phase.</p>
-
-<p>When packaging software make sure that:
-
-<list>
-
-<item>The software runs with the minimum privileges it needs:
-
-<list>
-<item>The package does install binaries setuid or setgid.
-<prgn>Lintian</prgn> will warn of <url id="
-http://lintian.debian.org/reports/Tsetuid-binary.html" name="setuid">,
-<url id="http://lintian.debian.org/reports/Tsetgid-binary.html"
-name="setgid"> and <url
-id="http://lintian.debian.org/reports/Tsetuid-gid-binary.html"
-name="setuid and setgid"> binaries.
-
-<item>The daemons the package provide run with a
-low privilege user (see <ref id="bpp-lower-privs">)
-
-</list>
-
-<item>Programmed (i.e., <prgn>cron</prgn>) tasks running in the
-system do NOT run as root or, if they do, do not implement complex
-tasks.
-
-</list>
-
-<p>If you have to do any of the above make sure the programs that
-might run with higher privileges have been audited for security
-bugs. If you are unsure, or need help, contact the <url
-id="http://www.debian.org/security/audit/" name="Debian Security Audit
-team">. In the case of setuid/setgid binaries, follow the Debian
-policy section regarding
-<url id="http://www.debian.org/doc/debian-policy/ch-files.html#s10.9"
-name="permissions and owners">
-</p>
-
-<p>For more information, specific to secure programming, make sure you
-read (or point your upstream to) <url
-id="http://www.dwheeler.com/secure-programs/" name="Secure Programming
-for Linux and Unix HOWTO"> and the <url
-id="https://buildsecurityin.us-cert.gov/portal/" name="Build Security
-In"> portal. For more information specific to Debian security you can
-read the <url
-id="http://www.debian.org/doc/manuals/securing-debian-howto/"
-name="Debian Security Manual">
-</p>
-
-<!-- This should be explained here until #291177 gets fixed and this is
- added to poliy -->
-
- <sect1 id="bpp-lower-privs">
- <heading>System users and groups for software daemons
-
-<p>If your software runs a daemon that does not need root privileges,
-you need to create a user for it. There are two kind of Debian users
-that can be used by packages: static uids (assigned by
-<package>base-passwd</package>) and dynamic uids in the range assigned
-to system users.
-
-<p>In the first case, you need to ask for a user or group id to the
-<package>base-passwd</package>, and a proper versioned depends to the
-<package>base-passwd</package> package that provides the user.
-
-<p>In the second case, you need to create the system user through maintainer
-scripts. <url id="http://www.debian.org/doc/debian-policy/ch-files.html#s10.9"
-name="policy"> requires you discuss an appropiate user and group name on
-<em>debian-devel</em> and make sure it is unique and does not overlap
-with other packages.
-
-<p>Running programs with a user with limited privileges makes sure
-that any security issue with the program makes limited damaged to the
-system and follows the principle of <em>least privilege</em> you can
-limit privileges in programs through other mechanisms besides running
-as non-root. Fore more information, read the <url
-id="http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/minimize-privileges.html"
-name="Minimize Privileges"> chapter of the <em>Secure Programming for
-Linux and Unix HOWTO</em> book.
-
- <sect2 id="bpp-create-sysuser">
- <heading>Creating system users and groups
-
-<p>If you want to create system groups on package installation you
-need to create it in either the <em>preinst</em> or in the <em>postinst</em>
-and have the package depend on <tt>adduser (>= 3.11)</tt>.
-
-<p>The following example code creates the user and group the daemon
-will run as when the package is installed or upgraded:
-
-<example>
-[...]
-case "$1" in
- install|upgrade)
-
- # If the package has default file it could be sourced, so that
- # the local admin can overwrite the defaults
- # Notice that the package could handle this defaults through
- # debconf so that the local admin could select a different
- # user name for the system user than the one hardcoded in the
- # package
-
- [ -f "/etc/default/<var>packagename</var>" ] && . /etc/default/<var>packagename</var>
-
-
- # Sane defaults:
-
- [ -z "$SERVER_HOME" ] && SERVER_HOME=<var>server_dir</var>
- [ -z "$SERVER_USER" ] && SERVER_USER=<var>server_user</var>
- [ -z "$SERVER_NAME" ] && SERVER_NAME="<var>Server description</var>"
- [ -z "$SERVER_GROUP" ] && SERVER_GROUP=<var>server_group</var>
-
- # Groups that the user will be added to, if undefined, then none.
- # Some daemons might need additional privileges and those can be
- # granted by adding it to additional groups.
- ADDGROUP=""
-
-
- # create user to avoid running server as root
- # 1. create group if not existing
- if ! getent group | grep -q "^$SERVER_GROUP:" ; then
- echo -n "Adding system group $SERVER_GROUP.."
- addgroup --quiet --system $SERVER_GROUP
- if ! getent group | grep -q "^$SERVER_GROUP:"; then
- echo "..ERROR creating system group. Aborting installation."
- exit 1
- fi
- echo "..done"
- fi
- # 2. create homedir if it does not exist
- test -d $SERVER_HOME || mkdir $SERVER_HOME
- # 3. create user if it does not exist
- if ! getent passwd | grep -q "^$SERVER_USER:"; then
- echo -n "Adding system user $SERVER_USER.."
- adduser --quiet \
- --system \
- --ingroup $SERVER_GROUP \
- --no-create-home \
- --disabled-password \
- $SERVER_USER
- if ! getent passwd | grep -q "^$SERVER_USER:"; then
- echo "..ERROR creating system user. Aborting installation."
- exit 1
- fi
- echo "..done"
- # 4. adjust passwd entry, only do this if the package
- # creates the user
- usermod -c "$SERVER_NAME" \
- -d $SERVER_HOME \
- -g $SERVER_GROUP \
- $SERVER_USER
- else
- # The package might want to check if the user already exists
- # and it is *not* a system user, in this case it could abort
- # the installation (like in this example) or ask the administrator.
- # Using a non-system user as the one in our package could
- # have unexpected consequences.
- # Some packages try to prevent this kind of collision by using
- # a prefix such as 'Debian-'
- for LINE in `grep SYSTEM_UID /etc/adduser.conf | grep -v "^#"`; do
- case $LINE in
- FIRST_SYSTEM_UID*)
- FIRST_SYSTEM_UID=`echo $LINE | cut -f2 -d '='`
- ;;
- LAST_SYSTEM_UID*)
- LAST_SYSTEM_UID=`echo $LINE | cut -f2 -d '='`
- ;;
- *)
- ;;
- esac
- done
- # Abort package installation if the user has not been created by
- # us.
- if [ -n "$FIRST_SYSTEM_UID" ] && [ -n "$LAST_SYSTEM_UID" ]; then
- if USERID=`getent passwd $SERVER_USER | cut -f 3 -d ':'`; then
- if [ -n "$USERID" ]; then
- if [ "$FIRST_SYSTEM_UID" -le "$USERID" ] && \
- [ "$USERID" -le "$LAST_SYSTEM_UID" ]; then
- echo "The user $SERVER_USER already exists as a non system user!" >&2
- echo "Aborting package installation" >&2
- exit 1
- fi
- fi
- fi
- fi
- fi
-
- # 5. adjust file and directory permissions
- # The example below sets the server home as 750 as it
- # contains (hypothetically) sensible information.
- if ! dpkg-statoverride --list $SERVER_HOME >/dev/null
- then
- chown -R $SERVER_USER:adm $SERVER_HOME
- chmod u=rwx,g=rxs,o= $SERVER_HOME
- fi
- # 6. Add the user to the ADDGROUP group
- if test -n $ADDGROUP
- then
- if ! groups $SERVER_USER | grep -q $ADDGROUP; then
- adduser $SERVER_USER $ADDGROUP
- fi
- fi
- ;;
- configure)
-
-[...]
-</example>
-
- <sect2 id="bpp-using-sysuser">
- <heading>Using system users
-
-<p>In order to make use of the system user you have to make sure that the
-init.d script file:
-
-<list>
-<item>Starts the daemon dropping privileges, if the software does not
-do the <manref name="setuid" section="2"> or <manref name="seteuid"
-section="2"> call itself, you can use the <tt>--chuid</tt>
-call of <prgn>start-stop-daemon</prgn>.
-
-<item>Stops the daemon only if the user id matches, you can use the
-<prgn>start-stop-daemon</prgn> <tt>--user</tt> option
-for this.
-
-<item>Does not run if either the user or the group do not exist:
-<example>
- if getent passwd | grep -q "^<var>server_user</var>:"; then
- echo "Server user does not exist. Aborting" >&2
- exit 1
- fi
- if getent group | grep -q "^<var>server_group</var>:" ; then
- echo "Server group does not exist. Aborting" >&2
- exit 1
- fi
-</example>
-
-</list>
-
-<p>File ownerships of files shipped by the package will need to be adjusted:
-
-<list>
-<item>Configuration files should be readable by the system user, if they
-contain sensitive information the system user should not own them unless there
-is a need for it to write to its own configuration files. Typically this means
-that the configuration files are owned by root and by the system group created
-by the package and are mode 0640.
-
-<item>If the The system user generates state files (such as pidfiles) it will
-need to have a directory under <tt>/var/run</tt> owned by itself. It can be
-created by the package maintainers script but, since it can be wiped after a
-system reboot, it should be be recreated by the init.d script since the state
-directory.
-
-<item>If the daemon logs directly to <tt>/var/log</tt> logfiles should be
-writable by the system user but, once rotated, they should not be either owned
-or writable by it to prevent it from overwritting old log entries if a security
-vulnerability in the software were to be used. If the daemon logs to a
-directory under <tt>/var/log/</tt> then the directory should be owned by the
-system user and rotated log files need not be changed ownership.
-
-</list>
-
- <sect2 id="bpp-removing-sysuser">
- <heading>Removing system users
-
-<p>If the package creates the system user it can remove it when it is
-purged in its <em>postrm</em> script. This currently <em>not</em> recommended
-for all situations since it has a few known
-<footnote>
-Some relevant threads discussing these issues include:
-<url
-id="http://lists.debian.org/debian-mentors/2004/10/msg00338.html">,
-<url id="http://lists.debian.org/debian-devel/2004/05/msg01156.html">
-and
-<url id="http://lists.debian.org/debian-devel/2005/10/msg00988.html">.
-</footnote>
-drawbacks. For example, files created by the daemon (or by an admin
-impersonating it) either on the local filesystem or in backup files will be
-orphaned and might be taken over by a new system user in the future if it is
-assigned the same uid. On the other hand, an unused local system user can be
-used to access even if the account has been locked (as some authentication
-systems might not use PAM or shadow authentication).
-
-<p>If you want to remove a system user and there is a possibility of it
-leaving orphaned files, the administrator should be asked for the preferred
-action either when the package is installed or when it is removed (see <ref
-id="debconf">).
-
-<p>The following example code removes the user and groups created
-before only, and only if, the uid is in the range of dynamic assigned system
-uids and the gid is belongs to a system group:
-
-<example>
-case "$1" in
- purge)
-[...]
- # find first and last SYSTEM_UID numbers
- if [ -r /etc/adduser.conf ] ; then
- for LINE in `grep SYSTEM_UID /etc/adduser.conf | grep -v "^#"`; do
- case $LINE in
- FIRST_SYSTEM_UID*)
- FIRST_SYSTEM_UID=`echo $LINE | cut -f2 -d '='`
- ;;
- LAST_SYSTEM_UID*)
- LAST_SYSTEM_UID=`echo $LINE | cut -f2 -d '='`
- ;;
- FIRST_SYSTEM_GID*)
- FIRST_SYSTEM_GID=`echo $LINE | cut -f2 -d '='`
- ;;
- LAST_SYSTEM_GID*)
- LAST_SYSTEM_GID=`echo $LINE | cut -f2 -d '='`
- ;;
- *)
- ;;
- esac
- done
- fi
- # Sane defaults
- [ -z "$FIRST_SYSTEM_UID" ] && FIRST_SYSTEM_UID=100
- [ -z "$LAST_SYSTEM_UID" ] && LAST_SYSTEM_UID=999
- [ -z "$FIRST_SYSTEM_GID" ] && FIRST_SYSTEM_GID=100
- [ -z "$LAST_SYSTEM_GID" ] && LAST_SYSTEM_GID=999
-
- # Remove system account if it is a system user
- CREATEDUSER="<var>server_user</var>"
- if [ -n "$FIRST_SYSTEM_UID" ] && [ -n "$LAST_SYSTEM_UID" ]; then
- if USERID=`getent passwd $CREATEDUSER | cut -f 3 -d ':'`; then
- if [ -n "$USERID" ]; then
- if [ "$FIRST_SYSTEM_UID" -le "$USERID" ] && \
- [ "$USERID" -le "$LAST_SYSTEM_UID" ]; then
- echo -n "Removing $CREATEDUSER system user.."
- deluser --quiet $CREATEDUSER || true
- echo "..done"
- fi
- fi
- fi
- fi
- # Remove system group if it is a system group
- CREATEDGROUP=<var>server_group</var>
- if [ -n "$FIRST_SYSTEM_GID" ] && [ -n "$LAST_SYSTEM_GID" ]; then
- if GROUPGID=`getent group $CREATEDGROUP | cut -f 3 -d ':'`; then
- if [ -n "$GROUPGID" ]; then
- if [ "$FIRST_SYSTEM_GID" -le "$GROUPID" ] && \
- [ "$GROUPID" -le "$LAST_SYSTEM_GID" ]; then
- echo -n "Removing $CREATEDGROUP group.."
- delgroup --only-if-empty $CREATEDGROUP || true
- echo "..done"
- fi
- fi
- fi
- fi
-[...]
-</example>
-
-<p>Other possibilities, are making sure the account is locked (has an invalid
-password and <em>/bin/false</em> as a shell) and/or changing the GECOS field
-pointing out that the account is no longer used.
-
-<!-- There is currently no consensus as to how any of the above should be
- done in a way that would make it easy for administrators to locate
- unused (but not removed) accounts -->
-
-</sect1>
-
-</sect>