source: postlfs/security/tripwire.xml@ 2634774

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY tripwire-download-http "https://github.com/Tripwire/tripwire-open-source/archive/&tripwire-version;.tar.gz">
  <!ENTITY tripwire-download-ftp  " ">
  <!ENTITY tripwire-md5sum        "4ec693b96112e4933235f75908695951">
  <!ENTITY tripwire-size          "945 KB">
  <!ENTITY tripwire-buildsize     "33 MB">
  <!ENTITY tripwire-time          "1.2 SBU (scripting install)">
]>

<sect1 id="tripwire" xreflabel="Tripwire-&tripwire-version;">
  <?dbhtml filename="tripwire.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Tripwire-&tripwire-version;</title>

  <indexterm zone="tripwire">
    <primary sortas="a-Tripwire">Tripwire</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Tripwire</title>

    <para>The <application>Tripwire</application> package contains programs
    used to verify the integrity of the files on a given system.</para>

    &lfs7a_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&tripwire-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&tripwire-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &tripwire-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &tripwire-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &tripwire-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &tripwire-time;</para>
      </listitem>
    </itemizedlist>

    <note>
      <para>
        The <application>tripwire</application> source tarball shown above
        downloads with the correct name, tripwire-open-source-&tripwire-version;.tar.gz,
        if using a browser such as Firefox. If you prefer to use a command line
        program such as wget, you normally would obtain
        &tripwire-version;.tar.gz. To obtain this package with the proper
        filename, run:

<screen><userinput>wget -c https://github.com/Tripwire/tripwire-open-source/archive/&tripwire-version;.tar.gz \
     -O tripwire-open-source-&tripwire-version;.tar.gz</userinput></screen>.
      </para>
    </note>

    <bridgehead renderas="sect3">Tripwire Dependencies</bridgehead>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended"><xref linkend="openssl"/></para>


    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">An <xref linkend="server-mail"/></para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/tripwire"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Tripwire</title>

    <para>Compile <application>Tripwire</application> by running the following
    commands:</para>

<screen><userinput>sed -e 's|TWDB="${prefix}|TWDB="/var|'   \
    -e '/TWMAN/ s|${prefix}|/usr/share|' \
    -e '/TWDOCS/s|${prefix}/doc/tripwire|/usr/share/doc/tripwire-&tripwire-version;|' \
    -i installer/install.cfg                               &amp;&amp;
find . -name Makefile.am | xargs                           \
    sed -i 's/^[[:alpha:]_]*_HEADERS.*=/noinst_HEADERS =/' &amp;&amp;
sed '/dist/d' -i man/man?/Makefile.am                      &amp;&amp;
autoreconf -fi                                             &amp;&amp;

./configure --prefix=/usr --sysconfdir=/etc/tripwire       &amp;&amp;
make</userinput></screen>

    <note><para>The default configuration is to use a local MTA. If
    you don't have an MTA installed and have no wish to install
    one, modify <filename>install/install.cfg</filename> to use an SMTP
    server instead.  Otherwise the install will fail.</para></note>

    <para>This package does not come with a test suite.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install &amp;&amp;
cp -v policy/*.txt /usr/share/doc/tripwire-&tripwire-version;</userinput></screen>

    <note>
      <para>
        During <command>make install</command>, several questions
        are asked, including passwords. If you want to make a script, you have
        to apply a <application>sed</application> before running
        <command>make install</command>:
      </para>

<screen><userinput>sed -i -e 's@installer/install.sh@&amp; -n -s <replaceable>&lt;site-password&gt;</replaceable> -l <replaceable>&lt;local-password&gt;</replaceable>@' Makefile</userinput></screen>

      <para>
        Of course, you should do this with dummy passwords and change them
        later.
      </para>

      <para>
        Another issue when scripting is that the installer exits when the
        standard input is not a terminal. You may disable this behavior
        with the following sed:
      </para>

<screen><userinput>sed '/-t 0/,+3d' -i installer/install.sh</userinput></screen>

    </note>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>sed ... installer/install.cfg</command>: This command tells
      the package to install the program database and reports in
      <filename class="directory">/var/lib/tripwire</filename> and sets the
      proper location for man pages and documentation.
    </para>

    <para>
      <command>find ...</command>, <command>sed ...</command>, and
      <command>autoreconf -fi</command>: The build system is unusable as is, and
      has to be modified for the build to succeed.
    </para>

    <para>
      <command>make install</command>: This command creates the
      <application>Tripwire</application> security keys as well as installing
      the binaries. There are two keys: a site key and a local key which are
      stored in <filename class="directory">/etc/tripwire/</filename>.
    </para>

    <para>
      <command>cp -v policy/*.txt /usr/doc/tripwire-&tripwire-version;</command>:
      This command installs the <application>tripwire</application> sample
      policy files with the other <application>tripwire</application>
      documentation.i
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Tripwire</title>

    <sect3 id="tripwire-config">
      <title>Config Files</title>

      <para><filename>/etc/tripwire/*</filename></para>

      <indexterm zone="tripwire tripwire-config">
        <primary sortas="e-etc-tripwire">/etc/tripwire/*</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para><application>Tripwire</application> uses a policy file to
      determine which files are integrity checked. The default policy
      file (<filename>/etc/tripwire/twpol.txt</filename>) is for a
      default installation and will need to be updated for your
      system.</para>

      <para>Policy files should be tailored to each individual distribution
      and/or installation. Some example policy files can be found in <filename
      class="directory">/usr/share/doc/tripwire/</filename>.</para>

      <para>If desired, copy the policy file you'd like to try into <filename
      class="directory">/etc/tripwire/</filename> instead of using the default
      policy file, <filename>twpol.txt</filename>.  It is, however, recommended
      that you edit your policy file. Get ideas from the examples above and
      read <filename>/usr/share/doc/tripwire/policyguide.txt</filename> for
      additional information. <filename>twpol.txt</filename> is a good policy
      file for learning about <application>Tripwire</application> as it will
      note any changes to the file system and can even be used as an annoying
      way of keeping track of changes for uninstallation of software.</para>

      <para>After your policy file has been edited to your satisfaction you may
      begin the configuration steps (perform as the <systemitem
      class='username'>root</systemitem>) user:</para>

<screen role="root"><userinput>twadmin --create-polfile --site-keyfile /etc/tripwire/site.key \
    /etc/tripwire/twpol.txt &amp;&amp;
tripwire --init</userinput></screen>

    <para>Depending on your system and the contents of the policy file, the
    initialization phase above can take a relatively long time.</para>

    </sect3>

    <sect3>
      <title>Usage Information</title>

      <para><application>Tripwire</application> will identify file changes in
      the critical system files specified in the policy file.  Using
      <application>Tripwire</application> while making frequent changes to
      these directories will flag all these changes.  It is most useful after a
      system has reached a configuration that the user considers stable.</para>

      <para>To use <application>Tripwire</application> after creating a policy
      file to run a report, use the following command:</para>

<screen role="root"><userinput>tripwire --check &gt; /etc/tripwire/report.txt</userinput></screen>

      <para>View the output to check the integrity of your files. An automatic
      integrity report can be produced by using a cron facility to schedule the
      runs.</para>

      <para>Reports are stored in binary and, if desired, encrypted.  View reports,
      as the <systemitem class="username">root</systemitem> user, with:</para>

<screen role="root"><userinput>twprint --print-report -r /var/lib/tripwire/report/<replaceable>&lt;report-name.twr&gt;</replaceable></userinput></screen>

      <para>After you run an integrity check, you should examine the
      report (or email) and then modify the <application>Tripwire</application>
      database to reflect the changed files on your system. This is so that
      <application>Tripwire</application> will not continually notify you that
      files you intentionally changed are a security violation. To do this you
      must first <command>ls -l /var/lib/tripwire/report/</command> and note
      the name of the newest file which starts with your system name as
      presented by the command <userinput>uname -n</userinput>
      and ends in <filename>.twr</filename>. These files were created
      during report creation and the most current one is needed to update the
      <application>Tripwire</application> database of your system. As the
      <systemitem class='username'>root</systemitem> user, type in the
      following command making the appropriate report name:</para>

<screen role="root"><userinput>tripwire --update --twrfile /var/lib/tripwire/report/<replaceable>&lt;report-name.twr&gt;</replaceable></userinput></screen>

      <para>You will be placed into <application>Vim</application> with a copy
      of the report in front of you. If all the changes were good, then just
      type <command>:wq</command> and after entering your local key, the database
      will be updated. If there are files which you still want to be warned
      about, remove the 'x' before the filename in the report and type
      <command>:wq</command>.</para>

     <!-- 10-12-2013 bad URL and no good URL found
      <para>A good summary of tripwire operations can be found at
      <ulink url="http://va-holladays.no-ip.info:2200/tools/security-docs/tripwire-v1.0.pdf"/>.</para>
     -->
    </sect3>

    <sect3>
      <title>Changing the Policy File</title>

      <para>If you are unhappy with your policy file and would like to modify
      it or use a new one, modify the policy file and then execute the following
      commands as the <systemitem class='username'>root</systemitem> user:</para>

<screen role="root"><userinput>twadmin --create-polfile /etc/tripwire/twpol.txt &amp;&amp;
tripwire --init</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>siggen, tripwire, twadmin, and twprint</seg>
        <seg>None</seg>
        <seg>/etc/tripwire, /var/lib/tripwire,
        and /usr/share/doc/tripwire-&tripwire-version;</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="siggen">
        <term><command>siggen</command></term>
        <listitem>
          <para>is a signature gathering utility that displays
          the hash function values for the specified files.</para>
          <indexterm zone="tripwire siggen">
            <primary sortas="b-siggen">siggen</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="tripwire-program">
        <term><command>tripwire</command></term>
        <listitem>
          <para>is the main file integrity checking program.</para>
          <indexterm zone="tripwire tripwire">
            <primary sortas="b-tripwire">tripwire</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="twadmin">
        <term><command>twadmin</command></term>
        <listitem>
          <para>administrative and utility tool used to perform
          certain administrative functions related to
          <application>Tripwire</application> files and configuration
          options.</para>
          <indexterm zone="tripwire twadmin">
            <primary sortas="b-twadmin">twadmin</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="twprint">
        <term><command>twprint</command></term>
        <listitem>
          <para>prints <application>Tripwire</application>
          database and report files in clear text format.</para>
          <indexterm zone="tripwire twprint">
            <primary sortas="b-twprint">twprint</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>