Stowage/clamav
2
0
Fork 0
mirror of https://github.com/Cisco-Talos/clamav.git synced 2025-10-19 10:23:17 +00:00
Code Issues Projects Releases Packages Wiki Activity
clamav/docs/man/clamscan.1.in
Valerie Snyder 13c4788f36
FIPS & FIPS-like limits on hash algs for cryptographic uses 
ClamAV will not function when using a FIPS-enabled OpenSSL 3.x.
This is because ClamAV uses MD5 and SHA1 algorithms for a variety of
purposes including matching for malware detection, matching to prevent
false positives on known-clean files, and for verification of MD5-based
RSA digital signatures for determining CVD (signature database archive)
authenticity.

Interestingly, FIPS had been intentionally bypassed when creating hashes
based whole buffers and whole files (by descriptor or `FILE`-pointer):
78d4a9985a
Note: this bypassed FIPS the 1.x way with:
`EVP_MD_CTX_set_flags(ctx, EVP_MD_CTX_FLAG_NON_FIPS_ALLOW);`

It was NOT disabled when using `cl_hash_init()` / `cl_update_hash()` /
`cl_finish_hash()`. That likely worked by coincidence in that the hash
was already calculated most of the time. It certainly would have made
use of those functions if the hash had not been calculated prior:
78d4a9985a/libclamav/matcher.c (L743)

Regardless, bypassing FIPS entirely is not the correct solution.
The FIPS restrictions against using MD5 and SHA1 are valid, particularly
when verifying CVD digital siganatures, but also I think when using a
hash to determine if the file is known-clean (i.e. the "clean cache" and
also MD5-based and SHA1-based FP signatures).

This commit extends the work to bypass FIPS using the newer 3.x method:
`md = EVP_MD_fetch(NULL, alg, "-fips");`

It does this for the legacy `cl_hash*()` functions including
`cl_hash_init()` / `cl_update_hash()` / `cl_finish_hash()`.
It also introduces extended versions that allow the caller to choose if
they want to bypass FIPS:
- `cl_hash_data_ex()`
- `cl_hash_init_ex()`
- `cl_update_hash_ex()`
- `cl_finish_hash_ex()`
- `cl_hash_destroy_ex()`
- `cl_hash_file_fd_ex()`
See the `flags` parameter for each.

Ironically, this commit does NOT use the new functions at this time.
The rational is that ClamAV may need MD5, SHA1, and SHA-256 hashes of
the same files both for determining if the file is malware, and for
determining if the file is clean.

So instead, this commit will do a checks when:

1. Creating a new ClamAV scanning engine. If FIPS-mode enabled, it will
   automatically toggle the "FIPS limits" engine option.
   When loading signatures, if the engine "FIPS limits" option is enabled,
   then MD5 and SHA1 FP signatures will be skipped.

2. Before verifying a CVD (e.g. also for loading, unpacking when
   verification enabled).
   If "FIPS limits" or FIPS-mode are enabled, then the legacy MD5-based RSA
   method is disabled.

   Note: This commit also refactors the interface for `cl_cvdverify_ex()`
   and `cl_cvdunpack_ex()` so they take a `flags` parameters, rather than a
   single `bool`. As these functions are new in this version, it does not
   break the ABI.

The cache was already switched to use SHA2-256, so that's not a concern
for checking FIPS-mode / FIPS limits options.

This adds an option for `freshclam.conf` and `clamd.conf`:

   FIPSCryptoHashLimits yes

And an equivalent command-line option for `clamscan` and `sigtool`:

   --fips-limits

You may programmatically enable FIPS-limits for a ClamAV engine like this:
```C
   cl_engine_set_num(engine, CL_ENGINE_FIPS_LIMITS, 1);
```

CLAM-2792
2025-08-14 22:39:15 -04:00

348 lines
16 KiB
Groff
Raw Blame History

.TH "clamscan" "1" "December 4, 2013" "ClamAV @VERSION@" "Clam AntiVirus"
.SH "NAME"
.LP
clamscan \- scan files and directories for viruses
.SH "SYNOPSIS"
.LP
clamscan [options] [file/directory/\-]
.SH "DESCRIPTION"
.LP
clamscan is a command line anti\-virus scanner.
.SH "OPTIONS"
.LP
Most of the options are simple switches which enable or disable some features. Options marked with [=yes/no(*)] can be optionally followed by =yes/=no; if they get called without the boolean argument the scanner will assume 'yes'. The asterisk marks the default internal setting for a given option.
.TP
\fB\-h, \-\-help\fR
Print help information and exit.
.TP
\fB\-V, \-\-version\fR
Print version number and exit.
.TP
\fB\-v, \-\-verbose\fR
Be verbose.
.TP
\fB\-a, \-\-archive\-verbose\fR
Show filenames inside scanned archives
.TP
\fB\-\-debug\fR
Display debug messages from libclamav.
.TP
\fB\-\-quiet\fR
Be quiet (only print error messages).
.TP
\fB\-\-stdout\fR
Write all messages (except for libclamav output) to the standard output (stdout).
.TP
\fB\-\-no\-summary\fR
Do not display summary at the end of scanning.
.TP
\fB\-i, \-\-infected\fR
Only print infected files.
.TP
\fB\-o, \-\-suppress\-ok\-results\fR
Skip printing OK files
.TP
\fB\-\-bell\fR
Sound bell on virus detection.
.TP
\fB\-\-tempdir=DIRECTORY\fR
Create temporary files in DIRECTORY. Directory must be writable for the '@CLAMAV_USER@' user or unprivileged user running clamscan.
.TP
\fB\-\-leave\-temps\fR
Do not remove temporary files.
.TP
\fB\-\-force\-to\-disk\fR
This option causes memory or nested map scans to dump the content to disk. If you turn on this option, more data is written to disk and is available when the LeaveTemporaryFiles option is enabled.
.TP
\fB\-\-gen\-json\fR
Generate JSON description of scanned file(s). JSON will be printed and also dropped to the temp directory if --leave-temps is enabled.
.TP
\fB\-d FILE/DIR, \-\-database=FILE/DIR\fR
Load virus database from FILE or load all virus database files from DIR.
.TP
\fB\-\-official\-db\-only=[yes/no(*)]\fR
Only load the official signatures published by the ClamAV project.
.TP
\fB\-\-fail\-if\-cvd\-older\-than=days\fR
Return with a nonzero error code if the virus database is older than the specified number of days.
.TP
\fB\-l FILE, \-\-log=FILE\fR
Save scan report to FILE.
.TP
\fB\-r, \-\-recursive\fR
Scan directories recursively. All the subdirectories in the given directory will be scanned.
.TP
\fB\-z, \-\-allmatch\fR
After a match, continue scanning within the file for additional matches.
.TP
\fB\-\-cross\-fs=[yes(*)/no]\fR
Scan files and directories on other filesystems.
.TP
\fB\-\-follow\-dir\-symlinks=[0/1(*)/2]\fR
Follow directory symlinks. There are 3 options: 0 - never follow directory symlinks, 1 (default) - only follow directory symlinks, which are passed as direct arguments to clamscan. 2 - always follow directory symlinks.
.TP
\fB\-\-follow\-file\-symlinks=[0/1(*)/2]\fR
Follow file symlinks. There are 3 options: 0 - never follow file symlinks, 1 (default) - only follow file symlinks, which are passed as direct arguments to clamscan. 2 - always follow file symlinks.
.TP
\fB\-f FILE, \-\-file\-list=FILE\fR
Scan files listed line by line in FILE.
.TP
\fB\-\-remove[=yes/no(*)]\fR
Remove infected files. \fBBe careful!\fR
.TP
\fB\-\-move=DIRECTORY\fR
Move infected files into DIRECTORY. Directory must be writable for the '@CLAMAV_USER@' user or unprivileged user running clamscan.
.TP
\fB\-\-copy=DIRECTORY\fR
Copy infected files into DIRECTORY. Directory must be writable for the '@CLAMAV_USER@' user or unprivileged user running clamscan.
.TP
\fB\-\-exclude=REGEX, \-\-exclude\-dir=REGEX\fR
Don't scan file/directory names matching regular expression. These options can be used multiple times.
.TP
\fB\-\-include=REGEX, \-\-include\-dir=REGEX\fR
Only scan file/directory matching regular expression. These options can be used multiple times.
.TP
\fB\-\-bytecode[=yes(*)/no]\fR
With this option enabled ClamAV will load bytecode from the database. It is highly recommended you keep this option turned on, otherwise you may miss detections for many new viruses.
.TP
\fB\-\-bytecode\-unsigned[=yes/no(*)]\fR
Allow loading bytecode from outside digitally signed .c[lv]d files. **Caution**: You should NEVER run bytecode signatures from untrusted sources. Doing so may result in arbitrary code execution.
.TP
\fB\-\-bytecode\-timeout=N\fR
Set bytecode timeout in milliseconds (default: 10000 = 10s)
.TP
\fB\-\-statistics[=none(*)/bytecode/pcre]\fR
Collect and print execution statistics.
.TP
\fB\-\-detect\-pua[=yes/no(*)]\fR
Detect Possibly Unwanted Applications.
.TP
\fB\-\-exclude\-pua=CATEGORY\fR
Exclude a specific PUA category. This option can be used multiple times. See https://docs.clamav.net/faq/faq-pua.html for the complete list of PUA
.TP
\fB\-\-include\-pua=CATEGORY\fR
Only include a specific PUA category. This option can be used multiple times. See https://docs.clamav.net/faq/faq-pua.html for the complete list of PUA
.TP
\fB\-\-detect\-structured[=yes/no(*)]\fR
Use the DLP (Data Loss Prevention) module to detect SSN and Credit Card numbers inside documents/text files.
.TP
\fB\-\-structured\-ssn\-format=X\fR
X=0: search for valid SSNs formatted as xxx-yy-zzzz (normal); X=1: search for valid SSNs formatted as xxxyyzzzz (stripped); X=2: search for both formats. Default is 0.
.TP
\fB\-\-structured\-ssn\-count=#n\fR
This option sets the lowest number of Social Security Numbers found in a file to generate a detect (default: 3).
.TP
\fB\-\-structured\-cc\-count=#n\fR
This option sets the lowest number of Credit Card numbers found in a file to generate a detect (default: 3).
.TP
\fB\-\-scan\-mail[=yes(*)/no]\fR
Scan mail files. If you turn off this option, the original files will still be scanned, but without parsing individual messages/attachments.
.TP
\fB\-\-phishing\-sigs[=yes(*)/no]\fR
Enable email signature-based phishing detection.
.TP
\fB\-\-phishing\-scan\-urls[=yes(*)/no]\fR
Enable URL signature-based phishing detection (Heuristics.Phishing.Email.*)
.TP
\fB\-\-heuristic\-alerts[=yes(*)/no]\fR
In some cases (eg. complex malware, exploits in graphic files, and others), ClamAV uses special algorithms to provide accurate detection. This option can be used to control the algorithmic detection.
.TP
\fB\-\-heuristic\-scan\-precedence[=yes/no(*)]\fR
Allow heuristic match to take precedence. When enabled, if a heuristic scan (such as phishingScan) detects a possible virus/phish it will stop scan immediately. Recommended, saves CPU scan-time. When disabled, virus/phish detected by heuristic scans will be reported only at the end of a scan. If an archive contains both a heuristically detected virus/phish, and a real malware, the real malware will be reported Keep this disabled if you intend to handle "Heuristics.*" viruses differently from "real" malware. If a non-heuristically-detected virus (signature-based) is found first, the scan is interrupted immediately, regardless of this config option.
.TP
\fB\-\-normalize[=yes(*)/no]\fR
Normalize (compress whitespace, downcase, etc.) html, script, and text files. Use normalize=no for yara compatibility.
.TP
\fB\-\-scan\-pe[=yes(*)/no]\fR
PE stands for Portable Executable \- it's an executable file format used in all 32\-bit versions of Windows operating systems. By default ClamAV performs deeper analysis of executable files and attempts to decompress popular executable packers such as UPX, Petite, and FSG. If you turn off this option, the original files will still be scanned but without additional processing.
.TP
\fB\-\-scan\-elf[=yes(*)/no]\fR
Executable and Linking Format is a standard format for UN*X executables. This option controls the ELF support. If you turn it off, the original files will still be scanned but without additional processing.
.TP
\fB\-\-scan\-ole2[=yes(*)/no]\fR
Scan Microsoft Office documents and .msi files. If you turn off this option, the original files will still be scanned but without additional processing.
.TP
\fB\-\-scan\-pdf[=yes(*)/no]\fR
Scan within PDF files. If you turn off this option, the original files will still be scanned, but without decoding and additional processing.
.TP
\fB\-\-scan\-swf[=yes(*)/no]\fR
Scan SWF files. If you turn off this option, the original files will still be scanned but without additional processing.
.TP
\fB\-\-scan\-html[=yes(*)/no]\fR
Detect, normalize/decrypt and scan HTML files and embedded scripts. If you turn off this option, the original files will still be scanned, but without additional processing.
.TP
\fB\-\-scan\-xmldocs[=yes(*)/no]\fR
Scan xml-based document files supported by libclamav. If you turn off this option, the original files will still be scanned, but without additional processing.
.TP
\fB\-\-scan\-hwp3[=yes(*)/no]\fR
Scan HWP3 files. If you turn off this option, the original files will still be scanned, but without additional processing.
.TP
\fB\-\-scan\-archive[=yes(*)/no]\fR
Scan archives supported by libclamav. If you turn off this option, the original files will still be scanned, but without unpacking and additional processing.
.TP
\fB\-\-scan\-image[=yes(*)/no]\fR
This option enables scanning of image (graphics). If you turn off this option, the original files will still be scanned, but without additional processing.
.TP
\fB\-\-scan\-image\-fuzzy\-hash[=yes(*)/no]\fR
This option enables detection by calculating a fuzzy hash of image (graphics) files. Signatures using image fuzzy hashes typically match files and documents by identifying images embedded or attached to those files. If you turn off this option, then some files may no longer be detected.
.TP
\fB\-\-alert\-broken[=yes/no(*)]\fR
Alert on broken executable files (PE & ELF).
.TP
\fB\-\-alert\-encrypted[=yes/no(*)]\fR
Alert on encrypted archives and documents (encrypted .zip, .7zip, .rar, .pdf).
.TP
\fB\-\-alert\-encrypted-archive[=yes/no(*)]\fR
Alert on encrypted archives (encrypted .zip, .7zip, .rar, .pdf).
.TP
\fB\-\-alert\-encrypted-doc[=yes/no(*)]\fR
Alert on encrypted documents (encrypted .zip, .7zip, .rar, .pdf).
.TP
\fB\-\-alert\-macros[=yes/no(*)]\fR
Alert on OLE2 files containing VBA macros (Heuristics.OLE2.ContainsMacros).
.TP
\fB\-\-alert\-exceeds\-max[=yes/no(*)]\fR
Alert on files that exceed max file size, max scan size, or max recursion limit (Heuristics.Limits.Exceeded).
.TP
\fB\-\-alert\-phishing\-ssl[=yes/no(*)]\fR
Alert on emails containing SSL mismatches in URLs (might lead to false positives!).
.TP
\fB\-\-alert\-phishing\-cloak[=yes/no(*)]\fR
Alert on emails containing cloaked URLs (might lead to some false positives).
.TP
\fB\-\-alert\-partition\-intersection[=yes/no(*)]\fR
Detect partition intersections in raw disk images using heuristics.
.TP
\fB\-\-nocerts\fR
Disable authenticode certificate chain verification in PE files.
.TP
\fB\-\-dumpcerts\fR
Dump authenticode certificate chain in PE files.
.TP
\fB\-\-max\-scantime=#n\fR
The maximum time to scan before giving up. The value is in milliseconds. The value of 0 disables the limit. This option protects your system against DoS attacks (default: 120000 = 120s or 2min)
.TP
\fB\-\-max\-filesize=#n\fR
Extract and scan at most #n bytes from each archive. You may pass the value in kilobytes in format xK or xk, or megabytes in format xM or xm, where x is a number. This option protects your system against DoS attacks (default: 100 MB, max: 2 GB)
.TP
\fB\-\-max\-scansize=#n\fR
Extract and scan at most #n bytes from each archive. The size the archive plus the sum of the sizes of all files within archive count toward the scan size. For example, a 1M uncompressed archive containing a single 1M inner file counts as 2M toward max-scansize. You may pass the value in kilobytes in format xK or xk, or megabytes in format xM or xm, where x is a number. This option protects your system against DoS attacks (default: 400 MB)
.TP
\fB\-\-max\-files=#n\fR
Extract at most #n files from each scanned file (when this is an archive, a document or another kind of container). This option protects your system against DoS attacks (default: 10000)
.TP
\fB\-\-max\-recursion=#n\fR
Set archive recursion level limit. This option protects your system against DoS attacks (default: 17) (maximum: 100).
.TP
\fB\-\-max\-dir\-recursion=#n\fR
Maximum depth directories are scanned at (default: 15).
.TP
\fB\-\-max\-embeddedpe=#n\fR
Maximum size file to check for embedded PE. You may pass the value in kilobytes in format xK or xk, or megabytes in format xM or xm, where x is a number (default: 40 MB).
.TP
\fB\-\-max\-htmlnormalize=#n\fR
Maximum size of HTML file to normalize. You may pass the value in kilobytes in format xK or xk, or megabytes in format xM or xm, where x is a number (default: 40 MB).
.TP
\fB\-\-max\-htmlnotags=#n\fR
Maximum size of normalized HTML file to scan. You may pass the value in kilobytes in format xK or xk, or megabytes in format xM or xm, where x is a number (default: 8 MB).
.TP
\fB\-\-max\-scriptnormalize=#n\fR
Maximum size of script file to normalize. You may pass the value in kilobytes in format xK or xk, or megabytes in format xM or xm, where x is a number (default: 20 MB).
.TP
\fB\-\-max\-ziptypercg=#n\fR
Maximum size zip to type reanalyze. You may pass the value in kilobytes in format xK or xk, or megabytes in format xM or xm, where x is a number (default: 1 MB).
.TP
\fB\-\-max\-partitions=#n\fR
This option sets the maximum number of partitions of a raw disk image to be scanned. This must be a positive integer (default: 50).
.TP
\fB\-\-max\-iconspe=#n\fR
This option sets the maximum number of icons within a PE to be scanned. This must be a positive integer (default: 100).
.TP
\fB\-\-max\-rechwp3=#n\fR
This option sets the maximum recursive calls to HWP3 parsing function (default: 16).
.TP
\fB\-\-pcre-match-limit=#n\fR
Maximum calls to the PCRE match function (default: 100000).
.TP
\fB\-\-pcre-recmatch-limit=#n\fR
Maximum recursive calls to the PCRE match function (default: 2000).
.TP
\fB\-\-pcre-max-filesize=#n\fR
Maximum size file to perform PCRE subsig matching (default: 100 MB).
.TP
\fB\-\-disable\-cache\fR
Disable caching and cache checks for hash sums of scanned files.
.TP
\fB\-\-hash\-hint\fR
The file hash so that libclamav does not need to calculate it. The type of hash must match the '\-\-hash-alg'.
.TP
\fB\-\-log\-hash\fR
Print the file hash after each file scanned. The type of hash printed will match the '\-\-hash-alg'.
.TP
\fB\-\-hash\-alg\fR
The hashing algorithm used for either '\-\-hash\-hint' or '\-\-log\-hash'. Supported algorithms are "md5", "sha1", "sha2\-256". If not specified, the default is "sha2\-256".
.TP
\fB\-\-file\-type\-hint\fR
The file type hint so that libclamav can optimize scanning. E.g. "pe", "elf", "zip", etc. You may also use ClamAV type names such as "CL_TYPE_PE". ClamAV will ignore the hint if it is not familiar with the specified type. See also: https://docs.clamav.net/appendix/FileTypes.html#file-types
.TP
\fB\-\-log\-file\-type\fR
Print the file type after each file scanned.
.TP
\fB\-\-cvdcertsdir=DIR\fR
Specify a directory containing the root CA cert needed to verify detached CVD digital signatures. If not provided, then clamscan will look in the default directory.
.TP
\fB\-\-fips\-limits\fR
Enforce FIPS\-like limits on using hash algorithms for cryptographic purposes. Will disable MD5 & SHA1 FP sigs and will require '.sign' files to verify CVD authenticity.
.SH "ENVIRONMENT VARIABLES"
.LP
clamscan uses the following environment variables:
.TP
\fBLD_LIBRARY_PATH\fR
May be used on startup to find the libclamunrar_iface shared library module to enable RAR archive support.
.TP
\fBCVD_CERTS_DIR\fR
Specify a directory containing the root CA cert needed to verify detached CVD digital signatures. If not provided, then clamscan will look in the default directory.
.SH "EXAMPLES"
.LP
.TP
(0) Scan a single file:
\fBclamscan file\fR
.TP
(1) Scan a current working directory:
\fBclamscan\fR
.TP
(2) Scan all files (and subdirectories) in /home:
\fBclamscan \-r /home\fR
.TP
(3) Load database from a file:
\fBclamscan \-d /tmp/newclamdb \-r /tmp\fR
.TP
(4) Scan a data stream:
\fBcat testfile | clamscan \-\fR
.TP
(5) Scan a mail spool directory:
\fBclamscan \-r /var/spool/mail\fR
.SH "RETURN CODES"
.LP
0 : No virus found.
.TP
1 : Virus(es) found.
.TP
2 : Some error(s) occurred.
.SH "CREDITS"
Please check the full documentation for credits.
.SH "AUTHOR"
.LP
Tomasz Kojm <tkojm@clamav.net>, Kevin Lin <klin@sourcefire.com>
.SH "SEE ALSO"
.LP
clamdscan(1), freshclam(1), freshclam.conf(5)
Reference in a new issue View git blame Copy permalink