Chapter 8. Change Control Process Integration

samhain 4.0 introduces a set of new features to allow seamless integration with an existing change control process. This feature set has been drafted as the result of a workshop, and is designed to meet some key criteria:

  1. The whole procedure can be run in an automated way, i.e. it can be executed by scripts and without human intervention, once a list of affected files is available. It is expected that the change control process will yield the list of affected files from the development or quality assurance stage.

  2. The feature set provided should be rather generic and not tied to any particular change control software.

  3. Immediately before a change is implemented, the affected files can be tested for their integrity. I.e. it can be verified that the system is in a known-good state before the change is put into effect.

  4. After a change is implemented, the baseline, i.e. the database of known-good file signatures, can be updated.

  5. The approval of the change(s) performed can be securely communicated to the running Samhain daemon on the affected machine(s), such that a subsequent file integrity check will raise no alerts.

1. Use cases

The following list shows the use cases that were considered, and how they may be handled.

1.1. Case I: Machine taken offline for a large patch

This case is best handled by a comple re-initialisation of the baseline database. The running Samhain daemon performs an on-demand file system scan immediately before the machine is taken offline to ensure a valid state, the database will be initialized after the patch has completed, and the Samhain daemon will re-start when the machine goes online again.

  1. Before taking the machine offline, a SIGTTOU signal is sent to the Samhain daemon to request a file check:
    	    sh# kill -s TTOU $( cat /var/run/ )
    It is possible to perform a wait-on-completion (with an optional timeout) that provides an exit status to indicate whether the file system scan found any inconsistencies:
    	    sh# samhain -w <timeout>
  2. The machine is taken offline for patching (e.g. by switching to another runlevel), and Samhain is shut down.
  3. After the patch, a new baseline is initialized:
    	    sh# samhain -t init
  4. The new baseline is transferred to the server and the Samhain daemon restarts when the machine is taken online again.
  5. There may be no feedback between different parts of the process that implements the change, thus the new baseline may not be available yet at restart. Therefore Samhain has an option to delay the download of the baseline at startup:
    	    # Delay database download at startup by N seconds
    	    StartupLoadDelay = N

1.2. Case II: Installation of a new package

In this case, because the package is not installed yet a "pre-flight" scan may be deemed unneccessary. After installation of the package, a DeltaDB (delta database) containing the added files will be generated and transferred to the server. There, it will be merged into the existing baseline database.

The approval of the file system changes will be done by the server asking the client to download the DeltaDB. For security, there is no client-side mechanism to trigger an approval of the file system changes.

  1. The list of files (package content + files affected by pre-/postinstall scripts) is generated in the QA stage.
  2. The package is installed.
  3. Based on the list of files, a DeltaDB (delta database) is generated:
    	    sh# samhain --outfile <DeltaDB> --create-database <file_list>
    [Note]File list

    One pathname per line, optionally preceded by a '+' (plus) sign which, if present, indicates that the content of the file should be stored. The configuration file will NOT be read, and the policy recorded in the baseline database will be ReadOnly.

  4. The DeltaDB is transferred to the server data directory, renamed with a fixed scheme of the form <baseline_file>.<UUID>, and merged with the baseline database. The merging function is provided as part of the Beltane II software:
    	    sh# beltane_update --merge <UUID> --update <baseline_file>
  5. The Samhain server (yule) is advised to inform the Samhain client that a DeltaDB of approved changes is available for download:
    	    sh# yulectl -c DELTA:<UUID> <client_fqdn>
    [Note]Location and naming scheme

    The DeltaDB must be named file.client_fqdn.UUID and must be located in the yule data directory, i.e. the same directory where the baseline database file.client_fqdn is located. The client will only ask for the UUID. Similar to the baseline database, the pathname of the file is constructed by the server, using the client FQDN and the requested UUID.

  6. The client receives the UUID and requests the DeltaDB from the server. In case of a failure, re-trying is controlled by the following two configuration options:
    	    # Maximum retry count
    	    SetDeltaRetryCount = N
    	    # Time in seconds between re-tries
    	    SetDeltaRetryInterval = N

1.3. Case III: Configuration change / Package upgrade

This case differs from Case II insofar as there are already installed files, and therefore it is desirable to verify the integrity of those files before the change is put into effect. To perform this check, on the server a PartialDB (partial database, containing only data for affected files) is generated from the full baseline database. This PartialDB is then transferred to the client and used to perform a verification scan.

If the affected files are found to be in a consistent state, the procedure continues as in Case II then.

  1. The list of affected files is generated in the QA stage.
  2. On the Samhain server, a PartialDB (partial baseline database) for the affected files is generated from the complete baseline:
    	    sh# samhain --outfile <PartialDB> --list-filter <list_file> --binary -d <baseline_file>
  3. The PartialDB is transferred to the client.
  4. The integrity of the affected files is verified before the change is implemented (success or failure indicated by exit status):
    	    sh# samhain --verify-database <PartialDB>
  5. After successful verification, the process continues as in Case II.