/usr/local/stat_watch/texts/ Current File: //usr/local/stat_watch/texts/help_usage.txt
GENERAL USE CASES

#==========================================#
#== Capturing Stats Now, Comparing Later ==#
#==========================================#

If a customer's site has been hacked and they are concerned that it will happen again, you can expedite future investigations by capturing the stats of their files now so that we have something to compare them to in the future.

Capture the current stats of files:
```    /root/bin/stat_watch --record /home/account/public_html > /root/stat_watch1.txt```

Note: If you add the "--verbose" flag, this will output every directory it's actively working within. This information isn't really all that USEFUL, but it's more exciting than staring at the terminal waiting for a command to finish

When we want to check the stats of files on the account again, we just need to run another report and then assess the differences:
```    /root/bin/stat_watch --record /home/account/public_html > /root/stat_watch2.txt
    /root/bin/stat_watch --diff /root/stat_watch1.txt /root/stat_watch2.txt```

#========================================#
#== Comparing Current Files to Backups ==#
#========================================#

Imagine a customer's site was hacked and you want to know what was different before you overwrite everything with the contents of a backup. The customer's document root is located at '/home/account/public_html' and you've expanded the backups so that the equivalent folder is located at '/home/lwtemp/account/homedir/public_html'. Here is the process of comparing the stats of the files in those directories:

Get the stats for the backup directory, using the "--as-dir" flag so that the output will show the files as if they came from the directory specified:
```    /root/bin/stat_watch --record /home/lwtemp/account/homedir/public_html --as-dir /home/account/public_html > /root/stat_watch1.txt```

Looking at the file that was created, the file paths will have been reported as '/home/account/public_html' rather than '/home/lwtemp/account/homedir/public_html'.

Next get the stats for the current contents of the directory:
```    /root/bin/stat_watch --record /home/account/public_html > /root/stat_watch2.txt```

Run "stat_watch --diff" as was done in the earlier example:
```    /root/bin/stat_watch --diff /root/stat_watch1.txt /root/stat_watch2.txt```

Note: It's likely that the backups were stored in such a way that the ctime of the files will not have been retained. In order to compensate for this, you will likely want to use the "--no-ctime" flag.

Note: It's possible that there's a cache directory present where a lot of changes have occurred. If you want to avoid outputting changes from a specific directory, just use the "--ignore" flag with the full path to that directory after:
```    /root/bin/stat_watch --diff /root/stat_watch1.txt /root/stat_watch2.txt --ignore /home/account/public_html/cache --no-ctime```

Now that we know what files have changed, we can use the Linux "diff" command to see how they differ and make an assessment on if those changes are malicious:
```    diff /home/lwtemp/account/homedir/public_html/.htaccess /home/account/public_html/.htaccess```

#==============================================#
#== Comparing Files AFTER Restoring a Backup ==#
#==============================================#

In the example above, there was enough free hard drive space on the server to expand the backup and still have original site contents in place, but there are circumstances where that is not the case - where the original MUST be deleted before the backup can be uncompressed.

In this situation, first capture the stats of the existing files:
```    /root/bin/stat_watch --record /home/account/public_html > /root/stat_watch2.txt```

Then once the backup is restored, capture the stats of the files as they were in the backup, then compare:
```    /root/bin/stat_watch --record /home/account/public_html > /root/stat_watch1.txt```

Be aware that "stat_watch --diff" will use the timestamps on the files it's given to determine which is older. This can make a big difference if a file is present in one place, but missing in the other - the output could say that it was removed rather than created.

In this circumstance, we need to run it against the newer set of files first, so to eliminate confusion, you can use the "--before" and "--after" flags to indicate which file was which:
```    /root/bin/stat_watch --diff --before /root/stat_watch1.txt --after /root/stat_watch2.txt```

Note: As above, it's possible that you will want to use the "--no-ctime" and "--ignore" flags

We won't have access to any of the changed files in order to compare their contents, but we will at least have the relevant timestamps so that we can search relevant logs to see if there is anything there worthy of note.

#===================================================#
#== Finding the Stat of a File Listed in a Report ==#
#===================================================#

Assuming that we previously created a Stat Watch report, we can check that report for the stats of a specific file using either the "--report-details" or the "--rd" flag, hollowed by the name of the report and the name of the file that we're interested in.
```    /root/bin/stat_watch --report-details /root/stat_watch1.txt /home/account/public_html/directory/script.php```

The output would look something like this:
```    Processing of '/home/account/public_html' started at '2018-10-23 02:00:03 -0400'
    
      FILE: '/home/account/public_html/directory/script.php_15335321890'
      SIZE: 1011 bytes   MD5 Sum: de31e27abb48dad3b8a2fcc61fdc575a
    ACCESS: f-0644  USER: (510 / account)  GROUP: (515 / account)
    MODIFY: 2018-08-06 01:09:49 -0400
    CHANGE: 2018-08-06 01:09:49 -0400```

#====================#
#== Advanced Rules ==#
#====================#

If there are specific files or file extensions that you want Stat Watch to include or ignore when generating a report, you can create a Stat Watch job file and specify that Stat Watch adhere to the rules outlined in that file by referencing it with the "-i" flag:
```    /root/bin/stat_watch --record /home/account/public_html -i /root/job_file.txt > /root/stat_watch1.txt```

For more information about what can be accomplished with the include/ignore file, run stat_watch with "--help job"
```    /root/bin/stat_watch --help job```

#=============================#
#== Also Capturing MD5 Sums ==#
#=============================#

Typically the combination of mtime, ctime, and file size is enough to know if a file has changed, however there are circumstances where it's desirable to have more reassurance regarding whether there have been any changes to a file's contents. Under these circumstances, the "--md5" flag can be used to capture MD5 sums of all the files present:
```    /root/bin/stat_watch --record /home/account/public_html --md5 > /root/stat_watch1.txt```

Typically it is not recommended that this feature be used as it results in additional processing power and disk IO. The advanced features available with include/ignore files allow for singling out individual files for which this added level of detail is necessary.

To capture any MD5 sums, whether using the "--md5" flag or settings within an include/ignore file, the perl modules 'Digest::MD5' and 'Digest::MD5::File' will need to be present. You can verify that everything you need for this is in place by running stat_watch with the "--md5-test" flag:
```    /root/bin/stat_watch --md5-test```

#====================================#
#== Backing Up Files from a Report ==#
#====================================#

Using a Stat Watch report generated with the "--record" functionality, you can create backups of certain files in order to ensure that you have copies available for later.

First you need to generate a Stat Watch report:
```    /root/bin/stat_watch --record /home/account/public_html > /root/stat_watch1.txt```

Then backup the files that you're interested in using the "--backup" flag in conjunction with the "--backupd", "--backup+", and "--backupr" flags. Here's an example that would backup all of the files found that end with extensions .php, .php4, .php5, .php7, .pl, .pm, .py, .js, .css, .htm, .html, .htaccess, .htpasswd, .sh, and .rb to the directory /home/stat_watch/temp_backup:
```    mkdir -p /home/stat_watch/temp_backup
    /root/bin/stat_watch --backup /root/stat_watch1.txt --backupr '\.(p(hp(4|5|7)?|[lym])|js|css|ht(ml?|access|passwd)|sh|rb)$' --backupd /home/stat_watch/temp_backup```

The files will be stored with the backup directory specified with the "--backupd" functioning as the equivalent of "/", and with a number appended to the end of their file name. Thus with the above command, the file '/home/account/public_html/directory/script.php' would have a backup located at '/home/stat_watch/temp_backup/home/account/public_html/directory/script.php_15335787200' (or some other string of numbers: The number at the end is the epoch timestamp at which the backup occurred followed by an additional digit). The ownership, permissions, and timestamps of the file are documented by writing them to a file with a name ending in "_stat", so for the above example, it would be '/home/stat_watch/temp_backup/home/account/public_html/directory/script.php_15335787200_stat'

#=================================#
#== Backing Up Individual Files ==#
#=================================#

You can have Stat Watch create a backup of a single file using the "--backup-file" flag or the "-a" flag. Note that a backup directory must be specified.
```    /root/bin/stat_watch -a /home/account/public_html/directory/script.php --backupd /home/stat_watch/temp_backup```

As above, the backup created would end up located at '/home/stat_watch/temp_backup/home/account/public_html/directory/script.php_15335787200' (or some other string of numbers).

You can also leave a comment when backing up a file. Such comments can be viewed when listing backed-up copies for files (see "Listing Backed-up Files" below):
```    /root/bin/stat_watch -a /home/account/public_html/directory/script.php --comment "Prior to changes for ticket 12345" --backupd /home/stat_watch/temp_backup```

#=======================================#
#== Listing Copies of Backed-up Files ==#
#=======================================#

Stat Watch maintains a list of all of the directories that it has backed up to, so it's easy to check from the command line if it has created a backup of a file.

For example, to see all of the backups made of '/home/account/public_html/directory/script.php', you would run the following command:
```    /root/bin/stat_watch --list /home/account/public_html/directory/script.php```

And the output you receive would look something like the following:
```    Available Backups for '/home/account/public_html/directory/script.php':
      '/home/account/public_html/directory/script.php_15335787200' -- Timestamp: 2018-08-06 14:05:20 -0400 -- 1024 bytes```

If there is a comment associated with one of the backups, the output would look something like this:
```    Available Backups for '/home/account/public_html/directory/script.php':
      '/home/account/public_html/directory/script.php_15335321890' -- Timestamp: 2018-08-06 01:09:49 -0400 -- 1011 bytes
        - Prior to changes for ticket 12345
      '/home/account/public_html/directory/script.php_15335787200' -- Timestamp: 2018-08-06 14:05:20 -0400 -- 1024 bytes```

The file names given here are not the actual full path to the backup file, but rather just a display name, quoted such that if the file contains any newline or non-printing characters, it will all appear on one line, and copying and pasting into the terminal will result in those characters being interpreted appropriately. This display name can be used to reference the file with other Stat Watch functions related to backups, such as "--restore" and "--compare"

#==============================#
#== Stats of Backed-up Files ==#
#==============================#

If you want to view the stats of a backed-up file, you can use the "--backup-stat" or "--bs" flag, along with the display name that was output by "--list":
```    /root/bin/stat_watch --backup-stat '/home/account/public_html/directory/script.php_15335321890'```

The output will look something like this:
```      FILE: '/home/account/public_html/directory/script.php_15335321890'
      SIZE: 1011 bytes   MD5 Sum: de31e27abb48dad3b8a2fcc61fdc575a
    ACCESS: f-0644  USER: (510 / account)  GROUP: (515 / account)
    MODIFY: 2018-08-06 01:09:49 -0400
    CHANGE: 2018-08-06 01:09:49 -0400```

#=======================================================#
#== Comparing a Backed-up File to the Current Version ==#
#=======================================================#

Given a scenario where you've discovered that a file has been changed, it's useful to be able to compare it to an existing backup. Stat Watch can do this as well:
```    /root/bin/stat_watch --compare '/home/account/public_html/directory/script.php'```

The output from this command will show any stat differences between the file and its most recent backup (not including any backups that have the same ctime stamp), as well as print a diff of the contents.

If you want to compare a file to a backup other than the most recent, just give the display name of the backup that you want to compare it to as well:
```  /root/bin/stat_watch --compare '/home/account/public_html/directory/script.php' '/home/account/public_html/directory/script.php_15335321890'```

#===============================#
#== Restoring Backed-up Files ==#
#===============================#

After getting a list of backed-up files, you can choose to restore one of them using the "--restore" flag:
```    /root/bin/stat_watch --restore '/home/account/public_html/directory/script.php_15335321890'```

This would return the version of the file from 2018-08-06 01:09:49 -0400 to its previous location at '/home/account/public_html/directory/script.php' with the same permissions and ownerships that it had had at that time.

#==========================#
#== Watching a Directory ==#
#==========================#

Stat Watch has all of the components necessary to run repeated checks against the contents of a directory and detect if changes are being made. Running Stat Watch with the "--create" flag will walk you through creating a job that can be run via cron to repeatedly check and compare the contents of one or more directories:
```    /root/bin/stat_watch --create```

By default, the job that's created will backup all files ending in the following extensions: .php, .php4, .php5, .php7, .pl, .pm, .py, .js, .css, .htm, .html, .htaccess, .htpasswd, .sh, .rb. This can be modified to capture whatever is desired.

Any time a change is detected, output will be generated specifying what what files were changed and which of their stats changed. If the file that changed has one of the extensions listed above, the new version of the file will be backed up. You can configure it to send an email that includes the details every time a change is detected.