<?xml version="1.0"?>
<!-- This Source Code Form is subject to the terms of the Mozilla Public
     License, v. 2.0. If a copy of the MPL was not distributed with this
     file, You can obtain one at http://mozilla.org/MPL/2.0/.

     This Source Code Form is "Incompatible With Secondary Licenses", as
     defined by the Mozilla Public License, v. 2.0.
-->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                      "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
    <!ENTITY % myents SYSTEM "bugzilla.ent">
    %myents;
]>

<chapter id="security">
<title>Bugzilla Security</title>

  <para>While some of the items in this chapter are related to the operating
  system Bugzilla is running on or some of the support software required to
  run Bugzilla, it is all related to protecting your data. This is not
  intended to be a comprehensive guide to securing Linux, Apache, MySQL, or
  any other piece of software mentioned. There is no substitute for active
  administration and monitoring of a machine. The key to good security is
  actually right in the middle of the word: <emphasis>U R It</emphasis>.
  </para>
  
  <para>While programmers in general always strive to write secure code,
  accidents can and do happen. The best approach to security is to always
  assume that the program you are working with isn't 100% secure and restrict
  its access to other parts of your machine as much as possible.
  </para>
 
  <section id="security-os">
  <title>Operating System</title>
  
    <section id="security-os-ports">
    <title>TCP/IP Ports</title>
    
      <!-- TODO: Get exact number of ports -->
      <para>The TCP/IP standard defines more than 65,000 ports for sending
      and receiving traffic. Of those, Bugzilla needs exactly one to operate
      (different configurations and options may require up to 3). You should
      audit your server and make sure that you aren't listening on any ports
      you don't need to be. It's also highly recommended that the server
      Bugzilla resides on, along with any other machines you administer, be
      placed behind some kind of firewall.
      </para>
    
    </section>
    
    <section id="security-os-accounts">
    <title>System User Accounts</title>
    
      <para>Many <glossterm linkend="gloss-daemon">daemons</glossterm>, such
      as Apache's <filename>httpd</filename> or MySQL's
      <filename>mysqld</filename>, run as either <quote>root</quote> or
      <quote>nobody</quote>. This is even worse on Windows machines where the
      majority of <glossterm linkend="gloss-service">services</glossterm>
      run as <quote>SYSTEM</quote>. While running as <quote>root</quote> or
      <quote>SYSTEM</quote> introduces obvious security concerns, the
      problems introduced by running everything as <quote>nobody</quote> may
      not be so obvious. Basically, if you run every daemon as
      <quote>nobody</quote> and one of them gets compromised it can
      compromise every other daemon running as <quote>nobody</quote> on your
      machine. For this reason, it is recommended that you create a user
      account for each daemon.
      </para>
    
      <note>
        <para>You will need to set the <option>webservergroup</option> option
        in <filename>localconfig</filename> to the group your web server runs
        as. This will allow <filename>./checksetup.pl</filename> to set file
        permissions on Unix systems so that nothing is world-writable.
        </para>
      </note>
    
    </section>
    
    <section id="security-os-chroot">
    <title>The <filename>chroot</filename> Jail</title>
    
      <para>
        If your system supports it, you may wish to consider running
        Bugzilla inside of a <filename>chroot</filename> jail. This option
        provides unprecedented security by restricting anything running
        inside the jail from accessing any information outside of it. If you
        wish to use this option, please consult the documentation that came
        with your system.
      </para>
      
    </section>
  
  </section>

  <section id="security-webserver">
  <title>Web server</title>

    <section id="security-webserver-access">
    <title>Disabling Remote Access to Bugzilla Configuration Files</title>
    
      <para>
        There are many files that are placed in the Bugzilla directory
        area that should not be accessible from the web server. Because of the way
        Bugzilla is currently layed out, the list of what should and should not
        be accessible is rather complicated. A quick way is to run
        <filename>testserver.pl</filename> to check if your web server serves
        Bugzilla files as expected. If not, you may want to follow the few
        steps below.
      </para>
      
      <tip>
        <para>Bugzilla ships with the ability to create
        <glossterm linkend="gloss-htaccess"><filename>.htaccess</filename></glossterm>
        files that enforce these rules. Instructions for enabling these
        directives in Apache can be found in <xref linkend="http-apache"/>
        </para>
      </tip>
        
      <itemizedlist spacing="compact">
        <listitem>
          <para>In the main Bugzilla directory, you should:</para>
          <itemizedlist spacing="compact">
            <listitem>
              <para>Block:
              <simplelist type="inline">
                <member><filename>*.pl</filename></member>
                <member><filename>*localconfig*</filename></member>
              </simplelist>
              </para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>In <filename class="directory">data</filename>:</para>
          <itemizedlist spacing="compact">
            <listitem>
              <para>Block everything</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>In <filename class="directory">data/webdot</filename>:</para>
          <itemizedlist spacing="compact">
            <listitem>
              <para>If you use a remote webdot server:</para>
              <itemizedlist spacing="compact">
                <listitem>
                  <para>Block everything</para>
                </listitem>
                <listitem>
                  <para>But allow
                  <simplelist type="inline">
                    <member><filename>*.dot</filename></member>
                  </simplelist>
                  only for the remote webdot server</para>
                </listitem>
              </itemizedlist>
            </listitem>
            <listitem>
              <para>Otherwise, if you use a local GraphViz:</para>
              <itemizedlist spacing="compact">
                <listitem>
                  <para>Block everything</para>
                </listitem>
                <listitem>
                  <para>But allow:
                  <simplelist type="inline">
                    <member><filename>*.png</filename></member>
                    <member><filename>*.gif</filename></member>
                    <member><filename>*.jpg</filename></member>
                    <member><filename>*.map</filename></member>
                  </simplelist>
                  </para>
                </listitem>
              </itemizedlist>
            </listitem>
            <listitem>
              <para>And if you don't use any dot:</para>
              <itemizedlist spacing="compact">
                <listitem>
                  <para>Block everything</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>In <filename class="directory">Bugzilla</filename>:</para>
          <itemizedlist spacing="compact">
            <listitem>
              <para>Block everything</para>
            </listitem>
          </itemizedlist>
        </listitem>

        <listitem>
          <para>In <filename class="directory">template</filename>:</para>
          <itemizedlist spacing="compact">
            <listitem>
              <para>Block everything</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

      <para>Be sure to test that data that should not be accessed remotely is
      properly blocked. Of particular interest is the localconfig file which
      contains your database password. Also, be aware that many editors
      create temporary and backup files in the working directory and that
      those should also not be accessible. For more information, see
      <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=186383">bug 186383</ulink>
      or
      <ulink url="http://online.securityfocus.com/bid/6501">Bugtraq ID 6501</ulink>.
      To test, simply run <filename>testserver.pl</filename>, as said above.
      </para>
      
      <tip>
        <para>Be sure to check <xref linkend="http"/> for instructions
        specific to the web server you use.
        </para>
      </tip>
    
    </section>

      
  </section>
  
  
  <section id="security-bugzilla">
  <title>Bugzilla</title>

    <section id="security-bugzilla-charset">
    <title>Prevent users injecting malicious Javascript</title>

      <para>If you installed Bugzilla version 2.22 or later from scratch,
      then the <emphasis>utf8</emphasis> parameter is switched on by default.
      This makes Bugzilla explicitly set the character encoding, following
      <ulink
      url="http://www.cert.org/tech_tips/malicious_code_mitigation.html#3">a
      CERT advisory</ulink> recommending exactly this.
      The following therefore does not apply to you; just keep
      <emphasis>utf8</emphasis> turned on.
      </para>

      <para>If you've upgraded from an older version, then it may be possible
      for a Bugzilla user to take advantage of character set encoding
      ambiguities to inject HTML into Bugzilla comments.
      This could include malicious scripts. 
      This is because due to internationalization concerns, we are unable to
      turn the <emphasis>utf8</emphasis> parameter on by default for upgraded
      installations.
      Turning it on manually will prevent this problem.
      </para>
    </section>    
    
  </section>

</chapter> 

<!-- Keep this comment at the end of the file 
Local variables: 
mode: sgml 
sgml-always-quote-attributes:t
sgml-auto-insert-required-elements:t
sgml-balanced-tag-edit:t
sgml-exposed-tags:nil
sgml-general-insert-case:lower
sgml-indent-data:t 
sgml-indent-step:2 
sgml-local-catalogs:nil
sgml-local-ecat-files:nil 
sgml-minimize-attributes:nil
sgml-namecase-general:t 
sgml-omittag:t
sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
sgml-shorttag:t 
sgml-tag-region-if-active:t 
End: -->
