Attachments

Fuglu has advanced attachment handling capabilities, depending on installed Python libraries. The following dependencies are highly recommended:

magic

pyton-magic supports detection of MIME types. Alternatively python-file can be used.

psutil

Optional dependency, will try to determine the maximum available memory that can be used to extract archives. This will prevent OOM errors on large archives.

rarfile

Required for analyzing rar archives. The Python library alone will allow access to rar metadata. To extract files from rar archives the command line unrar utility is requirered. For best results install unrar-nonfree. If you prefer an entirely free system, use unrar-free or bsdtar, however they will fail on many rar archives.

py7zr

Required for analyzing and extracting 7zip archives. Alternatively py7zlib can be used, but it’s less stable.

pypdf

Required for analyzing and extracting pdf files. Attached pdf files are handled like archives. Images, text parts, attachments are handled like files in an archive file. Additionally, URI links and e-mail addresses can be extracted from metadata and text parts. Be careful not to confuse it with PyPDF/PyPDF2. Alternatively mupdf/fitz can be used, but it’s less stable.

ssdeep

Required for generating fuzzy hash representations of attached files.

imagehash and numpy

Required for generating various types of fuzzy hash representations of attached image files. Imagehash will also require PIL. Numpy will also require cv2.

Archive extraction limits

Archives are extracted into memory. Several limits protect against oversized archives and decompression bombs:

  • archivecontentmaxsize (plugin option, e.g. FiletypePlugin, EncryptedArchives): maximum uncompressed size of a single file extracted from an archive. Larger files are not extracted for content inspection. The effective limit may be lower if psutil reports little available memory.

  • gzip (.gz): the single compressed member is decompressed incrementally and extraction stops at the archivecontentmaxsize limit, regardless of the size stated in the gzip trailer.

  • Compressed tar archives (.tar.gz/.tgz, .tar.bz2, .tar.xz): the total decompressed tar stream is limited to 512 MiB. Listing the files in a compressed tar requires decompressing everything up to the last file entry, so this limit applies even if no file is extracted. If an archive exceeds it, reading the archive fails with DecompressionLimitError and its content cannot be listed or inspected. If the attachment’s content type is application/gzip or application/x-gzip, fuglu then falls back to handling it as a single gzip-compressed file, subject to the gzip limit above. The limit is fixed (TAR_MAX_DECOMPRESSED in fuglu.extensions.filearchives) and not configurable; legitimate compressed tar archives of this size are not expected in mail.