---

Manual Reference Pages  - vfind (1)

---

vfind - Heterogeneous Antivirus Tool

CONTENT

Synopsis
Description
     Options
Usage
     Licenses
     Input
     Output
     Custom Messages
     Smartscan
     Speed
Locking
Restarting
Files
See Also
Bugs
Copyright

vfind	[-c, --copyright] [-h, --help] [-v, --version] [--vlist]
vfind	[-d, --dup-check] [--trig-count] [-e, --exit-on-error] [-ev, --exit-on-vdl-error] [--emu=options] [--emu-help] [--emu-config=file] [--end] [-i, --ignore-eof] [--jadevdl=file] [--keep-tmpfiles] [--liboff=library] [--libon=library] [--md5=file] [--cbayes=file] [--noload=virus] [--noloads=file] [--notell=virus] [--notells=file] [--noscan=filename] [--noscans=file] [--force-scan] [--recursion-limit=number] [--follow-symlinks] [--ignore-symlinks] [-p, --per-file] [--pid] [--quiet=num] [--quit] [--rcf=file] [--pidfile=file] [--savepid=file] [-ssr, --smartscan-read] [-sst, --smartscan-types] [-nosst, --no-smartscan-types] [--stdin] [--tmpdir=dir] [-u, --unbuf] [--uad=opts] [--vdl-list=file] [--vdl=file] [--vdl0=file] [--vdlc=file] [--vdle=file] [--vdlE=file] [--vdlm=file] [--vdl-data-file=file] [--max-vdl-data-size=bytes] [--rebuild-vdl-data] [--vexit] [--#=num] [--] [filenames...]
vfind-mt
	[--threads=num] [vfind options...]
lvfind	[--lock=file] [--lock-retries=count] [vfind options...]
Lvfind	[--lock=file] [--lock-retries=count] [--lock-sleeptime=seconds] [vfind options...]

VFind is a heterogeneous virus scanner that simultaneously scans for UNIX, Amiga, Macintosh, Windows 95/NT, and Dos viruses, including Denial of Service attacks, Back Door attacks, hostile Java Applications and Applets, OLE/VB5 Macro viruses, and common hacks.

-c, --copyright
	Display copyright information and then exit. All other options will be ignored.
-h, --help
	Display usage message and then exit. All other options will be ignored.
-v, --version
	Display version information and then exit. All other options will be ignored.
-d, --dup-check
	Tells vfind to check for duplicate VDL names and definitions, and other potential problems. With this option enabled, duplicates will be reported as parser errors. Also, any VDL segment which starts with an offset range or .* operator will be reported as a parser error. An offset at the beginning of a VDL segment is allowed by the CVDL syntax, but does not make sense to use, and may cause the VDL to run very slow.
--trig-count
	Lists the names of any VDLs that could not be indexed for speed, and also the trigger and run counts for all VDLs. In general, only simple VDL constructs can be indexed, and only constructs containing strings of four or more bytes. Having many non-indexed VDLs, or VDLs with excessive trigger hit counts, will make VFind run significantly slower.
-e, --exit-on-error
	Tells VFind to exit immediately after encountering any kind of error or warning condition. Normally, VFind prints a warning message and attempts to continue processing after encountering a non-fatal error, such as a syntax error in a VDL description.
-ev, --exit-on-vdl-error
	Tells VFind to exit immediately after encountering any kind of error related to processing of vdl files. Normally, vfind prints a warning message and attempts to continue processing after encountering a non-fatal error, such as a syntax error in a VDL description.
--emu=options
	Set options for polymorphic virus emulation. This option is still under development and its usage will be documented further in a future release.
--emu-help
	List options for polymorphic virus emulation. This option is still under development and its usage will be documented further in a future release.
--emu-config=file
	Specify emulation configuration file. This option is still under development and its usage will be documented further in a future release.
--end	Used to exit VFind while in Interactive mode.
-i, --ignore-eof
	Tells VFind to ignore end-of-file and keep trying to read input files names or SmartScan input. --end and --quit may still be used to exit Interactive mode.
--jadevdl=file
	Tells VFind to load additional virus signatures from file. File contains VDL models for hostile java applets and applications.
--libon=library, --liboff=library
	Turn on/off library. VFind will list the available libraries upon startup. Amiga and eicar libraries are turned off by default. Use --libon=’*’ to turn on all libraries.
--md5=file
	Tells vfind to read additional MD5 virus signatures from file.
--cbayes=file
	Tells vfind to read Read additional cbayes data from file.
--noload=virus
	This option provides a way to disable loading of individual VDLs. This may be useful if your site gets a lot of false positives for some particular virus due to the type of data you have. Virus is the name of the virus as it appears in the VDL file, for example: --noload="W32/Sircam.a"
--noloads=file
	This provides a way to specify multiple noload parameters in a file. File is a file that contains valid virus parameters as described in the "--noload" option. For each line of the file, leading and trailing whitespace is stripped, then lines which are empty or start with ’#’ (i.e. comments) are skipped.
--noscan=filename
	This option provides a way to turn off scanning of particular files or directories. This may be useful when scanning disks containing e.g. quarantined viruses or virus scanner configuratuion files. If the name contains a ’/’ (slash) character, if is matched agains the full name of the scanning target, otherwise, it is matched only agains the final component, after the final slash.
--noscans=file
	This option provides a way to specify multiple noscan parameters in a file. File is a file that contains file or directory names as described in the noscan option.
--notell=virus
	This option provides a way to turn off reporting of individual viruses. This may be useful if your site gets a lot of false positives for some particular virus due to the type of data you have. Virus is the name of the virus as it appears after "VIRUS ID: " in vfind’s output, for example: --notell="CVDL W32/Sircam.a"
--notells=file
	This option provides a way to specify multiple notell parameters in a file. File is a file that contains valid virus parameters as described in the notell option.
--force-scan
	Force scanning of the compiled vdl data file. This file is normally not scanned, as it would be very slow, and produce a large amount of false hits. The file is instead protected by a cryptographic checksum; any modifications to the file are reported as hits on the "Forgery.1" virus id.
--recursion-limit=number
	Maximum depth to recursively scan directories, negative for unlimited (the default), or zero to not scan directories at all.
--follow-symlinks
	If this flag is given, VFind will follow symbolic links pointing to directories; otherwise, such links are ignored. This option should be used with precaution, as loops in the directory structure can make VFind unable to scan all files.
--ignore-symlinks
	If ths flag is given, VFind will not follow symbolic links pointing to regular files, otherwise, such links are followed and the file scanned as usual. Setting this may be useful e.g. to limit scanning to a locally mounted file system.
--keep-tmpfiles
	The temporary files containing constituent files created during expansion are retained (normally they are deleted). These files are announced as each input file is scanned when this option is specified.
-p, --per-file
	Per-file: display the number of possible virus infections for each file.
--pid	Print process id to stderr. See also --pidfile.
--quiet=num
	This command provides a way of suppressing some of vfind’s verbosity. --quiet=0   The default behavior. --quiet=1   Suppresses the "Enter the name of the file to be checked:" prompt and its two trailing newlines. --quiet=2   Suppresses the "Checking file: filename" and its two trailing newlines. --quiet=3   Suppresses all per-file output, including virus detections. Available only for applications linked with vfind as a library using callback functions to handle detections. Thus, with --quiet=2, you can pipe a list of file names to vfind and there will be no per-file output unless a possible virus is found. There will always, however, be the final report of the number of files scanned and the number of possible infections found.
--quit	Used to exit vfind while in Interactive mode.
--rcf=file
	Run Control File. Tells VFind to read additional command-line arguments from file.
--pidfile=file
	Save process id to file.
--savepid=file
	This option is available for backwards compatibility only, and is scheduled to be removed in a future release.
-ssr, --smartscan-read
	This option will tell vfind to read a SmartScan input stream. There must be a process writing a SmartScan stream to vfind’s stdin.
-sst, --smartscan-types
	SmartScan Types: Displays file types and any VDL’s skipped due to file type restrictions.
-nosst, --no-smartscan-types
	No SmartScan Types: Disables skipping any VDLs due to file type restrictions. VDL file type restrictions will be ignored and all VDLs will be applied to all file types.
--stdin
	Use the data on standard input as the file to scan. This will be treated as a file called "-".
--threads=num
	Specify maximum number of threads (default=1). Only the multithreaded VFind executables vfind-mt and lvfind-mt support use of multiple threads.
--tmpdir=dir
	Set the directory used for temporary files to dir. Without this option, uad the default temp directory appropriate to the operating system is used.
-u, --unbuf
	Make SmartScan Read unbuffered. Use of this option may cause a performance penalty, so it should not be used unless your application requires it.
--uad=opts
	Tells vfind to run uad as a subprocess with the specified command-line opts which will be passed to uad in addition to -ssw and -s. Thus, uad will read file names from standard input and write smartscan output to vfind. Examples: 1. vfind --uad= 2. vfind --uad="-M -H3" are equivalent to: 1. uad -s -ssw | vfind -ssr 2. uad -s -ssw -M -H3 | vfind -ssr The --uad= option is mainly useful for multithreaded vfind-mt which will run a separate uad process for each thread. In this case there is no equivalent command using pipes. Example: vfind-mt --threads=4 --uad= will run 4 instances of uad, with each instance connected to a separate thread, and the file names from standard input will be distributed among the threads running in parallel.
--vdl-list=file
	Tells vfind to read the VDL library list from file instead of $VSTK_HOME/data/vfind/vdl.list. Must be the first command-line option if used because it must be processed before other options like --libon= which require the VDL library list file to already be read. Note that the VDL files specified in the VDL library list must be in the $VSTK_HOME/data/vfind/ directory.
--vdl=file
	Tells vfind to read additional virus description codes from file.
--vdl0=file
	Tells VFind to read additional virus descriptions from file, but without compiling them into the paralell search engine. The parallell engine provides fast scanning but no control over the order in which the VDL patterns are applied. With vdl0, VDL rules are placed in a first-in-last-out queue, so the last rule specified is the first one executed, and vdl0 rules are always executed before the parallel search engine. So the --vdl0 option is useful when you have some set of VDL rules which you want executed in a guaranteed order, and this would usually be used in conjunction with the --#=1 option to stop scanning after finding one match.
--vdlc=file
	Tells VFind to read additional case-insensitive virus descriptions from file. Case-insensitive VDL constructs (i.e. ~"..." strings) are not compiled into the regular parallel search engine. But VDL files specified using the --vdlc option are compiled into a separate case-insensitive parallel search engine for faster processing.
--vdle=file
	Tells VFind to read additional decrypted polymorphic virus descriptions from file. Used in conjunction with the --emu option. This option is still under development and its usage will be documented further in a future release.
--vdlE=file
	Tells VFind to read additional Entry point virus descriptions from file. Used in conjunction with the --emu option. This option is still under development and its usage will be documented further in a future release.
--vdlm=file
	Tells VFind to read additional meta virus descriptions from file. Note that meta VDLs match on the names of other VDL hits, not on the data being scanned. See the CVDL documentation for more information.
--vdl-data-file=file
	Name of the file holding the compiled VDL data between VFind invocations. If not set, $VSTK_HOME/var/vdl.dat is used.
--max-vdl-data-size=bytes
	Maximum size in Mbytes of the compiled VDL data file, default 128.
--rebuild-vdl-data
	This option causes VFind to always rebuild the VDL data file, even when it is up to date.
--vexit
	This option causes vfind to return a known value on exit. With this option vfind will return 0 if no viruses were detected. In the event that a virus has been detected, vfind will return 23. This functionality is useful when integrating vfind in a script or other program. The return values cannot be changed from the defaults (23 and 0).
--vlist
	This option causes vfind to print to stdout a list of all viruses for which it currently scans.
--#=num
	Stop scanning a file after finding num viruses, e.g. --#=1 will stop after finding 1 virus. Note that # starts a comment in the Unix Bourne shell, so you may have to specify this option in quotes: ’--#=1’
--	End of Options: Signals to VFind that all remaining arguments are to be treated as filenames, even if they start with ’-’.

VFind requires a LICENSE file to run. This LICENSE file is host specific, therefore vfind will only run on the licensed machine. Additional licenses may be purchased by contacting:

CyberSoft, Inc.
1508 Butler Pike
Conshohocken, PA 19428.
Phone: +1.610.825.4748
Fax: +1.610.825.6785

At start-up, vfind searches for the LICENSE file in these locations:

* /LICENSE
* /etc/LICENSE
* The current working directory.
* The VSTK library directory set at installation.

VFind can be run in three ways.

1. Interactive mode:
	Running vfind without any file arguments (or other input such as SmartScan and stdin) will result in a prompt asking what file to scan. Example: vfind
2. Batch mode:
	VFind can be invoked with a list of files (or other input such as SmartScan or stdin). In this mode, vfind will scan all of the targets and write a report to stdout. This mode is useful when scanning many files or directories. Example: vfind *.doc *.exe
3. Automated mode:
	VFind can be run from a script, batch file, or other application and be scheduled using UNIX cron or a similar program. To run in this mode simply create your vfind command and place it in the appropriate place in your script, batch file, or application. When this mode is invoked, vfind will run un-attended and generate a report to stdout. This report can be redirected to a file, emailed, or otherwise processed. This mode of operation is useful when scanning a large amount of data on a regular basis.

VFind’s output can be very verbose at times. In order to cut down the output we recommend using the choke method.

The choke method is as simple as piping the output from vfind into grep, or a similar tool.

Each line of output from vfind starts with a chevron as follows:

   Chevron         Meaning
  --------------------------------------
  ##==>       Informational Message
  ##==>>      VFind Warning
  ##==>>>     Serious VFind Condition
  ##==>>>>    Possible Virus Detection

Example:

  find / -type f | vfind | grep ’##==>>>’ > REPORT

The above example would only show errors and virus detection messages.

By default, VFind output is worded for virus scanning. When VFind is used for scanning for other things than viruses, it’s possible to customize its messages thru the use of particularly formatted comments in the *.vdl files, or in the vdl.list file for messages that are not specific to a particular vdl file. Comments of the form $name = value sets the named variable to the given value. The following variables are recognized, and will change the default text (in parentheses below) to the specified value.

$pattern-type (VIRUS)
	A short name used to identify the pattern.
$pattern-match (VIRUS POSSIBLE)
	Message presented when a pattern matches.
$pattern-description (possible virus infection)
	Message describing what the pattern matches.
$pattern-not-found (No apparent virus infections)
	Message presented when no patterns matched. Variable names and values are case independent; VFind adjusts the case to match the running text of the output. VFind adds -e or -es when needed to presents the pattern type or pattern description in plural; more complicated plurals can be given explicitly by specifying the variable value as singular/plural.

VFind is a SmartScan compliant tool. Specifying the -ssr option to vfind will cause it to read a SmartScan stream from stdin. For example:

  find /export/home -type f -print | uad -s -ssw | \
    vfind -ssr > REPORT

Why would you ever want to use less than the maximum speed? Most users will never have to worry about this; however, here are a couple of reasons someone might.

One reason is that there is a space/speed trade-off. If the dynamic space required to run vfind with --speed=2 is prohibitive on your machine (i.e., vfind can’t run or there is excessive paging), try --speed=1.

Another reason involves the trade-off between start-up time and marginal scan time. With --speed=2 there may be a substantial start-up time as vfind initializes various internal structures. This might be on the order of, e.g., a second. When scanning a single small file, this might be a waste of time.

On the other hand, --speed=2 provides the fastest marginal scan time, that is, the time needed to scan each extra byte of data. Thus, when scanning large amounts of data with a single invocation of vfind (such as when handling SmartScan data from uad(1) or handling a large number of file names piped in via standard input), --speed=2 (if you have the space for it) is a good idea despite the start-up time.

Note: This feature is provided for backwards compatibility only, and is scheduled to go away in a future release of VFind. To update VDL files on the fly, the files should be copied/untarred first with a different name, and then renamed to their correct name. This will assure that vfind can not read a file before it’s complete.

VFind includes an internal locking mechanism to facilitate VDL updates. This is useful for systems where vfind processes are started continuously, for example a mail server which runs vfind automatically to process one or more newly arrived mail messages. If updated VDL files were installed at the same time that a vfind process was started, the VDL data read by vfind could be wrong or missing. This problem is avoided by using lvfind and Lvfind links to vfind which use internal locking. A dummy file, $VSTK_HOME/data/LOCK by default, is used for the fcntl() locking. There is also a --lock= command-line option to specify an alternate lock file.

If vfind is invoked using a name starting with ’l’, (e.g. an lvfind symlink to vfind), then it attempts to acquire a shared (read-only) lock on the LOCK file. If invoked using a name starting with ’L’ (e.g. Lvfind), then it attempts to acquire an exclusive (read-write) lock on the LOCK file.

Shared locks do not interfere with other shared locks, but will fail if there is an existing exclusive lock. An exclusive lock will fail if there are any other locks of either type. Shared locks require only read access to the LOCK file, but an exclusive lock requires read-write access.

lvfind will release the lock only after reading all VDL files, including those from the data/vfind/vdl.list VDL list file plus any others specified using --vdl=, --vdlc=, etc. command-line options.

Lvfind simply waits up to 60 seconds (--sleep-time option) and then exits, it does not read any VDL files or scan any input data. It prints the process id to stderr (as though --pid was specified) to facilitate killing it.

The default values for command-line options are equivalent to specifying:

lvfind --lock-retries=60
Lvfind --lock-retries=60 --sleep-time=60

If locking fails due to interfering locks, it is retried up to 60 more times (--lock-retries option), with a 1 second delay between attempts. The locking could fail, for example, if a VDL update process is started while an lvfind process holds a shared lock. If the locking fails due to some reason other than interfering locks, that is a fatal locking error; lvfind will set the vfind error flag, give up on the locking, and continue; Lvfind will just exit.

After 60 failed locking attempts (--lock-retries option), lvfind will set the vfind error flag and give up, continuing with the rest of the program; but Lvfind will just exit.

VFind will restart using execvp() when receiving signal SIGHUP. This is useful with the -i,--ignore-eof option when running vfind as a daemon, to restart after updating VDLs. VFind should only be restarted when input is at EOF, otherwise stdio buffering can cause a loss of data and/or smartscan desyncronization.

$VSTK_HOME/LICENSE
$VSTK_HOME/data/vfind/vdl.list

vfind(1), vfindd(1), vdlc(1), uad(1), cit(1), thd(1), bhead(1), jdis(1), find(1), dd(1), grep(1), CVDL(5)

Please report all bugs to support@cyber.com Make sure to include the version of vfind, the platform and OS, the script or command used, the complete output showing the bug, a short description of the problem, and contact information.

Copyright 1991-2005 by CyberSoft, Inc. All rights reserved.