Quick Start

Before we begin, I want to personally thank you for trying malwatch. A genuine and heartfelt Thank You ❤ I hope it proves itself to be one of the best malware scanning solutions.

Installation

Create a directory anywhere you prefer, software is meant to be portable. A common choice is /opt/malwatch. Then extract the binary there from the downloaded archive:

wget https://github.com/defended-net/malwatch/releases/download/v1.0.0/malwatch_1.0.0_linux_amd64.tar.gz
mkdir /opt/malwatch
tar -C /opt/malwatch -xzvf malwatch-1.0.0.linux-amd64.tar.gz

It would be recommended to set up your PATH:

export PATH=$PATH:/opt/malwatch

All necessary config files will automatically be built upon execution and any malwatch command can be used for this purpose. Let's try without any args:

malwatch

If you are using automation such as Ansible and want a clean exit, then malwatch install can be used.

The initial setup will build all config files, including bundled integrations and alerting. Optional config files will have the .disabled file extension. These can be renamed to .toml to enable.

Real Time Scanning

Real time malware scanning is possible with malwatch-monitor. A systemd unit can automatically be created with malwatch install systemd. This is optional - feel free to set up your own or use any preferred setup such as a foreground process or even screen. We believe software should flexible to any preference.

Using systemd, it is necessary to enable followed by starting it:

systemctl enable malwatch-monitor
systemctl start malwatch-monitor

Cron

Your system's cron can be considered to schedule scans at preferred interval. It is not recommended to use scheduled scans if real time scanning with malwatch-monitor is already being used.

The command crontab -e is used to add or modify cron jobs. The command field would involve /opt/malwatch/malwatch scan to automatically scan all targets. An example configuration to scan each day at 01:00 AM is as follows:

0 1 * * * /opt/malwatch/malwatch scan

Setup

Some config variables needed for basic operation must be defined in the file cfg/cfg.toml. Shown below is what it looks like:

Identifier = "" # hostname
Cores = 0
Threads = 0

[Scans]
  Targets = ["^/var/www/(?P<target>[^/]+)"]
  Paths = ["/var/www/html"]
  Timeout = 300 # sec
  MaxAge = 0 # day
  BlkSz = 65536 # kib
  BatchSz = 500

  [Scans.Monitor]
    Timeout = 5 # sec

[Database]
  Dir = ""

[Log]
  Dir = ""
  Verbose = false

Targets

The term target means a group of paths which share a common level. This is accomplished using regex. In the example above (?P<target>.*) is a capture group. Any paths under the directory /var/www will be considered the target. Since we have the Paths config variable as /var/www/html it would mean any detections will be associated as target html.

We could also scan a path /var/www/images (which is outside of the Paths config) but any detections there would then be assigned the target images.

A scan of path /var/static does not match with the regex and thus is assigned the target fs, which is the catchall target for all detections which do not match the Targets regex.

Targets are essential to grouping detections, especially when sending alerts and saving detections to the database.

Let's now go over the other config variables to better understand their role.

Variable	Description
Identifier	Custom identifier, useful for alerts and logging. Defaults to system hostname.
Cores	Limit execution based on processor core count. 0 disables limit.
Threads	Limit execution based on thread count. 0 disables limit.
Targets	Regex to determine a path's target classification.
Paths	List of paths to scan. Multiple entries is possible ["/path/a", "/path/b"]
MaxAge	Maximum age of files to scan (days).
BlkSz	Chunk size (KiB) per read of each file.
BatchSz	Maximum number of detections per alert before sending the next alert.
Timeout	Time limit (min) of scans per target. 0 disables limit.
Monitor.Timeout	Interval (sec) for real time monitoring scans to start a cycle.
Verbose	Enables extra trace information in logs.

Once installed, you are ready to perform your first scan!

malwatch scan /var/www/html