LDAP Watchdog:一个实时兼容Linux的LDAP监控工具,用于检测目录变更,为管理员和安全研究人员提供添加、修改和删除操作的可见性。
LDAP Watchdog 是一款旨在实时监控 LDAP 目录中记录变更的工具。
它提供了一种机制来跟踪和可视化用户与组条目的修改、添加和删除,使用户能够将预期变更与实际变更相关联,并识别潜在的安全事件。
它的设计初衷是针对 OpenLDAP 和 Linux,并且需要一个为每个条目提供 entryUUID(RFC 4530)的服务器,因此不支持使用 objectGUID 的 Active Directory。
它使用 Python 编写,需要 ldap3 库,以及用于 Slack 通知的 requests 库。
本软件由 Joshua Rogers 编写。
如果您对以下任何内容感兴趣,那么 LDAP Watchdog 就是为您准备的:
除了监控 LDAP 目录中的修改、添加和删除之外,它还可以配置为忽略特定属性,甚至可以精细调整以根据属性的旧值/新值忽略细粒度属性。
变更始终会打印到终端,如果配置了 Slack webhook,也会转发到 Slack webhook。彩色输出可以关闭。
该项目以前名为 LDAP-Stalker(因为监控 LDAP 目录的变更是一种跟踪公司内变更的绝佳方式:在晋升公布之前了解晋升信息、新员工、离职人员等),关于该项目细节和历史的博客文章可在此处找到。
注意:在以下示例中,可以通过设置 LDAP_WATCHDOG_IGNORED_ATTRIBUTES=entryCSN,modifyTimestamp 来忽略现有条目上 entryCSN 和 modifyTimestamp 的变更。


实时监控: LDAP Watchdog 持续监控 LDAP 目录中用户和组条目的变更。
变更比较: 该工具比较连续 LDAP 搜索之间的变更,突出显示添加、修改和删除。
控制用户验证: LDAP Watchdog 支持控制用户机制,如果未找到控制用户的变更,则触发错误。
灵活的 LDAP 过滤: 用户可以使用 LDAP_WATCHDOG_SEARCH_FILTER 环境变量自定义 LDAP 过滤,以专注于特定的对象类或属性。
Slack 集成: 在 Slack 上接收有关添加、修改或删除 LDAP 条目的实时通知。
可自定义输出: 控制台输出以清晰且彩色的方式指示添加、修改和删除,便于查看。
忽略条目和属性: 用户可以指定在比较现有条目的变更时要忽略的 UUID 和属性。
条件忽略属性: 用户可以仅在属性变更涉及特定值时忽略该属性的变更,例如 memberOf 中的某个组。
ldap3 包。如果使用 Slack webhook,还需要 requests 包。pip install LDAP-Monitor
要包含 Slack webhook 支持:
pip install "LDAP-Monitor[slack]"
docker pull megamansec/ldap-monitor
或从 GitHub Container Registry 获取:
docker pull ghcr.io/megamansec/ldap-monitoring-watchdog
git clone https://github.com/MegaManSec/LDAP-Monitoring-Watchdog.git
cd LDAP-Monitoring-Watchdog
pip install ".[slack]"
从 1.x 升级: 自 2.0.0 起,LDAPS 连接会验证服务器证书,并验证该证书与 LDAP_WATCHDOG_SERVER 中的主机名或 IP 地址是否匹配;1.0.0 对两者均不检查。升级前,如果证书为自签名或来自私有 CA,请设置 LDAP_WATCHDOG_CA_CERTS_FILE;如果证书与该名称不匹配,请使用匹配的证书或设置 LDAP_WATCHDOG_TLS_VERIFY=false(参见配置下的 TLS 说明)。发布说明列出了其他变更。
从 1.x 或 2.0.0 升级: 自 2.0.1 起,布尔设置仅接受配置下列出的值。早期版本会将除 true、1 或 yes 之外的任何值都视为 false。现在,无法识别的值会在启动时终止进程,空值表示使用默认值,而 on 或带引号的 "true" 表示 true。例如,当 LDAP_WATCHDOG_USE_SSL 为空且仅提供主机名时,现在会通过端口 636 使用 LDAPS 连接,而不是通过端口 389 使用普通 LDAP。
export LDAP_WATCHDOG_SERVER='ldaps://ldaps.intra.lan'
export LDAP_WATCHDOG_BASE_DN='dc=mouse,dc=com'
export LDAP_WATCHDOG_USERNAME='cn=Emily,ou=People,dc=mouse,dc=com'
export LDAP_WATCHDOG_PASSWORD='qwerty123'
ldap-watchdog
或使用 python -m:
python -m ldap_watchdog
docker run -d --restart unless-stopped \
-e LDAP_WATCHDOG_SERVER='ldaps://ldaps.intra.lan' \
-e LDAP_WATCHDOG_BASE_DN='dc=mouse,dc=com' \
-e LDAP_WATCHDOG_USERNAME='cn=Emily,ou=People,dc=mouse,dc=com' \
-e LDAP_WATCHDOG_PASSWORD='qwerty123' \
-e SLACK_WEBHOOK_URL='https://hooks.slack.com/services/[...]' \
-e LDAP_WATCHDOG_IGNORED_ATTRIBUTES='entryCSN,modifyTimestamp,telephoneNumber,roomNumber,gecos' \
-e LDAP_WATCHDOG_DISABLE_COLOR_OUTPUT='true' \
megamansec/ldap-monitor
提供了一个基于 Debian 的安装脚本 install.sh。它需要 Python 3.10 或更高版本以及 python3-venv 包。当以 root 身份从本仓库的克隆中运行时,该脚本会:
/opt/ldap-watchdog 中创建(如有必要)一个 Python 虚拟环境。requirements.txt。/etc/ldap-watchdog.env 创建用于配置的环境文件,除非该文件已存在。/etc/systemd/system/ldap-watchdog.service),该服务以非特权动态用户在后台运行 ldap-watchdog,因此 CA 证书包必须全局可读。/var/log/ldap-watchdog.log 和 /var/log/ldap-watchdog-error.log。/etc/logrotate.d/ldap-watchdog 中设置日志轮转。从更新后的克隆重新运行该脚本即可升级安装。
你可以选择向 install.sh 传递单个参数,以便在首次创建环境文件时设置 SLACK_WEBHOOK_URL:
sudo ./install.sh "https://hooks.slack.com/services/[...]"
安装完成后,编辑 /etc/ldap-watchdog.env 以配置 LDAP 连接设置(在此之前服务会启动失败),然后重启服务:
sudo systemctl restart ldap-watchdog
所有配置均通过环境变量完成;空值与未设置相同,但 LDAP_WATCHDOG_SLACK_BULLETPOINT 除外。支持以下变量:
| 环境变量 | 描述 | 默认值 |
|---|---|---|
LDAP_WATCHDOG_SERVER | LDAP 服务器 URL 或主机名(例如 ldaps://ldaps.intra.lan)。必填。 | "" |
LDAP_WATCHDOG_BASE_DN | 用于 LDAP 搜索的基础 Distinguished Name | "" |
LDAP_WATCHDOG_USERNAME | 用于认证的绑定 DN(例如 cn=Emily,ou=People,dc=mouse,dc=com)。如果此项或密码为空,则绑定为匿名。 | "" |
LDAP_WATCHDOG_PASSWORD | LDAP_WATCHDOG_USERNAME 的密码 | "" |
LDAP_WATCHDOG_USE_SSL | 设为 true 以使用 SSL(LDAPS,默认端口 636 而非 389),否则设为 false。LDAP_WATCHDOG_SERVER 中的 ldaps:// 或 ldap:// 方案会覆盖此设置。 | true |
LDAP_WATCHDOG_CA_CERTS_FILE | 可选的 PEM CA 证书包,用于验证 LDAP 服务器证书。如果未设置,则使用系统信任根。 | 未设置 |
LDAP_WATCHDOG_TLS_VERIFY | 设为 false 以跳过验证 LDAP 服务器证书和主机名。连接仍会加密但不会进行认证。 | true |
LDAP_WATCHDOG_SEARCH_FILTER | 用于用户和组条目的 LDAP 过滤器 | (&(|(objectClass=inetOrgPerson)(objectClass=groupOfNames))) |
LDAP_WATCHDOG_SEARCH_ATTRIBUTE | 要检索的属性的逗号分隔列表。默认使用 *,+ 以包含操作属性。entryUUID 始终会被请求,并且每个条目都必须可读。 | *,+ |
LDAP_WATCHDOG_REFRESH_RATE | 每次 LDAP 搜索后等待下一次搜索的整数秒数 | 60 |
LDAP_WATCHDOG_NETWORK_TIMEOUT | LDAP 和 Slack 连接/读取操作的正整数超时秒数。这限制的是单次等待时间,而非一次轮询的总时长。 | 30 |
LDAP_WATCHDOG_DISABLE_COLOR_OUTPUT | 设为 true 以禁用彩色输出,即使输出到文件或 docker logs 时也会使用彩色输出 | false |
布尔设置接受 true、yes、on 或 1 以及 false、no、off 或 0,不区分大小写且可选带引号;任何其他值都会在启动时终止进程。
LDAPS 连接会验证服务器证书,并检查该证书对 LDAP_WATCHDOG_SERVER 中的主机名或 IP 地址是否有效。对于私有 CA,请将 LDAP_WATCHDOG_CA_CERTS_FILE 设置为可读的 PEM CA 证书包;在 Docker 中,将证书包挂载到容器中并使用其容器路径。自签名服务器证书本身可作为证书包使用。如果无法提供证书或证书与服务器名称不匹配,LDAP_WATCHDOG_TLS_VERIFY=false 会关闭验证;此时网络路径上的任何人都可以冒充服务器并捕获绑定密码。对于不使用 TLS 的服务器,请使用 ldap:// URL 或设置 LDAP_WATCHDOG_USE_SSL=false。
| 环境变量 | 描述 | 默认值 |
|---|---|---|
LDAP_WATCHDOG_CONTROL_UUID | 控制用户的 entryUUID,该用户会在每次轮询前被更改(例如由 cron 任务更改)。除非其在两个快照中都存在的某个属性具有新值,否则比较会以错误拒绝。该用户必须匹配基础 DN 和搜索过滤器,并且其更改会被通告,除非忽略过滤器将其隐藏,例如将其列入 LDAP_WATCHDOG_IGNORED_UUIDS。 | "" |
LDAP_WATCHDOG_CONTROL_USER_ATTRIBUTE | 要在控制用户中检查的特定属性。如果设置,它必须存在于两个快照中,且其值必须不同。 | "" |
控制检查失败会记录错误并跳过该次比较。下一次轮询会与最近一次成功获取的快照进行比较;被拒绝的比较中的更改不会被重放。而 LDAP 检索失败则会保留先前的快照,并在下一次轮询时重试。无法获取初始快照会终止进程。
| 环境变量 | 描述 | 默认值 |
|---|---|---|
SLACK_WEBHOOK_URL | 用于通知的 Slack Webhook URL。需要 slack 附加组件(pip install "LDAP-Monitor[slack]")。 | 未设置 |
LDAP_WATCHDOG_SLACK_BULLETPOINT | Slack 和控制台输出中每行变更开头的文本 | • 前有一个空格,后有三个空格 |
Slack 投递为尽力而为:HTTP 和网络故障会记录到 stderr,监控和控制台输出会继续。失败的通知不会排队或重试。超过 4,000 个字符的消息会通过将其最长的单词替换为 [...truncated...] 来缩短;如果这还不够,它们会在 4,000 个字符处被截断,丢弃最后几行(新增项先列出,然后是删除项,最后是修改项)。控制台输出永远不会被缩短。
这些过滤器适用于两个快照中都存在的条目的属性变更。条目新增和删除始终会连同所有检索到的属性一起通告,包括被忽略的 UUID。UUID 是 entryUUID 值,在每条消息中显示在 DN 后的括号内,名称和值必须完全匹配,包括大小写(modifyTimestamp,而非 modifytimestamp)。被 LDAP_WATCHDOG_IGNORED_ATTRIBUTES 或 LDAP_WATCHDOG_CONDITIONAL_IGNORED_ATTRIBUTES 隐藏的变更仍会连同其值写入 stderr;被忽略 UUID 的变更会被静默跳过。
| 环境变量 | 描述 | 默认值 |
|---|---|---|
LDAP_WATCHDOG_IGNORED_UUIDS | 逗号分隔的 UUID 列表,其属性变更会被忽略 | "" |
LDAP_WATCHDOG_IGNORED_ATTRIBUTES | 逗号分隔的属性列表,其在现有条目上的变更会被忽略 | "" |
LDAP_WATCHDOG_CONDITIONAL_IGNORED_ATTRIBUTES | 要条件忽略的属性的 JSON 字符串(见下文) | {} |
LDAP_WATCHDOG_CONDITIONAL_IGNORED_ATTRIBUTES 变量接受一个 JSON 对象,其中键是属性名称,值是用于忽略的值的数组(即使只有一个值也是数组):