Notifications

Notifications can be sent from several points in Powertech Antivirus, including on-demand scanning and on-access scanning. Scheduled emails can also be sent for status updates.

Notifications can also be set up using Configurations in the HelpSystems One web browser interface. See Configuration Properties pane.

Notification configuration

Three sections of Powertech Antivirus's config.ini are used for notification configuration: [avsvc], [avscan], and [notify].

[avsvc]
...
notify=mark,keith
...

[avscan]
notify=mark,sysadmin

[notify]
default.cmd=${PTAV_HOME}/notify-example.sh
default.options=none
mark.cmd=/bin/mail -s 'PTAV notification' mark.elf@northpole.com
mark.options=virus,quarantine
keith.cmd=/bin/mail -s 'PTAV notification' kris.kringle@northpole.com
keith.options=all
sysadmin.cmd=/bin/mail -s 'PTAV notification' sysadmin@northpole.com
sysadmin.options=none

The [avscan] and [avsvc] sections have a notify parameter. Default is blank. The notify parameter can be a comma-separated list to indicate the notifiers from the [notify] section that are to be called.

For avsvc, the notify parameter specifies which notifiers will be called. For avscan, the notify parameter specifies the default notifiers that will be called, unless overridden on the command-line.

The [notify] section has a pair of name.cmd and name.options values. The name is the key used in the notify value in the upper sections.

The default for a non-configured name.cmd is nothing, the default for a non-configured name.options is none.

If a name cannot be resolved to command and options at run-time, that notifier is not run.

The cmd value is the name of a script to be called that receives notification information through environment variables and standard input.

The options value determines which events cause notifications to occur. This can be a comma-separated list from: none, all, started, ended, error, timeout, virus, quarantine, delete, repair. The values none and all trump all others, in that order. Empty options default to none, meaning the notifier will not run.

avconfig tool

There is a standalone tool for configuring all three sections:

Powertech Antivirus configuration tool v6.0.0-705.
(c) Copyright HelpSystems, 2021. All rights reserved. Licensed material, property of HelpSystems.

Usage: ./avconfig [-d] [-h | -V | -C <params> | -U <params>]
-h        help
-d        debug
-V        validate config.ini
-C        create by overriding default settings
-U        create by overriding current settings
<params>  --<section> name=value ...
          e.g. --avsvc mime=yes programs=yes --avscan notify=default

The tool is for administrators and the -V, -C, and -U options require the user to be logged in as root.

For example, create a default configuration file:

avconfig -C

To override that default configuration:

avconfig -C --avscan notify=default --avsvc notify=default,other mime=yes --notify hello.cmd=/usr/local/bin/hello.sh hello.options=all

results in:

[avsvc]
access=open
include=/
exclude=/dev
threads=6
maxwait=300
delay=0
nice=0
clean=yes
cleanfail=quarantine
heuristic=yes
macro=yes
programs=no
archives=yes
files=dft
mime=yes
mount=
fsexcl=
notify=default,other
fscache=yes
fscacheage=0
fscacheidle=0
fscachesize=0

[avscan]
notify=default

[notify]
default.cmd=${PTAV_HOME}/notify-example.sh
default.options=none
hello.cmd=/usr/local/bin/hello.sh
hello.options=all

And to further override that configuration:

avconfig -U --avscan notify=hello --avsvc notify=default,hello

results in:

[avsvc]
access=open
include=/
exclude=/dev
threads=6
maxwait=300
delay=0
nice=0
clean=yes
cleanfail=quarantine
heuristic=yes
macro=yes
programs=no
archives=yes
files=dft
mime=yes
mount=
fsexcl=
notify=default,hello
fscache=yes
fscacheage=0
fscacheidle=0
fscachesize=0

[avscan]
notify=hello

[notify]
default.cmd=${PTAV_HOME}/notify-example.sh
default.options=none
hello.cmd=/usr/local/bin/hello.sh
hello.options=all
NOTE: Use escape characters to prevent configuration text from being expanded by the shell prior to it being received by avconfig. So, to configure the default command:
avconfig -U --notify default.cmd=\${PTAV_HOME}/notify-example.sh default.options=none

To upgrade a configuration file that does not have the new default notifier, use update with no parameters:

avconfig -U

Notification Messages

Messages mostly mirror the log messages that are related to file scanning:

  • started
    • “avsvc running with pid pid”
      • Occurs after load of DATs, at the same time we tell the service controller we are “ready.”
  • ended
    • “avsvc with pid pid stopped”
      • Also includes avsvcinfo output.
      • This is a 'best effort' message—Powertech Antivirus is in the process of shutting down at this point and discards any pending notifications not already in progress.
      • Powertech Antivirus attempts to wait for the notifier completion result, but a service controller or user could terminate before that happens.
  • error
    • “quarantine of infected file failed for file"
    • “delete of infected file failed for file”
    • “File ‘file’ not scanned, code code [reason] ”
  • timeout
    • “Timed out while scanning file 'file’”
      • Based on the value "maxwait=<value>"
  • virus
    • “VIRUS: 'file’ is INFECTED with virus”
      • EICAR files will trigger this.
      • Note that Powertech Antivirus only sends this event when a virus is detected, and not when access is granted to it through a cached result (i.e. you will not see it for the log message “VIRUS granted access to infected file ‘/file’”).
  • quarantine
    • “quarantined file file”
      • Based on the value "cleanfail=quarantine"
  • delete
    • “file file deleted”
      • Based on the value "cleanfail=delete"
  • repair
    • “Infected file ‘file’ [action] (code [code])”

Notification Action

When executed, the notification command will receive notification text on standard input. A sample notification script, notify-example.sh, is available in the installation directory.

The following environment variables will be available at runtime:

PTAV_HOME

The product installation directory.

PTAV_VERSION

The version of the antivirus software.

PTAV_ENGINE

The antivirus engine version and database level.

PTAV_DAT_AGE

The age, in days, of the antivirus database.

PTAV_NOTIFICATION

The notification event name (started, ended, error, timeout, virus, quarantine, deletion or repair).

Examples

To revert to product defaults:

avconfig -C

To create a configuration file based on product defaults and override the default avsvc settings for clean and macro options:

avconfig -C --avsvc clean=no macro=no

To extend that example to specify settings for notify for both avsvc and avscan, and include some notification configuration:

avconfig -C --avsvc clean=no macro=no notify=default --avscan notify=default,mailme --notify mailme.cmd=\${PTAV_HOME}/notify-example.sh mailme.options=started,ended

To change the current configuration to set the avsvc threads value:

avconfig -U --avsvc threads=8

Security

Administrative privileges are required to change the configuration file. At runtime, it must be owned by root and not writable by group or other.

The notification command runs as root. A process executes the command without any further checks. The directory is changed to “/” prior to running the command.

The on-access portion of the server identifies any viruses executed by the notification script. Note that this is not possible during service exit (the “ended” notification).