# Alertas de login SSH no celular: um hook PAM que também pega scp, sftp e port forwards

> Receba uma notificação push no iPhone ou Android sempre que alguém abrir uma sessão SSH no seu servidor Linux. Um hook pam_exec que nunca atrasa um login, mantém a chave de API acessível só ao root, silencia os seus próprios logins e evita uma escalada de privilégio para root que a configuração comum deixa aberta no Debian 12 e no Ubuntu.

*31.10.2026*

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

Se alguém entrar no seu servidor com uma chave roubada ou uma senha adivinhada, o próprio login costuma ser o único momento em que você poderia ter percebido. Depois disso, a pessoa parece qualquer outro usuário. Uma notificação push no seu celular para cada sessão SSH te dá esse momento: ou você reconhece o login, ou sabe em segundos que algo está errado.

Isso é detecção, não prevenção. Não vai impedir ninguém de entrar. Garante que você fique sabendo enquanto ainda dá tempo de agir.

O guia usa PAM, a camada por onde todo login SSH já passa. Foi testado no Debian 12 e 13, no Ubuntu 24.04 e no Rocky Linux 9, com uma API falsa que registrava cada requisição.

## Por que não /etc/profile, .bashrc ou sshrc

O trecho que a maioria das pessoas copia é uma chamada `curl` em `/etc/profile`, `~/.bashrc` ou `/etc/ssh/sshrc`. Testamos o que cada um deles realmente vê:

- **`/etc/profile`** roda só para shells de login. Nos nossos testes, `ssh host cmd`, `scp`, `sftp`, `rsync` e `ssh -N` fizeram login sem executá-lo.
- **`~/.bashrc`** pertence ao usuário. Quem tiver essa conta pode editá-lo, e `ssh host bash --norc` o ignora.
- **`/etc/ssh/sshrc`** é melhor: rodou para comandos, scp, sftp e rsync. Mas ele roda como o usuário que fez login, então a chave de API precisa ser legível por todas as contas. E se o usuário tiver um `~/.ssh/rc`, o sshd executa esse arquivo no lugar e o `sshrc` nunca roda.
- **Nenhum deles enxerga o `ssh -N`.** Um port forward ou um proxy SOCKS sobre SSH não abre shell, então nada é executado.

Todos esses rodam dentro da sessão, como o usuário, depois que o atacante já entrou. Um hook PAM roda dentro do sshd, como root, antes de a sessão começar.

## Como o PAM vê um login SSH

Com `UsePAM yes` (o padrão nas quatro distribuições), o sshd abre uma sessão PAM logo depois que a autenticação dá certo. Isso acontece antes de o cliente pedir um shell, um comando ou o sftp. Assim, o hook dispara para toda conexão autenticada, inclusive `ssh -N`, e não consegue diferenciar um shell interativo de um `rsync`: `PAM_TTY` fica como `ssh` mesmo quando você recebe um terminal. Uma conexão multiplexada (`ControlMaster`) abre uma única sessão PAM, não importa quantos comandos passem por ela.

O `pam_exec` executa um comando nesse ponto. Aqui está o que confirmamos nas máquinas de teste:

- Para o sshd, o comando roda como root.
- O `pam_exec` espera o comando terminar, e o login espera junto. Um `curl` lento aqui significa um login lento.
- A saída vai para `/dev/null` a menos que você adicione a opção `stdout`, então nada pode vazar para a sessão.
- O ambiente dele é o ambiente do PAM, não o do root. No Debian e no Rocky não existe `PATH`.

Estas são as variáveis que o script usa:

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Variável</th><th>Exemplo</th><th>De onde vem</th></tr></thead>
<tbody>
<tr><th><code>PAM_TYPE</code></th><td><code>open_session</code></td><td>Também <code>close_session</code> no logout</td></tr>
<tr><th><code>PAM_SERVICE</code></th><td><code>sshd</code></td><td>O arquivo PAM em uso</td></tr>
<tr><th><code>PAM_USER</code></th><td><code>root</code></td><td>A conta que fez login</td></tr>
<tr><th><code>PAM_RHOST</code></th><td><code>198.51.100.23</code></td><td>O endereço do cliente (um IP, com o <code>UseDNS no</code> padrão do sshd)</td></tr>
<tr><th><code>SSH_AUTH_INFO_0</code></th><td><code>publickey ssh-ed25519 AAAA...</code></td><td>Definida pelo sshd: o método e a chave pública aceita</td></tr>
</tbody>
</table>
</div>

`SSH_AUTH_INFO_0` estava presente em todas as distribuições que testamos, sem `ExposeAuthInfo`. Isso significa que a notificação pode informar a chave usada, e não só a conta.

## O que você precisa

- Um servidor Linux com OpenSSH. Confira se o PAM está ativo: `sudo sshd -T | grep -i usepam` deve mostrar `usepam yes`.
- `curl` e `jq`: `sudo apt install curl jq`, ou `sudo dnf install jq` no Rocky, Alma e RHEL (o curl já vem instalado nelas).
- O app Pocket Alert no [iPhone ou Android](/get-app) e uma chave de API em [Chaves de API](/account/apikeys). Crie uma chave separada para cada servidor, para poder revogar uma sem mexer nas outras.

## O script

```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
```

O que ele faz, e por quê:

- **A chamada HTTP roda em segundo plano.** O script inicia o `curl` e sai na hora, então o `pam_exec` para de esperar. Com a API respondendo normalmente, depois de 4 segundos, ou sem resposta alguma (um endereço que descarta pacotes), `ssh host true` levou entre 0,15 e 0,36 segundo em todas as vezes no Debian 12 e no Rocky 9. Um `curl` que não consegue conectar desiste em no máximo 15 segundos, e a falha vai para o syslog como `pa-ssh-login: push failed, curl exit code 7`.
- **Ele sempre sai com código 0**, e toda saída é redirecionada, então a sessão não vê nada. A saída de um login interativo e de `ssh host cmd` foi idêntica com e sem o hook, exceto pelo horário na linha "Last login".
- **A chave nunca aparece em uma linha de comando.** O `curl` lê o cabeçalho `Token` da entrada padrão (`-K -`). Argumentos são visíveis para todos os usuários locais no `ps`. Enquanto uma requisição ficava pendente, a chave não estava no `/proc/<pid>/cmdline` de nenhum processo.
- **Valores não confiáveis entram no JSON pelo `jq --arg`.** Rodamos o script com um nome de usuário, endereço, serviço e informação de chave cheios de aspas, barras invertidas, quebras de linha, `$(id)`, caracteres de controle e UTF-8 inválido. Todo corpo de requisição era JSON válido, e nada foi executado.
- **Os botões são adicionados só para endereço IP.** A API rejeita a mensagem inteira com `400` se um botão `view` não tiver uma URL válida. Um `PAM_RHOST` estranho ainda deve gerar o alerta, só sem os botões.
- **Os padrões são comparados em cada metade.** `user@address` é dividido no último `@`, e cada lado é comparado separadamente. Juntar tudo em uma string faria uma conta chamada `x@10.8.0.5` casar com `*@10.8.0.*` mesmo conectando de qualquer lugar.

Um login de um endereço desconhecido chega assim, com prioridade `high`, então passa pelo Foco no iPhone:

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

Para descobrir qual é a chave, rode `ssh-keygen -lf ~/.ssh/authorized_keys` no servidor. Ele mostra as mesmas impressões digitais, com os comentários.

## O arquivo de configuração

A chave fica em um arquivo que só o root consegue ler. O script se recusa a carregá-lo se ele não pertencer ao root ou não tiver permissão `600`, porque o script o carrega como código shell. Digite a chave em um prompt oculto, para que ela não acabe no histórico do 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` lista os logins que você espera, como padrões glob `user@address` separados por espaço. No exemplo, qualquer conta vinda da saída da sua VPN em `203.0.113.10` é esperada, e o mesmo vale para `deploy` a partir da sub-rede de CI. Eles chegam como `low`: no feed, sem som. Todo o resto recebe `PA_UNKNOWN_LEVEL`. Em um plano pago, você pode definir isso como `critical`, que toca mesmo com o interruptor silencioso e com o Não perturbe ativado. No plano gratuito, `critical` é entregue como `high`. Veja [níveis de prioridade](https://info.pocketalert.app/features/priority-levels.html) para o que cada nível faz no iOS e no Android.

Os padrões são globs, não CIDR: `198.51.100.*` cobre uma /24, e outras faixas precisam de mais de um padrão. Defina `PA_KNOWN_LEVEL=none` para não enviar nada para logins esperados.

Conte seus logins antes de deixar isso em `low`. O plano gratuito permite 50 mensagens por dia, e cada conexão SSH é uma mensagem. Um job de CI que roda `rsync` a cada 15 minutos usa 96 delas. Dê `none` para essas origens, ou mude para um plano pago. Ao atingir o limite diário, a API recusa mensagens até 00:00 UTC, e isso incluiria justamente o login que você mais precisa ver.

## Conecte ao PAM, no topo

Esta parte importa mais que o script. Mantenha um shell root aberto em outro terminal enquanto altera o PAM, para que um erro de digitação não te deixe do lado de fora. O sshd lê o arquivo PAM a cada conexão, então não há nada para reiniciar.

```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
```

No Debian, o último comando mostra:

```
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
```

Isso coloca a linha acima da primeira linha `session`, e não no fim do arquivo, como a maioria dos guias sugere. O motivo está no `/etc/pam.d/sshd` do Debian 12 e do Ubuntu 24.04:

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

`user_readenv=1` carrega variáveis do próprio `~/.pam_environment` do usuário para o ambiente do PAM. Qualquer linha `pam_exec` abaixo dela passa essas variáveis para o comando que executa. A página de manual do `pam_exec` avisa sobre isso: "Commands called by pam_exec need to be aware of that the user can have control over the environment."

Verificamos o que isso significa no Ubuntu 24.04. Com o hook no fim do arquivo, um usuário comum escreveu `LD_PRELOAD /tmp/x.so` no próprio `~/.pam_environment` e fez login. A biblioteca foi carregada no script root e em todos os programas que ele executou, como uid 0. Isso dá um shell root a quem consegue fazer login por SSH. Com o hook no topo, a variável não chegava. O Debian 13 e o Rocky 9 não definem `user_readenv`, mas colocar o hook primeiro não custa nada também nesses sistemas. O mesmo vale para qualquer linha `pam_exec` que você já tenha abaixo do `pam_env`.

As opções da linha:

- **`optional`**: se o script estiver ausente ou falhar, o login segue. Renomeamos o script e fizemos login. Funcionou, sem nada impresso.
- **`type=open_session`**: o `pam_exec` não executa o script no logout. Isso importa pelo mesmo motivo da posição: no logout, o `pam_env` já rodou, e no nosso teste o `LD_PRELOAD` vindo do `~/.pam_environment` estava de volta no ambiente.
- **`quiet`**: se o comando falhar, o `pam_exec` não mostra o código de saída ao usuário.

Em sistemas da família RHEL, a linha fica acima de `pam_selinux.so close`, então roda no contexto SELinux do sshd. Nossos testes rodaram em contêineres sem SELinux em modo enforcing. Se as notificações não chegarem em um sistema com enforcing, confira `sudo ausearch -m avc -ts recent`.

Atualizações de pacotes podem substituir o `/etc/pam.d/sshd`, ou deixar uma cópia `.dpkg-dist` ou `.rpmnew` ao lado dele. Depois de atualizar o OpenSSH, confira se a linha continua lá.

## Teste

Você pode chamar o script manualmente, do mesmo jeito que o `pam_exec` faz:

```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
```

Uma notificação com o título `SSH login: test@<hostname>` deve chegar em alguns segundos, com `Method: unknown`, já que não houve um login SSH real. Se quiser ver a requisição antes, adicione `POCKETALERT_API_URL=http://<your test endpoint>` ao arquivo de configuração, e remova-o quando terminar.

Depois, faça login de um lugar que não esteja em `PA_KNOWN`. Nas máquinas de teste, cada um destes gerou uma notificação: um shell interativo, `ssh host cmd`, `scp`, `sftp`, `rsync`, um login por senha e `ssh -N`.

## Opcional: su e sudo

O mesmo script pode reportar `su` e `sudo`, pelos próprios arquivos PAM. Eles precisam de uma opção a mais:

```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
```

Sem `seteuid`, o `pam_exec` roda o comando com o ID de usuário real do processo que o chamou. Para `su` e `sudo`, esse é o usuário que digitou o comando, não o root. Nas nossas máquinas de teste, o script rodou como uid 1000, não conseguiu ler o arquivo de configuração e não enviou nada. Com `seteuid`, ele roda como root, e a notificação fica assim: `sudo on web-1: alice as root`.

Para esses serviços, o script compara `PA_KNOWN` com o usuário que executou o comando, usando `local` como endereço. `alice@local` silencia o `sudo` da própria Alice. `root@local` silencia scripts que rodam como root e trocam para outro usuário com `su`, que também geram notificação.

Pense no volume antes de adicionar o `sudo`. Cada comando `sudo` abre uma sessão, então cada um deles vira uma notificação. Em um servidor em que as pessoas usam `sudo` o dia inteiro, conectar apenas o `su` costuma ser suficiente.

## Os botões

Nos planos pagos, cada notificação SSH tem dois [botões de ação](/features/action-buttons): **Copy IP** copia o endereço para a área de transferência, útil para uma regra de firewall ou uma busca nos logs, e **Look up IP** abre a consulta no ipinfo.io, para você ver se é o seu provedor ou uma rede de hospedagem em outro continente. No plano gratuito, o servidor remove os botões, e a notificação em si é entregue normalmente.

## O que isso não cobre

- **Logins que falharam.** Sessões PAM só abrem depois que a autenticação dá certo. Adivinhação de senha é trabalho do fail2ban, ou de uma verificação do log do sshd no journal.
- **Qualquer coisa depois do login.** Quem ganhar root pode apagar a linha de `/etc/pam.d/sshd`. Não consegue cancelar a notificação do login que permitiu a entrada: a requisição já está a caminho antes de o shell dessa pessoa começar.
- **Logins que não passam pela pilha PAM do sshd.** Isso inclui o console local, outros serviços de acesso remoto e o sshd com `UsePAM no`.
- **Diferenciar um shell de uma transferência de arquivos.** Como explicado acima, o PAM ainda não sabe. O endereço e a chave geralmente bastam para diferenciar seu job de CI de uma pessoa.

Isso cobre o momento em que alguém entra. Para outros eventos do servidor que valem uma notificação, veja [alertas de segurança](/use-cases/security-alerts).
