# 📅 Guia de Implementação: Alertas de SSH no Google Calendar & Telegram

Este guia fornece o instalador automatizado, scripts de configuração dinâmica e documentação técnica para implantar o sistema de monitoramento, auditoria de logins e alertas em tempo real em qualquer servidor da sua rede (ex: VPS 4, VPS 1, etc.).

---

## 🏗️ Como o Sistema Funciona

Para garantir que **100% de todos os acessos** sejam auditados (incluindo acessos de túneis de portas `-N`, SFTP, conexões VS Code e logins interativos) de forma robusta e assíncrona, o sistema é dividido em dois módulos integrados:

```text
[Login SSH Concluído]
       │
       ├─► [Gatilho do PAM: /etc/pam.d/sshd] (Intercepta todas as sessões: túneis, VS Code, shell, etc.)
       │         │
       │         └─► [Executa em Background: /usr/local/bin/ssh_pam_trigger.sh]
       │                   │
       │                   └─► [Chama: /usr/local/bin/ssh_gcal_alert.py]
       │                             │
       │                             ├─► [Busca GeoIP & ISP] (Cidade, Estado, País e Operadora)
       │                             │
       │                             ├─► [Rate-Limiting / Debounce] (Evita enchentes de alertas em curto tempo)
       │                             │
       │                             ├─► [Local Syslog] (Salva logs localmente em caso de falha de rede)
       │                             │
       │                             ├─► [Telegram Push] ──► Mensagem instantânea no Celular
       │                             │
       │                             └─► [Google Calendar API] ──► Registra Bloco Visual na Agenda
       │
       └─► [Sourced: /etc/profile.d/ssh_alert.sh] (Apenas em shells de login interativos)
                 │
                 └─► Exibe Banner de Auditoria Amarelo no Terminal do Usuário
```

---

## ⚡ Método Rápido (Recomendado - Instalação em 10 segundos)

Se você já possui o repositório de instruções em seu servidor, a instalação é totalmente automatizada através do script `install.sh`.

### Passo 1: Executar o Instalador Automático
Acesse a pasta de instruções e execute o instalador como `root` especificando o IP/Prefixo desta nova VPS (ex: `10.99.0.4`):

```bash
sudo ./install.sh --vps "10.99.0.X"
```
*(O script irá baixar e configurar todas as dependências, permissões, scripts integradores, PAM e o banner visual do terminal automaticamente).*

### Passo 2: Vincular o seu Chat do Telegram ao Bot
Para receber as notificações instantâneas no seu celular através do bot `@AcessosVPSbot`, execute o assistente de emparelhamento automático:

```bash
sudo /usr/local/bin/ssh_alert_setup_telegram.py
```

1. Abra o Telegram no seu celular.
2. Pesquise por **`@AcessosVPSbot`** (ou acesse [t.me/AcessosVPSbot](https://t.me/AcessosVPSbot)) e clique em **"Começar"** ou envie `/start`.
3. O terminal detectará instantaneamente a sua mensagem, capturará o seu Chat ID, atualizará a configuração do servidor e enviará uma confirmação no seu chat!

---

## 🛠️ Detalhamento Técnico e Estrutura de Arquivos

Caso queira entender a estrutura ou realizar alterações manuais, o ecossistema é formado pelos seguintes componentes:

### 1. Arquivo de Configuração Centralizada (`/etc/ssh/ssh_alerts_config.json`)
Guarda as chaves e credenciais de forma segura, com permissões restritas apenas para leitura (`chmod 640` para `root:deploy`).
```json
{
  "telegram_token": "8641435108:AAGL3rOiVj1GpYAyUi4D-pdeDJ9K_JUdlgM",
  "telegram_chat_id": "SEU_CHAT_ID_CAPTURADO_AQUI",
  "calendar_id": "385857c79ef3aed0f4923b29007637a8b7764d6f8359959500bce27611833f5d@group.calendar.google.com"
}
```

### 2. Script de Integração e Decisão (`/usr/local/bin/ssh_gcal_alert.py`)
Escrito em Python 3, realiza a chamada da API do Google Calendar e do Telegram, com tratamento de erros integrado no `syslog` local, controle de frequência (Rate-Limiting de 120s para o mesmo usuário/IP) e enriquecimento de GeoIP/ISP.

### 3. Script de Gatilho do PAM (`/usr/local/bin/ssh_pam_trigger.sh`)
Intercepta no nível de kernel/autenticação cada abertura de sessão SSH e envia os dados para o script Python em segundo plano.
```bash
#!/bin/bash
if [ "$PAM_TYPE" = "open_session" ] && [ "$PAM_SERVICE" = "sshd" ]; then
    USER_LOGIN="$PAM_USER"
    IP_LOGIN="$PAM_RHOST"
    DATE_LOGIN=$(date "+%Y-%m-%d %H:%M:%S")

    if [ -z "$IP_LOGIN" ]; then
        IP_LOGIN="127.0.0.1"
    fi

    if [[ ! "$IP_LOGIN" =~ ^10\.99\.0\. ]]; then
        AVISO_INDEVIDO="🚨 ALERTA: Acesso fora da rede VPN segura detectado!"
    else
        AVISO_INDEVIDO="✅ Acesso autorizado através da rede VPN segura."
    fi

    /usr/local/bin/ssh_gcal_alert.py --vps "10.99.0.X" --user "$USER_LOGIN" --ip "$IP_LOGIN" --status "$AVISO_INDEVIDO" > /dev/null 2>&1 &
fi
```

### 4. Configuração do PAM (`/etc/pam.d/sshd`)
Garante que o gatilho acima seja executado. É adicionada a seguinte linha ao final do arquivo:
```text
session optional pam_exec.so type=open_session /usr/local/bin/ssh_pam_trigger.sh
```

### 5. Banner de Terminal (`/etc/profile.d/ssh_alert.sh`)
Exibe o banner amarelo chamativo de auditoria apenas para usuários conectando de forma convencional via shell de terminal interativo.

---

## 🧪 Como Testar

Para certificar-se de que tudo está rodando adequadamente e simular o disparo direto do PAM com busca de GeoIP externa:

```bash
sudo PAM_TYPE=open_session PAM_SERVICE=sshd PAM_USER=deploy PAM_RHOST=8.8.8.8 /usr/local/bin/ssh_pam_trigger.sh
```

O evento correspondente deverá aparecer na sua agenda imediatamente (em vermelho intenso indicando fora da VPN), e uma mensagem push de alerta chegará instantaneamente no seu Telegram!
