clamscan(1)

📦
version 1.5.4 · 10 versions
, in arch rolling, nixpkgs unstable, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 clamscan(1) — Clam AntiVirus 🌸

okay bestie, buckle up 💖 this is clamscan from the Clam AntiVirus manual, section 1, and she's a whole icon.

✨ NAME ✨

clamscan — scan files and directories for viruses 🦠🔍

✨ SYNOPSIS ✨

clamscan [options] [file/directory/-]

✨ DESCRIPTION ✨

clamscan is a command line anti-virus scanner. that's it, that's the vibe. it goes through your files and tells you what's sus 💅

✨ OPTIONS ✨

okay so most of these are just lil switches that turn stuff on and off, no big deal. but the ones marked with [=yes/no(*)] can optionally be followed by =yes or =no — and if you call them without the boolean argument, the scanner just assumes 'yes' bc she's generous like that. the asterisk * marks the default internal setting for that option, iykyk 👑

  • -h, --help — print help info and dip. bye ✨
  • -V, --version — print the version number and exit. flex the build 🎀
  • -v, --verbose — be verbose. like, talk more.
  • -a, --archive-verbose — show the filenames inside scanned archives 👀
  • --debug — display debug messages coming out of libclamav 🐛
  • --quiet — be quiet. only error messages get through 🤫
  • --stdout — write all messages (except for libclamav output) to standard output (stdout).
  • --no-summary — do not display the summary at the end of scanning. no little recap for you 🙈
  • -i, --infected — only print infected files. main character files only 💀
  • -o, --suppress-ok-results — skip printing the OK files. we don't need the good news, apparently.
  • --bell — sound the bell when a virus is detected 🔔 (dramatic and honestly? deserved)
  • --tempdir=DIRECTORY — create temporary files in DIRECTORY. heads up: that directory has to be writable for the 'clamav' user, or for whatever unprivileged user is running clamscan.
  • --leave-temps — do not remove temporary files. let them linger 🫶
  • --force-to-disk — this one makes memory or nested map scans dump their content to disk. if you turn it on, more data gets written to disk and it becomes available when the LeaveTemporaryFiles option is enabled.
  • --gen-json — generate a JSON description of the scanned file(s). the JSON gets printed and also dropped into the temp directory if --leave-temps is enabled 📝
  • --json-store-html-uris — store html URIs in metadata. the URIs get written to the metadata.json file in an array called 'URIs'.
  • --json-store-pdf-uris — store pdf URIs in metadata. those URIs also get written to the metadata.json file in an array called 'URIs'.
  • --json-store-extra-hashes — store md5 and sha1 in addition to sha2-256 in metadata. more hashes, more power ⭐
  • -d FILE/DIR, --database=FILE/DIR — load the virus database from FILE, or load all the virus database files from DIR.
  • --official-db-only=[yes/no(*)] — only load the official signatures published by the ClamAV project. nothing unofficial in this house 🚫
  • --fail-if-cvd-older-than=days — return with a nonzero error code if the virus database is older than the specified number of days. expired db? we're failing, periodt ⏰
  • -l FILE, --log=FILE — save the scan report to FILE.
  • -r, --recursive — scan directories recursively. every single subdirectory inside the given directory gets scanned. the whole family tree 🌳
  • -z, --allmatch — after a match, keep scanning inside the file for additional matches. don't stop at the first one, we're thorough 💅
  • --cross-fs=[yes(*)/no] — scan files and directories on other filesystems.
  • --follow-dir-symlinks=[0/1(*)/2] — follow directory symlinks. three whole modes bestie: 0 — never follow directory symlinks; 1 (the default) — only follow directory symlinks that are passed as direct arguments to clamscan; 2 — always follow directory symlinks.
  • --follow-file-symlinks=[0/1(*)/2] — follow file symlinks. same three flavors: 0 — never follow file symlinks; 1 (the default) — only follow file symlinks that are passed as direct arguments to clamscan; 2 — always follow file symlinks.
  • -f FILE, --file-list=FILE — scan files listed line by line in FILE. a whole guest list 📋
  • --remove[=yes/no(*)] — remove infected files. be careful! ⚠️ like, genuinely. that's a delete. no undo. no takebacks.
  • --move=DIRECTORY — move infected files into DIRECTORY. that directory must be writable for the 'clamav' user or for the unprivileged user running clamscan.
  • --copy=DIRECTORY — copy infected files into DIRECTORY. same deal, directory must be writable for the 'clamav' user or the unprivileged user running clamscan.
  • --exclude=REGEX, --exclude-dir=REGEX — don't scan file/directory names that match the regular expression. you can use these options multiple times 🔁
  • --include=REGEX, --include-dir=REGEX — only scan file/directory names that match the regular expression. also usable multiple times 🔁
  • --bytecode[=yes(*)/no] — with this on, ClamAV will load bytecode from the database. and ngl? it's highly recommended you keep this turned on, otherwise you may miss detections for many new viruses 👑
  • --bytecode-unsigned[=yes/no(*)] — 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 💀💀💀 like that's not a vibe at all.
  • --bytecode-timeout=N — set the bytecode timeout in milliseconds (default: 10000 = 10s) ⏱️
  • --statistics[=none(*)/bytecode/pcre] — collect and print execution statistics 📊
  • --detect-pua[=yes/no(*)] — detect Possibly Unwanted Applications. the shady-but-not-quite-virus crowd 🙈
  • --exclude-pua=CATEGORY — exclude a specific PUA category. can be used multiple times. see https://docs.clamav.net/faq/faq-pua.html for the complete list of PUA.
  • --include-pua=CATEGORY — only include a specific PUA category. can be used multiple times. also see https://docs.clamav.net/faq/faq-pua.html for the complete list of PUA.
  • --detect-structured[=yes/no(*)] — use the DLP (Data Loss Prevention) module to detect SSN and Credit Card numbers inside documents/text files 🔍
  • --structured-ssn-format=X — 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.
  • --structured-ssn-count=#n — this option sets the lowest number of Social Security Numbers found in a file needed to generate a detect (default: 3).
  • --structured-cc-count=#n — this option sets the lowest number of Credit Card numbers found in a file needed to generate a detect (default: 3).
  • --scan-mail[=yes(*)/no] — scan mail files. if you turn this off, the original files still get scanned, just without parsing individual messages/attachments ✉️
  • --phishing-sigs[=yes(*)/no] — enable email signature-based phishing detection 🎣
  • --phishing-scan-urls[=yes(*)/no] — enable URL signature-based phishing detection (Heuristics.Phishing.Email.*)
  • --heuristic-alerts[=yes(*)/no] — in some cases (eg. complex malware, exploits in graphic files, and others), ClamAV uses special algorithms to provide accurate detection. this option controls that algorithmic detection 🧠
  • --heuristic-scan-precedence[=yes/no(*)] — allow heuristic matches to take precedence. when enabled, if a heuristic scan (such as phishingScan) detects a possible virus/phish, it will stop the scan immediately. recommended, saves CPU scan-time. when disabled, viruses/phishes 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. yeah, it's a lot, read it twice bestie 😭
  • --normalize[=yes(*)/no] — normalize (compress whitespace, downcase, etc.) html, script, and text files. use normalize=no for yara compatibility.
  • --scan-pe[=yes(*)/no] — 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 this option off, the original files still get scanned but without additional processing.
  • --scan-elf[=yes(*)/no] — 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 still get scanned but without additional processing.
  • --scan-ole2[=yes(*)/no] — scan Microsoft Office documents and .msi files. if you turn this option off, the original files still get scanned but without additional processing.
  • --scan-pdf[=yes(*)/no] — scan within PDF files. if you turn this option off, the original files still get scanned, but without decoding and additional processing.
  • --scan-swf[=yes(*)/no] — scan SWF files. if you turn this option off, the original files still get scanned but without additional processing.
  • --scan-html[=yes(*)/no] — detect, normalize/decrypt and scan HTML files and embedded scripts. if you turn this option off, the original files still get scanned, but without additional processing.
  • --scan-xmldocs[=yes(*)/no] — scan xml-based document files supported by libclamav. if you turn this option off, the original files still get scanned, but without additional processing.
  • --scan-hwp3[=yes(*)/no] — scan HWP3 files. if you turn this option off, the original files still get scanned, but without additional processing.
  • --scan-archive[=yes(*)/no] — scan archives supported by libclamav. if you turn this option off, the original files still get scanned, but without unpacking and additional processing 📦
  • --scan-image[=yes(*)/no] — this option enables scanning of image (graphics) files. if you turn this option off, the original files still get scanned, but without additional processing 🖼️
  • --scan-image-fuzzy-hash[=yes(*)/no] — 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 this option off, then some files may no longer be detected 👀
  • --alert-broken[=yes/no(*)] — alert on broken executable files (PE & ELF). cracked ones count too 🩹
  • --alert-encrypted[=yes/no(*)] — alert on encrypted archives and documents (encrypted .zip, .7zip, .rar, .pdf). secrets stay sus 🔐
  • --alert-encrypted-archive[=yes/no(*)] — bestie, this one yells at you when it clocks an encrypted archive (that's encrypted .zip, .7zip, .rar, .pdf). 🫶
  • --alert-encrypted-doc[=yes/no(*)] — same energy but for encrypted documents (also encrypted .zip, .7zip, .rar, .pdf). ✨
  • --alert-macros[=yes/no(*)] — alerts on OLE2 files that are hiding VBA macros in them, which it calls Heuristics.OLE2.ContainsMacros. macros? in my OLE2 file? it's more likely than you think 💀
  • --alert-exceeds-max[=yes/no(*)] — alerts when a file blows past max file size, max scan size, or the max recursion limit. the flag name for that whole mood is Heuristics.Limits.Exceeded. 😤
  • --alert-phishing-ssl[=yes/no(*)] — alerts on emails with SSL mismatches in their URLs. > heads up bestie: this one might lead to false positives! so don't come for it when it gets a lil dramatic 🙈
  • --alert-phishing-cloak[=yes/no(*)] — alerts on emails packing cloaked URLs. > also possibly false-positive-prone, so take it with a grain of salt (might lead to some false positives). ✨
  • --alert-partition-intersection[=yes/no(*)] — heuristics time! this detects partition intersections inside raw disk images. 🔍
  • --nocerts — turns off authenticode certificate chain verification in PE files. no verifying, just vibes. 💅
  • --dumpcerts — the opposite mood: dumps the authenticode certificate chain out of PE files. show me everything 👑
  • --max-scantime=#n — the absolute longest it'll keep scanning before it gives up on you. value's in milliseconds. set it to 0 and the limit is gone, poof, disabled. this is your armor against DoS attacks, so don't be reckless. (default: 120000 = 120s or 2min)
  • --max-filesize=#n — extract and scan at most #n bytes from each archive. you can hand it kilobytes like xK or xk, or megabytes like xM or xm, where x is a number. DoS protection, periodt. (default: 100 MB, max: 2 GB)
  • --max-scansize=#n — extract and scan at most #n bytes from each archive. here's the tea: the size of the archive plus the sum of all the files inside it both count toward the scan size. like, a 1M uncompressed archive with a single 1M inner file counts as 2M toward max-scansize. kilobytes come as xK or xk, megabytes as xM or xm, x being a number. DoS protection again 🛡️ (default: 400 MB)
  • --max-files=#n — extract at most #n files from each scanned file (and yeah, that means when the scanned thing is an archive, a document, or any other kind of container). more DoS protection. (default: 10000)
  • --max-recursion=#n — sets the archive recursion level limit. DoS protection, obviously. (default: 17) (maximum: 100).
  • --max-dir-recursion=#n — how deep directories get scanned. (default: 15).
  • --max-embeddedpe=#n — biggest file it'll check for embedded PE. kilobytes as xK or xk, megabytes as xM or xm, x is a number (default: 40 MB).
  • --max-htmlnormalize=#n — biggest HTML file it'll normalize. xK/xk for kilobytes, xM/xm for megabytes, x a number (default: 40 MB).
  • --max-htmlnotags=#n — biggest normalized HTML file it'll scan. xK/xk, xM/xm, x = number (default: 8 MB).
  • --max-scriptnormalize=#n — biggest script file it'll normalize. xK/xk, xM/xm, x = a number (default: 20 MB).
  • --max-ziptypercg=#n — biggest zip it'll type reanalyze. xK/xk, xM/xm, x = number (default: 1 MB).
  • --max-partitions=#n — max number of partitions of a raw disk image that get scanned. gotta be a positive integer (default: 50).
  • --max-iconspe=#n — max number of icons inside a PE that get scanned. must be a positive integer (default: 100).
  • --max-rechwp3=#n — max recursive calls to the HWP3 parsing function (default: 16).
  • --pcre-match-limit=#n — max calls to the PCRE match function (default: 100000).
  • --pcre-recmatch-limit=#n — max recursive calls to the PCRE match function (default: 2000).
  • --pcre-max-filesize=#n — biggest file that gets PCRE subsig matching (default: 100 MB).
  • --disable-cache — kills caching and cache checks for the hash sums of scanned files. fresh every time, no stored receipts ✨
  • --hash-hint — you hand over the file hash so libclamav doesn't have to calculate it. the type of hash has to match '--hash-alg' or it's not gonna work. 🎀
  • --log-hash — prints the file hash after each file scanned. what type of hash gets printed? whatever '--hash-alg' says. 👑
  • --hash-alg — the hashing algorithm used for either '--hash-hint' or '--log-hash'. supported ones are "md5", "sha1", "sha2-256". if you don't specify, it defaults to "sha2-256". 🔥
  • --file-type-hint — a file type hint so libclamav can optimize scanning. like "pe", "elf", "zip", etc. you can also use ClamAV type names like "CL_TYPE_PE". if it doesn't recognize the type you gave it, ClamAV just ignores the hint, no hard feelings. see also: https://docs.clamav.net/appendix/FileTypes.html#file-types 🦋
  • --log-file-type — prints the file type after each file scanned.
  • --cvdcertsdir=DIR — point it at a directory holding the root CA cert needed to verify detached CVD digital signatures. if you don't provide one, clamscan goes looking in the default directory. 🧚
  • --fips-limits — enforces FIPS-like limits on using hash algorithms for cryptographic purposes. this disables MD5 & SHA1 FP sigs and requires '.sign' files to verify CVD authenticity. not messing around with this one 💅

🌸 ENVIRONMENT VARIABLES 🌸

clamscan vibes with these environment variables:

  • LD_LIBRARY_PATH — may be used on startup to find the libclamunrar_iface shared library module, which is what enables RAR archive support. that's the whole plug 🫶
  • CVD_CERTS_DIR — specify a directory containing the root CA cert needed to verify detached CVD digital signatures. if it's not provided, clamscan looks in the default directory. 💖

✨ EXAMPLES ✨

(0) scan a single file:

clamscan file

(1) scan the current working directory:

clamscan

(2) scan all files (and subdirectories) in /home:

clamscan -r /home

(3) load the database from a file:

clamscan -d /tmp/newclamdb -r /tmp

(4) scan a data stream:

cat testfile | clamscan -

(5) scan a mail spool directory:

clamscan -r /var/spool/mail

💀 RETURN CODES 💀

  1. 0 : no virus found. ate and left no crumbs 👑
  2. 1 : virus(es) found. not the vibe 😭
  3. 2 : some error(s) occurred. it's giving chaos 🙈

🎀 CREDITS 🎀

please check the full documentation for credits. iykyk 💜

🌈 AUTHOR 🌈

Tomasz Kojm <tkojm@clamav.net>, Kevin Lin <klin@sourcefire.com> — icons, both of them ✨

🦋 SEE ALSO 🦋

clamdscan(1), freshclam(1), freshclam.conf(5)

and that's the whole page bestie!! 💖 this is from <b>ClamAV 1.5.4</b>, dated <b>December 4, 2013</b> (yes girl, that date is doing time travel, don't ask), and it's the clamscan(1) manual. go scan something, you're the main character now 👑💅

📦 where this page comes from