libclamav: Added a class of scan callback functions that can be added with the
following API function:
void cl_engine_set_scan_callback(struct cl_engine *engine, clcb_scan callback, cl_scan_callback_t location);
The scan callback location may be configured using the following five values:
CL_SCAN_CALLBACK_PRE_HASH: Occurs just after basic file-type detection and
before any hashes have been calculated either for the cache or the gen-json
metadata.
CL_SCAN_CALLBACK_PRE_SCAN: Occurs before parser modules run and before
pattern matching.
CL_SCAN_CALLBACK_POST_SCAN: Occurs after pattern matching and after
running parser modules. A.k.a. the scan is complete for this layer.
CL_SCAN_CALLBACK_ALERT: Occurs each time an alert (detection) would be
triggered during a scan.
CL_SCAN_CALLBACK_FILE_TYPE: Occurs each time the file type determination
is refined. This may happen more than once per layer.
Each callback may alter scan behavior using the following return codes:
-
CL_BREAK: Scan aborted by callback. The rest of the scan is skipped.
This does not mark the file as clean or infected, it just skips the rest of
the scan.
-
CL_SUCCESS / CL_CLEAN: File scan will continue.
For CL_SCAN_CALLBACK_ALERT: This means you want to ignore this specific
alert and keep scanning.
This is different than CL_VERIFIED because it does not affect prior or
future alerts. Return CL_VERIFIED instead if you want to remove prior
alerts for this layer and skip the rest of the scan for this layer.
-
CL_VIRUS: This means you do not trust the file. A new alert will be added.
For CL_SCAN_CALLBACK_ALERT: This means you agree with the alert and no
extra alert is needed.
-
CL_VERIFIED: Layer explicitly trusted by the callback and previous alerts
removed for THIS layer. You might want to do this if you trust the hash or
verified a digital signature. The rest of the scan will be skipped for THIS
layer. For contained files, this does NOT mean that the parent or adjacent
layers are trusted.
Each callback is given a pointer to the current scan layer from which they can
get previous layers, can get the layer's fmap, and then various attributes of
the layer and of the fmap. To make this possible, there are new APIs to
query scan-layer details and fmap details:
cl_error_t cl_fmap_set_name(cl_fmap_t *map, const char *name);
cl_error_t cl_fmap_get_name(cl_fmap_t *map, const char **name_out);
cl_error_t cl_fmap_set_path(cl_fmap_t *map, const char *path);
cl_error_t cl_fmap_get_path(cl_fmap_t *map, const char **path_out, size_t *offset_out, size_t *len_out);
cl_error_t cl_fmap_get_fd(const cl_fmap_t *map, int *fd_out, size_t *offset_out, size_t *len_out);
cl_error_t cl_fmap_get_size(const cl_fmap_t *map, size_t *size_out);
cl_error_t cl_fmap_set_hash(const cl_fmap_t *map, const char *hash_alg, char hash);
cl_error_t cl_fmap_have_hash(const cl_fmap_t *map, const char *hash_alg, bool *have_hash_out);
cl_error_t cl_fmap_will_need_hash_later(const cl_fmap_t *map, const char *hash_alg);
cl_error_t cl_fmap_get_hash(const cl_fmap_t *map, const char *hash_alg, char **hash_out);
cl_error_t cl_fmap_get_data(const cl_fmap_t *map, size_t offset, size_t len, const uint8_t **data_out, size_t *data_len_out);
cl_error_t cl_scan_layer_get_fmap(cl_scan_layer_t *layer, cl_fmap_t **fmap_out);
cl_error_t cl_scan_layer_get_parent_layer(cl_scan_layer_t *layer, cl_scan_layer_t **parent_layer_out);
cl_error_t cl_scan_layer_get_type(cl_scan_layer_t *layer, const char **type_out);
cl_error_t cl_scan_layer_get_recursion_level(cl_scan_layer_t *layer, uint32_t *recursion_level_out);
cl_error_t cl_scan_layer_get_object_id(cl_scan_layer_t *layer, uint64_t *object_id_out);
cl_error_t cl_scan_layer_get_last_alert(cl_scan_layer_t *layer, const char **alert_name_out);
cl_error_t cl_scan_layer_get_attributes(cl_scan_layer_t *layer, uint32_t *attributes_out);
This deprecates, but does not immediately remove, the existing scan callbacks:
void cl_engine_set_clcb_pre_cache(struct cl_engine *engine, clcb_pre_cache callback);
void cl_engine_set_clcb_file_inspection(struct cl_engine *engine, clcb_file_inspection callback);
void cl_engine_set_clcb_pre_scan(struct cl_engine *engine, clcb_pre_scan callback);
void cl_engine_set_clcb_post_scan(struct cl_engine *engine, clcb_post_scan callback);
void cl_engine_set_clcb_virus_found(struct cl_engine *engine, clcb_virus_found callback);
void cl_engine_set_clcb_hash(struct cl_engine *engine, clcb_hash callback);
There is an interactive test program to demonstrate the new callbacks.
See: examples/ex_scan_callbacks.c
GitHub pull request