API

class yaramail.MailScanner(header_rules: str | IOBase | Rules = None, body_rules: str | IOBase | Rules = None, header_body_rules: str | IOBase | Rules = None, attachment_rules: str | IOBase | Rules = None, passwords: List[str] | IOBase | str = None, max_zip_depth: int = None, implicit_safe_domains: List[str] | IOBase | str = None, allow_multiple_authentication_results: bool = False, use_authentication_results_original: bool = False)

A YARA scanner for emails that can also check Authentication-Results headers.

Parameters:

• header_rules – Rules that only apply to email header content

• body_rules – Rules that only apply to email body content

• header_body_rules – Rules that apply to combined email header and body content

• attachment_rules – Rules that only apply to file attachment content

• passwords – A list of passwords to use when attempting to scan password-protected files

• max_zip_depth – Number of times to recurse into nested ZIP files

• implicit_safe_domains – Always add the safe category to emails from these domains

• allow_multiple_authentication_results – Allow multiple Authentication-Results-Original headers when checking authentication results

• use_authentication_results_original – Use the Authentication-Results-Original header instead of the Authentication-Results header

Note

Each _rules parameter can accept raw rule content, a path to a rules file, a file-like object, or a yara.Rule object.

Tip

Use the include directive in the YARA rule files that you pass to MailScanner to include rules from other files. That way, rules can be divided into separate files as you see fit.

Warning

Authentication results are based on the headers of the email sample, so only trust authentication results on emails that have been received by trusted mail servers, and not on third-party emails.

Warning

Set allow_multiple_authentication_results to True if and only if the receiving mail service splits the results of each authentication method in separate Authentication-Results headers and always includes DMARC results.

Warning

Set use_authentication_results_original to True if and only if you use an email security gateway that adds an Authentication-Results-Original header, such as Proofpoint or Cisco IronPort. This does not include API-based email security solutions, such as Abnormal Security.

Note

infected`, ``malware, and the contents of the message body are always tried as passwords.

Note

Starting in version 2.1.0, the contents of the message body are automatically tried as passwords for password-protected ZIP attachments.

scan_email(email: str | IOBase | Dict, use_raw_headers: bool = False, use_raw_body: bool = False) → Dict

Scans an email using YARA rules

Parameters:

• email – Email file content, a path to an email file, a file-like object, or output from mailsuite.utils.parse_email()

• use_raw_headers – Scan headers with indentations included

• use_raw_body – Scan the raw email body instead of converting it to Markdown first

Returns: A dictionary

The returned dictionary contains the following key-value pairs:

• matches - A list of YARA match dictionaries

  • name - The name of the rule.

  • namespace - The namespace of the rule.

  • meta - A dictionary of key-value pairs from the meta section.

  • tags - A list of the rule’s tags.

  • strings - A list of lists identifying strings or patterns that match.

    0. The location/offset of the identified string

    1. The variable name of the string/pattern in the rule

    2. The matching string/pattern content

• categories - A list of categories of YARA matches

• msg_from_domain - Message From domain details

  • domain - The message From domain

  • authenticated - bool: domain is authenticated

  • implicit_safe - bool: domain is in the implicit_safe_domains list

• has_attachment - bool: The email sample has an attachment

• warnings - A list of warnings. Possible warnings include:

  • domain-authentication-failed - Authentication of the message From domain failed

  • from-domain-mismatch - The message From domain did not exactly match the value of the meta key from_domain

  • safe-rule-missing-from-domain - The rule is missing a from_domain meta key that is required for rules with the category meta key set to safe

  • unexpected-attachment - An email win an attachment matched a rule with the meta key no attachment or no_attachments set to true

• location - The part of the email where the match was found, for example:

  • header

  • body

  • header_body

  • attachment:filename

  • attachment:example.zip:evil.js

  • attachment:first.zip:nested.zip:evil.js

  • attachment:evil.eml:attachment:example.zip:evil.js

• verdict - The verdict of the scan. Possible verdicts include:

  • None - No categories matched

  • safe - The email is considered safe

  • ambiguous - Multiple categories matched

  • Any custom category specified in the meta section of a YARA rule