Stowage/clamav
2
0
Fork 0
mirror of https://github.com/Cisco-Talos/clamav.git synced 2025-10-19 10:23:17 +00:00
Code Issues Projects Releases Packages Wiki Activity
clamav/clambc/bcrun.c
Valerie Snyder f05770fb51
libclamav: scan-layer callback API functions 
Add the following scan callbacks:
```c
  cl_engine_set_scan_callback(engine, &pre_hash_callback, CL_SCAN_CALLBACK_PRE_HASH);
  cl_engine_set_scan_callback(engine, &pre_scan_callback, CL_SCAN_CALLBACK_PRE_SCAN);
  cl_engine_set_scan_callback(engine, &post_scan_callback, CL_SCAN_CALLBACK_POST_SCAN);
  cl_engine_set_scan_callback(engine, &alert_callback, CL_SCAN_CALLBACK_ALERT);
  cl_engine_set_scan_callback(engine, &file_type_callback, CL_SCAN_CALLBACK_FILE_TYPE);
```

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.
  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 don't trust the file. A new alert will be added.
  For CL_SCAN_CALLBACK_ALERT: Means you agree with the alert (no extra alert 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 the layer's fmap, and then
various attributes of the layer and of the fmap such as:
- layer recursion level
- layer object id
- layer file type
- layer attributes (was decerypted, normalized, embedded, or re-typed)
- layer last alert
- fmap name
- fmap hash (md5, sha1, or sha2-256)
- fmap data (pointer and size)
- fmap file descriptor, if any (fd, offset, size)
- fmap filepath, if any (filepath, offset, size)

To make this possible, this commits introduced a handful of 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, const 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 commit deprecates but does not 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);`

This commit also adds an interactive test program to demonstrate the callbacks.
See: `examples/ex_scan_callbacks.c`

CLAM-255
CLAM-2485
CLAM-2626
2025-08-14 22:39:14 -04:00

506 lines
15 KiB
C
Raw Blame History

/*
* ClamAV bytecode handler tool.
*
* Copyright (C) 2013-2025 Cisco Systems, Inc. and/or its affiliates. All rights reserved.
* Copyright (C) 2009-2013 Sourcefire, Inc.
*
* Authors: Török Edvin
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
* MA 02110-1301, USA.
*/
#if HAVE_CONFIG_H
#include "clamav-config.h"
#endif
#ifndef _WIN32
#include <sys/time.h>
#endif
#include <stdlib.h>
// libclamav
#include "clamav.h"
#include "dconf.h"
#include "others.h"
#include "bytecode.h"
#include "bytecode_priv.h"
#include "clamav_rust.h"
// common
#include "optparser.h"
#include "misc.h"
#include <fcntl.h>
#include <stdlib.h>
#include <errno.h>
#include <string.h>
#ifdef HAVE_UNISTD_H
#include <unistd.h>
#endif
static void help(void)
{
printf("\n");
printf(" Clam AntiVirus: Bytecode Testing Tool %s\n", get_version());
printf(" By The ClamAV Team: https://www.clamav.net/about.html#credits\n");
printf(" (C) 2025 Cisco Systems, Inc.\n");
printf("\n");
printf(" clambc <file> [function] [param1 ...]\n");
printf("\n");
printf(" --help -h Show this help\n");
printf(" --version -V Show version\n");
printf(" --debug Show debug\n");
printf(" --force-interpreter -f Force using the interpreter instead of the JIT\n");
printf(" --trust-bytecode -t Trust loaded bytecode (default yes)\n");
printf(" --info -i Print information about bytecode\n");
printf(" --printsrc -p Print bytecode source\n");
printf(" --printbcir -c Print IR of bytecode signature\n");
printf(" --input -c Input file to run the bytecode on\n");
printf(" --trace <level> -T Set bytecode trace level 0..7 (default 7)\n");
printf(" --no-trace-showsource -s Don't show source line during tracing\n");
printf(" --statistics=bytecode Collect and print bytecode execution statistics\n");
printf(" file File to test\n");
printf("\n");
printf("**Caution**: You should NEVER run bytecode signatures from untrusted sources.\nDoing so may result in arbitrary code execution.\n");
printf("\n");
return;
}
static struct dbg_state {
const char *directory;
const char *file;
const char *scope;
uint32_t scopeid;
unsigned line;
unsigned col;
unsigned showline;
} dbg_state;
static void tracehook(struct cli_bc_ctx *ctx, unsigned event)
{
dbg_state.directory = ctx->directory;
if (*ctx->file == '?')
return;
switch (event) {
case trace_func:
fprintf(stderr, "[trace] %s:%u:%u -> %s:%u:%u Entered function %s\n",
dbg_state.file, dbg_state.line, dbg_state.col,
ctx->file, ctx->line, ctx->col, ctx->scope);
dbg_state.scope = ctx->scope;
break;
case trace_param:
fprintf(stderr, "[trace] function parameter:\n");
return;
case trace_scope:
fprintf(stderr, "[trace] %s:%u:%u -> %s:%u:%u\n",
dbg_state.file, dbg_state.line, dbg_state.col,
ctx->file, ctx->line, ctx->col);
dbg_state.scope = ctx->scope;
break;
case trace_line:
case trace_col:
if (dbg_state.showline)
cli_bytecode_debug_printsrc(ctx);
else
fprintf(stderr, "[trace] %s:%u:%u\n",
dbg_state.file, dbg_state.line, dbg_state.col);
break;
default:
break;
}
dbg_state.file = ctx->file;
dbg_state.line = ctx->line;
dbg_state.col = ctx->col;
}
static void tracehook_op(struct cli_bc_ctx *ctx, const char *op)
{
UNUSEDPARAM(ctx);
fprintf(stderr, "[trace] %s\n", op);
}
static void tracehook_val(struct cli_bc_ctx *ctx, const char *name, uint32_t value)
{
UNUSEDPARAM(ctx);
fprintf(stderr, "[trace] %s = %u\n", name, value);
}
static void tracehook_ptr(struct cli_bc_ctx *ctx, const void *ptr)
{
UNUSEDPARAM(ctx);
fprintf(stderr, "[trace] %p\n", ptr);
}
static uint8_t debug_flag = 0;
static void print_src(const char *file)
{
char buf[4096];
int nread, i, found = 0, lcnt = 0;
FILE *f = fopen(file, "r");
if (!f) {
fprintf(stderr, "Unable to reopen %s\n", file);
return;
}
do {
nread = fread(buf, 1, sizeof(buf), f);
for (i = 0; i < nread - 1; i++) {
if (buf[i] == '\n') {
lcnt++;
}
/* skip over the logical trigger */
if (lcnt >= 2 && buf[i] == '\n' && buf[i + 1] == 'S') {
found = 1;
i += 2;
break;
}
}
} while (!found && (nread == sizeof(buf)));
if (debug_flag)
printf("[clambc] Source code:");
do {
for (; i + 1 < nread; i++) {
if (buf[i] == 'S' || buf[i] == '\n') {
putc('\n', stdout);
continue;
}
putc(((buf[i] & 0xf) | ((buf[i + 1] & 0xf) << 4)), stdout);
i++;
}
if (i == nread - 1 && nread != 1)
fseek(f, -1, SEEK_CUR);
i = 0;
nread = fread(buf, 1, sizeof(buf), f);
} while (nread > 0);
fclose(f);
}
static uint32_t deadbeefcounts[64] = {
0xdeadbeef,
0,
0xbeefdead,
0,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
0xdeadbeef,
};
int main(int argc, char *argv[])
{
FILE *f;
struct cli_bc *bc;
struct cli_bc_ctx *ctx;
int rc, dbgargc, bc_stats = 0;
struct optstruct *opts;
const struct optstruct *opt;
unsigned funcid = 0, i;
struct cli_all_bc bcs;
int fd = -1;
unsigned tracelevel;
#ifdef _WIN32
SetConsoleOutputCP(CP_UTF8);
#endif
if (check_flevel())
exit(1);
opts = optparse(NULL, argc, argv, 1, OPT_CLAMBC, 0, NULL);
if (!opts) {
fprintf(stderr, "ERROR: Can't parse command line options\n");
exit(1);
}
if (optget(opts, "version")->enabled) {
printf("Clam AntiVirus Bytecode Testing Tool %s\n", get_version());
cl_init(CL_INIT_DEFAULT);
cli_bytecode_printversion();
optfree(opts);
exit(0);
}
if (optget(opts, "help")->enabled || !opts->filename) {
optfree(opts);
help();
exit(0);
}
f = fopen(opts->filename[0], "r");
if (!f) {
fprintf(stderr, "Unable to load %s\n", argv[1]);
optfree(opts);
exit(2);
}
bc = malloc(sizeof(*bc));
if (!bc) {
fprintf(stderr, "Out of memory\n");
optfree(opts);
exit(3);
}
if (optget(opts, "debug")->enabled) {
cl_debug();
debug_flag = 1;
}
rc = cl_init(CL_INIT_DEFAULT);
if (rc != CL_SUCCESS) {
fprintf(stderr, "Unable to init libclamav: %s\n", cl_strerror(rc));
optfree(opts);
exit(4);
}
dbgargc = 1;
while (opts->filename[dbgargc]) dbgargc++;
if (dbgargc > 1)
cli_bytecode_debug(dbgargc, opts->filename);
if (optget(opts, "force-interpreter")->enabled) {
bcs.engine = NULL;
} else {
rc = cli_bytecode_init(&bcs);
if (rc != CL_SUCCESS) {
fprintf(stderr, "Unable to init bytecode engine: %s\n", cl_strerror(rc));
optfree(opts);
exit(4);
}
}
bcs.all_bcs = bc;
bcs.count = 1;
if ((opt = optget(opts, "statistics"))->enabled) {
while (opt) {
if (!strcasecmp(opt->strarg, "bytecode"))
bc_stats = 1;
opt = opt->nextarg;
}
}
rc = cli_bytecode_load(bc, f, NULL, optget(opts, "trust-bytecode")->enabled, bc_stats);
if (rc != CL_SUCCESS) {
fprintf(stderr, "Unable to load bytecode: %s\n", cl_strerror(rc));
optfree(opts);
exit(4);
}
fclose(f);
if (bc->state == bc_skip) {
fprintf(stderr, "bytecode load skipped\n");
exit(0);
}
if (debug_flag)
printf("[clambc] Bytecode loaded\n");
if (optget(opts, "info")->enabled) {
cli_bytecode_describe(bc);
} else if (optget(opts, "printsrc")->enabled) {
print_src(opts->filename[0]);
} else if (optget(opts, "printbcir")->enabled) {
unsigned i;
cli_bytetype_describe(bc);
for (i = 0; i < bc->num_func; ++i) {
printf("########################################################################\n"
"####################### Function id %3u ################################\n"
"########################################################################\n",
i);
cli_bytevalue_describe(bc, i);
cli_bytefunc_describe(bc, i);
}
} else {
cli_ctx cctx;
struct cl_engine *engine = cl_engine_new();
fmap_t *map = NULL;
memset(&cctx, 0, sizeof(cctx));
if (!engine) {
fprintf(stderr, "Unable to create engine\n");
optfree(opts);
exit(3);
}
rc = cl_engine_compile(engine);
if (rc) {
fprintf(stderr, "Unable to compile engine: %s\n", cl_strerror(rc));
optfree(opts);
exit(4);
}
rc = cli_bytecode_prepare2(engine, &bcs, BYTECODE_ENGINE_MASK);
if (rc != CL_SUCCESS) {
fprintf(stderr, "Unable to prepare bytecode: %s\n", cl_strerror(rc));
optfree(opts);
exit(4);
}
if (debug_flag)
printf("[clambc] Bytecode prepared\n");
ctx = cli_bytecode_context_alloc();
if (!ctx) {
fprintf(stderr, "Out of memory\n");
exit(3);
}
ctx->ctx = &cctx;
cctx.engine = engine;
cctx.recursion_stack_size = cctx.engine->max_recursion_level;
cctx.recursion_stack = calloc(sizeof(cli_scan_layer_t), cctx.recursion_stack_size);
if (!cctx.recursion_stack) {
fprintf(stderr, "Out of memory\n");
exit(3);
}
memset(&dbg_state, 0, sizeof(dbg_state));
dbg_state.file = "<libclamav>";
dbg_state.line = 0;
dbg_state.col = 0;
dbg_state.showline = !optget(opts, "no-trace-showsource")->enabled;
tracelevel = optget(opts, "trace")->numarg;
cli_bytecode_context_set_trace(ctx, tracelevel,
tracehook,
tracehook_op,
tracehook_val,
tracehook_ptr);
if (opts->filename[1]) {
funcid = atoi(opts->filename[1]);
}
cli_bytecode_context_setfuncid(ctx, bc, funcid);
if (debug_flag)
printf("[clambc] Running bytecode function :%u\n", funcid);
if (opts->filename[1]) {
i = 2;
while (opts->filename[i]) {
rc = cli_bytecode_context_setparam_int(ctx, i - 2, atoi(opts->filename[i]));
if (rc != CL_SUCCESS) {
fprintf(stderr, "Unable to set param %u: %s\n", i - 2, cl_strerror(rc));
}
i++;
}
}
if ((opt = optget(opts, "input"))->enabled) {
fd = open(opt->strarg, O_RDONLY | O_BINARY);
if (fd == -1) {
fprintf(stderr, "Unable to open input file %s: %s\n", opt->strarg, strerror(errno));
optfree(opts);
exit(5);
}
map = fmap_new(fd, 0, 0, opt->strarg, opt->strarg);
if (!map) {
fprintf(stderr, "Unable to map input file %s\n", opt->strarg);
exit(5);
}
// ctx was memset, so recursion_level starts at 0.
cctx.recursion_stack[cctx.recursion_level].fmap = map;
cctx.recursion_stack[cctx.recursion_level].type = CL_TYPE_ANY; /* ANY for the top level, because we don't yet know the type. */
cctx.recursion_stack[cctx.recursion_level].size = map->len;
rc = cli_bytecode_context_setfile(ctx, map);
if (rc != CL_SUCCESS) {
fprintf(stderr, "Unable to set file %s: %s\n", opt->strarg, cl_strerror(rc));
optfree(opts);
exit(5);
}
}
/* for testing */
ctx->hooks.match_counts = deadbeefcounts;
ctx->hooks.match_offsets = deadbeefcounts;
/*
* Run the bytecode.
*/
rc = cli_bytecode_run(&bcs, bc, ctx);
if (rc != CL_SUCCESS) {
fprintf(stderr, "Unable to run bytecode: %s\n", cl_strerror(rc));
} else {
uint64_t v;
if (debug_flag)
printf("[clambc] Bytecode run finished\n");
v = cli_bytecode_context_getresult_int(ctx);
if (debug_flag)
printf("[clambc] Bytecode returned: 0x%llx\n", (long long)v);
}
cli_bytecode_context_destroy(ctx);
if (map)
fmap_free(map);
if (cctx.recursion_stack[cctx.recursion_level].evidence) {
evidence_free(cctx.recursion_stack[cctx.recursion_level].evidence);
}
free(cctx.recursion_stack);
cl_engine_free(engine);
}
cli_bytecode_destroy(bc);
cli_bytecode_done(&bcs);
free(bc);
optfree(opts);
if (fd != -1)
close(fd);
if (debug_flag)
printf("[clambc] Exiting\n");
return 0;
}
Reference in a new issue View git blame Copy permalink