# SSH 登录告警推送到手机：用 PAM 钩子同时捕获 scp、sftp 和端口转发

> 每次有人登录你的 Linux 服务器打开 SSH 会话，你都能在 iPhone 或 Android 上收到手机推送通知。这个 pam_exec 钩子不会拖慢登录，API 密钥只有 root 可读，还能屏蔽你自己的登录，并避开常见配置在 Debian 12 和 Ubuntu 上留下的 root 提权漏洞。

*31.10.2026*

<!-- source: https://pocketalert.app/zh/blog/ssh-login-alerts -->

如果有人用被盗的密钥或猜到的密码登录你的服务器，登录本身往往是你唯一能察觉的时机。之后他们看起来和任何普通用户没有区别。每次 SSH 会话都在手机上推送一条通知，就能给你这个时机：你要么认得出这次登录，要么几秒之内就知道出了问题。

这是检测，不是防护。它不能阻止任何人进来，但能保证你在还来得及处理时就收到消息。

本指南使用 PAM，也就是每次 SSH 登录都会经过的那一层。我们在 Debian 12 和 13、Ubuntu 24.04 以及 Rocky Linux 9 上测试过，测试时使用了一个记录每次请求的模拟 API。

## 为什么不用 /etc/profile、.bashrc 或 sshrc

大多数人会复制的方案，是在 `curl`、`/etc/profile` 或 `~/.bashrc` 里加一条 `/etc/ssh/sshrc` 命令。我们测试了每种方式实际能捕获到什么：

- **`/etc/profile`** 只对登录 shell 生效。在我们的测试中，`ssh host cmd`、`scp`、`sftp`、`rsync` 和 `ssh -N` 登录时都没有执行它。
- **`~/.bashrc`** 属于用户本人。任何拥有该账户的人都可以编辑它，而 `ssh host bash --norc` 会跳过它。
- **`/etc/ssh/sshrc`** 好一些：执行命令、scp、sftp 和 rsync 时它都会运行。但它以登录用户的身份运行，所以 API 密钥必须对每个账户可读。另外，如果用户有 `~/.ssh/rc`，sshd 会改为运行它，`sshrc` 就永远不会执行。
- **它们都看不到 `ssh -N`。** 通过 SSH 做端口转发或 SOCKS 代理时不会打开 shell，所以什么都不会执行。

这些方式都是在会话内部、以用户身份运行的，而那时攻击者已经进来了。PAM 钩子则是在 sshd 内部、以 root 身份、会话开始之前运行。

## PAM 如何看到 SSH 登录

在四个发行版上默认都是 `UsePAM yes`，身份验证成功后，sshd 会立即打开一个 PAM 会话。这发生在客户端请求 shell、命令或 sftp 之前。因此钩子会在每个通过身份验证的连接上触发，包括 `ssh -N`，而且它分辨不出交互式 shell 和 `rsync`：即使你拿到了终端，`PAM_TTY` 也只是 `ssh`。多路复用连接（`ControlMaster`）只会打开一个 PAM 会话，不管其上跑了多少条命令。

`pam_exec` 会在这个时机运行一条命令。以下是我们在测试机上确认的行为：

- 对 sshd 来说，命令以 root 身份运行。
- `pam_exec` 会等待命令退出，登录也随之等待。这里如果 `curl` 很慢，登录也会很慢。
- 除非加上 `/dev/null` 选项，否则它的输出会被丢弃到 `stdout`，因此不会泄漏到会话里。
- 它的环境变量是 PAM 环境，而不是 root 的环境。在 Debian 和 Rocky 上没有 `PATH`。

脚本使用的变量如下：

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>变量</th><th>示例</th><th>来源</th></tr></thead>
<tbody>
<tr><th><code>PAM_TYPE</code></th><td><code>open_session</code></td><td>注销时还会出现 <code>close_session</code></td></tr>
<tr><th><code>PAM_SERVICE</code></th><td><code>sshd</code></td><td>正在使用的 PAM 文件</td></tr>
<tr><th><code>PAM_USER</code></th><td><code>root</code></td><td>登录的账户</td></tr>
<tr><th><code>PAM_RHOST</code></th><td><code>198.51.100.23</code></td><td>客户端地址（在 sshd 默认的 <code>UseDNS no</code> 下为 IP）</td></tr>
<tr><th><code>SSH_AUTH_INFO_0</code></th><td><code>publickey ssh-ed25519 AAAA...</code></td><td>由 sshd 设置：认证方式以及被接受的公钥</td></tr>
</tbody>
</table>
</div>

在我们尝试的每个发行版上，即使没有 `SSH_AUTH_INFO_0`，`ExposeAuthInfo` 也都存在。这意味着推送可以写明所使用的密钥，而不仅仅是账户名。

## 你需要准备什么

- 运行 OpenSSH 的 Linux 服务器。请检查 PAM 是否开启：`sudo sshd -T | grep -i usepam` 应输出 `usepam yes`。
- `curl` 和 `jq`：执行 `sudo apt install curl jq`，在 Rocky、Alma 和 RHEL 上执行 `sudo dnf install jq`（这些系统已经自带 curl）。
- 在 [iPhone 或 Android](/get-app) 上安装 Pocket Alert 应用，并从 [API 密钥](/account/apikeys) 页面获取 API 密钥。每台服务器请分别创建一个密钥，这样撤销某一个时不会影响其他服务器。

## 脚本

```bash
#!/bin/bash
# /usr/local/sbin/pa-ssh-login
# Run by pam_exec when a session opens. It must never slow down or break a login.
PATH=/usr/sbin:/usr/bin:/sbin:/bin
CONF=/etc/pa-ssh-login.conf

[ "$PAM_TYPE" = open_session ] || exit 0
[ "$(stat -c '%u %a' "$CONF" 2>/dev/null)" = "0 600" ] || exit 0
# shellcheck source=/dev/null
. "$CONF"
[ -n "$POCKETALERT_API_KEY" ] || exit 0

host=$(uname -n)
if [ "$PAM_SERVICE" = sshd ]; then
  who=${PAM_USER:-unknown}
  from=${PAM_RHOST:-unknown}
  title="SSH login: $who@$host"
  auth=${SSH_AUTH_INFO_0%%$'\n'*}
  case $auth in
    publickey\ *) auth="Key: $(ssh-keygen -lf - <<<"${auth#publickey }" 2>/dev/null | awk '{print $2, $NF}')" ;;
    '') auth="Method: unknown" ;;
    *) auth="Method: ${auth%% *}" ;;
  esac
  message="From $from"$'\n'"$auth"
else
  who=${PAM_RUSER:-unknown}
  from=local
  title="$PAM_SERVICE on $host: $who as ${PAM_USER:-unknown}"
  message="Terminal: ${PAM_TTY:-none}"
fi

level=${PA_UNKNOWN_LEVEL:-high}
read -ra rules <<<"${PA_KNOWN:-}"
for rule in "${rules[@]}"; do
  # shellcheck disable=SC2053 # user@address, both halves are glob patterns on purpose
  if [[ $who == ${rule%@*} && $from == ${rule##*@} ]]; then
    level=${PA_KNOWN_LEVEL:-low}
    break
  fi
done
[ "$level" = none ] && exit 0

ip=
[[ $from =~ ^[0-9A-Fa-f:.]+$ ]] && ip=$from

json=$(jq -n --arg title "$title" --arg message "$message" --arg level "$level" --arg ip "$ip" '
  {title: $title, message: $message, level: $level}
  + (if $ip == "" then {} else {actions: [
      {type: "copy", label: "Copy IP", value: $ip},
      {type: "view", label: "Look up IP", value: ("https://ipinfo.io/" + $ip)}
    ]} end)') || exit 0

{
  printf 'header = "Token: %s"\n' "$POCKETALERT_API_KEY" |
    curl -fsS -o /dev/null --connect-timeout 5 --max-time 15 -K - \
      -H 'Content-Type: application/json' --data-binary "$json" \
      "${POCKETALERT_API_URL:-https://api.pocketalert.app/v1/messages}" ||
    logger -t pa-ssh-login "push failed, curl exit code $?"
} </dev/null >/dev/null 2>&1 &

exit 0
```

```bash
sudo install -m 0755 -o root -g root pa-ssh-login /usr/local/sbin/pa-ssh-login
```

它做了什么，以及为什么这样做：

- **HTTP 请求在后台运行。** 脚本启动 `curl` 后立即退出，因此 `pam_exec` 不会等待。在 Debian 12 和 Rocky 9 上，无论 API 正常响应、4 秒后才响应，还是完全没有响应（一个会丢包的地址），`ssh host true` 每次都只用了 0.15 到 0.36 秒。无法连接时，`curl` 最多等待 15 秒后放弃，失败信息会以 `pa-ssh-login: push failed, curl exit code 7` 的形式写入 syslog。
- **它总是以 0 退出**，并且所有输出都被重定向，所以会话看不到任何内容。无论是否启用钩子，交互式登录和 `ssh host cmd` 的输出都完全相同，只有 "Last login" 行的时间不同。
- **密钥从不出现在命令行中。** `curl` 通过标准输入（`Token`）读取 `-K -` 请求头。参数对本机所有用户都可以通过 `ps` 看到。在请求挂起期间，我们在任何进程的 `/proc/<pid>/cmdline` 中都没有找到密钥。
- **不可信的值通过 `jq --arg` 写入 JSON。** 我们用包含引号、反斜杠、换行符、`$(id)`、控制字符和无效 UTF-8 的用户名、地址、服务名和密钥信息运行了脚本。每个请求体都是合法的 JSON，并且没有任何内容被执行。
- **只有 IP 地址才会添加按钮。** 如果 `400` 按钮中的不是合法 URL，API 会以 `view` 拒绝整条消息。异常的 `PAM_RHOST` 仍应让你收到提醒，只是不带按钮。
- **模式按两部分分别匹配。** `user@address` 在最后一个 `@` 处切分，两边各自比较。如果把两部分拼成一个字符串，名为 `x@10.8.0.5` 的账户就可能匹配 `*@10.8.0.*`，而实际是从任意地址连接的。

来自未知地址的登录会以 `high` 级别送达，因此可以穿透 iPhone 上的专注模式，推送大致如下：

```
SSH login: root@web-1
From 198.51.100.23
Key: SHA256:iZtVU4EwMulogUeoneZkIXA9eeQfCvpyRB66QrrxBRA (ED25519)
```

要查看这是哪把密钥，可以在服务器上运行 `ssh-keygen -lf ~/.ssh/authorized_keys`。它会输出相同的指纹，并附带注释。

## 配置文件

密钥需要放在只有 root 能读取的文件中。由于脚本会把该文件当作 shell 代码来加载，因此只有在文件归 root 所有且权限为 `600` 时，脚本才会加载它。请在隐藏输入的提示中输入密钥，这样它就不会留在 shell 历史记录里：

```bash
sudo bash -c 'umask 077; read -rsp "API key: " k; echo; printf "POCKETALERT_API_KEY=%s\n" "$k" > /etc/pa-ssh-login.conf'
sudo tee -a /etc/pa-ssh-login.conf >/dev/null <<'EOF'
PA_KNOWN="*@203.0.113.10 deploy@198.51.100.*"
PA_KNOWN_LEVEL=low
PA_UNKNOWN_LEVEL=high
EOF
sudo stat -c '%U %a' /etc/pa-ssh-login.conf   # root 600
```

`PA_KNOWN` 列出你预期的登录，格式为以空格分隔的 `user@address` 通配符模式。在这个示例中，来自 `203.0.113.10` 这个 VPN 出口的任何账户都视为预期登录，来自 CI 网段的 `deploy` 也是如此。它们以 `low` 级别送达：在消息列表中出现，但不发声。其他所有登录都使用 `PA_UNKNOWN_LEVEL`。在付费套餐上，你可以把它设为 `critical`，这样即使开启静音开关或勿扰模式也会发出声音。在免费套餐上，`critical` 会按 `high` 送达。各级别在 iOS 和 Android 上的具体效果，请参阅[优先级说明](https://info.pocketalert.app/features/priority-levels.html)。

模式使用的是通配符，而不是 CIDR：`198.51.100.*` 覆盖一个 /24 网段，其他范围则需要多条模式。如果希望预期登录完全不发送任何消息，请设置 `PA_KNOWN_LEVEL=none`。

在保持 `low` 之前，先统计一下你的登录次数。免费套餐每天允许 50 条消息，而每次 SSH 连接都会产生一条消息。如果一个 CI 任务每 15 分钟运行一次 `rsync`，每天就会消耗 96 条。请对这类来源设置 `none`，或升级到付费套餐。一旦达到每日上限，API 会拒绝发送消息，直到 UTC 时间 00:00，而这其中也包括你最关心的那次登录。

## 把钩子接入 PAM，放在最前面

这一步比脚本更重要。修改 PAM 时，请在另一个终端保持一个 root shell 打开，这样即使打错字，你也不会被锁在外面。sshd 会在每次连接时读取 PAM 文件，因此无需重启任何服务。

```bash
sudo cp /etc/pam.d/sshd /root/pam.d-sshd.bak
sudo sed -i '0,/^session/s|^session|session    optional     pam_exec.so quiet type=open_session /usr/local/sbin/pa-ssh-login\n&|' /etc/pam.d/sshd
sudo grep -n -m2 '^session' /etc/pam.d/sshd
```

在 Debian 上，最后一条命令会输出：

```
19:session    optional     pam_exec.so quiet type=open_session /usr/local/sbin/pa-ssh-login
20:session [success=ok ignore=ignore module_unknown=ignore default=bad]        pam_selinux.so close
```

这一行被放在第一个 `session` 行之上，而不是像多数指南那样加到文件末尾。原因在于 Debian 12 和 Ubuntu 24.04 的 `/etc/pam.d/sshd` 中有这样一行：

```
session    required     pam_env.so user_readenv=1 envfile=/etc/default/locale
```

`user_readenv=1` 会把用户自己的 `~/.pam_environment` 中的变量加载到 PAM 环境中。位于它之后的任何 `pam_exec` 行都会把这些变量传递给它运行的命令。`pam_exec` 的手册页对此有过警告："Commands called by pam_exec need to be aware of that the user can have control over the environment."（由 pam_exec 调用的命令需要注意，用户可以控制环境变量。）

我们在 Ubuntu 24.04 上验证了这意味着什么。把钩子放在文件末尾时，一个普通用户把 `LD_PRELOAD /tmp/x.so` 写入了 `~/.pam_environment`，然后登录。这个库被加载进了 root 运行的脚本，以及脚本启动的每个程序中，且 uid 为 0。这意味着任何能通过 SSH 登录的人都能获得 root shell。把钩子放在最前面后，这个变量就不存在了。Debian 13 和 Rocky 9 并未设置 `user_readenv`，但把钩子放在最前面在这些系统上也没有任何代价。如果你的 `pam_exec` 之后已经有其他 `pam_env` 行，同样的道理也适用。

这一行中各选项的含义：

- **`optional`**：如果脚本缺失或执行失败，登录仍会继续。我们把脚本改名后登录，结果是登录正常，且没有任何输出。
- **`type=open_session`**：`pam_exec` 在注销时根本不会运行脚本。这与位置问题的原因相同：注销时 `pam_env` 已经运行过，在我们的测试中，来自 `LD_PRELOAD` 的 `~/.pam_environment` 又回到了环境变量中。
- **`quiet`**：如果命令失败，`pam_exec` 不会向用户打印其退出状态。

在 RHEL 系列系统上，这一行会位于 `pam_selinux.so close` 之上，因此它运行在 sshd 的 SELinux 上下文中。我们的测试是在未启用 SELinux 强制模式的容器中进行的。如果在启用强制模式的系统上推送没有送达，请运行 `sudo ausearch -m avc -ts recent` 进行检查。

软件包升级可能会替换 `/etc/pam.d/sshd`，或在旁边留下一个 `.dpkg-dist` 或 `.rpmnew` 副本。OpenSSH 升级后，请检查这一行是否仍然存在。

## 测试一下

你可以像 `pam_exec` 那样手动调用脚本：

```bash
sudo env PAM_TYPE=open_session PAM_SERVICE=sshd PAM_USER=test PAM_RHOST=203.0.113.9 /usr/local/sbin/pa-ssh-login
```

几秒钟之内，你应该会收到一条标题为 `SSH login: test@<hostname>` 的推送，内容为 `Method: unknown`，因为这次并没有真正的 SSH 登录。如果想先查看请求内容，可以在配置文件中加入 `POCKETALERT_API_URL=http://<your test endpoint>`，测试完成后记得删除。

然后从一个不在 `PA_KNOWN` 中的地方登录。在测试机上，以下每种方式各产生了一条推送：交互式 shell、`ssh host cmd`、`scp`、`sftp`、`rsync`、密码登录，以及 `ssh -N`。

## 可选：su 和 sudo

同一个脚本也可以通过各自的 PAM 文件，报告 `su` 和 `sudo` 的使用情况。这需要额外一个选项：

```bash
for f in su sudo; do
  sudo sed -i '0,/^session/s|^session|session    optional     pam_exec.so quiet seteuid type=open_session /usr/local/sbin/pa-ssh-login\n&|' /etc/pam.d/$f
done
```

如果没有 `seteuid`，`pam_exec` 会以调用进程的真实用户 ID 运行命令。对于 `su` 和 `sudo`，这个 ID 是输入命令的那个用户，而不是 root。在我们的测试机上，脚本以 uid 1000 运行，无法读取配置文件，也就什么都没有发送。加上 `seteuid` 后，脚本以 root 身份运行，推送内容类似 `sudo on web-1: alice as root`。

对于这些服务，脚本会用运行命令的用户加上 `PA_KNOWN` 作为地址，去匹配 `local`。`alice@local` 会屏蔽 Alice 自己的 `sudo` 推送。`root@local` 则会屏蔽那些以 root 身份运行、并通过 `su` 切换到其他用户的脚本，尽管它们同样会产生推送。

添加 `sudo` 之前，请先考虑推送量。每次 `sudo` 命令都会打开一个会话，因此每一次都会产生一条推送。在一台整天都有人使用 `sudo` 的服务器上，通常只钩入 `su` 就足够了。

## 按钮

在付费套餐上，每条 SSH 推送都带有两个[操作按钮](/features/action-buttons)：**Copy IP** 会把地址复制到剪贴板，方便你添加防火墙规则或搜索日志；**Look up IP** 会在 ipinfo.io 上打开该地址，让你看出它来自你的服务商，还是另一大洲的托管网络。在免费套餐上，服务器会去掉这些按钮，但推送本身仍会照常送达。

## 这些不覆盖什么

- **登录失败。** PAM 会话只会在身份验证成功后才打开。密码猜测需要交给 fail2ban，或者检查 journal 中 sshd 的日志。
- **登录之后发生的事。** 获得 root 权限的人可以从 `/etc/pam.d/sshd` 中删除这一行。但他们无法撤回那次让他们进入的登录所产生的推送：请求在他们的 shell 启动之前就已经发出了。
- **不经过 sshd PAM 栈的登录。** 包括本地控制台、其他远程访问服务，以及设置了 `UsePAM no` 的 sshd。
- **区分 shell 和文件传输。** 如上所述，PAM 目前还无法分辨。通常地址和密钥就足以区分你的 CI 任务和真人操作。

以上就是有人进入服务器那一刻的监控。如果你还想为其他值得推送的服务器事件设置提醒，请参阅[安全告警](/use-cases/security-alerts)。
