1 ;;; spam-stat.el --- detecting spam based on statistics
3 ;; Copyright (C) 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
5 ;; Author: Alex Schroeder <alex@gnu.org>
7 ;; URL: http://www.emacswiki.org/cgi-bin/wiki.pl?SpamStat
9 ;; This file is part of GNU Emacs.
11 ;; This is free software; you can redistribute it and/or modify it
12 ;; under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 3, or (at your option)
16 ;; This is distributed in the hope that it will be useful, but WITHOUT
17 ;; ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
18 ;; or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
19 ;; License for more details.
21 ;; You should have received a copy of the GNU General Public License
22 ;; along with GNU Emacs; see the file COPYING. If not, write to the
23 ;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
24 ;; Boston, MA 02110-1301, USA.
28 ;; This implements spam analysis according to Paul Graham in "A Plan
29 ;; for Spam". The basis for all this is a statistical distribution of
30 ;; words for your spam and non-spam mails. We need this information
31 ;; in a hash-table so that the analysis can use the information when
32 ;; looking at your mails. Therefore, before you begin, you need tons
33 ;; of mails (Graham uses 4000 non-spam and 4000 spam mails for his
36 ;; The main interface to using spam-stat, are the following functions:
38 ;; `spam-stat-buffer-is-spam' -- called in a buffer, that buffer is
39 ;; considered to be a new spam mail; use this for new mail that has
40 ;; not been processed before
42 ;; `spam-stat-buffer-is-non-spam' -- called in a buffer, that buffer
43 ;; is considered to be a new non-spam mail; use this for new mail that
44 ;; has not been processed before
46 ;; `spam-stat-buffer-change-to-spam' -- called in a buffer, that
47 ;; buffer is no longer considered to be normal mail but spam; use this
48 ;; to change the status of a mail that has already been processed as
51 ;; `spam-stat-buffer-change-to-non-spam' -- called in a buffer, that
52 ;; buffer is no longer considered to be spam but normal mail; use this
53 ;; to change the status of a mail that has already been processed as
56 ;; `spam-stat-save' -- save the hash table to the file; the filename
57 ;; used is stored in the variable `spam-stat-file'
59 ;; `spam-stat-load' -- load the hash table from a file; the filename
60 ;; used is stored in the variable `spam-stat-file'
62 ;; `spam-stat-score-word' -- return the spam score for a word
64 ;; `spam-stat-score-buffer' -- return the spam score for a buffer
66 ;; `spam-stat-split-fancy' -- for fancy mail splitting; add
67 ;; the rule (: spam-stat-split-fancy) to `nnmail-split-fancy'
69 ;; This requires the following in your ~/.gnus file:
71 ;; (require 'spam-stat)
76 ;; Typical test will involve calls to the following functions:
78 ;; Reset: (spam-stat-reset)
79 ;; Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam")
80 ;; Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc")
81 ;; Save table: (spam-stat-save)
82 ;; File size: (nth 7 (file-attributes spam-stat-file))
83 ;; Number of words: (hash-table-count spam-stat)
84 ;; Test spam: (spam-stat-test-directory "~/Mail/mail/spam")
85 ;; Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc")
86 ;; Reduce table size: (spam-stat-reduce-size)
87 ;; Save table: (spam-stat-save)
88 ;; File size: (nth 7 (file-attributes spam-stat-file))
89 ;; Number of words: (hash-table-count spam-stat)
90 ;; Test spam: (spam-stat-test-directory "~/Mail/mail/spam")
91 ;; Test non-spam: (spam-stat-test-directory "~/Mail/mail/misc")
93 ;;; Dictionary Creation:
95 ;; Typically, you will filter away mailing lists etc. using specific
96 ;; rules in `nnmail-split-fancy'. Somewhere among these rules, you
97 ;; will filter spam. Here is how you would create your dictionary:
99 ;; Reset: (spam-stat-reset)
100 ;; Learn spam: (spam-stat-process-spam-directory "~/Mail/mail/spam")
101 ;; Learn non-spam: (spam-stat-process-non-spam-directory "~/Mail/mail/misc")
102 ;; Repeat for any other non-spam group you need...
103 ;; Reduce table size: (spam-stat-reduce-size)
104 ;; Save table: (spam-stat-save)
108 ;; Speed it up. Integrate with Gnus such that it uses spam and expiry
109 ;; marks to call the appropriate functions when leaving the summary
110 ;; buffer and saves the hash table when leaving Gnus. More testing:
111 ;; More mails, disabling SpamAssassin, double checking algorithm, find
112 ;; improved algorithm.
116 ;; Ted Zlatanov <tzz@lifelogs.com>
117 ;; Jesper Harder <harder@myrealbox.com>
118 ;; Dan Schmidt <dfan@dfan.org>
119 ;; Lasse Rasinen <lrasinen@iki.fi>
120 ;; Milan Zamazal <pdm@zamazal.org>
125 (require 'mail-parse
)
127 (defvar gnus-original-article-buffer
)
129 (defgroup spam-stat nil
130 "Statistical spam detection for Emacs.
131 Use the functions to build a dictionary of words and their statistical
132 distribution in spam and non-spam mails. Then use a function to determine
133 whether a buffer contains spam or not."
137 (defcustom spam-stat-file
"~/.spam-stat.el"
138 "File used to save and load the dictionary.
139 See `spam-stat-to-hash-table' for the format of the file."
143 (defcustom spam-stat-install-hooks t
144 "Whether spam-stat should install its hooks in Gnus.
145 This is set to nil if you use spam-stat through spam.el."
149 (defcustom spam-stat-unknown-word-score
0.2
150 "The score to use for unknown words.
151 Also used for words that don't appear often enough."
155 (defcustom spam-stat-max-word-length
15
156 "Only words shorter than this will be considered."
160 (defcustom spam-stat-max-buffer-length
10240
161 "Only the beginning of buffers will be analyzed.
162 This variable says how many characters this will be."
166 (defcustom spam-stat-split-fancy-spam-group
"mail.spam"
167 "Name of the group where spam should be stored.
168 If `spam-stat-split-fancy' is used in fancy splitting rules. Has
169 no effect when spam-stat is invoked through spam.el."
173 (defcustom spam-stat-split-fancy-spam-threshold
0.9
174 "Spam score threshold in spam-stat-split-fancy."
178 (defcustom spam-stat-washing-hook nil
179 "Hook applied to each message before analysis."
183 (defcustom spam-stat-score-buffer-user-functions nil
184 "List of additional scoring functions.
185 Called one by one on the buffer.
187 If all of these functions return non-nil answers, these numerical
188 answers are added to the computed spam stat score on the buffer. If
189 you defun such functions, make sure they don't return the buffer in a
190 narrowed state or such: use, for example, `save-excursion'. Each of
191 your functions is also passed the initial spam-stat score which might
194 Also be careful when defining such functions. If they take a long
195 time, they will slow down your mail splitting. Thus, if the buffer is
196 large, don't forget to use smaller regions, by wrapping your work in,
197 say, `with-spam-stat-max-buffer-size'."
201 (defcustom spam-stat-process-directory-age
90
202 "Max. age of files to be processed in directory, in days.
203 When using `spam-stat-process-spam-directory' or
204 `spam-stat-process-non-spam-directory', only files that have
205 been touched in this many days will be considered. Without
206 this filter, re-training spam-stat with several thousand messages
207 will start to take a very long time."
211 (defvar spam-stat-last-saved-at nil
212 "Time stamp of last change of spam-stat-file on this run")
214 (defvar spam-stat-syntax-table
215 (let ((table (copy-syntax-table text-mode-syntax-table
)))
216 (modify-syntax-entry ?-
"w" table
)
217 (modify-syntax-entry ?_
"w" table
)
218 (modify-syntax-entry ?.
"w" table
)
219 (modify-syntax-entry ?
! "w" table
)
220 (modify-syntax-entry ??
"w" table
)
221 (modify-syntax-entry ?
+ "w" table
)
223 "Syntax table used when processing mails for statistical analysis.
224 The important part is which characters are word constituents.")
226 (defvar spam-stat-dirty nil
227 "Whether the spam-stat database needs saving.")
229 (defvar spam-stat-buffer nil
230 "Buffer to use for scoring while splitting.
231 This is set by hooking into Gnus.")
233 (defvar spam-stat-buffer-name
" *spam stat buffer*"
234 "Name of the `spam-stat-buffer'.")
236 (defvar spam-stat-coding-system
237 (if (mm-coding-system-p 'emacs-mule
) 'emacs-mule
'raw-text
)
238 "Coding system used for `spam-stat-file'.")
242 (defun spam-stat-store-current-buffer ()
243 "Store a copy of the current buffer in `spam-stat-buffer'."
244 (let ((buf (current-buffer)))
245 (with-current-buffer (get-buffer-create spam-stat-buffer-name
)
247 (insert-buffer-substring buf
)
248 (setq spam-stat-buffer
(current-buffer)))))
250 (defun spam-stat-store-gnus-article-buffer ()
251 "Store a copy of the current article in `spam-stat-buffer'.
252 This uses `gnus-article-buffer'."
253 (with-current-buffer gnus-original-article-buffer
254 (spam-stat-store-current-buffer)))
256 ;; Data -- not using defstruct in order to save space and time
258 (defvar spam-stat
(make-hash-table :test
'equal
)
259 "Hash table used to store the statistics.
260 Use `spam-stat-load' to load the file.
261 Every word is used as a key in this table. The value is a vector.
262 Use `spam-stat-ngood', `spam-stat-nbad', `spam-stat-good',
263 `spam-stat-bad', and `spam-stat-score' to access this vector.")
265 (defvar spam-stat-ngood
0
266 "The number of good mails in the dictionary.")
268 (defvar spam-stat-nbad
0
269 "The number of bad mails in the dictionary.")
271 (defvar spam-stat-error-holder nil
272 "A holder for condition-case errors while scoring buffers.")
274 (defsubst spam-stat-good
(entry)
275 "Return the number of times this word belongs to good mails."
278 (defsubst spam-stat-bad
(entry)
279 "Return the number of times this word belongs to bad mails."
282 (defsubst spam-stat-score
(entry)
283 "Set the score of this word."
286 spam-stat-unknown-word-score
))
288 (defsubst spam-stat-set-good
(entry value
)
289 "Set the number of times this word belongs to good mails."
290 (aset entry
0 value
))
292 (defsubst spam-stat-set-bad
(entry value
)
293 "Set the number of times this word belongs to bad mails."
294 (aset entry
1 value
))
296 (defsubst spam-stat-set-score
(entry value
)
297 "Set the score of this word."
298 (aset entry
2 value
))
300 (defsubst spam-stat-make-entry
(good bad
)
301 "Return a vector with the given properties."
302 (let ((entry (vector good bad nil
)))
303 (spam-stat-set-score entry
(spam-stat-compute-score entry
))
308 (defun spam-stat-compute-score (entry)
309 "Compute the score of this word. 1.0 means spam."
310 ;; promote all numbers to floats for the divisions
311 (let* ((g (* 2.0 (spam-stat-good entry
)))
312 (b (float (spam-stat-bad entry
))))
315 ((= 0 spam-stat-ngood
)
317 ((= 0 spam-stat-nbad
)
321 (min .99 (/ (/ b spam-stat-nbad
)
322 (+ (/ g spam-stat-ngood
)
323 (/ b spam-stat-nbad
)))))))))
327 (defmacro with-spam-stat-max-buffer-size
(&rest body
)
328 "Narrow the buffer down to the first 4k characters, then evaluate BODY."
330 (when (> (- (point-max)
332 spam-stat-max-buffer-length
)
333 (narrow-to-region (point-min)
334 (+ (point-min) spam-stat-max-buffer-length
)))
337 (defun spam-stat-buffer-words ()
338 "Return a hash table of words and number of occurrences in the buffer."
339 (run-hooks 'spam-stat-washing-hook
)
340 (with-spam-stat-max-buffer-size
341 (with-syntax-table spam-stat-syntax-table
342 (goto-char (point-min))
343 (let ((result (make-hash-table :test
'equal
))
345 (while (re-search-forward "\\w+" nil t
)
346 (setq word
(match-string-no-properties 0)
347 count
(1+ (gethash word result
0)))
348 (when (< (length word
) spam-stat-max-word-length
)
349 (puthash word count result
)))
352 (defun spam-stat-buffer-is-spam ()
353 "Consider current buffer to be a new spam mail."
354 (setq spam-stat-nbad
(1+ spam-stat-nbad
))
357 (let ((entry (gethash word spam-stat
)))
359 (spam-stat-set-bad entry
(+ count
(spam-stat-bad entry
)))
360 (setq entry
(spam-stat-make-entry 0 count
)))
361 (spam-stat-set-score entry
(spam-stat-compute-score entry
))
362 (puthash word entry spam-stat
)))
363 (spam-stat-buffer-words))
364 (setq spam-stat-dirty t
))
366 (defun spam-stat-buffer-is-non-spam ()
367 "Consider current buffer to be a new non-spam mail."
368 (setq spam-stat-ngood
(1+ spam-stat-ngood
))
371 (let ((entry (gethash word spam-stat
)))
373 (spam-stat-set-good entry
(+ count
(spam-stat-good entry
)))
374 (setq entry
(spam-stat-make-entry count
0)))
375 (spam-stat-set-score entry
(spam-stat-compute-score entry
))
376 (puthash word entry spam-stat
)))
377 (spam-stat-buffer-words))
378 (setq spam-stat-dirty t
))
380 (autoload 'gnus-message
"gnus-util")
382 (defun spam-stat-buffer-change-to-spam ()
383 "Consider current buffer no longer normal mail but spam."
384 (setq spam-stat-nbad
(1+ spam-stat-nbad
)
385 spam-stat-ngood
(1- spam-stat-ngood
))
388 (let ((entry (gethash word spam-stat
)))
390 (gnus-message 8 "This buffer has unknown words in it")
391 (spam-stat-set-good entry
(- (spam-stat-good entry
) count
))
392 (spam-stat-set-bad entry
(+ (spam-stat-bad entry
) count
))
393 (spam-stat-set-score entry
(spam-stat-compute-score entry
))
394 (puthash word entry spam-stat
))))
395 (spam-stat-buffer-words))
396 (setq spam-stat-dirty t
))
398 (defun spam-stat-buffer-change-to-non-spam ()
399 "Consider current buffer no longer spam but normal mail."
400 (setq spam-stat-nbad
(1- spam-stat-nbad
)
401 spam-stat-ngood
(1+ spam-stat-ngood
))
404 (let ((entry (gethash word spam-stat
)))
406 (gnus-message 8 "This buffer has unknown words in it")
407 (spam-stat-set-good entry
(+ (spam-stat-good entry
) count
))
408 (spam-stat-set-bad entry
(- (spam-stat-bad entry
) count
))
409 (spam-stat-set-score entry
(spam-stat-compute-score entry
))
410 (puthash word entry spam-stat
))))
411 (spam-stat-buffer-words))
412 (setq spam-stat-dirty t
))
414 ;; Saving and Loading
416 (defun spam-stat-save (&optional force
)
417 "Save the `spam-stat' hash table as lisp file.
418 With a prefix argument save unconditionally."
420 (when (or force spam-stat-dirty
)
421 (let ((coding-system-for-write spam-stat-coding-system
))
422 (with-temp-file spam-stat-file
423 (let ((standard-output (current-buffer))
424 (font-lock-maximum-size 0))
425 (insert (format ";-*- coding: %s; -*-\n" spam-stat-coding-system
))
426 (insert (format "(setq spam-stat-ngood %d spam-stat-nbad %d
427 spam-stat (spam-stat-to-hash-table '(" spam-stat-ngood spam-stat-nbad
))
428 (maphash (lambda (word entry
)
430 (spam-stat-good entry
)
431 (spam-stat-bad entry
))))
434 (message "Saved %s." spam-stat-file
)
435 (setq spam-stat-dirty nil
436 spam-stat-last-saved-at
(nth 5 (file-attributes spam-stat-file
)))))
438 (defun spam-stat-load ()
439 "Read the `spam-stat' hash table from disk."
440 ;; TODO: maybe we should warn the user if spam-stat-dirty is t?
441 (let ((coding-system-for-read spam-stat-coding-system
))
442 (cond (spam-stat-dirty (message "Spam stat not loaded: spam-stat-dirty t"))
443 ((or (not (boundp 'spam-stat-last-saved-at
))
444 (null spam-stat-last-saved-at
)
445 (not (equal spam-stat-last-saved-at
446 (nth 5 (file-attributes spam-stat-file
)))))
448 (load-file spam-stat-file
)
449 (setq spam-stat-dirty nil
450 spam-stat-last-saved-at
451 (nth 5 (file-attributes spam-stat-file
)))))
452 (t (message "Spam stat file not loaded: no change in disk..")))))
454 (defun spam-stat-to-hash-table (entries)
455 "Turn list ENTRIES into a hash table and store as `spam-stat'.
456 Every element in ENTRIES has the form \(WORD GOOD BAD) where WORD is
457 the word string, NGOOD is the number of good mails it has appeared in,
458 NBAD is the number of bad mails it has appeared in, GOOD is the number
459 of times it appeared in good mails, and BAD is the number of times it
460 has appeared in bad mails."
461 (let ((table (make-hash-table :size
(length entries
)
465 (spam-stat-make-entry (nth 1 l
) (nth 2 l
))
470 (defun spam-stat-reset ()
471 "Reset `spam-stat' to an empty hash-table.
472 This deletes all the statistics."
474 (setq spam-stat
(make-hash-table :test
'equal
)
477 (setq spam-stat-dirty t
))
481 (defvar spam-stat-score-data nil
482 "Raw data used in the last run of `spam-stat-score-buffer'.")
484 (defsubst spam-stat-score-word
(word)
485 "Return score for WORD.
486 The default score for unknown words is stored in
487 `spam-stat-unknown-word-score'."
488 (spam-stat-score (gethash word spam-stat
)))
490 (defun spam-stat-buffer-words-with-scores ()
491 "Process current buffer, return the 15 most conspicuous words.
492 These are the words whose spam-stat differs the most from 0.5.
493 The list returned contains elements of the form \(WORD SCORE DIFF),
494 where DIFF is the difference between SCORE and 0.5."
495 (let (result word score
)
496 (maphash (lambda (word ignore
)
497 (setq score
(spam-stat-score-word word
)
498 result
(cons (list word score
(abs (- score
0.5)))
500 (spam-stat-buffer-words))
501 (setq result
(sort result
(lambda (a b
) (< (nth 2 b
) (nth 2 a
)))))
502 (setcdr (nthcdr 14 result
) nil
)
505 (defun spam-stat-score-buffer ()
506 "Return a score describing the spam-probability for this buffer.
507 Add user supplied modifications if supplied."
508 (interactive) ; helps in debugging.
509 (setq spam-stat-score-data
(spam-stat-buffer-words-with-scores))
510 (let* ((probs (mapcar 'cadr spam-stat-score-data
))
511 (prod (apply #'* probs
))
513 (/ prod
(+ prod
(apply #'* (mapcar #'(lambda (x) (- 1 x
))
517 spam-stat-error-holder
518 (spam-stat-score-buffer-user score0
)
521 (if score1s
(+ score0 score1s
) score0
)))
522 (when (interactive-p)
526 (defun spam-stat-score-buffer-user (&rest args
)
531 spam-stat-score-buffer-user-functions
)))
532 (if (memq nil scores
) nil
533 (apply #'+ scores
))))
535 (defun spam-stat-split-fancy ()
536 "Return the name of the spam group if the current mail is spam.
537 Use this function on `nnmail-split-fancy'. If you are interested in
538 the raw data used for the last run of `spam-stat-score-buffer',
539 check the variable `spam-stat-score-data'."
540 (condition-case spam-stat-error-holder
542 (set-buffer spam-stat-buffer
)
543 (goto-char (point-min))
544 (when (> (spam-stat-score-buffer) spam-stat-split-fancy-spam-threshold
)
545 (when (boundp 'nnmail-split-trace
)
546 (mapc (lambda (entry)
547 (push entry nnmail-split-trace
))
548 spam-stat-score-data
))
549 spam-stat-split-fancy-spam-group
))
550 (error (message "Error in spam-stat-split-fancy: %S" spam-stat-error-holder
)
555 (defun spam-stat-strip-xref ()
556 "Strip the the Xref header."
558 (mail-narrow-to-head)
559 (when (re-search-forward "^Xref:.*\n" nil t
)
560 (delete-region (match-beginning 0) (match-end 0)))))
562 (defun spam-stat-process-directory (dir func
)
563 "Process all the regular files in directory DIR using function FUNC."
564 (let* ((files (directory-files dir t
"^[^.]"))
565 (max (/ (length files
) 100.0))
569 (when (and (file-readable-p f
)
571 (> (nth 7 (file-attributes f
)) 0)
572 (< (time-to-number-of-days (time-since (nth 5 (file-attributes f
))))
573 spam-stat-process-directory-age
))
574 (setq count
(1+ count
))
575 (message "Reading %s: %.2f%%" dir
(/ count max
))
576 (insert-file-contents-literally f
)
577 (spam-stat-strip-xref)
581 (defun spam-stat-process-spam-directory (dir)
582 "Process all the regular files in directory DIR as spam."
584 (spam-stat-process-directory dir
'spam-stat-buffer-is-spam
))
586 (defun spam-stat-process-non-spam-directory (dir)
587 "Process all the regular files in directory DIR as non-spam."
589 (spam-stat-process-directory dir
'spam-stat-buffer-is-non-spam
))
591 (defun spam-stat-count ()
592 "Return size of `spam-stat'."
594 (hash-table-count spam-stat
))
596 (defun spam-stat-test-directory (dir &optional verbose
)
597 "Test all the regular files in directory DIR for spam.
598 If the result is 1.0, then all files are considered spam.
599 If the result is 0.0, non of the files is considered spam.
600 You can use this to determine error rates.
602 If VERBOSE is non-nil display names of files detected as spam or
603 non-spam in a temporary buffer. If it is the symbol `ham',
604 display non-spam files; otherwise display spam files."
605 (interactive "DDirectory: ")
606 (let* ((files (directory-files dir t
"^[^.]"))
609 (total (length files
))
611 (max (/ total
100.0)); float
615 (when (and (file-readable-p f
)
617 (> (nth 7 (file-attributes f
)) 0))
618 (setq count
(1+ count
))
619 (message "Reading %.2f%%, score %.2f"
620 (/ count max
) (/ score count
))
621 (insert-file-contents-literally f
)
622 (setq buffer-score
(spam-stat-score-buffer))
623 (when (> buffer-score
0.9)
624 (setq score
(1+ score
)))
626 (if (> buffer-score
0.9)
627 (unless (eq verbose
'ham
) (push f display-files
))
628 (when (eq verbose
'ham
) (push f display-files
))))
631 (with-output-to-temp-buffer "*spam-stat results*"
632 (dolist (file display-files
)
635 (message "Final score: %d / %d = %f" score total
(/ score total
))))
637 ;; Shrinking the dictionary
639 (defun spam-stat-reduce-size (&optional count
)
640 "Reduce the size of `spam-stat'.
641 This removes all words that occur less than COUNT from the dictionary.
644 (setq count
(or count
5))
645 (maphash (lambda (key entry
)
646 (when (< (+ (spam-stat-good entry
)
647 (spam-stat-bad entry
))
649 (remhash key spam-stat
)))
651 (setq spam-stat-dirty t
))
653 (defun spam-stat-install-hooks-function ()
654 "Install the spam-stat function hooks."
656 (add-hook 'nnmail-prepare-incoming-message-hook
657 'spam-stat-store-current-buffer
)
658 (add-hook 'gnus-select-article-hook
659 'spam-stat-store-gnus-article-buffer
))
661 (when spam-stat-install-hooks
662 (spam-stat-install-hooks-function))
664 (defun spam-stat-unload-hook ()
665 "Uninstall the spam-stat function hooks."
667 (remove-hook 'nnmail-prepare-incoming-message-hook
668 'spam-stat-store-current-buffer
)
669 (remove-hook 'gnus-select-article-hook
670 'spam-stat-store-gnus-article-buffer
))
672 (add-hook 'spam-stat-unload-hook
'spam-stat-unload-hook
)
676 ;; arch-tag: ff1d2200-8ddb-42fb-bb7b-1b5e20448554
677 ;;; spam-stat.el ends here