Reinstate the seperate security section as a chapter.

1 files changed, 411 insertions, 0 deletions

diff --git a/docs/xml/security.xml b/docs/xml/security.xml
new file mode 100644
index 000000000..de859e6b5
--- /dev/null
+++ b/docs/xml/security.xml
@@ -0,0 +1,411 @@
+<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> -->
+<!-- $Id: security.xml,v 1.1 2004/12/02 04:21:27 jake%bugzilla.org Exp $ -->
+
+<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 kinda of firewall.
+      </para>
+    
+    </section>
+    
+    <section id="security-os-accounts">
+    <title>System User Accounts</title>
+    
+      <para>Many <glossterm linkend="gloss-daemon">daemon</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 comprimised it can
+      comprimise 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 webserver 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 unpresidented 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-mysql">
+  <title>MySQL</title>
+  
+    <section id="security-mysql-account">
+    <title>The MySQL System Account</title>
+    
+      <para>As mentioned in <xref linkend="security-os-accounts"/>, the MySQL
+      daemon should run as a non-privleged, unique user. Be sure to consult
+      the MySQL documentation or the documentation that came with your system
+      for instructions.
+      </para>
+    </section>
+    
+    <section id="security-mysql-root">
+    <title>The MySQL <quote>root</quote> and <quote>anonymous</quote> Users</title>
+    
+      <para>By default, MySQL comes with a <quote>root</quote> user with a
+      blank password and an <quote>anonymous</quote> user, also with a blank
+      password. In order to protect your data, the <quote>root</quote> user
+      should be given a password and the anonymous user should be disabled.
+      </para>
+      
+      <example id="security-mysql-account-root">
+      <title>Assigning the MySQL <quote>root</quote> User a Password</title>
+      
+        <screen>
+<prompt>bash$</prompt> mysql mysql
+<prompt>mysql&gt;</prompt> UPDATE user SET password = password('<replaceable>new_password</replaceable>') WHERE user = 'root';
+<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
+        </screen>
+      </example>
+      
+      <example id="security-mysql-account-anonymous">
+      <title>Disabling the MySQL <quote>anonymous</quote> User</title>
+        <screen>
+<prompt>bash$</prompt> mysql -u root -p mysql           <co id="security-mysql-account-anonymous-mysql"/>
+<prompt>Enter Password:</prompt> <replaceable>new_password</replaceable>
+<prompt>mysql&gt;</prompt> DELETE FROM user WHERE user = '';
+<prompt>mysql&gt;</prompt> FLUSH PRIVILEGES;
+        </screen>
+        <calloutlist>
+          <callout arearefs="security-mysql-account-anonymous-mysql">
+            <para>This command assumes that you have already completed
+            <xref linkend="security-mysql-account-root"/>.
+            </para>
+          </callout>
+        </calloutlist>
+      </example>
+          
+    </section>
+    
+    <section id="security-mysql-network">
+    <title>Network Access</title>
+    
+      <para>If MySQL and your webserver both run on the same machine and you
+      have no other reason to access MySQL remotely, then you should disable
+      the network access. This, along with the suggestion in
+      <xref linkend="security-os-ports"/>, will help protect your system from
+      any remote vulnerabilites in MySQL. This is done using different
+      methods in MySQL versions 3 and 4.
+      </para>
+      
+      <example>
+      <title>Disabling Networking in MySQL 3.x</title>
+      
+        <para>Simply enter the following in <filename>/etc/my.conf</filename>:
+        <screen>
+[myslqd]
+# Prevent network access to MySQL.
+skip-networking
+        </screen>
+        </para>
+      </example>
+      
+      <example>
+      <title>Disabling Networking in MySQL 4.x</title>
+      
+        <para>There's a bug in Bugzilla about this</para>
+      </example>
+      
+    </section>
+
+
+<!-- For possible addition in the future: How to better control the bugs user
+    <section id="security-mysql-bugs">
+    <title>The bugs User</title>
+    
+    </section>
+-->
+  
+  </section>
+  
+  
+  
+  <section id="security-webserver">
+  <title>Webserver</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 accessable from the web. Because of the way
+      Bugzilla is currently layed out, the list of what should and should not
+      be accessible is rather complicated. A new installation method is
+      currently in the works which should solve this by allowing files that
+      shouldn't be accessible from the web to be placed in directory outside
+      the webroot. See 
+      <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=44659">bug 44659</ulink>
+      for more information.
+      </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>
+                <member><filename>runtests.sh</filename></member>
+              </simplelist>
+              </para>
+            </listitem>
+            <listitem>
+              <para>But allow:
+              <simplelist type="inline">
+                <member><filename>localconfig.js</filename></member>
+                <member><filename>localconfig.rdf</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>
+            <listitem>
+              <para>But allow:
+              <simplelist type="inline">
+                <member><filename>duplicates.rdf</filename></member>
+              </simplelist>
+              </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 intrest 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 accessable. 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 point your web browser at the file; for example, to
+      test mozilla.org's installation, we'd try to access
+      <ulink url="http://bugzilla.mozilla.org/localconfig"/>. You should get
+      a <errorcode>403</errorcode> <errorname>Forbidden</errorname> error.
+      </para>
+      
+      <tip>
+        <para>Be sure to check <xref linkend="http"/> for instructions
+        specific to the webserver you use.
+        </para>
+      </tip>
+    
+    </section>
+
+
+    <section id="security-webserver-mod-throttle">
+      <title>Using <filename>mod_throttle</filename> to Prevent a DOS</title>
+
+      <note>
+        <para>This section only applies to people who have chosen the Apache
+        webserver. It may be possible to do similar things with other
+        webservers. Consult the documentation that came with your webserver
+        to find out.
+        </para>
+      </note>
+
+      <para>It is possible for a user, by mistake or on purpose, to access
+      the database many times in a row which can result in very slow access
+      speeds for other users (effectively, a
+      <glossterm linkend="gloss-dos">DOS</glossterm> attack). If your
+      Bugzilla installation is experiencing this problem, you may install
+      the Apache module <filename>mod_throttle</filename> which can limit
+      connections by IP address. You may download this module at 
+      <ulink url="http://www.snert.com/Software/mod_throttle/"/>.
+      Follow the instructions to install into your Apache install. 
+      The command you need is 
+      <command>ThrottleClientIP</command>. See the 
+      <ulink url="http://www.snert.com/Software/mod_throttle/">documentation</ulink>
+      for more information.</para>
+    </section>
+
+      
+  </section>
+  
+  
+  <section id="security-bugzilla">
+  <title>Bugzilla</title>
+
+    <section id="security-bugzilla-charset">
+    <title>Prevent users injecting malicious Javascript</title>
+
+      <para>It is possible for a Bugzilla user to take advantage of character
+      set encoding ambiguities to inject HTML into Bugzilla comments. This
+      could include malicious scripts. 
+      Due to internationalization concerns, we are unable to
+      incorporate by default the code changes suggested by 
+      <ulink
+      url="http://www.cert.org/tech_tips/malicious_code_mitigation.html#3">
+      the CERT advisory</ulink> on this issue.
+      If your installation is for an English speaking audience only, making the
+      change below will prevent this problem. 
+      </para>
+
+      <para>Simply locate the following line in
+      <filename>Bugzilla/CGI.pm</filename>:
+      <programlisting>$self->charset('');</programlisting>
+      and change it to:
+      <programlisting>$self->charset('ISO-8859-1');</programlisting>
+      </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: -->