File	Date	Author	Commit
AUTHORS	2013-10-03	c.cboldt	[0a9748] Initial Commit at mktwpol-0.2.1 rev level
CHANGES	2020-12-12	c.cboldt	[f4ab4e] Release of Version 1.0.2
Makefile	2019-12-28	c.cboldt	[5e79d5] Pre-update to version 1.0.2
README	2020-12-12	c.cboldt	[f4ab4e] Release of Version 1.0.2
mktwpol-1.0.2.sh	2020-06-06	c.cboldt	[4593dc] Revisions to June 6, 2020
mktwpol-default.rules	2020-12-12	c.cboldt	[f4ab4e] Release of Version 1.0.2
mktwpol-generic-1.0.0.sh	2017-03-31	c.cboldt	[738b6f] Release of version 1.0.0
mktwpol-gentoo-packages.rules	2020-12-12	c.cboldt	[f4ab4e] Release of Version 1.0.2
mktwpol-portage-tree.rules	2020-12-12	c.cboldt	[f4ab4e] Release of Version 1.0.2
mktwpol.cfg	2017-03-31	c.cboldt	[738b6f] Release of version 1.0.0
twsetup-1.0.2.sh	2019-12-28	c.cboldt	[5e79d5] Pre-update to version 1.0.2

Read Me

README
Last Edit: 01 APR 2017

mktwpol.sh & twsetup.sh
https://sourceforge.net/projects/mktwpol

 A companion pair of scripts to install and maintain a tripwire database
 Provides a (mostly) Gentoo-oriented Tripwire Policy Text Generator

 mktwpol.sh outputs tripwire policy text tailored to installed files
 twsetup.sh performs the commands that set-up a tripwire installation

 ===========================================
 Synopsis of tripwire installation and setup
 ===========================================

 - Install tripwire			(emerge tripwire)
 - Install mktwpol.sh and twsetup.sh	(emerge mktwpol)

 - Choose between	- mktwpol-default.rules
			- mktwpol-portage-tree.rules
			- mktwpol-gentoo-packages.rules

   Copy or `touch` the desired rules file
   mktwpol.sh will use the most recent mktwpol*.rules found in
   /etc/tripwire, /etc/mktwpol, /root, or /var/lib/mktwpol

 - Run `twsetup.sh`
   * Makes and/or reviews /etc/tripwire/twcfg.txt
   * Calls `twadmin` to make the encrypted key files and tw.cfg
   * Calls `mktwpol.sh` to generate a plain-text tripwire policy
   * Calls `twadmin` to make the encrypted tripwire policy, tw.pol
   * Calls `tripwire` to scan the system and make the tripwire database

 =========================================
 Synopsis of tripwire and mktwpol.sh usage
 =========================================

 - Periodically run `tripwire --check`
   for example, via a cron job at /etc/cron.daily/tripwire

 - Run `tripwire --update` when `tripwire --check` reports a violation
 - Run `mktwpol.sh -u` when tripwire reports "Warning: File system error"
 - Run `mktwpol.sh -u` to adapt to "wildcard" directory name changes
   * A cue is a tripwire report of files removed, but no additions
	Some packages install in version-numbered directories,
	e.g., /opt/*/bin /opt/*/*/bin /usr/*/*-bin/* /usr/lib/*/bin

 ===============
 Tips and Tricks
 ===============

 - Use bash aliases to simplify ongoing tripwire usage.
   `tripwire --update` must be given the name of an existing report.

     alias last.tw.report='echo `ls -t /var/lib/tripwire/report/* | head -1`'
     alias tw.report='twprint  --print-report -r `last.tw.report`'
     alias tw.update='tripwire --update -r `last.tw.report`'

 - Delete the plain-text twcfg.txt tripwire configuration file and
   plain-text twpol.txt tripwire policy file after they have been encrypted.
   They are both easily recovered into their original form.

     `twadmin --print-cfgfile`  will recreate plain-text config from tw.cfg
     `twadmin --print-polfile`  will recreate plain-text policy from tw.pol
     `twprint --print-dbfile`	will show the tripwire database

   Note: Add "-c /path/to/tw.cfg" switch to decrypt the config file and
   policy file if the tripwire set-up deviates from tripwire's default
   /etc/tripwire/tw.cfg location.

 - Check the encryption status of tripwire files

     `twadmin --examine /etc/tripwire/tw.pol`
     `twadmin --examine /etc/tripwire/tw.cfg`
     `twadmin --examine /var/lib/tripwire/*.twd`
     `twadmin --examine /var/lib/tripwire/report/*`

 - To automate the input of tripwire passphrases, define SITE_PASSPHRASE
   and LOCAL_PASSPHRASE in mktwpol.cfg.  This can be made secure by
   putting mktwpol.cfg on removable media, and calling mktwpol.sh with

     `mktwpol.sh -C /mnt/removable-media/mktwpol.cfg`

 - The creation of an encrypted tripwire report requires the use of
   the local passphrase.  In a non-console setting like cron, that means
   passing the local passphrase on the tripwire command line.

     `tripwire --check --quiet -E -P "secretlocalpassphrase"`

   Making the tripwire database and report directories readable only
   by the user "root" is as secure as encrypting the reports.

 - Why does tripwire sometimes report a file "Removed:", and other times
   throw a "### Warning: File system error/### No such file or directory"?

   The warning occurs on absence of a file -specifically named- in the policy.
   The "Removed:" report occurs when a file was in a directory that is
   scanned following the tripwire policy.

   Run: `tripwire --update` to cure a "Removed:" note in a tripwire report
   Run: `mktwpol -u` to cure "### Warning: ... No such file or directory"

 - Colorize inspection of "tripwire --update" display with nanorc
   Nanorc tip ... show trailing whitespace with 'color ,red "[[:space:]]+$"'

     ## At the end of /usr/share/nano/local.nanorc
     ## Tripwire report temp file.  Don't show trailing whitespace.
     syntax "tripwire" "twtemp*"
     color green "^(==|--).*$"
     color yellow "(\"/).*$" ":  .*$" "\(/.*\)"
     color brightred "^(\*).*$" "^\[.\]"
     color white "[[:space:]]+$"

 ----------------------------------------------------------------

 Usage: twsetup.sh [-c tw_cfg_dir] [-d db_root] [-r] [-u]
		   [-p "tw-policy-generator"|-b] [-h|-V]

	-c Install tripwire configuration files in "tw_cfg_dir"
	   Default tw_cfg_dir = /etc/tripwire
	-d Database and report directories go in a directory tree off "db_root"
	   Default db_root = /var/lib
	   Default tripwire database directory = /var/lib/tripwire
	   Default tripwire reports directory  = /var/lib/tripwire/report
	-r Remove twcfg.txt and twpol.txt after processing
	-u Skip generating tripwire keys and encrypted config
	-p Plain-text policy generator command line (escape with '"' chars)
	   Default policy text generator command line is "mktwpol.sh"
	-b Bypass plain-text policy generator
	   Use most recent "twpol*txt" file for tripwire policy
	-h Show version and help information
	-V Show version information

 Makes "tw_cfg_dir" directory if it does not exist
 Makes database and report directories off "db_root" if they do not exist
 Can configure tripwire into an empty directory

 ----------------------------------------------------------------

 Usage: mktwpol.sh	[-c tw_cfg_dir]  [-R rules_file] [-C config_file]
			[-u[-r]] [-s] [-x] [-h|-V] [debug [#]]

	-c Use tripwire configuration files found in "tw_cfg_dir"
	   Default tw_cfg_dir = /etc/tripwire
	-R Read RULENAME[], PACKAGES[], FILELIST[] from rules_file
	   Default rules_file = most recent mktwpol*.rules
	   in "tw_cfg_dir", /etc/mktwpol, /root, or /var/lib/mktwpol
	-C Change defaults (or modify RULE[] definitions) from config_file
	   Default (optional) config_file = most recent mktwpol*.cfg
	   in "tw_cfg_dir", /etc/mktwpol, /root, or /var/lib/mktwpol
	-u Create tripwire policy and database after producing policy text file
	-r Remove policy text file after tripwire has processed it
	-s Skip processing of PACKAGES[] arrays
	-x List executable files outside of catchall rule (not recommended)
	-h Show version and help information
	-V Show version information

 `mktwpol.sh` without "-u" command line parameter:
	- sends policy text to STDOUT, suitable for redirection with ">"

 `mktwpol.sh -u`  produces no policy on STDOUT. -- ! WON'T REDIRECT ! --
	- sends policy text to a datenamed file in "tw_cfg_dir"
	- calls `twadmin`  to create tw.pol from that file
	- calls `tripwire` to create the system database

 `mktwpol.sh debug`
	- limits output to one selected rule.  Default is RULENAME[0]

 ===============================
 mktwpol.sh : Miscellaneous Tips
 ===============================

 - Read the mktwpol.cfg file.

 - If a package is not named in a PACKAGES[] list, important file changes will
   be caught by a catchall rule, "OS Bin and Lib" or "User Bin and Lib".

 - Optional mktwpol.cfg (or other) script configuration file can be used to:
	- set default mktwpol.sh & twsetup.sh command-line switches
	- substitute, augment, or modify package and file lists
	- automate passphrase response to tripwire prompts

   Copy or `touch` the desired config file
   mktwpol.sh will use the most recent mktwpol*.cfg found in
   /etc/tripwire, /etc/mktwpol, /root, or /var/lib/mktwpol

 - mktwpol-generic.sh is structured to allow the definition of
   package manager program(s) for filename extraction.

 - To see the list of package names being considered for inclusion
   in the generated tripwire policy, run `mktwpol.sh dump`
   This is equivalent to:

	cd /etc/tripwire
	source mktwpol*.rules; source mktwpol.cfg
	echo ${PACKAGES[@]} | tr [:space:] '\n' | sort

 - To find listed package names that don't exist in the Portage tree,
   run `mktwpol.sh cruft`
   This is equivalent to:

	PORTDIR=`portageq get_repo_path / gentoo`
	for i in `mktwpol.sh dump`; do
	  [[ $i =~ / ]] || i=*/$i
	  stat $PORTDIR/$i -c %n > /dev/null 2>&1 || \
	  echo $i Not Found in Portage tree $PORTDIR
	done

   The point of this is to check the "Gentoo Packages" rules file
   for package names that are not in Gentoo's official Portage tree.

   If `mktwpol.sh cruft` is run against the "Gentoo Portage Tree" rule,
   it will reveal installed packages that are installed from overlays.

 - To compare the tripwire coverage established by different
   mktwpol-*.rules files, first put all the rules files in the
   /etc/tripwire directory, then run the following script:

   #!/bin/bash
   # /usr/local/sbin/compare-mktwpol-rules
   # Subroutine to make plain text policy and have tripwire process it
   # -----------------------------------------------------------------
   run_policy_generator()
   {
   time mktwpol.sh -R /etc/tripwire/mktwpol-$i.rules > test-$i.txt
   printf "\n Policy file contains %7s lines\n" \
	$(wc -l test-$i.txt | cut -d" " -f1)
   twadmin --create-polfile test-$i.txt > /dev/null
   tripwire --init > /dev/null
   twprint --print-dbfile > test-$i-db.txt
   grep "Object name" test-$i-db.txt > test-$i-tmp.txt
   sort test-$i-tmp.txt > test-$i-files.txt
   rm -f test-$i-db.txt test-$i-tmp.txt
   printf " Total objects scanned: %5s\n" \
	$(wc -l test-$i-files.txt | cut -d" " -f1)
   }

   # Main Routine
   # ------------
   chown root /etc/tripwire/mktwpol-*.rules
   chmod 600  /etc/tripwire/mktwpol-*.rules
   rule_sets="$*"
   rule_sets=${rule_sets:="gentoo-packages portage-tree default"}

   for i in $rule_sets
   do
     run_policy_generator
     if [ $i !=  gentoo-packages ]; then
      diff test-gentoo-packages-files.txt test-$i-files.txt > packages-2-$i.txt
      printf " ---------------------------------------------------\n"
       if [ -s packages-2-$i.txt ]; then
	printf " Dropped compared with mktwpol-gentoo-packages.rules\n"
	grep '<' packages-2-$i.txt
	printf " ---------------------------------------------------\n"
	printf " Added compared with mktwpol-gentoo-packages.rules\n"
	grep '>' packages-2-$i.txt
       else
	printf " Same tripwire scope as mktwpol-gentoo-packages.rules\n"
       fi
     fi
     printf " ===================================================\n"
   done