-
Notifications
You must be signed in to change notification settings - Fork 669
/
clamav.h
1666 lines (1517 loc) · 64.7 KB
/
clamav.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
/*
* Copyright (C) 2013-2024 Cisco Systems, Inc. and/or its affiliates. All rights reserved.
* Copyright (C) 2007-2013 Sourcefire, Inc.
*
* Authors: Tomasz Kojm
*
* 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.
*/
#ifndef __CLAMAV_H
#define __CLAMAV_H
#ifdef _WIN32
#ifndef OWN_WINSOCK
#include <winsock2.h>
#endif
#endif
#include <openssl/ssl.h>
#include <openssl/err.h>
/* Certain OSs already use 64bit variables in their stat struct */
#if (!defined(__FreeBSD__) && !defined(__APPLE__))
#define STAT64_OK 1
#else
#define STAT64_OK 0
#endif
#if defined(HAVE_STAT64) && STAT64_OK
#include <unistd.h>
#define STATBUF struct stat64
#define CLAMSTAT stat64
#define LSTAT lstat64
#define FSTAT fstat64
#define safe_open(a, b) open(a, b | O_LARGEFILE)
#else
#define STATBUF struct stat
#define CLAMSTAT stat
#define LSTAT lstat
#define FSTAT fstat
/* Nothing is safe in windows, not even open, safe_open defined under /win32 */
#ifndef _WIN32
#define safe_open open
#endif
#endif
#define UNUSEDPARAM(x) (void)(x)
#include <sys/types.h>
#include <sys/stat.h>
#include <stdbool.h>
#include "clamav-types.h"
#include "clamav-version.h"
#ifdef __cplusplus
extern "C" {
#endif
#define CL_COUNT_PRECISION 4096
/* return codes */
typedef enum cl_error_t {
/* libclamav specific */
CL_CLEAN = 0,
CL_SUCCESS = 0,
CL_VIRUS,
CL_ENULLARG,
CL_EARG,
CL_EMALFDB,
CL_ECVD,
CL_EVERIFY,
CL_EUNPACK,
/* I/O and memory errors */
CL_EOPEN,
CL_ECREAT,
CL_EUNLINK,
CL_ESTAT,
CL_EREAD,
CL_ESEEK,
CL_EWRITE,
CL_EDUP,
CL_EACCES,
CL_ETMPFILE,
CL_ETMPDIR,
CL_EMAP,
CL_EMEM,
CL_ETIMEOUT,
/* internal (not reported outside libclamav) */
CL_BREAK,
CL_EMAXREC,
CL_EMAXSIZE,
CL_EMAXFILES,
CL_EFORMAT,
CL_EPARSE,
CL_EBYTECODE, /* may be reported in testmode */
CL_EBYTECODE_TESTFAIL, /* may be reported in testmode */
/* c4w error codes */
CL_ELOCK,
CL_EBUSY,
CL_ESTATE,
CL_VERIFIED, /* The binary has been deemed trusted */
CL_ERROR, /* Unspecified / generic error */
/* no error codes below this line please */
CL_ELAST_ERROR
} cl_error_t;
/* db options */
// clang-format off
#define CL_DB_PHISHING 0x2
#define CL_DB_PHISHING_URLS 0x8
#define CL_DB_PUA 0x10
#define CL_DB_CVDNOTMP 0x20 /* obsolete */
#define CL_DB_OFFICIAL 0x40 /* internal */
#define CL_DB_PUA_MODE 0x80
#define CL_DB_PUA_INCLUDE 0x100
#define CL_DB_PUA_EXCLUDE 0x200
#define CL_DB_COMPILED 0x400 /* internal */
#define CL_DB_DIRECTORY 0x800 /* internal */
#define CL_DB_OFFICIAL_ONLY 0x1000
#define CL_DB_BYTECODE 0x2000
#define CL_DB_SIGNED 0x4000 /* internal */
#define CL_DB_BYTECODE_UNSIGNED 0x8000 /* Caution: You should never run bytecode signatures from untrusted sources. Doing so may result in arbitrary code execution. */
#define CL_DB_UNSIGNED 0x10000 /* internal */
#define CL_DB_BYTECODE_STATS 0x20000
#define CL_DB_ENHANCED 0x40000
#define CL_DB_PCRE_STATS 0x80000
#define CL_DB_YARA_EXCLUDE 0x100000
#define CL_DB_YARA_ONLY 0x200000
/* recommended db settings */
#define CL_DB_STDOPT (CL_DB_PHISHING | CL_DB_PHISHING_URLS | CL_DB_BYTECODE)
/*** scan options ***/
struct cl_scan_options {
uint32_t general;
uint32_t parse;
uint32_t heuristic;
uint32_t mail;
uint32_t dev;
};
/* general */
#define CL_SCAN_GENERAL_ALLMATCHES 0x1 /* scan in all-match mode */
#define CL_SCAN_GENERAL_COLLECT_METADATA 0x2 /* collect metadata (--gen-json) */
#define CL_SCAN_GENERAL_HEURISTICS 0x4 /* option to enable heuristic alerts */
#define CL_SCAN_GENERAL_HEURISTIC_PRECEDENCE 0x8 /* allow heuristic match to take precedence. */
#define CL_SCAN_GENERAL_UNPRIVILEGED 0x10 /* scanner will not have read access to files. */
/* parsing capabilities options */
#define CL_SCAN_PARSE_ARCHIVE 0x1
#define CL_SCAN_PARSE_ELF 0x2
#define CL_SCAN_PARSE_PDF 0x4
#define CL_SCAN_PARSE_SWF 0x8
#define CL_SCAN_PARSE_HWP3 0x10
#define CL_SCAN_PARSE_XMLDOCS 0x20
#define CL_SCAN_PARSE_MAIL 0x40
#define CL_SCAN_PARSE_OLE2 0x80
#define CL_SCAN_PARSE_HTML 0x100
#define CL_SCAN_PARSE_PE 0x200
#define CL_SCAN_PARSE_ONENOTE 0x400
#define CL_SCAN_PARSE_IMAGE 0x800 /* option to enable/disable parsing images (graphics) */
#define CL_SCAN_PARSE_IMAGE_FUZZY_HASH 0x1000 /* option to enable/disable image fuzzy hash calculation. */
/* heuristic alerting options */
#define CL_SCAN_HEURISTIC_BROKEN 0x2 /* alert on broken PE and broken ELF files */
#define CL_SCAN_HEURISTIC_EXCEEDS_MAX 0x4 /* alert when files exceed scan limits (filesize, max scansize, or max recursion depth) */
#define CL_SCAN_HEURISTIC_PHISHING_SSL_MISMATCH 0x8 /* alert on SSL mismatches */
#define CL_SCAN_HEURISTIC_PHISHING_CLOAK 0x10 /* alert on cloaked URLs in emails */
#define CL_SCAN_HEURISTIC_MACROS 0x20 /* alert on OLE2 files containing macros */
#define CL_SCAN_HEURISTIC_ENCRYPTED_ARCHIVE 0x40 /* alert if archive is encrypted (rar, zip, etc) */
#define CL_SCAN_HEURISTIC_ENCRYPTED_DOC 0x80 /* alert if a document is encrypted (pdf, docx, etc) */
#define CL_SCAN_HEURISTIC_PARTITION_INTXN 0x100 /* alert if partition table size doesn't make sense */
#define CL_SCAN_HEURISTIC_STRUCTURED 0x200 /* data loss prevention options, i.e. alert when detecting personal information */
#define CL_SCAN_HEURISTIC_STRUCTURED_SSN_NORMAL 0x400 /* alert when detecting social security numbers */
#define CL_SCAN_HEURISTIC_STRUCTURED_SSN_STRIPPED 0x800 /* alert when detecting stripped social security numbers */
#define CL_SCAN_HEURISTIC_STRUCTURED_CC 0x1000 /* alert when detecting credit card numbers */
#define CL_SCAN_HEURISTIC_BROKEN_MEDIA 0x2000 /* alert if a file does not match the identified file format, works with JPEG, TIFF, GIF, PNG */
/* mail scanning options */
#define CL_SCAN_MAIL_PARTIAL_MESSAGE 0x1
/* dev options */
#define CL_SCAN_DEV_COLLECT_SHA 0x1 /* Enables hash output in sha-collect builds - for internal use only */
#define CL_SCAN_DEV_COLLECT_PERFORMANCE_INFO 0x2 /* collect performance timings */
/* cl_countsigs options */
#define CL_COUNTSIGS_OFFICIAL 0x1
#define CL_COUNTSIGS_UNOFFICIAL 0x2
#define CL_COUNTSIGS_ALL (CL_COUNTSIGS_OFFICIAL | CL_COUNTSIGS_UNOFFICIAL)
/* For the new engine_options bit field in the engine */
#define ENGINE_OPTIONS_NONE 0x0
#define ENGINE_OPTIONS_DISABLE_CACHE 0x1
#define ENGINE_OPTIONS_FORCE_TO_DISK 0x2
#define ENGINE_OPTIONS_DISABLE_PE_STATS 0x4
#define ENGINE_OPTIONS_DISABLE_PE_CERTS 0x8
#define ENGINE_OPTIONS_PE_DUMPCERTS 0x10
// clang-format on
struct cl_engine;
struct cl_settings;
/* ----------------------------------------------------------------------------
* Enable global libclamav features.
*/
/**
* @brief Enable debug messages
*/
extern void cl_debug(void);
/**
* @brief Set libclamav to always create section hashes for PE files.
*
* Section hashes are used in .mdb signature.
*/
extern void cl_always_gen_section_hash(void);
/* ----------------------------------------------------------------------------
* Scan engine functions.
*/
/**
* @brief This function initializes the openssl crypto system.
*
* Called by cl_init() and does not need to be cleaned up as de-init
* is handled automatically by openssl 1.0.2.h and 1.1.0
*
* @return Always returns 0
*/
int cl_initialize_crypto(void);
/**
* @brief This is a deprecated function that used to clean up ssl crypto inits.
*
* Call to EVP_cleanup() has been removed since cleanup is now handled by
* auto-deinit as of openssl 1.0.2h and 1.1.0
*/
void cl_cleanup_crypto(void);
#define CL_INIT_DEFAULT 0x0
/**
* @brief Initialize the ClamAV library.
*
* @param initoptions Unused.
* @return cl_error_t CL_SUCCESS if everything initialized correctly.
*/
extern cl_error_t cl_init(unsigned int initoptions);
/**
* @brief Allocate a new scanning engine and initialize default settings.
*
* The engine should be freed with `cl_engine_free()`.
*
* @return struct cl_engine* Pointer to the scanning engine.
*/
extern struct cl_engine *cl_engine_new(void);
enum cl_engine_field {
CL_ENGINE_MAX_SCANSIZE, /* uint64_t */
CL_ENGINE_MAX_FILESIZE, /* uint64_t */
CL_ENGINE_MAX_RECURSION, /* uint32_t */
CL_ENGINE_MAX_FILES, /* uint32_t */
CL_ENGINE_MIN_CC_COUNT, /* uint32_t */
CL_ENGINE_MIN_SSN_COUNT, /* uint32_t */
CL_ENGINE_PUA_CATEGORIES, /* (char *) */
CL_ENGINE_DB_OPTIONS, /* uint32_t */
CL_ENGINE_DB_VERSION, /* uint32_t */
CL_ENGINE_DB_TIME, /* time_t */
CL_ENGINE_AC_ONLY, /* uint32_t */
CL_ENGINE_AC_MINDEPTH, /* uint32_t */
CL_ENGINE_AC_MAXDEPTH, /* uint32_t */
CL_ENGINE_TMPDIR, /* (char *) */
CL_ENGINE_KEEPTMP, /* uint32_t */
CL_ENGINE_BYTECODE_SECURITY, /* uint32_t */
CL_ENGINE_BYTECODE_TIMEOUT, /* uint32_t */
CL_ENGINE_BYTECODE_MODE, /* uint32_t */
CL_ENGINE_MAX_EMBEDDEDPE, /* uint64_t */
CL_ENGINE_MAX_HTMLNORMALIZE, /* uint64_t */
CL_ENGINE_MAX_HTMLNOTAGS, /* uint64_t */
CL_ENGINE_MAX_SCRIPTNORMALIZE, /* uint64_t */
CL_ENGINE_MAX_ZIPTYPERCG, /* uint64_t */
CL_ENGINE_FORCETODISK, /* uint32_t */
CL_ENGINE_CACHE_SIZE, /* uint32_t */
CL_ENGINE_DISABLE_CACHE, /* uint32_t */
CL_ENGINE_DISABLE_PE_STATS, /* uint32_t */
CL_ENGINE_STATS_TIMEOUT, /* uint32_t */
CL_ENGINE_MAX_PARTITIONS, /* uint32_t */
CL_ENGINE_MAX_ICONSPE, /* uint32_t */
CL_ENGINE_MAX_RECHWP3, /* uint32_t */
CL_ENGINE_MAX_SCANTIME, /* uint32_t */
CL_ENGINE_PCRE_MATCH_LIMIT, /* uint64_t */
CL_ENGINE_PCRE_RECMATCH_LIMIT, /* uint64_t */
CL_ENGINE_PCRE_MAX_FILESIZE, /* uint64_t */
CL_ENGINE_DISABLE_PE_CERTS, /* uint32_t */
CL_ENGINE_PE_DUMPCERTS, /* uint32_t */
};
enum bytecode_security {
CL_BYTECODE_TRUST_ALL = 0, /* obsolete */
CL_BYTECODE_TRUST_SIGNED, /* default */
CL_BYTECODE_TRUST_NOTHING /* paranoid setting */
};
enum bytecode_mode {
CL_BYTECODE_MODE_AUTO = 0, /* JIT if possible, fallback to interpreter */
CL_BYTECODE_MODE_JIT, /* force JIT */
CL_BYTECODE_MODE_INTERPRETER, /* force interpreter */
CL_BYTECODE_MODE_TEST, /* both JIT and interpreter, compare results, all failures are fatal */
CL_BYTECODE_MODE_OFF /* for query only, not settable */
};
struct cli_section_hash {
unsigned char md5[16];
size_t len;
};
typedef struct cli_stats_sections {
size_t nsections;
struct cli_section_hash *sections;
} stats_section_t;
/**
* @brief Set a numerical engine option.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine An initialized scan engine.
* @param cl_engine_field A CL_ENGINE option.
* @param num The new engine option value.
* @return cl_error_t CL_SUCCESS if successfully set.
* @return cl_error_t CL_EARG if the field number was incorrect.
* @return cl_error_t CL_ENULLARG null arguments were provided.
*/
extern cl_error_t cl_engine_set_num(struct cl_engine *engine, enum cl_engine_field field, long long num);
/**
* @brief Get a numerical engine option.
*
* @param engine An initialized scan engine.
* @param cl_engine_field A CL_ENGINE option.
* @param err (optional) A cl_error_t status code.
* @return long long The numerical option value.
*/
extern long long cl_engine_get_num(const struct cl_engine *engine, enum cl_engine_field field, int *err);
/**
* @brief Set a string engine option.
*
* If the string option has already been set, the existing string will be free'd
* and the new string will replace it.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine An initialized scan engine.
* @param cl_engine_field A CL_ENGINE option.
* @param str The new engine option value.
* @return cl_error_t CL_SUCCESS if successfully set.
* @return cl_error_t CL_EARG if the field number was incorrect.
* @return cl_error_t CL_EMEM if a memory allocation error occurred.
* @return cl_error_t CL_ENULLARG null arguments were provided.
*/
extern cl_error_t cl_engine_set_str(struct cl_engine *engine, enum cl_engine_field field, const char *str);
/**
* @brief Get a string engine option.
*
* @param engine An initialized scan engine.
* @param cl_engine_field A CL_ENGINE option.
* @param err (optional) A cl_error_t status code.
* @return const char * The string option value.
*/
extern const char *cl_engine_get_str(const struct cl_engine *engine, enum cl_engine_field field, int *err);
/**
* @brief Copy the settings from an existing scan engine.
*
* The cl_settings pointer is allocated and must be freed with cl_engine_settings_free().
*
* @param engine An configured scan engine.
* @return struct cl_settings* The settings.
*/
extern struct cl_settings *cl_engine_settings_copy(const struct cl_engine *engine);
/**
* @brief Apply settings from a settings structure to a scan engine.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine A scan engine.
* @param settings The settings.
* @return cl_error_t CL_SUCCESS if successful.
* @return cl_error_t CL_EMEM if a memory allocation error occurred.
*/
extern cl_error_t cl_engine_settings_apply(struct cl_engine *engine, const struct cl_settings *settings);
/**
* @brief Free a settings struct pointer.
*
* @param settings The settings struct pointer.
* @return cl_error_t CL_SUCCESS if successful.
* @return cl_error_t CL_ENULLARG null arguments were provided.
*/
extern cl_error_t cl_engine_settings_free(struct cl_settings *settings);
/**
* @brief Prepare the scanning engine.
*
* Call this after all required databases have been loaded and settings have
* been applied.
*
* @param engine A scan engine.
* @return cl_error_t CL_SUCCESS if successful.
* @return cl_error_t CL_ENULLARG null arguments were provided.
*/
extern cl_error_t cl_engine_compile(struct cl_engine *engine);
/**
* @brief Add a reference count to the engine.
*
* Thread safety mechanism so that the engine is not free'd by another thread.
*
* The engine is initialized with refcount = 1, so this only needs to be called
* for additional scanning threads.
*
* @param engine A scan engine.
* @return cl_error_t CL_SUCCESS if successful.
* @return cl_error_t CL_ENULLARG null arguments were provided.
*/
extern cl_error_t cl_engine_addref(struct cl_engine *engine);
/**
* @brief Free an engine.
*
* Will lower the reference count on an engine. If the reference count hits
* zero, the engine will be freed.
*
* @param engine A scan engine.
* @return cl_error_t CL_SUCCESS if successful.
* @return cl_error_t CL_ENULLARG null arguments were provided.
*/
extern cl_error_t cl_engine_free(struct cl_engine *engine);
/* ----------------------------------------------------------------------------
* Callback function type definitions.
*/
/**
* @brief Pre-cache callback.
*
* Called for each processed file (both the entry level - AKA 'outer' - file and
* inner files - those generated when processing archive and container files), before
* the actual scanning takes place.
*
* @param fd File descriptor which is about to be scanned.
* @param type File type detected via magic - i.e. NOT on the fly - (e.g. "CL_TYPE_MSEXE").
* @param context Opaque application provided data.
* @return CL_CLEAN = File is scanned.
* @return CL_BREAK = Allowed by callback - file is skipped and marked as clean.
* @return CL_VIRUS = Blocked by callback - file is skipped and marked as infected.
*/
typedef cl_error_t (*clcb_pre_cache)(int fd, const char *type, void *context);
/**
* @brief Set a custom pre-cache callback function.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_pre_cache(struct cl_engine *engine, clcb_pre_cache callback);
/*
* Attributes of each layer in scan.
*/
#define LAYER_ATTRIBUTES_NONE 0x0
#define LAYER_ATTRIBUTES_NORMALIZED 0x1 /** This layer was modified to make matching more generic, reliable. */
#define LAYER_ATTRIBUTES_DECRYPTED 0x2 /** Decryption was used to extract this layer. I.e. had to decrypt some previous layer. */
/**
* @brief File inspection callback.
*
* DISCLAIMER: This interface is to be considered unstable while we continue to evaluate it.
* We may change this interface in the future.
*
* Called for each NEW file (inner and outer).
* Provides capability to record embedded file information during a scan.
*
* @param fd Current file descriptor which is about to be scanned.
* @param type Current file type detected via magic - i.e. NOT on the fly - (e.g. "CL_TYPE_MSEXE").
* @param ancestors An array of ancestors filenames of size `recursion_level`. filenames may be NULL.
* @param parent_file_size Parent file size.
* @param file_name Current file name, or NULL if the file does not have a name or ClamAV failed to record the name.
* @param file_size Current file size.
* @param file_buffer Current file buffer pointer.
* @param recursion_level Recursion level / depth of the current file.
* @param layer_attributes See LAYER_ATTRIBUTES_* flags.
* @param context Opaque application provided data.
* @return CL_CLEAN = File is scanned.
* @return CL_BREAK = Whitelisted by callback - file is skipped and marked as clean.
* @return CL_VIRUS = Blacklisted by callback - file is skipped and marked as infected.
*/
typedef cl_error_t (*clcb_file_inspection)(int fd, const char *type, const char **ancestors, size_t parent_file_size,
const char *file_name, size_t file_size, const char *file_buffer,
uint32_t recursion_level, uint32_t layer_attributes, void *context);
/**
* @brief Set a custom file inspection callback function.
*
* DISCLAIMER: This interface is to be considered unstable while we continue to evaluate it.
* We may change this interface in the future.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_file_inspection(struct cl_engine *engine, clcb_file_inspection callback);
/**
* @brief Pre-scan callback.
*
* Called for each NEW file (inner and outer) before the scanning takes place. This is
* roughly the same as clcb_before_cache, but it is affected by clean file caching.
* This means that it won't be called if a clean cached file (inner or outer) is
* scanned a second time.
*
* @param fd File descriptor which is about to be scanned.
* @param type File type detected via magic - i.e. NOT on the fly - (e.g. "CL_TYPE_MSEXE").
* @param context Opaque application provided data.
* @return CL_CLEAN = File is scanned.
* @return CL_BREAK = Allowed by callback - file is skipped and marked as clean.
* @return CL_VIRUS = Blocked by callback - file is skipped and marked as infected.
*/
typedef cl_error_t (*clcb_pre_scan)(int fd, const char *type, void *context);
/**
* @brief Set a custom pre-scan callback function.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_pre_scan(struct cl_engine *engine, clcb_pre_scan callback);
/**
* @brief Post-scan callback.
*
* Called for each processed file (inner and outer), after the scanning is complete.
* In all-match mode, the virname will be one of the matches, but there is no
* guarantee in which order the matches will occur, thus the final virname may
* be any one of the matches.
*
* @param fd File descriptor which was scanned.
* @param result The scan result for the file.
* @param virname A signature name if there was one or more matches.
* @param context Opaque application provided data.
* @return Scan result is not overridden.
* @return CL_BREAK = Allowed by callback - scan result is set to CL_CLEAN.
* @return Blocked by callback - scan result is set to CL_VIRUS.
*/
typedef cl_error_t (*clcb_post_scan)(int fd, int result, const char *virname, void *context);
/**
* @brief Set a custom post-scan callback function.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_post_scan(struct cl_engine *engine, clcb_post_scan callback);
/**
* @brief Virus-found callback.
*
* Called for each signature match.
* If all-match is enabled, clcb_virus_found() may be called multiple times per
* scan.
*
* In addition, clcb_virus_found() does not have a return value and thus.
* can not be used to ignore the match.
*
* @param fd File descriptor which was scanned.
* @param virname Virus name.
* @param context Opaque application provided data.
*/
typedef void (*clcb_virus_found)(int fd, const char *virname, void *context);
/**
* @brief Set a custom virus-found callback function.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_virus_found(struct cl_engine *engine, clcb_virus_found callback);
/**
* @brief Signature-load callback.
*
* May be used to ignore signatures at database load time.
*
* WARNING: Some signatures (notably ldb, cbc) can be dependent upon other signatures.
* Failure to preserve dependency chains will result in database loading failure.
* It is the implementor's responsibility to guarantee consistency.
*
* @param type The signature type (e.g. "db", "ndb", "mdb", etc.)
* @param name Signature name.
* @param custom The signature is official (custom == 0) or custom (custom != 0)
* @param context Opaque application provided data
* @return 0 to load the current signature.
* @return Non-0 to skip the current signature.
*/
typedef int (*clcb_sigload)(const char *type, const char *name, unsigned int custom, void *context);
/**
* @brief Set a custom signature-load callback function.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
* @param context Opaque application provided data.
*/
extern void cl_engine_set_clcb_sigload(struct cl_engine *engine, clcb_sigload callback, void *context);
enum cl_msg {
/* leave room for more message levels in the future */
CL_MSG_INFO_VERBOSE = 32, /* verbose */
CL_MSG_WARN = 64, /* LibClamAV WARNING: */
CL_MSG_ERROR = 128 /* LibClamAV ERROR: */
};
/**
* @brief Progress callback for sig-load, engine-compile, and engine-free.
*
* Progress is complete when total_items == now_completed.
*
* Note: The callback should return CL_SUCCESS. We reserve the right to have it
* cancel the operation in the future if you return something else...
* ... but for now, the return value will be ignored.
*
* @param total_items Total number of items
* @param now_completed Number of items completed
* @param context Opaque application provided data
* @return cl_error_t reserved for future use
*/
typedef cl_error_t (*clcb_progress)(size_t total_items, size_t now_completed, void *context);
/**
* @brief Set a progress callback function to be called incrementally during a
* database load.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine
* @param callback The callback function pointer
* @param context Opaque application provided data
*/
extern void cl_engine_set_clcb_sigload_progress(struct cl_engine *engine, clcb_progress callback, void *context);
/**
* @brief Set a progress callback function to be called incrementally during an
* engine compile.
*
* Disclaimer: the number of items for this is a rough estimate of the items that
* tend to take longest to compile and doesn't represent an accurate number of
* things compiled.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine
* @param callback The callback function pointer
* @param context Opaque application provided data
*/
extern void cl_engine_set_clcb_engine_compile_progress(struct cl_engine *engine, clcb_progress callback, void *context);
/**
* @brief Set a progress callback function to be called incrementally during an
* engine free (if the engine is in fact freed).
*
* Disclaimer: the number of items for this is a rough estimate of the items that
* tend to take longest to free and doesn't represent an accurate number of
* things freed.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine
* @param callback The callback function pointer
* @param context Opaque application provided data
*/
extern void cl_engine_set_clcb_engine_free_progress(struct cl_engine *engine, clcb_progress callback, void *context);
/**
* @brief Logging message callback for info, warning, and error messages.
*
* The specified callback will be called instead of logging to stderr.
* Messages of lower severity than specified are logged as usual.
*
* Callback may be used to silence logging by assigning a do-nothing function.
* Does not affect debug log messages.
*
* Just like with cl_debug() this must be called before going multithreaded.
* Callable before cl_init, if you want to log messages from cl_init() itself.
*
* You can use context of cl_scandesc_callback to convey more information to
* the callback (such as the filename!).
*
* Note: setting a 2nd callbacks overwrites previous, multiple callbacks are not
* supported.
*
* @param severity Message severity (CL_MSG_INFO_VERBOSE, CL_MSG_WARN, or CL_MSG_ERROR).
* @param fullmsg The log message including the "LibClamAV <severity>: " prefix.
* @param msg The log message.
* @param context Opaque application provided data.
*/
typedef void (*clcb_msg)(enum cl_msg severity, const char *fullmsg, const char *msg, void *context);
/**
* @brief Set a custom logging message callback function for all of libclamav.
*
* @param callback The callback function pointer.
*/
extern void cl_set_clcb_msg(clcb_msg callback);
/**
* @brief LibClamAV hash stats callback.
*
* Callback that provides the hash of a scanned sample if a signature alerted.
* Provides a mechanism to record detection statistics.
*
* @param fd File descriptor if available, else -1.
* @param size Sample size
* @param md5 Sample md5 hash
* @param virname Signature name that the sample matched against
* @param context Opaque application provided data
*/
typedef void (*clcb_hash)(int fd, unsigned long long size, const unsigned char *md5, const char *virname, void *context);
/**
* @brief Set a custom hash stats callback function.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_hash(struct cl_engine *engine, clcb_hash callback);
/**
* @brief Archive meta matching callback function.
*
* May be used to block archive/container samples based on archive metadata.
* Function is invoked multiple times per archive. Typically once per contained file.
*
* Note: Used by the --archive-verbose clamscan option. Overriding this will alter
* the output from --archive-verbose.
*
* @param container_type String name of type (CL_TYPE).
* @param fsize_container Sample size
* @param filename Filename associated with the data in archive.
* @param fsize_real Size of file after decompression (according to the archive).
* @param is_encrypted Boolean non-zero if the contained file is encrypted.
* @param filepos_container File index in container.
* @param context Opaque application provided data.
* @return CL_VIRUS to block (alert on)
* @return CL_CLEAN to continue scanning
*/
typedef cl_error_t (*clcb_meta)(const char *container_type, unsigned long fsize_container, const char *filename,
unsigned long fsize_real, int is_encrypted, unsigned int filepos_container, void *context);
/**
* @brief Set a custom archive metadata matching callback function.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_meta(struct cl_engine *engine, clcb_meta callback);
/**
* @brief File properties callback function.
*
* Invoked after a scan the CL_SCAN_GENERAL_COLLECT_METADATA general scan option
* is enabled and libclamav was built with json support.
*
* @param j_propstr File properties/metadata in a JSON encoded string.
* @param rc The cl_error_t return code from the scan.
* @param cbdata Opaque application provided data.
*/
typedef int (*clcb_file_props)(const char *j_propstr, int rc, void *cbdata);
/**
* @brief Set a custom file properties callback function.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_file_props(struct cl_engine *engine, clcb_file_props callback);
/**
* @brief generic data callback function.
*
* Callback handler prototype for callbacks passing back data and application context.
*
* @param data A pointer to some data. Should be treated as read-only and may be freed after callback.
* @param data_len The length of data.
* @param cbdata Opaque application provided data.
*/
typedef int (*clcb_generic_data)(const unsigned char *const data, const size_t data_len, void *cbdata);
/**
* @brief Set a custom VBA macro callback function.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_vba(struct cl_engine *engine, clcb_generic_data callback);
/* ----------------------------------------------------------------------------
* Statistics/telemetry gathering callbacks.
*
* The statistics callback functions may be used to implement a telemetry
* gathering feature.
*
* The structure definition for `cbdata` is entirely up to the caller, as are
* the implementations of each of the callback functions defined below.
*/
/**
* @brief Set a pointer the caller-defined cbdata structure.
*
* The data must persist at least until `clcb_stats_submit()` is called, or
* `clcb_stats_flush()` is called (optional).
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The scanning engine.
* @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
*/
extern void cl_engine_set_stats_set_cbdata(struct cl_engine *engine, void *cbdata);
/**
* @brief Add sample metadata to the statistics for a sample that matched on a signature.
*
* @param virname Name of the signature that matched.
* @param md5 Sample hash.
* @param size Sample size.
* @param sections PE section data, if applicable.
* @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
*/
typedef void (*clcb_stats_add_sample)(const char *virname, const unsigned char *md5, size_t size, stats_section_t *sections, void *cbdata);
/**
* @brief Set a custom callback function to add sample metadata to a statistics report.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_stats_add_sample(struct cl_engine *engine, clcb_stats_add_sample callback);
/**
* @brief Remove a specific sample from the statistics report.
*
* @param virname Name of the signature that matched.
* @param md5 Sample hash.
* @param size Sample size.
* @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
*/
typedef void (*clcb_stats_remove_sample)(const char *virname, const unsigned char *md5, size_t size, void *cbdata);
/**
* @brief Set a custom callback function to remove sample metadata from a statistics report.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_stats_remove_sample(struct cl_engine *engine, clcb_stats_remove_sample callback);
/**
* @brief Decrement the hit count listed in the statistics report for a specific sample.
*
* @param virname Name of the signature that matched.
* @param md5 Sample hash.
* @param size Sample size.
* @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
*/
typedef void (*clcb_stats_decrement_count)(const char *virname, const unsigned char *md5, size_t size, void *cbdata);
/**
* @brief Set a custom callback function to decrement the hit count listed in the statistics report for a specific sample.
*
* This function may remove the sample from the report if the hit count is decremented to 0.
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_stats_decrement_count(struct cl_engine *engine, clcb_stats_decrement_count callback);
/**
* @brief Function to submit a statistics report.
*
* @param engine The initialized scanning engine.
* @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
*/
typedef void (*clcb_stats_submit)(struct cl_engine *engine, void *cbdata);
/**
* @brief Set a custom callback function to submit the statistics report.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_stats_submit(struct cl_engine *engine, clcb_stats_submit callback);
/**
* @brief Function to flush/free the statistics report data.
*
* @param engine The initialized scanning engine.
* @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
*/
typedef void (*clcb_stats_flush)(struct cl_engine *engine, void *cbdata);
/**
* @brief Set a custom callback function to flush/free the statistics report data.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_stats_flush(struct cl_engine *engine, clcb_stats_flush callback);
/**
* @brief Function to get the number of samples listed in the statistics report.
*
* @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
*/
typedef size_t (*clcb_stats_get_num)(void *cbdata);
/**
* @brief Set a custom callback function to get the number of samples listed in the statistics report.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_stats_get_num(struct cl_engine *engine, clcb_stats_get_num callback);
/**
* @brief Function to get the size of memory used to store the statistics report.
*
* @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
*/
typedef size_t (*clcb_stats_get_size)(void *cbdata);
/**
* @brief Set a custom callback function to get the size of memory used to store the statistics report.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.
* @param callback The callback function pointer.
*/
extern void cl_engine_set_clcb_stats_get_size(struct cl_engine *engine, clcb_stats_get_size callback);
/**
* @brief Function to get the machine's unique host ID.
*
* @param cbdata The statistics data. Probably a pointer to a malloc'd struct.
*/
typedef char *(*clcb_stats_get_hostid)(void *cbdata);
/**
* @brief Set a custom callback function to get the machine's unique host ID.
*
* Caution: changing options for an engine that is in-use is not thread-safe!
*
* @param engine The initialized scanning engine.