{"componentChunkName":"component---src-templates-post-template-js","path":"/clamav-simple-filescan-en","result":{"data":{"markdownRemark":{"id":"d8b38ed2-d26f-58b1-856d-3b7a060bc837","html":"
\n

This page has been machine-translated from the original page.

\n
\n

I’ve been reading through the ClamAV source code without any particular goal, but I’ve reached a natural stopping point, so I’m publishing notes on the sequence of operations that occur from the time ClamAV scans an Eicar file until it is detected.

\n\n

Table of Contents

\n\n

Scanning a File with clamscan or clamdscan

\n

clamdscan is a client program that performs file scanning as a client of a running clamd instance.

\n

clamscan, on the other hand, uses ClamAV’s libclamav to act as a scanner for files and directories.

\n

Unlike clamdscan, clamscan does not require a running clamd instance; instead, it creates a new scan engine and loads the virus database each time it is invoked.

\n

Reference: Scanning - ClamAV Documentation

\n

Let’s start by actually trying scans with both clamscan and clamdscan.

\n

The following commands were used to fetch an Eicar test file and verify detection.

\n
# Fetch the Eicar file\nwget https://secure.eicar.org/eicar.com\n\n# Detection test\nclamscan eicar.com\nclamdscan --fdpass eicar.com
\n

\n \n \n \n \n \n \n \n \n

\n

Note: when clamd is configured to run as the clamav user, clamd may be unable to access the file requested by clamdscan, causing the scan to fail with File path check failure: Permission denied. ERROR.

\n

For this reason, clamd was started in LocalSocket mode and scan requests were issued using the --fdpass option, which passes the file descriptor directly to clamd.

\n

\n \n debug' messages.\n --no-summary Disable summary at end of scanning\n --infected -i Only print infected files\n --suppress-ok-results -o Skip printing OK files\n --bell Sound bell on virus detection\n\n --tempdir=DIRECTORY Create temporary files in DIRECTORY\n --leave-temps[=yes/no(*)] Do not remove temporary files\n --gen-json[=yes/no(*)] Generate JSON metadata for the scanned file(s). For testing & development use ONLY.\n JSON will be printed if --debug is enabled.\n A JSON file will dropped to the temp directory if --leave-temps is enabled.\n --database=FILE/DIR -d FILE/DIR Load virus database from FILE or load all supported db files from DIR\n --official-db-only[=yes/no(*)] Only load official signatures\n --log=FILE -l FILE Save scan report to FILE\n --recursive[=yes/no(*)] -r Scan subdirectories recursively\n --allmatch[=yes/no(*)] -z Continue scanning within file after finding a match\n --cross-fs[=yes(*)/no] Scan files and directories on other filesystems\n --follow-dir-symlinks[=0/1(*)/2] Follow directory symlinks (0 = never, 1 = direct, 2 = always)\n --follow-file-symlinks[=0/1(*)/2] Follow file symlinks (0 = never, 1 = direct, 2 = always)\n --file-list=FILE -f FILE Scan files from FILE\n --remove[=yes/no(*)] Remove infected files. Be careful!\n --move=DIRECTORY Move infected files into DIRECTORY\n --copy=DIRECTORY Copy infected files into DIRECTORY\n --exclude=REGEX Don't scan file names matching REGEX\n --exclude-dir=REGEX Don't scan directories matching REGEX\n --include=REGEX Only scan file names matching REGEX\n --include-dir=REGEX Only scan directories matching REGEX\n\n --bytecode[=yes(*)/no] Load bytecode from the database\n --bytecode-unsigned[=yes/no(*)] Load unsigned bytecode\n **Caution**: You should NEVER run bytecode signatures from untrusted sources.\n Doing so may result in arbitrary code execution.\n --bytecode-timeout=N Set bytecode timeout (in milliseconds)\n --statistics[=none(*)/bytecode/pcre] Collect and print execution statistics\n --detect-pua[=yes/no(*)] Detect Possibly Unwanted Applications\n --exclude-pua=CAT Skip PUA sigs of category CAT\n --include-pua=CAT Load PUA sigs of category CAT\n --detect-structured[=yes/no(*)] Detect structured data (SSN, Credit Card)\n --structured-ssn-format=X SSN format (0=normal,1=stripped,2=both)\n --structured-ssn-count=N Min SSN count to generate a detect\n --structured-cc-count=N Min CC count to generate a detect\n --structured-cc-mode=X CC mode (0=credit debit and private label, 1=credit cards only\n --scan-mail[=yes(*)/no] Scan mail files\n --phishing-sigs[=yes(*)/no] Enable email signature-based phishing detection\n --phishing-scan-urls[=yes(*)/no] Enable URL signature-based phishing detection\n --heuristic-alerts[=yes(*)/no] Heuristic alerts\n --heuristic-scan-precedence[=yes/no(*)] Stop scanning as soon as a heuristic match is found\n --normalize[=yes(*)/no] Normalize html, script, and text files. Use normalize=no for yara compatibility\n --scan-pe[=yes(*)/no] Scan PE files\n --scan-elf[=yes(*)/no] Scan ELF files\n --scan-ole2[=yes(*)/no] Scan OLE2 containers\n --scan-pdf[=yes(*)/no] Scan PDF files\n --scan-swf[=yes(*)/no] Scan SWF files\n --scan-html[=yes(*)/no] Scan HTML files\n --scan-xmldocs[=yes(*)/no] Scan xml-based document files\n --scan-hwp3[=yes(*)/no] Scan HWP3 files\n --scan-archive[=yes(*)/no] Scan archive files (supported by libclamav)\n --alert-broken[=yes/no(*)] Alert on broken executable files (PE & ELF)\n --alert-broken-media[=yes/no(*)] Alert on broken graphics files (JPEG, TIFF, PNG, GIF)\n --alert-encrypted[=yes/no(*)] Alert on encrypted archives and documents\n --alert-encrypted-archive[=yes/no(*)] Alert on encrypted archives\n --alert-encrypted-doc[=yes/no(*)] Alert on encrypted documents\n --alert-macros[=yes/no(*)] Alert on OLE2 files containing VBA macros\n --alert-exceeds-max[=yes/no(*)] Alert on files that exceed max file size, max scan size, or max recursion limit\n --alert-phishing-ssl[=yes/no(*)] Alert on emails containing SSL mismatches in URLs\n --alert-phishing-cloak[=yes/no(*)] Alert on emails containing cloaked URLs\n --alert-partition-intersection[=yes/no(*)] Alert on raw DMG image files containing partition intersections\n --nocerts Disable authenticode certificate chain verification in PE files\n --dumpcerts Dump authenticode certificate chain in PE files\n\n --max-scantime=#n Scan time longer than this will be skipped and assumed clean (milliseconds)\n --max-filesize=#n Files larger than this will be skipped and assumed clean\n --max-scansize=#n The maximum amount of data to scan for each container file (**)\n --max-files=#n The maximum number of files to scan for each container file (**)\n --max-recursion=#n Maximum archive recursion level for container file (**)\n --max-dir-recursion=#n Maximum directory recursion level\n --max-embeddedpe=#n Maximum size file to check for embedded PE\n --max-htmlnormalize=#n Maximum size of HTML file to normalize\n --max-htmlnotags=#n Maximum size of normalized HTML file to scan\n --max-scriptnormalize=#n Maximum size of script file to normalize\n --max-ziptypercg=#n Maximum size zip to type reanalyze\n --max-partitions=#n Maximum number of partitions in disk image to be scanned\n --max-iconspe=#n Maximum number of icons in PE file to be scanned\n --max-rechwp3=#n Maximum recursive calls to HWP3 parsing function\n --pcre-match-limit=#n Maximum calls to the PCRE match function.\n --pcre-recmatch-limit=#n Maximum recursive calls to the PCRE match function.\n --pcre-max-filesize=#n Maximum size file to perform PCRE subsig matching.\n --disable-cache Disable caching and cache checks for hash sums of scanned files.\n\nPass in - as the filename for stdin.\n\n(*) Default scan settings\n(**) Certain files (e.g. documents, archives, etc.) may in turn contain other\n files inside. The above options ensure safe processing of this kind of data.\n

clamscan provides options to control output (such as --quiet, --infected, and --no-summary), to specify the virus database used by the scan engine, and to remove or quarantine detected files.

\n

Many additional options are available for finely controlling scan targets and exclusion criteria.

\n

clamdscan Options

\n

Because clamdscan performs file scanning as a client of a running clamd instance, unlike clamscan — which loads the engine and virus database fresh on each invocation — clamdscan has far fewer runtime scan options. The tradeoff is reduced overhead since the already-running clamd handles the actual scanning.

\n
$ clamdscan --help\n\n                      Clam AntiVirus: Daemon Client 0.104.0\n           By The ClamAV Team: https://www.clamav.net/about.html#credits\n           (C) 2021 Cisco Systems, Inc.\n\n    clamdscan [options] [file/directory/-]\n\n    --help              -h             Show this help\n    --version           -V             Print version number and exit\n    --verbose           -v             Be verbose\n    --quiet                            Be quiet, only output error messages\n    --stdout                           Write to stdout instead of stderr. Does not affect 'debug' messages.\n                                       (this help is always written to stdout)\n    --log=FILE          -l FILE        Save scan report in FILE\n    --file-list=FILE    -f FILE        Scan files from FILE\n    --ping              -p A[:I]       Ping clamd up to [A] times at optional interval [I] until it responds.\n    --wait              -w             Wait up to 30 seconds for clamd to start. Optionally use alongside --ping to set attempts [A] and interval [I] to check clamd.\n    --remove                           Remove infected files. Be careful!\n    --move=DIRECTORY                   Move infected files into DIRECTORY\n    --copy=DIRECTORY                   Copy infected files into DIRECTORY\n    --config-file=FILE                 Read configuration from FILE.\n    --allmatch            -z           Continue scanning within file after finding a match.\n    --multiscan           -m           Force MULTISCAN mode\n    --infected            -i           Only print infected files\n    --no-summary                       Disable summary at end of scanning\n    --reload                           Request clamd to reload virus database\n    --fdpass                           Pass filedescriptor to clamd (useful if clamd is running as a different user)\n    --stream                           Force streaming files to clamd (for debugging and unit testing)
\n

When using clamdscan, output control through --quiet, --infected, and --no-summary is available, similar to clamscan. Removing and quarantining detected files with --remove and --move is also supported.

\n

Scan Behavior of clamdscan

\n

In this section we trace the behavior when a scan is performed with clamdscan.

\n

In the main function of clamdscan, after parsing all runtime options, the following code is executed.

\n
date_start = time(NULL);\ngettimeofday(&t1, NULL);\n\nret = client(opts, &infected, &err);\noptfree(clamdopts);\n\n/* TODO: Implement STATUS in clamd */\nif (!optget(opts, \"no-summary\")->enabled) {\n    struct tm tmp;\n\n    date_end = time(NULL);\n    gettimeofday(&t2, NULL);\n    ds  = t2.tv_sec - t1.tv_sec;\n    dms = t2.tv_usec - t1.tv_usec;\n    ds -= (dms < 0) ? (1) : (0);\n    dms += (dms < 0) ? (1000000) : (0);\n    logg(\"\\n----------- SCAN SUMMARY -----------\\n\");\n    logg(\"Infected files: %d\\n\", infected);\n    if (err)\n        logg(\"Total errors: %d\\n\", err);\n    if (notremoved) {\n        logg(\"Not removed: %d\\n\", notremoved);\n    }\n    if (notmoved) {\n        logg(\"Not moved: %d\\n\", notmoved);\n    }\n    logg(\"Time: %d.%3.3d sec (%d m %d s)\\n\", ds, dms / 1000, ds / 60, ds % 60);\n\n#ifdef _WIN32\n    if (0 != localtime_s(&tmp, &date_start)) {\n#else\n    if (!localtime_r(&date_start, &tmp)) {\n#endif\n        logg(\"!Failed to get local time for Start Date.\\n\");\n    }\n    strftime(buffer, sizeof(buffer), \"%Y:%m:%d %H:%M:%S\", &tmp);\n    logg(\"Start Date: %s\\n\", buffer);\n\n#ifdef _WIN32\n    if (0 != localtime_s(&tmp, &date_end)) {\n#else\n    if (!localtime_r(&date_end, &tmp)) {\n#endif\n        logg(\"!Failed to get local time for End Date.\\n\");\n    }\n    strftime(buffer, sizeof(buffer), \"%Y:%m:%d %H:%M:%S\", &tmp);\n    logg(\"End Date:   %s\\n\", buffer);\n}
\n

Reference: clamav/clamdscan/clamdscan.c at rel/0.104 · kash1064/clamav

\n

Executing the client Function

\n

First, the client function is called with a variable holding a pointer to the parsed options list.

\n

The client function receives the list via const struct optstruct *opts, extracts each option and configuration value, performs the scan of the target file, and returns the result.

\n
struct optstruct {\n    char *name;\n    char *cmd;\n    char *strarg;\n    long long numarg;\n    int enabled;\n    int active;\n    int flags;\n    int idx;\n    struct optstruct *nextarg;\n    struct optstruct *next;\n\n    char **filename; /* cmdline */\n};\n\nint ds, dms, ret, infected = 0, err = 0;\nstruct optstruct *opts;\n\nret = client(opts, &infected, &err);
\n

The client function is implemented in clamdscan/client.c as follows.

\n
int client(const struct optstruct *opts, int *infected, int *err)\n{\n    int remote, scantype, session = 0, errors = 0, scandash = 0, maxrec, flags = 0;\n    const char *fname;\n\n    if (optget(opts, \"wait\")->enabled) {\n        int16_t ping_result = ping_clamd(opts);\n        switch (ping_result) {\n            case 0:\n                break;\n            case 1:\n                return (int)CL_ETIMEOUT;\n            default:\n                return (int)CL_ERROR;\n        }\n    }\n\n    scandash = (opts->filename && opts->filename[0] && !strcmp(opts->filename[0], \"-\") && !optget(opts, \"file-list\")->enabled && !opts->filename[1]);\n    remote   = isremote(opts) | optget(opts, \"stream\")->enabled;\n#ifdef HAVE_FD_PASSING\n    if (!remote && optget(clamdopts, \"LocalSocket\")->enabled && (optget(opts, \"fdpass\")->enabled || scandash)) {\n        scantype = FILDES;\n        session  = optget(opts, \"multiscan\")->enabled;\n    } else\n#endif\n        if (remote || scandash) {\n        scantype = STREAM;\n        session  = optget(opts, \"multiscan\")->enabled;\n    } else if (optget(opts, \"multiscan\")->enabled)\n        scantype = MULTI;\n    else if (optget(opts, \"allmatch\")->enabled)\n        scantype = ALLMATCH;\n    else\n        scantype = CONT;\n\n    maxrec    = optget(clamdopts, \"MaxDirectoryRecursion\")->numarg;\n    maxstream = optget(clamdopts, \"StreamMaxLength\")->numarg;\n    if (optget(clamdopts, \"FollowDirectorySymlinks\")->enabled)\n        flags |= CLI_FTW_FOLLOW_DIR_SYMLINK;\n    if (optget(clamdopts, \"FollowFileSymlinks\")->enabled)\n        flags |= CLI_FTW_FOLLOW_FILE_SYMLINK;\n    flags |= CLI_FTW_TRIM_SLASHES;\n\n    *infected = 0;\n\n    if (scandash) {\n        int sockd, ret;\n        STATBUF sb;\n        if (FSTAT(0, &sb) < 0) {\n            logg(\"client.c: fstat failed for file name \\\"%s\\\", with %s\\n.\",\n                 opts->filename[0], strerror(errno));\n            return 2;\n        }\n        if ((sb.st_mode & S_IFMT) != S_IFREG) scantype = STREAM;\n        if ((sockd = dconnect()) >= 0 && (ret = dsresult(sockd, scantype, NULL, &ret, NULL)) >= 0)\n            *infected = ret;\n        else\n            errors = 1;\n        if (sockd >= 0) closesocket(sockd);\n    } else if (opts->filename || optget(opts, \"file-list\")->enabled) {\n        if (opts->filename && optget(opts, \"file-list\")->enabled)\n            logg(\"^Only scanning files from --file-list (files passed at cmdline are ignored)\\n\");\n\n        while ((fname = filelist(opts, NULL))) {\n            if (!strcmp(fname, \"-\")) {\n                logg(\"!Scanning from standard input requires \\\"-\\\" to be the only file argument\\n\");\n                continue;\n            }\n            errors += client_scan(fname, scantype, infected, err, maxrec, session, flags);\n            /* this may be too strict\n    if(errors >= 10) {\nlogg(\"!Too many errors\\n\");\nbreak;\n    }\n    */\n        }\n    } else {\n        errors = client_scan(\"\", scantype, infected, err, maxrec, session, flags);\n    }\n    return *infected ? 1 : (errors ? 2 : 0);\n}
\n

Reference: clamav/clamdscan/client.c at rel/0.104 · kash1064/clamav

\n

Setting the scantype

\n

Inside this function, two variables, scandash and remote, are declared first.

\n
scandash = (opts->filename && opts->filename[0] && !strcmp(opts->filename[0], \"-\") && !optget(opts, \"file-list\")->enabled && !opts->filename[1]);\n\nremote = isremote(opts) | optget(opts, \"stream\")->enabled;
\n

scandash stores the AND of (opts->filename && opts->filename[0] && !strcmp(opts->filename[0], \"-\") and !optget(opts, \"file-list\")->enabled && !opts->filename[1]) for the received opts.

\n

This appears to be a check for whether the file-list option is disabled and the input uses - (stdin).

\n

Reference: linux - What’s the magic of ”-” (a dash) in command-line parameters? - Stack Overflow

\n

remote = isremote(opts) | optget(opts, \"stream\")->enabled; checks whether clamdscan is running remotely or whether the Stream option is enabled.

\n

If either the scandash or remote flag is true, scantype is set to STREAM.

\n

In this case, however, we are using a LocalSocket and the --fdpass option, so scantype becomes FILDES and this branch is skipped.

\n
#ifdef HAVE_FD_PASSING\n    if (!remote && optget(clamdopts, \"LocalSocket\")->enabled && (optget(opts, \"fdpass\")->enabled || scandash)) {\n        scantype = FILDES;\n        session  = optget(opts, \"multiscan\")->enabled;\n    } else\n#endif\n    if (remote || scandash) {\n        scantype = STREAM;\n        session  = optget(opts, \"multiscan\")->enabled;\n    } else if (optget(opts, \"multiscan\")->enabled)\n        scantype = MULTI;\n    else if (optget(opts, \"allmatch\")->enabled)\n        scantype = ALLMATCH;\n    else\n        scantype = CONT;
\n

Calling the Scan Function

\n

When scandash is false (as in this case), client_scan is called directly with the scantype and other variables.

\n
*infected = 0;\n\nif (scandash) {\n    /* omitted */\n} else {\n    errors = client_scan(\"\", scantype, infected, err, maxrec, session, flags);   \n}
\n

Inside client_scan, the absolute path of the target file (file) is resolved.

\n

Based on the received session value (session = optget(opts, \"multiscan\")->enabled;), either serial_client_scan or parallel_client_scan is then called.

\n
/* Recursively scans a path with the given scantype\n * Returns non zero for serious errors, zero otherwise */\nstatic int client_scan(const char *file, int scantype, int *infected, int *err, int maxlevel, int session, int flags)\n{\n    int ret;\n    char *real_path = NULL;\n    char *fullpath  = NULL;\n\n    /* Convert relative path to fullpath */\n    fullpath = makeabs(file);\n\n    /* Convert fullpath to the real path (evaluating symlinks and . and ..).\n       Doing this early on will ensure that the scan results will appear consistent\n       across regular scans, --fdpass scans, and --stream scans. */\n    if (CL_SUCCESS != cli_realpath(fullpath, &real_path)) {\n        logg(\"*client_scan: Failed to determine real filename of %s.\\n\", fullpath);\n    } else {\n        free(fullpath);\n        fullpath = real_path;\n    }\n\n    if (!fullpath)\n        return 0;\n    if (!session)\n        ret = serial_client_scan(fullpath, scantype, infected, err, maxlevel, flags);\n    else\n        ret = parallel_client_scan(fullpath, scantype, infected, err, maxlevel, flags);\n    free(fullpath);\n    return ret;\n}
\n

When the multiscan option is not used, the file path, scantype, and other information are passed to serial_client_scan.

\n
/* Non-IDSESSION handler\n * Returns non zero for serious errors, zero otherwise */\nint serial_client_scan(char *file, int scantype, int *infected, int *err, int maxlevel, int flags)\n{\n    struct cli_ftw_cbdata data;\n    struct client_serial_data cdata;\n    int ftw;\n\n    cdata.infected = 0;\n    cdata.files    = 0;\n    cdata.errors   = 0;\n    cdata.printok  = printinfected ^ 1;\n    cdata.scantype = scantype;\n    data.data      = &cdata;\n\n    ftw = cli_ftw(file, flags, maxlevel ? maxlevel : INT_MAX, serial_callback, &data, ftw_chkpath);\n    *infected += cdata.infected;\n    *err += cdata.errors;\n\n    if (!cdata.errors && (ftw == CL_SUCCESS || ftw == CL_BREAK)) {\n        if (cdata.printok)\n            logg(\"~%s: OK\\n\", file);\n        return 0;\n    } else if (!cdata.files) {\n        logg(\"~%s: No files scanned\\n\", file);\n        return 0;\n    }\n    return 1;\n}
\n

A debugger confirms that char *file holds the full path of the target file at this point.

\n

\n \n \n \n \n \n \n \n \n

\n

Inside this function, a client_serial_data struct variable cdata is initialized, stored into the data member of a cli_ftw_cbdata struct variable data, and then cli_ftw is called with the file information and other arguments.

\n
/* wrap void*, so that we don't mix it with some other pointer */\nstruct cli_ftw_cbdata {\n    void *data;\n};\n\n/* Used by serial_callback() */\nstruct client_serial_data {\n    int infected;\n    int scantype;\n    int printok;\n    int files;\n    int errors;\n};\n\nstruct cli_ftw_cbdata data;\nstruct client_serial_data cdata;\nint ftw;\n\ncdata.infected = 0;\ncdata.files    = 0;\ncdata.errors   = 0;\ncdata.printok  = printinfected ^ 1;\ncdata.scantype = scantype;\ndata.data      = &cdata;\n\nftw = cli_ftw(file, flags, maxlevel ? maxlevel : INT_MAX, serial_callback, &data, ftw_chkpath);\n*infected += cdata.infected;\n*err += cdata.errors;
\n

Executing the cli_ftw Function

\n

cli_ftw is a function implemented in others_common.c in libclamav and performs roughly the following operations.

\n
    \n
  1. handle_filetype retrieves the file type and checks whether it should be skipped (if the type is ft_skipped_link or ft_skipped_special, the entry appears to be skipped).
    2. \n
  2. ft_skipped checks whether to skip the entry (it appears to be skipped when ft != ft_regular && ft != ft_directory is true).
    3. \n
  3. For directories, the callback function (in this case serial_callback) is called directly; for files, it is called via handle_entry.
    4. \n
\n

Reference: clamav/libclamav/others_common.c at rel/0.104 · kash1064/clamav

\n

As described above, when clamdscan is invoked with a specific file, the full path of the target file is stored in the filename member of a dirent_data struct variable entry, and then handle_entry is called.

\n
/*\n * Now call handle_entry() to either call the callback for files,\n * or recurse deeper into the file tree walk.\n * TODO: Recursion is bad, this whole thing should be iterative\n */\nif (entry.is_dir) {\n    entry.dirname = path;\n} else {\n    /* Allocate the filename for the callback function within the handle_entry function. TODO: this FTW code is spaghetti, refactor. */\n    filename_for_handleentry = cli_strdup(path);\n    if (NULL == filename_for_handleentry) {\n        goto done;\n    }\n\n    entry.filename = filename_for_handleentry;\n}\nstatus = handle_entry(&entry, flags, maxdepth, callback, data, pathchk);
\n

Debugging the call to handle_entry confirms that the filename member holds the full path of eicar.com.

\n
> print *(struct dirent_data *)entry\n\n$3 = {\n  filename = 0x55555559b0c0 \"/home/kash1064/Downloads/eicar.com\",\n  dirname = 0x0,\n  statbuf = <optimized out>,\n  ino = <optimized out>,\n  is_dir = <optimized out>\n}
\n

handle_entry simply calls the callback function (in this case serial_callback).

\n

The fourth argument cli_ftw_reason receives visit_file.

\n
static int handle_entry(struct dirent_data *entry, int flags, int maxdepth, cli_ftw_cb callback, struct cli_ftw_cbdata *data, cli_ftw_pathchk pathchk)\n{\n    if (!entry->is_dir) {\n        return callback(entry->statbuf, entry->filename, entry->filename, visit_file, data);\n    } else {\n        return cli_ftw_dir(entry->dirname, flags, maxdepth, callback, data, pathchk);\n    }\n}
\n

Calling serial_callback

\n

serial_callback is implemented in clamdscan/proto.c and was passed as the callback function when cli_ftw was called from serial_client_scan.

\n

Reference: clamav/clamdscan/proto.c at rel/0.104 · kash1064/clamav

\n

After performing several checks, dconnect connects to the clamd daemon, and dsresult issues a scan request over the obtained socket.

\n

dsresult returns the number of infected files as an integer.

\n
if ((sockd = dconnect()) < 0) {\n    c->errors++;\n    goto done;\n}\nret = dsresult(sockd, c->scantype, f, &c->printok, &c->errors);\nclosesocket(sockd);\nif (ret < 0) {\n    c->errors++;\n    goto done;\n}\nc->infected += ret;\nif (reason == visit_directory_toplev) {\n    status = CL_BREAK;\n    goto done;\n}
\n

Debugging the dsresult call confirms that the first argument sockd is 3 and the third argument filename holds the path of the target file.

\n

\n \n \n \n \n \n \n \n \n

\n

sockd is the file descriptor of the socket obtained inside dconnect via sockd = socket(AF_UNIX, SOCK_STREAM, 0) when using LocalSocket mode.

\n

This can be confirmed by running ls -la /proc/$(pgrep clamdscan)/fd/ or lsof -p $(pgrep clamdscan) to verify that clamdscan has the socket open using that file descriptor.

\n

\n \n ;\n\nif (-1 == (linksz = readlink(link, fname, PATH_MAX - 1))) {\n cli_dbgmsg(\"cli_get_filepath_from_filedesc: Failed to resolve filename for descriptor %d (%s)\\n\", desc, link);\n status = CL_EOPEN;\n goto done;\n}\n

The obtained file path is then saved as evaluated_filepath and assigned to the filepath argument received by the function.

\n
cli_dbgmsg(\"cli_get_filepath_from_filedesc: File path for fd [%d] is: %s\\n\", desc, evaluated_filepath);\nstatus    = CL_SUCCESS;\n*filepath = evaluated_filepath;
\n

Tracing this function’s return in the debugger revealed that it is called from the scanfd function in scanner.c.

\n
/* Try and get the real filename, for logging purposes */\nif (!stream) {\n    if (CL_SUCCESS != cli_get_filepath_from_filedesc(fd, &filepath)) {\n        logg(\"*%s: Unable to determine the filepath given the file descriptor.\\n\", fdstr);\n    } else {\n        log_filename = filepath;\n    }\n}
\n

Reference: clamav/clamd/scanner.c at rel/0.104 · kash1064/clamav

\n

Executing the Scan Callback Function

\n

The file path obtained from the file descriptor is saved as log_filename and then passed to the cl_scandesc_callback function.

\n
thrmgr_setactivetask(fdstr, NULL);\ncontext.filename = fdstr;\ncontext.virsize  = 0;\ncontext.scandata = NULL;\nret              = cl_scandesc_callback(fd, log_filename, &virname, scanned, engine, options, &context);\nthrmgr_setactivetask(NULL, NULL);\n\nif (thrmgr_group_need_terminate(conn->group)) {\n    logg(\"*Client disconnected while scanjob was active\\n\");\n    ret = ret == CL_ETIMEOUT ? ret : CL_BREAK;\n    goto done;\n}
\n

In the code above, thrmgr_setactivetask registers fdstr and context is initialized before calling cl_scandesc_callback. The function then receives the file descriptor and file path to perform the actual scan.

\n
/**\n * @brief Scan a file, given a file descriptor.\n *\n * This callback variant allows the caller to provide a context structure that caller provided callback functions can interpret.\n *\n * @param desc              File descriptor of an open file. The caller must provide this or the map.\n * @param filename          (optional) Filepath of the open file descriptor or file map.\n * @param[out] virname      Will be set to a statically allocated (i.e. needs not be freed) signature name if the scan matches against a signature.\n * @param[out] scanned      The number of bytes scanned.\n * @param engine            The scanning engine.\n * @param scanoptions       Scanning options.\n * @param[in,out] context   An opaque context structure allowing the caller to record details about the sample being scanned.\n * @return cl_error_t       CL_CLEAN, CL_VIRUS, or an error code if an error occured during the scan.\n */\nextern cl_error_t cl_scandesc_callback(int desc, const char *filename, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options *scanoptions, void *context);
\n

cl_scandesc_callback is implemented in libclamav’s scanner.c.

\n

Inside this function, cli_basename extracts the filename from the received file path as filename_base, and fmap maps the file as a fmap_t structure used for ClamAV file scanning.

\n
if (NULL != filename) {\n    (void)cli_basename(filename, strlen(filename), &filename_base);\n}\n\nif (NULL == (map = fmap(desc, 0, sb.st_size, filename_base))) {\n    cli_errmsg(\"CRITICAL: fmap() failed\\n\");\n    status = CL_EMEM;\n    goto done;\n}\n\nstatus = scan_common(map, filename, virname, scanned, engine, scanoptions, context);
\n

Reference: clamav/libclamav/scanners.c at rel/0.104 · kash1064/clamav

\n

The mapped structure is passed together with the file path and other information to scan_common, where the actual virus scan is performed.

\n

About the fmap_t Structure

\n

ClamAV uses the cl_fmap_t (fmap_t) data structure to perform memory mapping for efficient file scanning.

\n
struct cl_fmap;\ntypedef cl_fmap_t fmap_t;\n\nstruct cl_fmap {\n    /* handle interface */\n    void *handle;\n    clcb_pread pread_cb;\n\n    /* internal */\n    time_t mtime;\n    uint64_t pages;\n    uint64_t pgsz;\n    uint64_t paged;\n    uint16_t aging;\n    uint16_t dont_cache_flag;\n    uint16_t handle_is_fd;\n\n    /* memory interface */\n    const void *data;\n\n    /* common interface */\n    size_t offset;        /* file offset */\n    size_t nested_offset; /* buffer offset for nested scan*/\n    size_t real_len;      /* amount of data mapped from file, starting at offset */\n    size_t len;           /* length of data accessible via current fmap */\n\n    /* real_len = nested_offset + len\n     * file_offset = offset + nested_offset + need_offset\n     * maximum offset, length accessible via fmap API: len\n     * offset in cached buffer: nested_offset + need_offset\n     *\n     * This allows scanning a portion of an already mapped file without dumping\n     * to disk and remapping (for uncompressed archives for example) */\n\n    /* vtable for implementation */\n    void (*unmap)(fmap_t *);\n    const void *(*need)(fmap_t *, size_t at, size_t len, int lock);\n    const void *(*need_offstr)(fmap_t *, size_t at, size_t len_hint);\n    const void *(*gets)(fmap_t *, char *dst, size_t *at, size_t max_len);\n    void (*unneed_off)(fmap_t *, size_t at, size_t len);\n#ifdef _WIN32\n    HANDLE fh;\n    HANDLE mh;\n#endif\n    unsigned char maphash[16];\n    uint64_t *bitmap;\n    char *name;\n};
\n

File Mapping Process

\n

For a clamdscan request such as this one, the scan target file is mapped into memory as a fmap_t structure by the fmap_check_empty function.

\n

Reference: clamav/libclamav/fmap.c at rel/0.104 · kash1064/clamav

\n
fmap_t *fmap_check_empty(int fd, off_t offset, size_t len, int *empty, const char *name)\n{\n    STATBUF st;\n    fmap_t *m = NULL;\n\n    *empty = 0;\n    if (FSTAT(fd, &st)) {\n        cli_warnmsg(\"fmap: fstat failed\\n\");\n        return NULL;\n    }\n\n    if (!len) len = st.st_size - offset; /* bound checked later */\n    if (!len) {\n        cli_dbgmsg(\"fmap: attempted void mapping\\n\");\n        *empty = 1;\n        return NULL;\n    }\n    if (!CLI_ISCONTAINED(0, st.st_size, offset, len)) {\n        cli_warnmsg(\"fmap: attempted oof mapping\\n\");\n        return NULL;\n    }\n    m = cl_fmap_open_handle((void *)(ssize_t)fd, offset, len, pread_cb, 1);\n    if (!m)\n        return NULL;\n    m->mtime = st.st_mtime;\n\n    if (NULL != name) {\n        m->name = cli_strdup(name);\n        if (NULL == m->name) {\n            funmap(m);\n            return NULL;\n        }\n    }\n\n    return m;\n}
\n

This function first uses fstat to store the state of the received file descriptor into a STATBUF struct (stat or stat64) variable st.

\n
STATBUF st;\nfmap_t *m = NULL;\n\n*empty = 0;\nif (FSTAT(fd, &st)) {\n    cli_warnmsg(\"fmap: fstat failed\\n\");\n    return NULL;\n}
\n

For the eicar.com file being scanned, fstat wrote the following information into st.

\n

\n \n \n \n \n \n \n \n \n

\n

This matches the output of the stat eicar.com command, confirming that the stat information was retrieved correctly.

\n

\n \n \n \n \n \n \n \n \n

\n

After validating the mapping range of the file, cl_fmap_open_handle is called with the file descriptor and other information.

\n

Inside cl_fmap_open_handle, memory is allocated by cli_calloc (which wraps calloc) and the resulting fmap_t struct region m is populated with file information and pointers to several callbacks.

\n
m->handle          = handle;\nm->pread_cb        = pread_cb;\nm->aging           = use_aging;\nm->offset          = offset;\nm->nested_offset   = 0;\nm->len             = len; /* m->nested_offset + m->len = m->real_len */\nm->real_len        = len;\nm->pages           = pages;\nm->pgsz            = pgsz;\nm->paged           = 0;\nm->dont_cache_flag = 0;\nm->unmap           = unmap_handle;\nm->need            = handle_need;\nm->need_offstr     = handle_need_offstr;\nm->gets            = handle_gets;\nm->unneed_off      = handle_unneed_off;\nm->handle_is_fd    = 1;\n\n/* Calculate the fmap hash to be used by the FP check later */\nif (CL_SUCCESS != fmap_get_MD5(hash, m)) {\n    cli_warnmsg(\"fmap: failed to get MD5\\n\");\n    goto done;\n}\nmemcpy(m->maphash, hash, 16);
\n

fmap_get_MD5 then computes the MD5 hash using the allocated fmap_t structure.

\n

After this processing, the fmap_t structure is confirmed to have the MD5 hash of eicar.com — 44d88612fea8a8f36de82e1278abb02f — correctly written to it.

\n

\n \n \n \n \n \n \n \n \n

\n

Furthermore, inside fmap_get_MD5, the file data read via m->need (handle_need) — called through fmap_need_off_once — can be confirmed to be stored in m->data.

\n

\n \n \n \n \n \n \n \n \n

\n

Tracing the Scanner Processing

\n

Up to this point, the scan request from clamdscan triggered cl_scandesc_callback, inside which the fmap_check_empty function (called from fmap) mapped the scan target file into memory as a fmap_t structure.

\n

Next, scan_common is called from cl_scandesc_callback with this mapped file information as an argument.

\n
/**\n * @brief   The main function to initiate a scan of an fmap.\n *\n * @param map               File map.\n * @param filepath          (optional, recommended) filepath of the open file descriptor or file map.\n * @param[out] virname      Will be set to a statically allocated (i.e. needs not be freed) signature name if the scan matches against a signature.\n * @param[out] scanned      The number of bytes scanned.\n * @param engine            The scanning engine.\n * @param scanoptions       Scanning options.\n * @param[inout] context    An opaque context structure allowing the caller to record details about the sample being scanned.\n * @return int              CL_CLEAN, CL_VIRUS, or an error code if an error occured during the scan.\n */\nstatic cl_error_t scan_common(cl_fmap_t *map, const char *filepath, const char **virname, unsigned long int *scanned, const struct cl_engine *engine, struct cl_scan_options *scanoptions, void *context)
\n

Reference: clamav/libclamav/scanners.c at main · Cisco-Talos/clamav

\n

Arguments of the scan_common Function

\n

Among the arguments passed to scan_common, the first argument cl_fmap_t *map contains the fmap structure mapped into memory as described in the previous section.

\n

The second argument filepath holds the full path of the scan target file (/home/kash1064/Downloads/eicar.com).

\n

The fifth argument const struct cl_engine *engine contains the configuration of the cl_engine structure used for scanning.

\n

This structure is defined as follows.

\n

Reference: clamav/libclamav/others.h at main · Cisco-Talos/clamav

\n
struct cl_engine {\n    uint32_t refcount; /* reference counter */\n    uint32_t sdb;\n    uint32_t dboptions;\n    uint32_t dbversion[2];\n    uint32_t ac_only;\n    uint32_t ac_mindepth;\n    uint32_t ac_maxdepth;\n    char *tmpdir;\n    uint32_t keeptmp;\n    uint64_t engine_options;\n\n    /* Limits */\n    uint32_t maxscantime; /* Time limit (in milliseconds) */\n    uint64_t maxscansize; /* during the scanning of archives this size\n           * will never be exceeded\n           */\n    uint64_t maxfilesize; /* compressed files will only be decompressed\n           * and scanned up to this size\n           */\n    uint32_t maxreclevel; /* maximum recursion level for archives */\n    uint32_t maxfiles;    /* maximum number of files to be scanned\n           * within a single archive\n           */\n    /* This is for structured data detection.  You can set the minimum\n     * number of occurrences of an CC# or SSN before the system will\n     * generate a notification.\n     */\n    uint32_t min_cc_count;\n    uint32_t min_ssn_count;\n\n    /* Roots table */\n    struct cli_matcher **root;\n\n    /* hash matcher for standard MD5 sigs */\n    struct cli_matcher *hm_hdb;\n    /* hash matcher for MD5 sigs for PE sections */\n    struct cli_matcher *hm_mdb;\n    /* hash matcher for MD5 sigs for PE import tables */\n    struct cli_matcher *hm_imp;\n    /* hash matcher for allow list db */\n    struct cli_matcher *hm_fp;\n\n    /* Container metadata */\n    struct cli_cdb *cdb;\n\n    /* Phishing .pdb and .wdb databases*/\n    struct regex_matcher *allow_list_matcher;\n    struct regex_matcher *domain_list_matcher;\n    struct phishcheck *phishcheck;\n\n    /* Dynamic configuration */\n    struct cli_dconf *dconf;\n\n    /* Filetype definitions */\n    struct cli_ftype *ftypes;\n    struct cli_ftype *ptypes;\n\n    /* Container password storage */\n    struct cli_pwdb **pwdbs;\n\n    /* Pre-loading test matcher\n     * Test for presence before using; cleared on engine compile.\n     */\n    struct cli_matcher *test_root;\n\n    /* Ignored signatures */\n    struct cli_matcher *ignored;\n\n    /* PUA categories (to be included or excluded) */\n    char *pua_cats;\n\n    /* Icon reference storage */\n    struct icon_matcher *iconcheck;\n\n    /* Negative cache storage */\n    struct CACHE *cache;\n\n    /* Database information from .info files */\n    struct cli_dbinfo *dbinfo;\n\n    /* Signature counting, for progress callbacks */\n    size_t num_total_signatures;\n\n    /* Used for memory pools */\n    mpool_t *mempool;\n\n    /* crtmgr stuff */\n    crtmgr cmgr;\n\n    /* Callback(s) */\n    clcb_pre_cache cb_pre_cache;\n    clcb_pre_scan cb_pre_scan;\n    clcb_post_scan cb_post_scan;\n    clcb_virus_found cb_virus_found;\n    clcb_sigload cb_sigload;\n    void *cb_sigload_ctx;\n    clcb_hash cb_hash;\n    clcb_meta cb_meta;\n    clcb_file_props cb_file_props;\n    clcb_progress cb_sigload_progress;\n    void *cb_sigload_progress_ctx;\n    clcb_progress cb_engine_compile_progress;\n    void *cb_engine_compile_progress_ctx;\n    clcb_progress cb_engine_free_progress;\n    void *cb_engine_free_progress_ctx;\n\n    /* Used for bytecode */\n    struct cli_all_bc bcs;\n    unsigned *hooks[_BC_LAST_HOOK - _BC_START_HOOKS];\n    unsigned hooks_cnt[_BC_LAST_HOOK - _BC_START_HOOKS];\n    unsigned hook_lsig_ids;\n    enum bytecode_security bytecode_security;\n    uint32_t bytecode_timeout;\n    enum bytecode_mode bytecode_mode;\n\n    /* Engine max settings */\n    uint64_t maxembeddedpe;      /* max size to scan MSEXE for PE */\n    uint64_t maxhtmlnormalize;   /* max size to normalize HTML */\n    uint64_t maxhtmlnotags;      /* max size for scanning normalized HTML */\n    uint64_t maxscriptnormalize; /* max size to normalize scripts */\n    uint64_t maxziptypercg;      /* max size to re-do zip filetype */\n\n    /* Statistics/intelligence gathering */\n    void *stats_data;\n    clcb_stats_add_sample cb_stats_add_sample;\n    clcb_stats_remove_sample cb_stats_remove_sample;\n    clcb_stats_decrement_count cb_stats_decrement_count;\n    clcb_stats_submit cb_stats_submit;\n    clcb_stats_flush cb_stats_flush;\n    clcb_stats_get_num cb_stats_get_num;\n    clcb_stats_get_size cb_stats_get_size;\n    clcb_stats_get_hostid cb_stats_get_hostid;\n\n    /* Raw disk image max settings */\n    uint32_t maxpartitions; /* max number of partitions to scan in a disk image */\n\n    /* Engine max settings */\n    uint32_t maxiconspe; /* max number of icons to scan for PE */\n    uint32_t maxrechwp3; /* max recursive calls for HWP3 parsing */\n\n    /* PCRE matching limitations */\n    uint64_t pcre_match_limit;\n    uint64_t pcre_recmatch_limit;\n    uint64_t pcre_max_filesize;\n\n#ifdef HAVE_YARA\n    /* YARA */\n    struct _yara_global *yara_global;\n#endif\n};
\n

The sixth argument specifies scan options via the cl_scan_options structure.

\n
/*** scan options ***/\nstruct cl_scan_options {\n    uint32_t general;\n    uint32_t parse;\n    uint32_t heuristic;\n    uint32_t mail;\n    uint32_t dev;\n};
\n

The options set during this clamdscan invocation were as follows.

\n

\n \n \n \n \n \n \n \n \n

\n

These arguments received by scan_common are subsequently saved as members of the cli_ctx struct variable ctx after it is initialized.

\n
memset(&ctx, '\\0', sizeof(cli_ctx));\nctx.engine  = engine;\nctx.virname = virname;\nctx.scanned = scanned;\nctx.options = malloc(sizeof(struct cl_scan_options));\nmemcpy(ctx.options, scanoptions, sizeof(struct cl_scan_options));\nctx.found_possibly_unwanted = 0;\nctx.containers              = cli_calloc(sizeof(cli_ctx_container), ctx.engine->maxreclevel + 2);\nif (!ctx.containers) {\n    rc = CL_EMEM;\n    goto done;\n}\ncli_set_container(&ctx, CL_TYPE_ANY, 0);\nctx.dconf  = (struct cli_dconf *)engine->dconf;\nctx.cb_ctx = context;\nfmap_head  = cli_calloc(sizeof(fmap_t *), ctx.engine->maxreclevel + 3);\nif (!fmap_head) {\n    rc = CL_EMEM;\n    goto done;\n}\nif (!(ctx.hook_lsig_matches = cli_bitset_init())) {\n    rc = CL_EMEM;\n    goto done;\n}\n\n/*\n * The first fmap in ctx.fmap must be NULL so we can fmap-- while not NULL.\n * But we need an fmap to be set so we can append viruses or report the\n * fmap's file descriptor in the virus found callback (like for deferred\n * low-seveerity alerts).\n */\nctx.fmap  = fmap_head + 1;\n*ctx.fmap = map;
\n

This structure contains the file path of the scan target and various other status information, as defined below.

\n

The structure is ultimately passed from scan_common to the actual scan function cli_magic_scan via cli_magic_scan(&ctx, CL_TYPE_ANY);.

\n
/* internal clamav context */\ntypedef struct cli_ctx_tag {\n    char *target_filepath;    /**< (optional) The filepath of the original scan target */\n    const char *sub_filepath; /**< (optional) The filepath of the current file being parsed. May be a temp file. */\n    char *sub_tmpdir;         /**< The directory to store tmp files at this recursion depth. */\n    const char **virname;\n    unsigned int num_viruses;\n    unsigned long int *scanned;\n    const struct cli_matcher *root;\n    const struct cl_engine *engine;\n    unsigned long scansize;\n    struct cl_scan_options *options;\n    unsigned int recursion;\n    unsigned int scannedfiles;\n    unsigned int found_possibly_unwanted;\n    unsigned int corrupted_input;\n    unsigned int img_validate;\n    cli_ctx_container *containers; /* set container type after recurse */\n    unsigned char handlertype_hash[16];\n    struct cli_dconf *dconf;\n    fmap_t **fmap; /* pointer to current fmap in an allocated array, incremented with recursion depth */\n    bitset_t *hook_lsig_matches;\n    void *cb_ctx;\n    cli_events_t *perf;\n#ifdef HAVE__INTERNAL__SHA_COLLECT\n    int sha_collect;\n#endif\n#ifdef HAVE_JSON\n    struct json_object *properties;\n    struct json_object *wrkproperty;\n#endif\n    struct timeval time_limit;\n    int limit_exceeded;\n} cli_ctx;
\n

Dumping ctx at the time cli_magic_scan is called reveals the following information.

\n

\n \n .\n# Default: no\nDisableCache yes\n

With this change, repeating the clamdscan scan request skips the cacheset lookup in cache_check, and cli_magic_scan continues to subsequent processing.

\n

After several operations, cli_magic_scan calls various scan functions corresponding to the type of the scan target file.

\n

Since the Eicar file is classified as CL_TYPE_TEXT_ASCII, a check via cli_scan_structured(ctx); is performed.

\n
ctx->recursion++;\nperf_nested_start(ctx, PERFT_CONTAINER, PERFT_SCAN);\n/* set current level as container AFTER recursing */\ncli_set_container(ctx, type, (*ctx->fmap)->len);\nswitch (type) {\n    case CL_TYPE_IGNORED:\n        break;\n    /* omitted */\n    case CL_TYPE_BINARY_DATA:\n    case CL_TYPE_TEXT_UTF16BE:\n        if (SCAN_HEURISTICS && (DCONF_OTHER & OTHER_CONF_MYDOOMLOG))\n            ret = cli_check_mydoom_log(ctx);\n        break;\n\n    case CL_TYPE_TEXT_ASCII:\n        if (SCAN_HEURISTIC_STRUCTURED && (DCONF_OTHER & OTHER_CONF_DLP))\n            /* TODO: consider calling this from cli_scanscript() for\n             * a normalised text\n             */\n\n            ret = cli_scan_structured(ctx);\n        break;\n\n    default:\n        break;\n}\nperf_nested_stop(ctx, PERFT_CONTAINER, PERFT_SCAN);\nctx->recursion--;
\n

However, this function is used for DLP purposes to check whether credit card numbers or SSNs are present, so it can be ignored for this case.

\n

Continuing to trace cli_magic_scan, we find that it ultimately calls scanraw(ctx, type, typercg, &dettype, (ctx->engine->engine_options & ENGINE_OPTIONS_DISABLE_CACHE) ? NULL : hash);.

\n
/* CL_TYPE_HTML: raw HTML files are not scanned, unless safety measure activated via DCONF */\nif (type != CL_TYPE_IGNORED && (type != CL_TYPE_HTML || !(SCAN_PARSE_HTML) || !(DCONF_DOC & DOC_CONF_HTML_SKIPRAW)) && !ctx->engine->sdb) {\n    res = scanraw(ctx, type, typercg, &dettype, (ctx->engine->engine_options & ENGINE_OPTIONS_DISABLE_CACHE) ? NULL : hash);\n    if (res != CL_CLEAN) {\n        switch (res) {\n            /* List of scan halts, runtime errors only! */\n/* omitted */\n            case CL_VIRUS:\n                ret = res;\n                if (SCAN_ALLMATCHES)\n                    break;\n                cli_bitset_free(ctx->hook_lsig_matches);\n                ctx->hook_lsig_matches = old_hook_lsig_matches;\n                goto done;\n            /* omitted */\n        }\n    }\n}
\n

scanraw performs a raw scan of the fmap that contains the mapped scan target file, so the actual file scanning happens inside this function.

\n
/**\n * @brief Perform raw scan of current fmap.\n *\n * @param ctx           Current scan context.\n * @param type          File type\n * @param typercg       Enable type recognition (file typing scan results).\n *                      If 0, will be a regular ac-mode scan.\n * @param[out] dettype  If typercg enabled and scan detects HTML or MAIL types,\n *                      will output HTML or MAIL types after performing HTML/MAIL scans\n * @param refhash       Hash of current fmap\n * @return cl_error_t\n */\nstatic cl_error_t scanraw(cli_ctx *ctx, cli_file_t type, uint8_t typercg, cli_file_t *dettype, unsigned char *refhash)
\n

Within scanraw, various scan routines are again called depending on the file type. The actual Eicar detection occurs inside cli_scan_fmap.

\n
perf_start(ctx, PERFT_RAW);\nret = cli_scan_fmap(ctx, type == CL_TYPE_TEXT_ASCII ? CL_TYPE_ANY : type, 0, &ftoffset, acmode, NULL, refhash);\nperf_stop(ctx, PERFT_RAW);
\n

Inside cli_scan_fmap, two checks are performed: a signature-matcher scan that reads the file in fixed-size buffer chunks, and a hash-based scan.

\n

The hash-based scan uses the database (hdb) from ctx->engine->hm_hdb.

\n

The Eicar file used in this case was detected via hash-based scanning at the following location.

\n
hdb = ctx->engine->hm_hdb;\nfp  = ctx->engine->hm_fp;\n\n/* omitted */\n\nvirname = NULL;\nfor (hashtype = CLI_HASH_MD5; hashtype < CLI_HASH_AVAIL_TYPES; hashtype++) {\n    const char *virname_w = NULL;\n    int found             = 0;\n\n    /* If no hash, skip to next type */\n    if (!compute_hash[hashtype])\n        continue;\n\n    /* Do hash scan */\n    if ((ret = cli_hm_scan(digest[hashtype], map->len, &virname, hdb, hashtype)) == CL_VIRUS) {\n        found += 1;\n    }\n    if (!found || SCAN_ALLMATCHES) {\n        if ((ret = cli_hm_scan_wild(digest[hashtype], &virname_w, hdb, hashtype)) == CL_VIRUS)\n            found += 2;\n    }\n\n    /* If found, do immediate hash-only FP check */\n    if (found && fp) {\n        for (hashtype2 = CLI_HASH_MD5; hashtype2 < CLI_HASH_AVAIL_TYPES; hashtype2++) {\n            if (!compute_hash[hashtype2])\n                continue;\n            if (cli_hm_scan(digest[hashtype2], map->len, NULL, fp, hashtype2) == CL_VIRUS) {\n                found = 0;\n                ret   = CL_CLEAN;\n                break;\n            } else if (cli_hm_scan_wild(digest[hashtype2], NULL, fp, hashtype2) == CL_VIRUS) {\n                found = 0;\n                ret   = CL_CLEAN;\n                break;\n            }\n        }\n    }\n\n    /* If matched size-based hash ... */\n    if (found % 2) {\n        viruses_found = 1;\n        ret           = cli_append_virus(ctx, virname);\n        if (!SCAN_ALLMATCHES || ret != CL_CLEAN)\n            break;\n        virname = NULL;\n    }\n    /* If matched size-agnostic hash ... */\n    if (found > 1) {\n        viruses_found = 1;\n        ret           = cli_append_virus(ctx, virname_w);\n        if (!SCAN_ALLMATCHES || ret != CL_CLEAN)\n            break;\n    }\n}
\n

For hash-based scanning, the hm_scan function is ultimately used.

\n

Inside it, the hash list contained in the cli_sz_hash structure is compared against the scan target’s hash using the hm_cmp function.

\n
/* cli_hm_scan will scan only size-specific hashes, if any */\nstatic int hm_scan(const unsigned char *digest, const char **virname, const struct cli_sz_hash *szh, enum CLI_HASH_TYPE type)\n{\n    unsigned int keylen;\n    size_t l, r;\n\n    if (!digest || !szh || !szh->items)\n        return CL_CLEAN;\n\n    keylen = hashlen[type];\n\n    l = 0;\n    r = szh->items - 1;\n    while (l <= r) {\n        size_t c = (l + r) / 2;\n        int res  = hm_cmp(digest, &szh->hash_array[keylen * c], keylen);\n\n        if (res < 0) {\n            if (!c)\n                break;\n            r = c - 1;\n        } else if (res > 0)\n            l = c + 1;\n        else {\n            if (virname)\n                *virname = szh->virusnames[c];\n            return CL_VIRUS;\n        }\n    }\n    return CL_CLEAN;\n}
\n

Reference: clamav/libclamav/matcher-hash.c at rel/0.104 · kash1064/clamav

\n

Because hm_cmp returns lexicographic comparison results, the hash list is searched using a binary search algorithm.

\n

The hash table itself is also relatively small, since cli_htu32_find is used beforehand to extract the first byte of the scan target’s hash as a key for lookup.

\n

This is how efficient hash-based scanning detects known viruses such as Eicar.

\n

After detecting the Eicar file through the above process, cli_hm_scan is also used to compare against the false-positive (fp) database.

\n

Summary

\n

The implementation turned out to be simpler than I expected, but the many branches and jumps still made reading the code quite exhausting.

\n

The second half got a bit rambling, but I managed to trace the full scan flow related to Eicar detection.

","fields":{"slug":"/clamav-simple-filescan-en","tagSlugs":["/tag/clam-av-en/","/tag/malware-en/","/tag/linux-en/","/tag/english/"]},"frontmatter":{"date":"2025-05-12","description":"Notes on tracing the scan behavior in ClamAV from invocation to detection of the Eicar test file.","tags":["ClamAV (en)","Malware (en)","Linux (en)","English"],"title":"Notes on Tracing the ClamAV Scan Process Until the Eicar Test File Is Detected","socialImage":{"publicURL":"/static/92427d7f750e6d3190ec4ea4cca00ed0/clamav-simple-filescan.png"}}}},"pageContext":{"slug":"/clamav-simple-filescan-en"}},"staticQueryHashes":["251939775","401334301","825871152"]}