diff --git a/README.md b/README.md index 2e51055..6634fb4 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ When a desired change occurs, such as upgrading a package, the baseline database ## Getting Started -This section covers manual setup of Open Source Tripwire. If you're installing from an RPM or Debian package, or via "make install", a setup script will walk you through the initial setup steps and these will not need to be done by hand. +This section covers manual setup of Open Source Tripwire. If you're installing from an RPM or Debian package, or via "make install", a setup script will walk you through the initial setup steps (key generation thru policy creation) and these will not need to be done by hand. ### Generating Keys The first step is to generate site and local key files. This is necessary because Tripwire policy, configuration, and database files are signed by default, and report files may also be signed. The site key is used to sign config and policy files, with the idea that multiple machines will share a site key, but each will have its own local key. The policy and config files can then be created once and distributed across these machines. @@ -24,7 +24,7 @@ A common practice is to include the hostname in the local key filename, as follo ``` ### Creating a configuration file -The next step is to create a tripwire config file. The config file contains a variety of settings including the locations of tripwire binaries and key files, email report settings, and parameters that control baseline/check behavior. These settings are explained in detail in the twconfig(4) manual page. +The next step is to create a Tripwire config file. The config file contains a variety of settings including the locations of Tripwire binaries and key files, email report settings, and parameters that control baseline/check behavior. These settings are explained in detail in the twconfig(4) manual page. This command line creates the config text in /etc/tripwire/twcfg.txt, validates and signs it with the site key file, and writes the results to /etc/tripwire/tw.cfg: @@ -40,7 +40,7 @@ Now it's time to configure OST for what you want to monitor. A few simple examp /another/start -> +pinugS; # Get selected attributes for this dir tree !/start/point/subdir/to/ignore; # Don't monitor this dir tree ``` -The tripwire policy language is documented in detail in the twpolicy(4) manual page, and default policies for several popular operating systems are available in the OST project's policy subdirectory. +The Tripwire policy language is documented in detail in the twpolicy(4) manual page, and default policies for several popular operating systems are available in the OST project's policy subdirectory. ``` ./twadmin --create-polfile -S /etc/tripwire/twpol.txt @@ -59,13 +59,15 @@ This creates a database file in the configured directory, typically a file with ``` tripwire --check ``` -This runs a check, again with an optional "--verbose" option that explains what it's doing. Scan results are written to standard out, as well as a report file, which typically has a .twr extension and lives in /var/lib/tripwire/report. If email reporting is enabled, emails will be sent at the end of the check. +This runs a check, again with an optional "--verbose" option that displays what it's doing. Scan results are written to standard out, as well as a report file, which typically has a .twr extension and lives in /var/lib/tripwire/report. If email reporting is enabled, emails will be sent at the end of the check. ### Printing a report ``` - twprint -m r -r /path/to/reportfile.twr + twprint -m r -t [0-4] -r /path/to/reportfile.twr ``` -Databases can be also printed with +The -t argument specifies the level of report verbosity, where 0 is a single line summary of the report contents, and 4 displays all gathered attributes on all changed objects. The report level defaults to 3 if not specified on the command line or via the REPORTLEVEL config file option. + +Databases can be also printed with: ``` twprint -m d -d /path/to/database.twd @@ -82,14 +84,26 @@ While a ``` tripwire --update ``` -brings up a text report in the user's preferred editor (as configured in the config file), wich a checkbox next to each detected change. If you save and exit the editor, the database will only be updated for those objects that remain selected with an [x]. +brings up a text report in the user's preferred editor (as configured in the config file's EDITOR option), with a checkbox next to each detected change. If you save and exit the editor, the database will only be updated for those objects that remain selected with an [x]. ### Updating a policy -TODO +Policy update mode makes it possible to modify the existing Tripwire policy without losing existing baselines. + +``` + tripwire --update-policy updated-policy.txt +``` + +A check is run with the new policy as part of the update process. + +TODO: Explain circumstances in which policy update fails due to check outcome. ### Testing the email configuration -TODO +To test email configuration: +``` + tripwire --test --email user@domain.tld +``` +This sends a test email to the specified address, using the email settings specified in the config file. ## Building OST @@ -103,52 +117,38 @@ Perl 5 [what version?] to run the project's test suite. ### Configuring & Building -OST uses a fairly standard automake build, such that your first step will generally be: +OST uses a standard automake build, such that your first step will generally be: ``` ./configure ``` Different paths, compiler args (like Debian hardening options), non-default locations can be set up in this step. -[give some common configure options here] +[TODO: give some common configure options here] You might need to run the script ``` ./touchconfig.sh``` -before you're able to build the project. The script simply touches files in the right order so files' last change times are not all identical, and that they're different in the right order. +before you're able to build the project. The script simply touches files in the right order so their last change times are not all identical, and that they're different in the right order. Then just -``` -make``` +```make``` to build the project. ## Running the test suites -the "make check" make target runs two things: The test harness suite in the src/test-harness directory, and unit tests by running twtest, which is built in the bin directory along with other tripwire binaries. These tests can also be run separately: -``` -./twtest -``` -runs all unit tests, while -``` -./twtest list -``` -lists all available tests. -``` -./twtest Groupname -``` -runs all tests in a group, and -``` -./twtest Groupname/Testname -``` -just runs the specified test. +the ```make check``` make target runs two things: The acceptance test suite in the src/test-harness directory, and unit tests by running twtest, which is built in the bin directory along with other tripwire binaries. These tests can also be run separately: +```./twtest``` runs all unit tests, while ```./twtest list``` lists all available tests. +```./twtest Groupname``` runs all tests in a group, and +```./twtest Groupname/Testname``` just runs the specified test. -[ TODO: how to run test-harness tests ] +To run the acceptance tests manually, cd to the src/test-harness directory and run ```perl ./twtest.pl```. ## Deployment -The "make install" target installs OST to the configured location, and "make install-strip" installs and removes symbols from the tripwire binaries. A "make dist" creates a gzipped source bundle. +The ```make install``` target installs OST to the configured location, and ```make install-strip``` installs and removes symbols from the tripwire binaries. A ```make dist``` creates a gzipped source bundle. ## Authors @@ -157,28 +157,22 @@ The "make install" target installs OST to the configured location, and "make ins ## License -The developer of the original code and/or files is Tripwire, Inc. Portions -created by Tripwire, Inc. are copyright 2000-2018 Tripwire, Inc. Tripwire is a -registered trademark of Tripwire, Inc. All rights reserved. +The developer of the original code and/or files is Tripwire, Inc. +Portions created by Tripwire, Inc. are copyright 2000-2018 Tripwire, Inc. +Tripwire is a registered trademark of Tripwire, Inc. All rights reserved. -This program is free software. The contents of this file are subject to the -terms of the GNU General Public License as published by the Free Software -Foundation; either version 2 of the License, or (at your option) any later -version. You may redistribute it and/or modify it only in compliance with -the GNU General Public License. +This program is free software. The contents of this file are subject to the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. You may redistribute it and/or modify it only in compliance with the GNU General Public License. This program is distributed in the hope that it will be useful. However, this program is distributed "AS-IS" WITHOUT ANY WARRANTY; INCLUDING THE IMPLIED WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Please see the GNU General Public License for more details. -You should have received a copy of the GNU General Public License along with -this program; if not, write to the Free Software Foundation, Inc., +You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. Nothing in the GNU General Public License or any other license to use the -code or files shall permit you to use Tripwire's trademarks, service marks, -or other intellectual property without Tripwire's prior written consent. +code or files shall permit you to use Tripwire's trademarks, service marks, or other intellectual property without Tripwire's prior written consent. If you have any questions, please contact Tripwire, Inc. at either info@tripwire.org or www.tripwire.org.