Intevation/intelmq-mailgen

# IntelMQ Mailgen 用于处理事件的 IntelMQ 命令行工具。 调用 ``intelmqcbmail --help`` 以查看当前用法。 概念文档可在此处找到： https://intevation.github.io/intelmq-mailgen/ # 安装说明 ## 依赖项 需要以下库和程序： - Python 库 ``psycopg2``（``python3-psycopg2``）用于 PostgreSQL 通信。 - Python 库 ``gpg``（``python3-gpg``），gpgme 库的一部分。由于 Ubuntu 20.04 存在问题，使用 ``pip`` 或 ``setup.py`` 安装时不会安装此依赖项。其他分发方式（deb 包）不受此错误影响。 - GnuPG (v>=2.2)，供 ``python3-gpg`` 使用。 作为一个 Python3 应用程序，其依赖项请参见 setup.py 中的 ``install_requires`` 部分。 如果您安装 deb 包，包管理器会处理所有依赖项。 若要从源码安装，请使用以下命令： :: pip3 install -v -e . **为了使用 IntelMQ Mailgen，您需要在 IntelMQ 中拥有一个正常工作的 certbund-contact-expert，因为 Mailgen 会使用 IntelMQ 默认字段中不可用的信息和数据。** ## IntelMQ 配置 为了使 Mailgen 正常工作，需要先配置以下 IntelMQ bot： 1. Expert：CERT-bund Contact Database 2. Expert：CERT-bund Contact Rules 3. Output：PostgreSQL 在设置 Mailgen 之前，您**必须遵循这些 bot 的设置说明**。 ## 数据库 ``intelmq-events`` 数据库和 ``intelmq`` 数据库用户应已通过配置 PostgreSQL 输出 bot（引擎为 `postgresql` 的 SQL 输出 bot）完成设置。 与 Mailgen 配合使用时，需扩展此设置： 以数据库超级用户身份（通常通过系统用户 postgres）： 1. 创建新的数据库用户： :: createuser --encrypted --pwprompt intelmq_mailgen 2. 扩展数据库：``psql -f sql/notifications.sql intelmq-events`` 3. 授予 ``intelmq`` 通过 trigger 插入新事件的权限： ``psql -c "GRANT eventdb_insert TO intelmq" intelmq-events`` 4. 授予新用户发送通知的权限： ``psql -c "GRANT eventdb_send_notifications TO intelmq_mailgen" intelmq-events`` ## 与 IntelMQ 及事件数据库的交互 写入事件数据库的事件已经过 rules bot 处理，该 bot 会向事件添加通知指令。这些指令告诉 mailgen 根据该事件生成哪些通知。``sql/notifications.sql`` 中的语句向事件数据库添加了 trigger 和表，以便在指令传入时进行处理并为 mailgen 的使用做好准备。具体包括： - ``directives`` 表包含所有指令。一条指令的主要属性包括 - 事件 ID - 收件人地址 - 数据格式 - 模板名称（参见下文“模板”） - 聚合方式 - 是否以及何时已发送。这是 ``sent`` 表中对应行的 ID（见下文） - 当新事件插入 ``events`` 表时，一个 trigger 过程会提取指令并将它们插入到 ``directives`` 中。 - ``sent`` 表记录了实际已发送的通知。其主要属性包括 - 为通知生成的 ticket 编号 - 指示发送时间的时间戳 当 mailgen 处理指令时，它会从数据库中读取尚未发送的指令，将足够相似以致可以在同一封邮件中发送的指令进行聚合，并为每个聚合后的指令调用一系列脚本。这些脚本会检查指令，如果它们能够处理该指令，就会据此生成邮件。然后 mailgen 会发送这些邮件并将其记录在 ``sent`` 表中。 ## Ticket 编号 Mailgen 发送的每封电子邮件都会生成一个 ticket 编号。如果邮件成功发送，此编号将连同邮件发送的时间戳一起存储在 ``sent`` 表中。 # 配置 ``intelmq-mailgen`` 目前在以下两个位置搜索配置文件： 1. ``$HOME/.intelmq/intelmq-mailgen.conf``（用户配置文件）和 2. ``/etc/intelmq/intelmq-mailgen.conf``（系统配置文件）。 系统会读取这两个文件的设置，其中用户主目录中的文件具有优先权。 系统配置文件路径可以使用 ``--config`` 命令行参数进行覆盖。 两个文件必须均为 JSON 格式。完整示例可在 ``intelmq-mailgen.conf.example`` 中找到。 ## OpenPGP 签名 ``gnupg_home`` 必须指向用于电子邮件签名的 GnuPG 主目录。它必须满足： - 包含用于 OpenPGP 签名的无密码保护的私钥和公钥部分。 - 对于运行 intelmq-mailgen 的用户具有读写权限。 例如，以下步骤将创建这样一个目录并导入一个测试签名密钥。 :: GNUPGHOME=/tmp/gnupghome mkdir $GNUPGHOME chmod og-rwx $GNUPGHOME GNUPGHOME=/tmp/gnupghome gpg2 --list-secret-keys GNUPGHOME=/tmp/gnupghome gpg2 --import src/intelmq-mailgen/tests/keys/test1.sec 根据您的 GnuPG 版本，您可能希望通过编辑 ``$GNUPGHOME/gpg.conf`` 来设置其他选项。 例如，以下设置将设置默认的摘要算法、禁止输出 GnuPG 版本，并为签名添加注释行： :: personal-digest-preferences SHA256 no-emit-version comment Key verification （详情请参阅 GnuPG 文档。） 现在，您应该能够使用此密钥进行签名，而不会提示您输入密码。例如，尝试： :: echo Moin moin. | GNUPGHOME=/tmp/gnupghome gpg2 --clearsign --local-user "5F503EFAC8C89323D54C252591B8CD7E15925678" ## 模板 mailgen 附带了一种模板机制，处理指令的脚本可以使用该机制。此机制假设所有模板均为配置文件中 ``template_dir`` 设置所指定目录中的文件。 mailgen 附带的脚本会直接从它们正在处理的指令中提取模板名称。这意味着该名称是由 rules bot 使用的规则设定的，因此请参阅其文档和配置以了解您需要哪些模板。 ## 模板格式 模板文件的第一行将用作邮件的主题行。其余行将作为邮件正文。正文与主题行之间可以选择用一个或多个空行隔开。 主题和正文文本都将被解释为 `Python3 Template strings `__，并且根据格式的不同，允许进行一些替换。主题和正文允许相同的替换。 通常支持的替换： - 所有格式： - ``${ticket_number}`` - 基于 CSV 格式的附加替换： - ``${events_as_csv}`` 用于 CSV 格式的事件数据。这仅在正文中有效。 - 按事件字段聚合时，也可以使用事件字段。例如，如果指令按 ``source.asn`` 聚合，您可以使用 ``${source.asn}`` 与模板名称一样，聚合由 rules bot 决定，因此请参阅相关文档获取详细信息。 # 操作手册 应监控日志文件以发现错误，从而检测异常情况。 特别需要 grep 的内容： :: ``` * 'ERROR' * 'Error:' ``` 每种错误情况都应由管理员或维修技术人员尽快处理。建议使用监控系统，以便在日志中出现此类字符串时立即通知管理员。 ## 日志文件内容 mailgen 的日志中不应包含任何 ``Traceback`` 或其他 ERROR 信息。请阅读相关行，它们通常会提供有关故障原因的良好提示。某些问题可以通过更正配置来解决。 INFO 行在正常操作期间出现。产生 INFO 消息的一种情况是 Mailgen 检测到它已在运行，从而使得第二个实例无法启动。如果发生这种情况，正在运行的 Mailgen 进程可能仍然存在问题，并且由于日志文件的性质，尝试启动的 Mailgen 的消息可能会与错误情况交织在一起。 ## Mailgen 需要锁定数据库行 在一次运行期间，如果 mailgen 被第二次启动，它将无法锁定数据库中所需的行。``postgres.log`` 文件将记录失败的锁定，例如： :: 2020-12-15 09:00:02 UTC ERROR: could not obtain lock on row in relation "directives" 这种情况可以被忽略。 ## Mailgen 尝试继续运行 Mailgen 会尝试继续处理指令并发送邮件，即使由于某些原因无法发送某些批次的邮件。 例如，如果找不到模板，它将继续处理下一条指令并记录一条错误消息和 stacktrace。该错误消息包含有关无法处理的指令的信息。 输出中的 ``directive_ids`` 部分是一个列表，包含 ``directives`` 表中行的 ID，而 ``event_ids`` 是 ``events`` 表中事件 ID 的列表。 管理员可以使用此信息详细查看哪些事件和电子邮件可能未发出，以便稍后处理，如果需要，可以根据问题原因使用一个小脚本进行处理。 # 开发者信息 ## 数据库架构 使用 pgadmin4 的 `ERD tool `_ 生成： .. image:: contactdb-design.png 源文件位于 `intelmq-certbund-contact/sql/contactdb.erd `_。 ## 安全注意事项 - 假设我们需要防范通过数据库传送给我们的恶意外部数据。 - 我们不需要（也无法）防范具有管理员权限的本地攻击。 - 由于我们的命令能够在有和没有用户交互的情况下运行，我们假设只有具有管理员权限的用户才能访问机器并被允许启动交互式变体。 - 用于签名的私钥材料没有通过密码进行额外保护，因此系统本身需要得到充分的保护。（这可以包括将 intelmq 本身的设置分离到另一台仅具有填充数据库权限的机器上。） - 我们应注意防止整个系统成为有效的签名（或加密）预言机。解释一下：考虑一个将从我们系统收到自动通知的攻击者。如果此攻击者还能通过使用的 feed 触发警告，她可能会部分控制要签名的明文（或在某处加密的内容）并获得自动化结果。在某些情况下，这存在很小的可能被用于自适应明文攻击。 ## 列名 可以在代码中定义 CSV 列的名称。例如，在 ``example_scripts/10shadowservercsv.py`` 中，字典 ``standard_column_titles`` 将事件字段名称映射到列标题。稍后在 ``table_formats`` 中定义的大多数 CSV 格式都会使用这些标题。如果需要，那里指定的格式仍然可以使用特殊的列标题。 ## 数据转换 当前，数据在添加到 CSV 输出时不会进行转换。 Mailgen 始终会从 ``time.source`` 的时间戳中移除“UTC”标记。它确保时间戳始终为 UTC。 ## 测试 测试实际电子邮件发送的一种简单方法是使用运行 ``DebuggingServer`` 的 Python ``smtpd`` 模块： :: python3 -m smtpd -d -n -c DebuggingServer localhost:8025 （不要忘记在您的配置中配置相应的 SMTP host 和 port。） 如果您想以 Maildir 格式捕获电子邮件，可以使用 https://pypi.org/project/dsmtpd/，例如： .. code:: sh git clone git://github.com/matrixise/dsmtpd.git cd dsmtpd python3 -m dsmtpd -i localhost -p 8025 -d /path/to/Maildir ``/path/to/Maildir`` 必须是一个已存在的 `Maildir `__，或者是尚不存在的路径，在后一种情况下，它将由 dsmtpd 创建。 您可以使用 mutt 访问 Maildir，例如： :: mutt -f /path/to/Maildir 提示：默认情况下，``Esc P`` 将触发 mutt 的 ```` `功能 `__，以防您想检查非 MIME 签名。 ## 测试套件 测试套件分为两部分，因为某些测试可能会因硬件规格（执行时间）而失败，并且它们的失败本身并不表示存在错误。 必须成功的常规单元测试可以通过 ``make check`` 启动；要运行完整的测试套件，请使用 ``make check_all``。 # 历史 intelmq-mailgen 文件最初复制自 https://github.com/certat/intelmq/blob/a29da5d798bd114535326ffdd2f5000c4b6a21e7/intelmq/bin/intelmqcli （修订日期为 2016-03-08）。

标签：CSIRT, GnuPG, IntelMQ, PostgreSQL, Python, 事件管理, 威胁情报, 安全告警, 开发者工具, 无后门, 测试用例, 网络安全, 自动化处理, 邮件通知, 隐私保护