Example Program: Add --disable-cache feature

Also minor fixes to sys.rs and clamav.h formatting

Author: val-ms

examples/ex_scan_callbacks.c

@@ -1277,6 +1277,8 @@ int main(int argc, char **argv)
     char *hash_out      = NULL;
     char *file_type_out = NULL;
 
+    bool disable_cache = false;
+
     int i = 0;
 
     const char *help_string =
@@ -1296,6 +1298,7 @@ int main(int argc, char **argv)
         "                             Corresponding to the interactive scan options.\n"
         "--one-match (-1)           : Disable allmatch (stops scans after one match).\n"
         "--gen-json                 : Generate scan metadata JSON.\n"
+        "--disable-cache            : Disable caching of clean scan results.\n"
         "\n"
         "Scripted scan options are:\n"
         "%s";
@@ -1332,6 +1335,9 @@ int main(int argc, char **argv)
         } else if (strcmp(argv[i], "--debug") == 0) {
             debug_mode = true;
             printf("Enabling debug mode.\n");
+        } else if (strcmp(argv[i], "--disable-cache") == 0) {
+            printf("Disabling caching of clean scan results.\n");
+            disable_cache = true;
         } else {
             printf("Unknown option: %s\n", argv[i]);
             printf(help_string, argv[0], argv[0], command_list);
@@ -1386,6 +1392,10 @@ int main(int argc, char **argv)
     cl_engine_set_num(engine, CL_ENGINE_MAX_SCANSIZE, 1024 /*MB*/ * 1024 /*KB*/ * 1024 /*bytes*/);
     cl_engine_set_num(engine, CL_ENGINE_MAX_FILESIZE, 1024 /*MB*/ * 1024 /*KB*/ * 1024 /*bytes*/);
 
+    if (disable_cache) {
+        cl_engine_set_num(engine, CL_ENGINE_DISABLE_CACHE, 1); // Disable cache for clean results
+    }
+
     /*
      * Load signatures.
      * At least 1 signature required to initialize stuff required for scanning.

libclamav/clamav.h

@@ -87,7 +87,7 @@ extern "C" {
 typedef enum cl_verdict_t {
     CL_VERDICT_NOTHING_FOUND = 0,    /**< No alerting signatures matched. */
     CL_VERDICT_TRUSTED,              /**< The scan target has been deemed trusted (e.g. by FP signature or Authenticode). */
-    CL_VERDICT_STRONG_INDICATOR,                /**< One or more strong indicator signatures matched. */
+    CL_VERDICT_STRONG_INDICATOR,     /**< One or more strong indicator signatures matched. */
     CL_VERDICT_POTENTIALLY_UNWANTED, /**< One or more potentially unwanted signatures matched. */
 } cl_verdict_t;
 

libclamav_rust/src/sys.rs

@@ -129,22 +129,22 @@ pub struct cl_scan_layer {
     _unused: [u8; 0],
 }
 pub type cl_scan_layer_t = cl_scan_layer;
-#[doc = " @brief Callback interface to get access to the current layer using the scan-\n layer abstraction. This grants access to file content and attributes as well\n as those of each ancestor layers (if any).\n\n Called for each processed file including both the top level file (i.e. the\n zeroeth layer) and all contained files (recursively).\n\n @param layer          Scan layer (abstraction) for the current layer being scanned.\n                       Use the `cl_scan_layer_*` functions to access layer data and metadata.\n                       You may want to use `cl_scan_layer_get_fmap()` to get the file map for the current layer.\n                       You may also use it to access ancestor layers using `cl_scan_layer_get_parent_layer()`.\n\n @param context        The application context pointer passed in to the `cl_scan*()` function.\n\n @return CL_BREAK\n\n         Scan aborted by callback (the rest of the scan is skipped).\n         This does not mark the file as clean or infected, it just skips the rest of the scan.\n\n @return CL_SUCCESS / CL_CLEAN\n\n         File scan will continue.\n\n         For CL_SCAN_CALLBACK_ALERT: Means you want to ignore this specific alert and keep scanning.\n         This is different than CL_VERIFIED because it does not affect prior or future alerts.\n         Return CL_VERIFIED instead if you want to remove prior alerts for this layer and skip\n         the rest of the scan for this layer.\n\n @return CL_VIRUS\n\n         This will mark the file as infected. A new alert will be added.\n\n         For CL_SCAN_CALLBACK_ALERT: Means you agree with the alert (no extra alert needed).\n                                     Remember that CL_SUCCESS means you want to ignore the alert.\n\n @return CL_VERIFIED\n\n         Layer explicitly trusted by the callback and previous alerts removed FOR THIS layer.\n         You might want to do this if you trust the hash or verified a digital signature.\n         The rest of the scan will be skipped FOR THIS layer.\n         For contained files, this does NOT mean that the parent or adjacent layers are trusted."]
+#[doc = " @brief Callback interface to get access to the current layer using the scan-\n layer abstraction. This grants access to file content and attributes as well\n as those of each ancestor layers (if any).\n\n Called for each processed file including both the top level file (i.e. the\n zeroeth layer) and all contained files (recursively).\n\n @param layer          Scan layer (abstraction) for the current layer being scanned.\n                       Use the `cl_scan_layer_*` functions to access layer data and metadata.\n                       You may want to use `cl_scan_layer_get_fmap()` to get the file map for the current layer.\n                       You may also use it to access ancestor layers using `cl_scan_layer_get_parent_layer()`.\n\n @param context        The application context pointer passed in to the `cl_scan*()` function.\n\n @return CL_BREAK\n\n         Scan aborted by callback (the rest of the scan is skipped).\n         This does not mark the file as clean or infected, it just skips the rest of the scan.\n\n @return CL_SUCCESS\n\n         File scan will continue.\n\n         For CL_SCAN_CALLBACK_ALERT: Means you want to ignore this specific alert and keep scanning.\n         This is different than CL_VERIFIED because it does not affect prior or future alerts.\n         Return CL_VERIFIED instead if you want to remove prior alerts for this layer and skip\n         the rest of the scan for this layer.\n\n @return CL_VIRUS\n\n         This will mark the file as infected. A new alert will be added.\n\n         For CL_SCAN_CALLBACK_ALERT: Means you agree with the alert (no extra alert needed).\n                                     Remember that CL_SUCCESS means you want to ignore the alert.\n\n @return CL_VERIFIED\n\n         Layer explicitly trusted by the callback and previous alerts removed FOR THIS layer.\n         You might want to do this if you trust the hash or verified a digital signature.\n         The rest of the scan will be skipped FOR THIS layer.\n         For contained files, this does NOT mean that the parent or adjacent layers are trusted."]
 pub type clcb_scan = ::std::option::Option<
     unsafe extern "C" fn(
         layer: *mut cl_scan_layer_t,
         context: *mut ::std::os::raw::c_void,
     ) -> cl_error_t,
 >;
-#[doc = " @brief Pre-cache callback.\n\n @deprecated This function is deprecated and will be removed in a future release.\n Use `CL_SCAN_CALLBACK_PRE_HASH` with `cl_engine_set_scan_callback()` instead.\n\n Called for each processed file (both the entry level - AKA 'outer' - file and\n inner files - those generated when processing archive and container files), before\n the actual scanning takes place.\n\n @param fd        File descriptor which is about to be scanned.\n @param type      File type detected via magic - i.e. NOT on the fly - (e.g. \"CL_TYPE_MSEXE\").\n @param context   Opaque application provided data.\n @return          CL_CLEAN = File is scanned.\n @return          CL_BREAK = Allowed by callback - file is skipped and marked as clean.\n @return          CL_VIRUS = Blocked by callback - file is skipped and marked as infected."]
+#[doc = " @brief Pre-cache callback.\n\n @deprecated This function is deprecated and will be removed in a future release.\n Use `CL_SCAN_CALLBACK_PRE_HASH` with `cl_engine_set_scan_callback()` instead.\n\n Called for each processed file (both the entry level - AKA 'outer' - file and\n inner files - those generated when processing archive and container files), before\n the actual scanning takes place.\n\n @param fd        File descriptor which is about to be scanned.\n @param type      File type detected via magic - i.e. NOT on the fly - (e.g. \"CL_TYPE_MSEXE\").\n @param context   Opaque application provided data.\n @return          CL_SUCCESS = File is scanned.\n @return          CL_BREAK = Allowed by callback - file is skipped and marked as clean.\n @return          CL_VIRUS = Blocked by callback - file is skipped and marked as infected."]
 pub type clcb_pre_cache = ::std::option::Option<
     unsafe extern "C" fn(
         fd: ::std::os::raw::c_int,
         type_: *const ::std::os::raw::c_char,
         context: *mut ::std::os::raw::c_void,
     ) -> cl_error_t,
 >;
-#[doc = " @brief File inspection callback.\n\n @deprecated This function is deprecated and will be removed in a future release.\n Use `CL_SCAN_CALLBACK_PRE_SCAN` with `cl_engine_set_scan_callback()` instead.\n\n You can use the `cl_fmap_*` functions to access the file map, file name, file size, file contents,\n and those of each ancestor layers (if any).\n\n Called for each NEW file (inner and outer).\n Provides capability to record embedded file information during a scan.\n\n @param fd                  Current file descriptor which is about to be scanned.\n @param type                Current file type detected via magic - i.e. NOT on the fly - (e.g. \"CL_TYPE_MSEXE\").\n @param ancestors           An array of ancestors filenames of size `recursion_level`. filenames may be NULL.\n @param parent_file_size    Parent file size.\n @param file_name           Current file name, or NULL if the file does not have a name or ClamAV failed to record the name.\n @param file_size           Current file size.\n @param file_buffer         Current file buffer pointer.\n @param recursion_level     Recursion level / depth of the current file.\n @param layer_attributes    See LAYER_ATTRIBUTES_* flags.\n @param context             Opaque application provided data.\n @return                    CL_CLEAN = File is scanned.\n @return                    CL_BREAK = Whitelisted by callback - file is skipped and marked as clean.\n @return                    CL_VIRUS = Blacklisted by callback - file is skipped and marked as infected."]
+#[doc = " @brief File inspection callback.\n\n @deprecated This function is deprecated and will be removed in a future release.\n Use `CL_SCAN_CALLBACK_PRE_SCAN` with `cl_engine_set_scan_callback()` instead.\n\n You can use the `cl_fmap_*` functions to access the file map, file name, file size, file contents,\n and those of each ancestor layers (if any).\n\n Called for each NEW file (inner and outer).\n Provides capability to record embedded file information during a scan.\n\n @param fd                  Current file descriptor which is about to be scanned.\n @param type                Current file type detected via magic - i.e. NOT on the fly - (e.g. \"CL_TYPE_MSEXE\").\n @param ancestors           An array of ancestors filenames of size `recursion_level`. filenames may be NULL.\n @param parent_file_size    Parent file size.\n @param file_name           Current file name, or NULL if the file does not have a name or ClamAV failed to record the name.\n @param file_size           Current file size.\n @param file_buffer         Current file buffer pointer.\n @param recursion_level     Recursion level / depth of the current file.\n @param layer_attributes    See LAYER_ATTRIBUTES_* flags.\n @param context             Opaque application provided data.\n @return                    CL_SUCCESS = File is scanned.\n @return                    CL_BREAK = Whitelisted by callback - file is skipped and marked as clean.\n @return                    CL_VIRUS = Blacklisted by callback - file is skipped and marked as infected."]
 pub type clcb_file_inspection = ::std::option::Option<
     unsafe extern "C" fn(
         fd: ::std::os::raw::c_int,
@@ -159,15 +159,15 @@ pub type clcb_file_inspection = ::std::option::Option<
         context: *mut ::std::os::raw::c_void,
     ) -> cl_error_t,
 >;
-#[doc = " @brief Pre-scan callback.\n\n @deprecated This function is deprecated and will be removed in a future release.\n\n Called for each NEW file (inner and outer) before the scanning takes place. This is\n roughly the same as clcb_before_cache, but it is affected by clean file caching.\n This means that it won't be called if a clean cached file (inner or outer) is\n scanned a second time.\n\n @param fd        File descriptor which is about to be scanned.\n @param type      File type detected via magic - i.e. NOT on the fly - (e.g. \"CL_TYPE_MSEXE\").\n @param context   Opaque application provided data.\n @return          CL_CLEAN = File is scanned.\n @return          CL_BREAK = Allowed by callback - file is skipped and marked as clean.\n @return          CL_VIRUS = Blocked by callback - file is skipped and marked as infected."]
+#[doc = " @brief Pre-scan callback.\n\n @deprecated This function is deprecated and will be removed in a future release.\n\n Called for each NEW file (inner and outer) before the scanning takes place. This is\n roughly the same as clcb_before_cache, but it is affected by clean file caching.\n This means that it won't be called if a clean cached file (inner or outer) is\n scanned a second time.\n\n @param fd        File descriptor which is about to be scanned.\n @param type      File type detected via magic - i.e. NOT on the fly - (e.g. \"CL_TYPE_MSEXE\").\n @param context   Opaque application provided data.\n @return          CL_SUCCESS = File is scanned.\n @return          CL_BREAK = Allowed by callback - file is skipped and marked as clean.\n @return          CL_VIRUS = Blocked by callback - file is skipped and marked as infected."]
 pub type clcb_pre_scan = ::std::option::Option<
     unsafe extern "C" fn(
         fd: ::std::os::raw::c_int,
         type_: *const ::std::os::raw::c_char,
         context: *mut ::std::os::raw::c_void,
     ) -> cl_error_t,
 >;
-#[doc = " @brief Post-scan callback.\n\n @deprecated This function is deprecated and will be removed in a future release.\n Use `CL_SCAN_CALLBACK_PRE_SCAN` with `cl_engine_set_scan_callback()` instead.\n\n Called for each processed file (inner and outer), after the scanning is complete.\n In all-match mode, the virname will be one of the matches, but there is no\n guarantee in which order the matches will occur, thus the final virname may\n be any one of the matches.\n\n @param fd        File descriptor which was scanned.\n @param result    The scan result for the file.\n @param virname   A signature name if there was one or more matches.\n @param context   Opaque application provided data.\n @return          Scan result is not overridden.\n @return          CL_BREAK = Allowed by callback - scan result is set to CL_CLEAN.\n @return          Blocked by callback - scan result is set to CL_VIRUS."]
+#[doc = " @brief Post-scan callback.\n\n @deprecated This function is deprecated and will be removed in a future release.\n Use `CL_SCAN_CALLBACK_PRE_SCAN` with `cl_engine_set_scan_callback()` instead.\n\n Called for each processed file (inner and outer), after the scanning is complete.\n In all-match mode, the virname will be one of the matches, but there is no\n guarantee in which order the matches will occur, thus the final virname may\n be any one of the matches.\n\n @param fd        File descriptor which was scanned.\n @param result    The scan result for the file.\n @param virname   A signature name if there was one or more matches.\n @param context   Opaque application provided data.\n @return          CL_SUCCESS = File is scanned.\n @return          CL_BREAK = Allowed by callback - file is skipped and marked as clean.\n @return          CL_VIRUS = Blocked by callback - file is skipped and marked as infected."]
 pub type clcb_post_scan = ::std::option::Option<
     unsafe extern "C" fn(
         fd: ::std::os::raw::c_int,
@@ -211,7 +211,7 @@ pub type clcb_hash = ::std::option::Option<
         context: *mut ::std::os::raw::c_void,
     ),
 >;
-#[doc = " @brief Archive meta matching callback function.\n\n May be used to block archive/container samples based on archive metadata.\n Function is invoked multiple times per archive. Typically once per contained file.\n\n Note: Used by the --archive-verbose clamscan option. Overriding this will alter\n the output from --archive-verbose.\n\n @param container_type    String name of type (CL_TYPE).\n @param fsize_container   Sample size\n @param filename          Filename associated with the data in archive.\n @param fsize_real        Size of file after decompression (according to the archive).\n @param is_encrypted      Boolean non-zero if the contained file is encrypted.\n @param filepos_container File index in container.\n @param context           Opaque application provided data.\n @return                  CL_VIRUS to block (alert on)\n @return                  CL_CLEAN to continue scanning"]
+#[doc = " @brief Archive meta matching callback function.\n\n May be used to block archive/container samples based on archive metadata.\n Function is invoked multiple times per archive. Typically once per contained file.\n\n Note: Used by the --archive-verbose clamscan option. Overriding this will alter\n the output from --archive-verbose.\n\n @param container_type    String name of type (CL_TYPE).\n @param fsize_container   Sample size\n @param filename          Filename associated with the data in archive.\n @param fsize_real        Size of file after decompression (according to the archive).\n @param is_encrypted      Boolean non-zero if the contained file is encrypted.\n @param filepos_container File index in container.\n @param context           Opaque application provided data.\n @return                  CL_VIRUS to block (alert on)\n @return                  CL_SUCCESS to continue scanning"]
 pub type clcb_meta = ::std::option::Option<
     unsafe extern "C" fn(
         container_type: *const ::std::os::raw::c_char,