/
lua_task.c
6945 lines (5983 loc) · 165 KB
/
lua_task.c
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 2016 Vsevolod Stakhov
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#include "lua_common.h"
#include "lua_url.h"
#include "message.h"
#include "images.h"
#include "archives.h"
#include "utlist.h"
#include "unix-std.h"
#include "libmime/smtp_parsers.h"
#include "libserver/mempool_vars_internal.h"
#include "libserver/dkim.h"
#include "libserver/task.h"
#include "libserver/cfg_file_private.h"
#include "libmime/scan_result_private.h"
#include "libstat/stat_api.h"
#include "libserver/maps/map_helpers.h"
#include <math.h>
/***
* @module rspamd_task
* This module provides routines for tasks manipulation in rspamd. Tasks usually
* represent messages being scanned, and this API provides access to such elements
* as headers, symbols, metrics and so on and so forth. Normally, task objects
* are passed to the lua callbacks allowing to check specific properties of messages
* and add the corresponding symbols to the scan's results.
@example
rspamd_config.DATE_IN_PAST = function(task)
local dm = task:get_date{format = 'message', gmt = true}
local dt = task:get_date{format = 'connect', gmt = true}
-- A day
if dt - dm > 86400 then
return true
end
return false
end
*/
/* Task methods */
/***
* @function rspamd_task.create([cfg])
* Create a new empty task
* @return {rspamd_task} new task
*/
LUA_FUNCTION_DEF (task, create);
/***
* @function rspamd_task.load_from_file(filename[, cfg])
* Loads a message from specific file
* @return {boolean,rspamd_task|error} status + new task or error message
*/
LUA_FUNCTION_DEF (task, load_from_file);
/***
* @function rspamd_task.load_from_string(message[, cfg])
* Loads a message from specific file
* @return {boolean,rspamd_task|error} status + new task or error message
*/
LUA_FUNCTION_DEF (task, load_from_string);
/***
* @method task:get_message()
* Returns task raw message content as opaque text
* @return {rspamd_text} task raw content
*/
LUA_FUNCTION_DEF (task, get_message);
/***
* @method task:set_message(msg)
* Updates task message with another message; It also parses a message to
* fill the internal structures.
* Input might be a string, a lua_text or a table of the former stuff.
* @param {string/text/table} msg new message to set
* @return {boolean,number} if a message has been set + its raw size
*/
LUA_FUNCTION_DEF (task, set_message);
/***
* @method task:process_message()
* Parses message
*/
LUA_FUNCTION_DEF (task, process_message);
/***
* @method task:get_cfg()
* Get configuration object for a task.
* @return {rspamd_config} (config.md)[configuration object] for the task
*/
LUA_FUNCTION_DEF (task, get_cfg);
LUA_FUNCTION_DEF (task, set_cfg);
LUA_FUNCTION_DEF (task, destroy);
/***
* @method task:get_mempool()
* Returns memory pool valid for a lifetime of task. It is used internally by
* many rspamd routines.
* @return {rspamd_mempool} memory pool object
*/
LUA_FUNCTION_DEF (task, get_mempool);
/***
* @method task:get_session()
* Returns asynchronous session object that is used by many rspamd asynchronous
* utilities internally.
* @return {rspamd_session} session object
*/
LUA_FUNCTION_DEF (task, get_session);
/***
* @method task:set_session(session)
* Sets new async session for a task
*/
LUA_FUNCTION_DEF (task, set_session);
/***
* @method task:get_ev_base()
* Return asynchronous event base for using in callbacks and resolver.
* @return {rspamd_ev_base} event base
*/
LUA_FUNCTION_DEF (task, get_ev_base);
/***
* @method task:get_worker()
* Returns a worker object associated with the task
* @return {rspamd_worker} worker object
*/
LUA_FUNCTION_DEF (task, get_worker);
/***
* @method task:insert_result([enforce_symbol,]symbol, weight[, option1, ...])
* Insert specific symbol to the tasks scanning results assigning the initial
* weight to it.
* @param {boolean} enforce_symbol if represented and true, then insert symbol even if it is not registered in the metric
* @param {string} symbol symbol to insert
* @param {number} weight initial weight (this weight is multiplied by the metric weight)
* @param {string} options list of optional options attached to a symbol inserted
@example
local function cb(task)
if task:get_header('Some header') then
task:insert_result('SOME_HEADER', 1.0, 'Got some header')
end
end
*/
LUA_FUNCTION_DEF (task, insert_result);
/***
* @method task:insert_result_named(shadow_result, [enforce_symbol,]symbol, weight[, option1, ...])
* Insert specific symbol to the tasks scanning results assigning the initial
* weight to it.
* @param {string} shadow_result name of shadow result
* @param {boolean} enforce_symbol if represented and true, then insert symbol even if it is not registered in the metric
* @param {string} symbol symbol to insert
* @param {number} weight initial weight (this weight is multiplied by the metric weight)
* @param {string} options list of optional options attached to a symbol inserted
*/
LUA_FUNCTION_DEF (task, insert_result_named);
/***
* @method task:adjust_result(symbol, score[, option1, ...])
* Alters the existing symbol's score to a new score. It is not affected by
* metric score or grow factor. You can also add new options
* using this method. Symbol must be already inserted into metric or an error
* will be emitted.
* @param {string} symbol symbol to adjust
* @param {number} score this value is NOT multiplied by the metric score
* @param {string/table} options list of optional options attached to a symbol adjusted
*/
LUA_FUNCTION_DEF (task, adjust_result);
/***
* @method task:set_pre_result(action, [message, [module], [score], [priority], [flags])
* Sets pre-result for a task. It is used in pre-filters to specify early result
* of the task scanned. If a pre-filter sets some result, then further processing
* may be skipped. For selecting action it is possible to use global table
* `rspamd_actions` or a string value:
*
* - `reject`: reject message permanently
* - `add header`: add spam header
* - `rewrite subject`: rewrite subject to spam subject
* - `greylist`: greylist message
* - `accept` or `no action`: whitelist message
*
* This function also accepts a table from Rspamd 2.6 with the following keys:
* - action: string required
* - message: string
* - module: string
* - score: number
* - priority: integer
* - flags: flags string
* - result: named result if needed
*
* @param {rspamd_action or string} action a numeric or string action value
* @param {string} message action message
* @param {string} module optional module name
* @param {number/nil} score optional explicit score
* @param {number/nil} priority optional explicit priority
* @param {string/nil} flags optional flags (e.g. 'least' for least action)
@example
local function cb(task)
local gr = task:get_header('Greylist')
if gr and gr == 'greylist' then
task:set_pre_result('soft reject', 'Greylisting required')
end
end
*/
LUA_FUNCTION_DEF (task, set_pre_result);
/***
* @method task:has_pre_result()
* Returns true if task has some pre-result being set
*
* @return {boolean} true if task has some pre-result being set
*/
LUA_FUNCTION_DEF (task, has_pre_result);
/***
* @method task:append_message(message, [category])
* Adds a message to scanning output.
* @param {string} message
* @param {category} message category
@example
local function cb(task)
task:append_message('Example message')
end
*/
LUA_FUNCTION_DEF (task, append_message);
/***
* @method task:get_urls([need_emails|list_protos][, need_images])
* Get all URLs found in a message. Telephone urls and emails are not included unless explicitly asked in `list_protos`
* @param {boolean} need_emails if `true` then reutrn also email urls, this can be a comma separated string of protocols desired or a table (e.g. `mailto` or `telephone`)
* @param {boolean} need_images return urls from images (<img src=...>) as well
* @return {table rspamd_url} list of all urls found
@example
local function phishing_cb(task)
local urls = task:get_urls({'https', 'http'});
if urls then
for _,url in ipairs(urls) do
if url:is_phished() then
return true
end
end
end
return false
end
*/
LUA_FUNCTION_DEF (task, get_urls);
/***
* @method task:has_urls([need_emails])
* Returns 'true' if a task has urls listed
* @param {boolean} need_emails if `true` then reutrn also email urls
* @return {boolean} true if a task has urls (urls or emails if `need_emails` is true)
*/
LUA_FUNCTION_DEF (task, has_urls);
/***
* @method task:inject_url(url)
* Inserts an url into a task (useful for redirected urls)
* @param {lua_url} url url to inject
*/
LUA_FUNCTION_DEF (task, inject_url);
/***
* @method task:get_content()
* Get raw content for the specified task
* @return {text} the data contained in the task
*/
LUA_FUNCTION_DEF (task, get_content);
/***
* @method task:get_filename()
* Returns filename for a specific task
* @return {string|nil} filename or nil if unknown
*/
LUA_FUNCTION_DEF (task, get_filename);
/***
* @method task:get_rawbody()
* Get raw body for the specified task
* @return {text} the data contained in the task
*/
LUA_FUNCTION_DEF (task, get_rawbody);
/***
* @method task:get_emails()
* Get all email addresses found in a message.
* @return {table rspamd_url} list of all email addresses found
*/
LUA_FUNCTION_DEF (task, get_emails);
/***
* @method task:get_text_parts()
* Get all text (and HTML) parts found in a message
* @return {table rspamd_text_part} list of text parts
*/
LUA_FUNCTION_DEF (task, get_text_parts);
/***
* @method task:get_parts()
* Get all mime parts found in a message
* @return {table rspamd_mime_part} list of mime parts
*/
LUA_FUNCTION_DEF (task, get_parts);
/***
* @method task:get_meta_words([how='stem'])
* Get meta words from task (subject and displayed names)
* - `stem`: stemmed words (default)
* - `norm`: normalised words (utf normalised + lowercased)
* - `raw`: raw words in utf (if possible)
* - `full`: list of tables, each table has the following fields:
* - [1] - stemmed word
* - [2] - normalised word
* - [3] - raw word
* - [4] - flags (table of strings)
*/
LUA_FUNCTION_DEF (task, get_meta_words);
/***
* @method task:get_request_header(name)
* Get value of a HTTP request header.
* @param {string} name name of header to get
* @return {rspamd_text} value of an HTTP header
*/
LUA_FUNCTION_DEF (task, get_request_header);
/***
* @method task:set_request_header(name, value)
* Set value of a HTTP request header. If value is omitted, then a header is removed
* @param {string} name name of header to get
* @param {rspamd_text/string} value new header's value
*/
LUA_FUNCTION_DEF (task, set_request_header);
/***
* @method task:get_subject()
* Returns task subject (either from the protocol override or from a header)
* @return {string} value of a subject (decoded)
*/
LUA_FUNCTION_DEF (task, get_subject);
/***
* @method task:get_header(name[, case_sensitive])
* Get decoded value of a header specified with optional case_sensitive flag.
* By default headers are searched in caseless matter.
* @param {string} name name of header to get
* @param {boolean} case_sensitive case sensitiveness flag to search for a header
* @return {string} decoded value of a header
*/
LUA_FUNCTION_DEF (task, get_header);
/***
* @method task:has_header(name[, case_sensitive])
* Get decoded value of a header specified with optional case_sensitive flag.
* By default headers are searched in caseless matter.
* @param {string} name name of header to get
* @param {boolean} case_sensitive case sensitiveness flag to search for a header
* @return {boolean},{number} true if header exists, the second value is number of headers with this name
*/
LUA_FUNCTION_DEF (task, has_header);
/***
* @method task:get_header_raw(name[, case_sensitive])
* Get raw value of a header specified with optional case_sensitive flag.
* By default headers are searched in caseless matter.
* @param {string} name name of header to get
* @param {boolean} case_sensitive case sensitiveness flag to search for a header
* @return {string} raw value of a header
*/
LUA_FUNCTION_DEF (task, get_header_raw);
/***
* @method task:get_header_full(name[, case_sensitive])
* Get raw value of a header specified with optional case_sensitive flag.
* By default headers are searched in caseless matter. This method returns more
* information about the header as a list of tables with the following structure:
*
* - `name` - name of a header
* - `value` - raw value of a header
* - `decoded` - decoded value of a header
* - `tab_separated` - `true` if a header and a value are separated by `tab` character
* - `empty_separator` - `true` if there are no separator between a header and a value
* @param {string} name name of header to get
* @param {boolean} case_sensitive case sensitiveness flag to search for a header
* @return {list of tables} all values of a header as specified above
@example
function check_header_delimiter_tab(task, header_name)
for _,rh in ipairs(task:get_header_full(header_name)) do
if rh['tab_separated'] then return true end
end
return false
end
*/
LUA_FUNCTION_DEF (task, get_header_full);
/***
* @method task:get_header_count(name[, case_sensitive])
* Lightweight version if you need just a header's count
* * By default headers are searched in caseless matter.
* @param {string} name name of header to get
* @param {boolean} case_sensitive case sensitiveness flag to search for a header
* @return {number} number of header's occurrencies or 0 if not found
*/
LUA_FUNCTION_DEF (task, get_header_count);
/***
* @method task:get_raw_headers()
* Get all undecoded headers of a message as a string
* @return {rspamd_text} all raw headers for a message as opaque text
*/
LUA_FUNCTION_DEF (task, get_raw_headers);
/***
* @method task:get_received_headers()
* Returns a list of tables of parsed received headers. A tables returned have
* the following structure:
*
* - `from_hostname` - string that represents hostname provided by a peer
* - `from_ip` - string representation of IP address as provided by a peer
* - `real_hostname` - hostname as resolved by MTA
* - `real_ip` - string representation of IP as resolved by PTR request of MTA
* - `by_hostname` - MTA hostname
* - `proto` - protocol, e.g. ESMTP or ESMTPS
* - `timestamp` - received timestamp
* - `for` - for value (unparsed mailbox)
*
* Please note that in some situations rspamd cannot parse all the fields of received headers.
* In that case you should check all strings for validity.
* @return {table of tables} list of received headers described above
*/
LUA_FUNCTION_DEF (task, get_received_headers);
/***
* @method task:get_queue_id()
* Returns queue ID of the message being processed.
*/
LUA_FUNCTION_DEF (task, get_queue_id);
/***
* @method task:get_uid()
* Returns ID of the task being processed.
*/
LUA_FUNCTION_DEF (task, get_uid);
/***
* @method task:get_resolver()
* Returns ready to use rspamd_resolver object suitable for making asynchronous DNS requests.
* @return {rspamd_resolver} resolver object associated with the task's session
* @example
local logger = require "rspamd_logger"
local function task_cb(task)
local function dns_cb(resolver, to_resolve, results, err)
-- task object is available due to closure
task:inc_dns_req()
if results then
logger.info(string.format('<%s> [%s] resolved for symbol: %s',
task:get_message_id(), to_resolve, 'EXAMPLE_SYMBOL'))
task:insert_result('EXAMPLE_SYMBOL', 1)
end
end
local r = task:get_resolver()
r:resolve_a(task:get_session(), task:get_mempool(), 'example.com', dns_cb)
end
*/
LUA_FUNCTION_DEF (task, get_resolver);
/***
* @method task:set_resolver(resolver)
* Sets rspamd_resolver for a specified task.
*/
LUA_FUNCTION_DEF (task, set_resolver);
/***
* @method task:inc_dns_req()
* Increment number of DNS requests for the task. Is used just for logging purposes.
*/
LUA_FUNCTION_DEF (task, inc_dns_req);
/***
* @method task:get_dns_req()
* Get number of dns requests being sent in the task
* @return {number} number of DNS requests
*/
LUA_FUNCTION_DEF (task, get_dns_req);
/***
* @method task:has_recipients([type])
* Return true if there are SMTP or MIME recipients for a task.
* @param {integer|string} type if specified has the following meaning: `0` or `any` means try SMTP recipients and fallback to MIME if failed, `1` or `smtp` means checking merely SMTP recipients and `2` or `mime` means MIME recipients only
* @return {bool} `true` if there are recipients of the following type
*/
LUA_FUNCTION_DEF (task, has_recipients);
/***
* @method task:get_recipients([type])
* Return SMTP or MIME recipients for a task. This function returns list of internet addresses each one is a table with the following structure:
*
* - `name` - name of internet address in UTF8, e.g. for `Vsevolod Stakhov <blah@foo.com>` it returns `Vsevolod Stakhov`
* - `addr` - address part of the address
* - `user` - user part (if present) of the address, e.g. `blah`
* - `domain` - domain part (if present), e.g. `foo.com`
* @param {integer|string} type if specified has the following meaning: `0` or `any` means try SMTP recipients and fallback to MIME if failed, `1` or `smtp` means checking merely SMTP recipients and `2` or `mime` means MIME recipients only
* @return {list of addresses} list of recipients or `nil`
*/
LUA_FUNCTION_DEF (task, get_recipients);
/***
* @method task:get_principal_recipient()
* Returns a single string with so called `principal recipient` for a message. The order
* of check is the following:
*
* - deliver-to request header
* - the first recipient (envelope)
* - the first recipient (mime)
* @return {string} principal recipient
*/
LUA_FUNCTION_DEF (task, get_principal_recipient);
/***
* @method task:get_reply_sender()
* Returns a single string with address that should be used to reply on a message
*
* - reply-to header
* - from header
* - smtp from as a last resort
* @return {address} email address
*/
LUA_FUNCTION_DEF (task, get_reply_sender);
/***
* @method task:set_recipients([type], {rcpt1, rcpt2...})
* Sets sender for a task. This function accepts table that will be converted to the address.
* If some fields are missing they are subsequently reconstructed by this function. E.g. if you
* specify 'user' and 'domain', then address and raw string will be reconstructed
*
* - `name` - name of internet address in UTF8, e.g. for `Vsevolod Stakhov <blah@foo.com>` it returns `Vsevolod Stakhov`
* - `addr` - address part of the address
* - `user` - user part (if present) of the address, e.g. `blah`
* - `domain` - domain part (if present), e.g. `foo.com`
* @param {integer|string} type if specified has the following meaning: `0` or `any` means try SMTP recipients and fallback to MIME if failed, `1` or `smtp` means checking merely SMTP recipients and `2` or `mime` means MIME recipients only
* @param {list of tables} recipients recipients to set
* @return {boolean} result of the operation
*/
LUA_FUNCTION_DEF (task, set_recipients);
/***
* @method task:has_from([type])
* Return true if there is SMTP or MIME sender for a task.
* @param {integer|string} type if specified has the following meaning: `0` or `any` means try SMTP recipients and fallback to MIME if failed, `1` or `smtp` means checking merely SMTP recipients and `2` or `mime` means MIME recipients only
* @return {bool} `true` if there is sender of the following type
*/
LUA_FUNCTION_DEF (task, has_from);
/***
* @method task:get_from([type])
* Return SMTP or MIME sender for a task. This function returns an internet address which one is a table with the following structure:
*
* - `raw` - the original value without any processing
* - `name` - name of internet address in UTF8, e.g. for `Vsevolod Stakhov <blah@foo.com>` it returns `Vsevolod Stakhov`
* - `addr` - address part of the address
* - `user` - user part (if present) of the address, e.g. `blah`
* - `domain` - domain part (if present), e.g. `foo.com`
* - `flags` - table with following keys set to true if given condition fulfilled:
* - [valid] - valid SMTP address in conformity with https://tools.ietf.org/html/rfc5321#section-4.1.
* - [ip] - domain is IPv4/IPv6 address
* - [braced] - angled `<blah@foo.com>` address
* - [quoted] - quoted user part
* - [empty] - empty address
* - [backslash] - user part contains backslash
* - [8bit] - contains 8bit characters
* @param {integer|string} type if specified has the following meaning: `0` or `any` means try SMTP sender and fallback to MIME if failed, `1` or `smtp` means checking merely SMTP sender and `2` or `mime` means MIME `From:` only
* @return {address} sender or `nil`
*/
LUA_FUNCTION_DEF (task, get_from);
/***
* @method task:set_from(type, addr)
* Sets sender for a task. This function accepts table that will be converted to the address.
* If some fields are missing they are subsequently reconstructed by this function. E.g. if you
* specify 'user' and 'domain', then address and raw string will be reconstructed
*
* - `name` - name of internet address in UTF8, e.g. for `Vsevolod Stakhov <blah@foo.com>` it returns `Vsevolod Stakhov`
* - `addr` - address part of the address
* - `user` - user part (if present) of the address, e.g. `blah`
* - `domain` - domain part (if present), e.g. `foo.com`
* @param {integer|string} type if specified has the following meaning: `0` or `any` means try SMTP sender and fallback to MIME if failed, `1` or `smtp` means checking merely SMTP sender and `2` or `mime` means MIME `From:` only
* @param {table
* @return {boolean} success or not
*/
LUA_FUNCTION_DEF (task, set_from);
/***
* @method task:get_user()
* Returns authenticated user name for this task if specified by an MTA.
* @return {string} username or nil
*/
LUA_FUNCTION_DEF (task, get_user);
/***
* @method task:set_user([username])
* Sets or resets (if username is not specified) authenticated user name for this task.
* @return {string} the previously set username or nil
*/
LUA_FUNCTION_DEF (task, set_user);
/***
* @method task:get_from_ip()
* Returns [ip_addr](ip.md) object of a sender that is provided by MTA
* @return {rspamd_ip} ip address object
*/
LUA_FUNCTION_DEF (task, get_from_ip);
/***
* @method task:set_from_ip(str)
* Set tasks's IP address based on the passed string
* @param {string} str string representation of ip
*/
LUA_FUNCTION_DEF (task, set_from_ip);
LUA_FUNCTION_DEF (task, get_from_ip_num);
/***
* @method task:get_client_ip()
* Returns [ip_addr](ip.md) object of a client connected to rspamd (normally, it is an IP address of MTA)
* @return {rspamd_ip} ip address object
*/
LUA_FUNCTION_DEF (task, get_client_ip);
/***
* @method task:get_helo()
* Returns the value of SMTP helo provided by MTA.
* @return {string} HELO value
*/
LUA_FUNCTION_DEF (task, get_helo);
LUA_FUNCTION_DEF (task, set_helo);
/***
* @method task:get_hostname()
* Returns the value of sender's hostname provided by MTA
* @return {string} hostname value
*/
LUA_FUNCTION_DEF (task, get_hostname);
LUA_FUNCTION_DEF (task, set_hostname);
/***
* @method task:get_images()
* Returns list of all images found in a task as a table of `rspamd_image`.
* Each image has the following methods:
*
* * `get_width` - return width of an image in pixels
* * `get_height` - return height of an image in pixels
* * `get_type` - return string representation of image's type (e.g. 'jpeg')
* * `get_filename` - return string with image's file name
* * `get_size` - return size in bytes
* @return {list of rspamd_image} images found in a message
*/
LUA_FUNCTION_DEF (task, get_images);
/***
* @method task:get_archives()
* Returns list of all archives found in a task as a table of `rspamd_archive`.
* Each archive has the following methods available:
*
* * `get_files` - return list of strings with filenames inside archive
* * `get_files_full` - return list of tables with all information about files
* * `is_encrypted` - return true if an archive is encrypted
* * `get_type` - return string representation of image's type (e.g. 'zip')
* * `get_filename` - return string with archive's file name
* * `get_size` - return size in bytes
* @return {list of rspamd_archive} archives found in a message
*/
LUA_FUNCTION_DEF (task, get_archives);
/***
* @method task:get_dkim_results()
* Returns list of all dkim check results as table of maps. Callee must ensure that
* dkim checks have been completed by adding dependency on `DKIM_TRACE` symbol.
* Fields in map:
*
* * `result` - string result of check:
* - `reject`
* - `allow`
* - `tempfail`
* - `permfail`
* - `not found`
* - `bad record`
* * `domain` - dkim domain
* * `selector` - dkim selector
* * `bhash` - short version of b tag (8 base64 symbols)
* * `fail_reason` - reason of failure (if applicable)
* @return {list of maps} dkim check results
*/
LUA_FUNCTION_DEF (task, get_dkim_results);
/***
* @method task:get_symbol(name, [shadow_result_name])
* Searches for a symbol `name` in all metrics results and returns a list of tables
* one per metric that describes the symbol inserted. Please note that this function
* is intended to return values for **inserted** symbols, so if this symbol was not
* inserted it won't be in the function's output. This method is useful for post-filters mainly.
* The symbols are returned as the list of the following tables:
*
* - `metric` - name of metric
* - `score` - score of a symbol in that metric
* - `options` - a table of strings representing options of a symbol
* - `group` - a group of symbol (or 'ungrouped')
* @param {string} name symbol's name
* @return {list of tables} list of tables or nil if symbol was not found
*/
LUA_FUNCTION_DEF (task, get_symbol);
/***
* @method task:get_symbols_all()
* Returns array of symbols matched in default metric with all metadata
* @return {table} table of tables formatted as in `task:get_symbol()` except that `metric` is absent and `name` is added
*/
LUA_FUNCTION_DEF (task, get_symbols_all);
/***
* @method task:get_symbols([shadow_result_name])
* Returns array of all symbols matched for this task
* @return {table, table} table of strings with symbols names + table of theirs scores
*/
LUA_FUNCTION_DEF (task, get_symbols);
/***
* @method task:get_groups([need_private])
* Returns a map [group -> group_score] for matched group. If `need_private` is
* unspecified, then the global option `public_groups_only` is used for default.
* @return {table, number} a map [group -> group_score]
*/
LUA_FUNCTION_DEF (task, get_groups);
/***
* @method task:get_symbols_numeric()
* Returns array of all symbols matched for this task
* @return {table|number, table|number} table of numbers with symbols ids + table of theirs scores
*/
LUA_FUNCTION_DEF (task, get_symbols_numeric);
/***
* @method task:get_symbols_tokens()
* Returns array of all symbols as statistical tokens
* @return {table|number} table of numbers
*/
LUA_FUNCTION_DEF (task, get_symbols_tokens);
/***
* @method task:process_ann_tokens(symbols, ann_tokens, offset, [min])
* Processes ann tokens
* @param {table|string} symbols list of symbols in this profile
* @param {table|number} ann_tokens list of tokens (including metatokens)
* @param {integer} offset offset for symbols token (#metatokens)
* @param {number} min minimum value for symbols found (e.g. for 0 score symbols)
* @return nothing
*/
LUA_FUNCTION_DEF (task, process_ann_tokens);
/***
* @method task:has_symbol(name, [shadow_result_name])
* Fast path to check if a specified symbol is in the task's results
* @param {string} name symbol's name
* @return {boolean} `true` if symbol has been found
*/
LUA_FUNCTION_DEF (task, has_symbol);
/***
* @method task:enable_symbol(name)
* Enable specified symbol for this particular task
* @param {string} name symbol's name
* @return {boolean} `true` if symbol has been found
*/
LUA_FUNCTION_DEF (task, enable_symbol);
/***
* @method task:disable_symbol(name)
* Disable specified symbol for this particular task
* @param {string} name symbol's name
* @return {boolean} `true` if symbol has been found
*/
LUA_FUNCTION_DEF (task, disable_symbol);
/***
* @method task:get_date(type[, gmt])
* Returns timestamp for a connection or for a MIME message. This function can be called with a
* single table arguments with the following fields:
*
* * `format` - a format of date returned:
* - `message` - returns a mime date as integer (unix timestamp)
* - `connect` - returns a unix timestamp of a connection to rspamd
* * `gmt` - returns date in `GMT` timezone (normal for unix timestamps)
*
* By default this function returns connection time in numeric format.
* @param {string} type date format as described above
* @param {boolean} gmt gmt flag as described above
* @return {string/number} date representation according to format
* @example
rspamd_config.DATE_IN_PAST = function(task)
local dm = task:get_date{format = 'message', gmt = true}
local dt = task:get_date{format = 'connect', gmt = true}
-- A day
if dt - dm > 86400 then
return true
end
return false
end
*/
LUA_FUNCTION_DEF (task, get_date);
/***
* @method task:get_message_id()
* Returns message id of the specified task
* @return {string} if of a message
*/
LUA_FUNCTION_DEF (task, get_message_id);
/***
* @method task:get_timeval([raw])
* Returns the timestamp for a task start processing time.
* @param {boolean} raw if true then two float numbers are returned: task start timestamp and timeout event timestamp
* @return {table} table with fields as described in `struct timeval` in C
*/
LUA_FUNCTION_DEF (task, get_timeval);
/***
* @method task:get_scan_time([set])
* Returns 2 floating point numbers: scan real time and scan virtual time.
* If `set` is `true`, then the finishing time is also set (enabled by default).
* This function should be normally called on idempotent phase.
* @return {number,number} real and virtual times in seconds with floating point
*/
LUA_FUNCTION_DEF (task, get_scan_time);
/***
* @method task:get_metric_result()
* Get full result of a metric as a table:
* - `score`: current score
* - `action`: current action as a string
* - `nnegative`: number of negative rules matched
* - `npositive`: number of positive rules matched
* - `positive_score`: total score for positive rules
* - `negative_score`: total score for negative rules
* - `passthrough`: set to true if message has a passthrough result
* @return {table} metric result
*/
LUA_FUNCTION_DEF (task, get_metric_result);
/***
* @method task:get_metric_score(name)
* Get the current score of metric `name` (must be nil or 'default') . Should be used in idempotent filters only.
* @param {string} name name of a metric
* @return {number,number} 2 numbers containing the current score and required score of the metric
*/
LUA_FUNCTION_DEF (task, get_metric_score);
/***
* @method task:get_metric_action(name)
* Get the current action of metric `name` (must be nil or 'default'). Should be used in idempotent filters only.
* @param {string} name name of a metric
* @return {string} the current action of the metric as a string
*/
LUA_FUNCTION_DEF (task, get_metric_action);
/***
* @method task:set_metric_score(name, score)
* Set the current score of metric `name`. Should be used in post-filters only.
* @param {string} name name of a metric
* @param {number} score the current score of the metric
*/
LUA_FUNCTION_DEF (task, set_metric_score);
/***
* @method task:set_metric_subject(subject)
* Set the subject in the default metric
* @param {string} subject subject to set
*/
LUA_FUNCTION_DEF (task, set_metric_subject);
/***
* @method task:learn(is_spam[, classifier)
* Learn classifier `classifier` with the task. If `is_spam` is true then message
* is learnt as spam. Otherwise HAM is learnt. By default, this function learns
* `bayes` classifier.
* @param {boolean} is_spam learn spam or ham
* @param {string} classifier classifier's name
* @return {boolean} `true` if classifier has been learnt successfully
*/
LUA_FUNCTION_DEF (task, learn);
/***
* @method task:set_settings(obj)
* Set users settings object for a task. The format of this object is described
* [here](https://rspamd.com/doc/configuration/settings.html).
* @param {any} obj any lua object that corresponds to the settings format
*/
LUA_FUNCTION_DEF (task, set_settings);
/***
* @method task:set_settings_id(id)
* Set users settings id for a task (must be registered previously)
* @available 2.0+
* @param {number} id numeric id
* @return {boolean} true if settings id has been replaced from the existing one
*/
LUA_FUNCTION_DEF (task, set_settings_id);
/***
* @method task:get_settings()
* Gets users settings object for a task. The format of this object is described
* [here](https://rspamd.com/doc/configuration/settings.html).
* @return {lua object} lua object generated from UCL
*/
LUA_FUNCTION_DEF (task, get_settings);
/***
* @method task:lookup_settings(key)
* Gets users settings object with the specified key for a task.
* @param {string} key key to lookup
* @return {lua object} lua object generated from UCL
*/
LUA_FUNCTION_DEF (task, lookup_settings);
/***
* @method task:get_settings_id()
* Get numeric hash of settings id if specified for this task. 0 is returned otherwise.
* @return {number} settings-id hash
*/
LUA_FUNCTION_DEF (task, get_settings_id);
/***
* @method task:set_milter_reply(obj)
* Set special reply for milter
* @param {any} obj any lua object that corresponds to the settings format
* @example
task:set_milter_reply({
add_headers = {['X-Lua'] = 'test'},
-- 1 is the position of header to remove
remove_headers = {['DKIM-Signature'] = 1},
})
*/
LUA_FUNCTION_DEF (task, set_milter_reply);
/***
* @method task:process_re(params)
* Processes the specified regexp and returns number of captures (cached or new)
* Params is the table with the following fields (mandatory fields are marked with `*`):
* - `re`* : regular expression object
* - `type`*: type of regular expression:
* + `mime`: mime regexp
* + `header`: header regexp
* + `rawheader`: raw header expression
* + `rawmime`: raw mime regexp
* + `body`: raw body regexp
* + `url`: url regexp
* - `header`: for header and rawheader regexp means the name of header
* - `strong`: case sensitive match for headers
* @return {number} number of regexp occurrences in the task (limited by 255 so far)
*/
LUA_FUNCTION_DEF (task, process_regexp);
/***
* @method task:cache_set(key, value)
* Store some value to the task cache
* @param {string} key key to use
* @param {any} value any value (including functions and tables)
*/
LUA_FUNCTION_DEF (task, cache_set);
/***
* @method task:cache_get(key)
* Returns cached value or nil if nothing is cached
* @param {string} key key to use
* @return {any} cached value
*/
LUA_FUNCTION_DEF (task, cache_get);
/***
* @method task:get_size()
* Returns size of the task in bytes (that includes headers + parts size)
* @return {number} size in bytes
*/
LUA_FUNCTION_DEF (task, get_size);
/***
* @method task:set_flag(flag_name[, set])
* Set specific flag for task:
*
* - `no_log`: do not log task summary
* - `no_stat`: do not include task into scanned stats
* - `pass_all`: check all filters for task
* - `extended_urls`: output extended info about urls
* - `skip`: skip task processing
* - `learn_spam`: learn message as spam
* - `learn_ham`: learn message as ham
* - `broken_headers`: header data is broken for a message
* @param {string} flag to set
* @param {boolean} set set or clear flag (default is set)
@example
--[[
For messages with undefined queue ID (scanned with rspamc or WebUI)
do not include results into statistics and do not log task summary
(it will not appear in the WebUI history as well).
]]--
-- Callback function to set flags
local function no_log_stat_cb(task)
if not task:get_queue_id() then
task:set_flag('no_log')
task:set_flag('no_stat')
end
end
rspamd_config:register_symbol({
name = 'LOCAL_NO_LOG_STAT',
type = 'postfilter',
callback = no_log_stat_cb
})
*/
LUA_FUNCTION_DEF (task, set_flag);
/***
* @method task:has_flag(flag_name)
* Checks for a specific flag in task:
*
* - `no_log`: do not log task summary
* - `no_stat`: do not include task into scanned stats
* - `pass_all`: check all filters for task
* - `extended_urls`: output extended info about urls
* - `skip`: skip task processing
* - `learn_spam`: learn message as spam
* - `learn_ham`: learn message as ham
* - `broken_headers`: header data is broken for a message
* @param {string} flag to check
* @return {boolean} true if flags is set
*/
LUA_FUNCTION_DEF (task, has_flag);
/***
* @method task:get_flags()
* Get list of flags for task:
*
* - `no_log`: do not log task summary