HostGuard：SSH 防护与端口安全管理系统

文章来源(Source)：https://dqzboy.com

文章来源(Source)：https://dqzboy.com AI 文章摘要时光AI(本站开发)

Linux 服务器开放 SSH 之后，登录失败、无效用户探测和暴力破解往往会持续出现。服务器上的业务越来越多，防火墙规则也会逐渐复杂：哪些端口需要开放、哪些来源应该拒绝、Docker 发布端口是否受到控制，以及修改规则后会不会把自己锁在服务器之外，都是日常运维需要面对的问题。

HostGuard 就是围绕这些需求开发的一款 Linux 主机安全工具。它把 SSH 登录事件检测、恶意 IP 自动封禁、安全组规则、端口监听和操作审计整合到一个 Web 控制台中，让主机安全配置和日常维护更加直观。

一、HostGuard 有哪些功能？

1. SSH 登录行为检测与自动封禁

HostGuard 默认持续读取 systemd journal 中的 SSH 登录事件，识别无效用户名、密码认证失败等行为，并通过 nftables 或 iptables 执行封禁。

当前防护逻辑以允许登录的用户名和连续密码失败次数为基础：

无效用户，或不在允许名单中的用户名，命中对应登录事件后永久封禁来源 IP。
允许用户在统计窗口内连续密码认证失败达到阈值后，永久封禁来源 IP。
默认失败阈值为 3 次，默认统计窗口为 10 分钟。
成功认证会重置对应来源和用户的连续失败计数。
永久封禁不会自动到期，需要管理员手动解除。

这里封禁的对象是来源 IP。如果多个管理员共用一个 NAT 或 VPN 出口，其中一个人的失败登录也可能影响其他人。因此，部署后需要及时核对允许登录的用户名和实际管理网络。

2. 自动识别 SSH 监听端口

HostGuard 会通过实际 SSH 握手探测宿主机的监听端口，不要求 SSH 一定运行在 TCP 22。

例如，服务器将 SSH 改到 33 后，控制台应显示实际识别到的端口，后续的 SSH 防护和安全组配置也应围绕这个端口进行。

生产模式下，如果没有识别到可用的 SSH 端口，且没有可用配置回退，后端会拒绝继续应用防火墙，避免在缺少管理端口信息的情况下修改规则。

3. 两种 SSH 防护模式

HostGuard 提供两种防护模式：

模式	行为	适用场景
公网行为防护	允许公网来源建立 SSH 连接，再根据登录行为执行封禁	管理员公网 IP 经常变化，需要从不同网络登录
严格来源准入	仅允许配置的 IP 或 CIDR 连接 SSH，其他来源在网络层被丢弃	有固定办公出口、固定 VPN 出口或明确运维网段

严格模式中的允许来源仍受登录失败封禁规则约束。也就是说，将一个 IP 加入 SSH 接入来源名单，并不意味着它可以无限次尝试密码。

4. 可视化安全组管理

通过安全组页面，可以维护：

入站和出站规则。
允许或拒绝动作。
TCP、UDP、ICMP 等协议。
单个 IP、CIDR 网段等来源。
端口或端口范围。
规则优先级和启用状态。

规则可以覆盖宿主机直接监听的服务，以及 Docker 使用 ports 发布的端口。对于 Docker 发布端口，HostGuard 会按外部客户端访问的宿主机端口进行控制。例如端口映射为 8443:443，需要控制的对外入口就是 TCP 8443。

5. 端口监听与 Docker 容器关联

端口监听页面可以查看：

TCP、UDP 监听端口。
监听地址及作用范围。
关联的 PID、进程名称和命令。
Docker 容器名称、镜像和目标端口。

这样可以先确认服务实际监听在哪里，再配置对应的防火墙规则。

6. 攻击记录与操作审计

HostGuard 使用 SQLite 保存账号、会话、封禁、SSH 策略、安全组规则和审计记录。SSH 攻击事件按来源、用户名、事件类型和分钟聚合保存，减少高频攻击下的重复记录。管理员可以搜索来源 IP，查看尝试次数、事件类型和封禁状态。此外，还支持手动扫描 lastb / btmp 历史失败记录，先生成候选清单，经管理员确认后再批量封禁。

二、部署前准备

准备一台安装了 Docker Engine 和 Docker Compose 插件的 Linux 主机，并确认 SSH 服务正在运行。本文的默认部署使用 systemd journal，因此优先使用具备 systemd 和 SSH journal 记录的 Linux 环境。

Docker镜像包下载：tar包下载链接

uname -m
docker version
docker compose version

sudo ss -lntp
sudo journalctl -u ssh -u sshd -n 30 --no-pager

三、使用 Docker Compose 部署

1、准备配置和运行目录

/data/hostguard/
├── docker-compose.yaml
└── backend/
    ├── data/
    └── run/

mkdir -p /data/hostguard/{data,run} 
cd /data/hostguard/

2、了解部署结构

仓库中的 Compose 配置会启动三个服务：

服务	作用	关键配置
`backend`	SSH 事件检测、IP 封禁、防火墙管理和管理 API	host 网络、host PID、`NET_ADMIN`、`SYS_PTRACE`
`frontend`	Web 控制台和 API 反向代理	host 网络，监听 TCP `19443`
`docker-metadata`	读取并裁剪 Docker 容器和端口元数据	无网络、移除 capabilities，通过 Unix Socket 提供元数据

后端镜像已经内置 nftables、iptables 等工具。

3、创建docker-compose.yaml

在 /data/hostguard/ 下创建 docker-compose.yaml，完整内容如下：

services:
  docker-metadata:
    container_name: hostguard-docker-metadata
    image: hostguard-api:latest
    pull_policy: never
    command:
      - docker-metadata-proxy
      - --listen-socket=/run/hostguard/docker-metadata.sock
      - --docker-socket=/var/run/docker.sock
    network_mode: none
    cap_drop:
      - ALL
    security_opt:
      - no-new-privileges:true
    read_only: true
    volumes:
      - ./backend/run:/run/hostguard
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

  backend:
    container_name: hostguard-backend
    image: hostguard-api:latest
    pull_policy: never
    network_mode: host
    pid: host
    depends_on:
      - docker-metadata
    cap_add:
      - NET_ADMIN
      - SYS_PTRACE
    environment:
      HOSTGUARD_DOCKER_METADATA_SOCKET: /run/hostguard/docker-metadata.sock
    volumes:
      - ./backend/data:/var/lib/hostguard
      - ./backend/run:/run/hostguard:ro
      - /run/log/journal:/run/log/journal:ro
      - /var/log/journal:/var/log/journal:ro
      - /var/log:/host/var/log:ro
      - /etc/machine-id:/etc/machine-id:ro
    healthcheck:
      test:
        - CMD
        - /usr/local/bin/hostguard
        - healthcheck
      interval: 2s
      timeout: 2s
      retries: 60
      start_period: 3s
    restart: unless-stopped

  frontend:
    container_name: hostguard-frontend
    image: hostguard-web:latest
    pull_policy: never
    network_mode: host
    depends_on:
      backend:
        condition: service_healthy
    restart: unless-stopped

4、导入镜像并启动

通过提供的网盘下载我打包好的Docker镜像tar包，上传到你的服务器后，通过docker官方load命令导入到服务器

# 导入镜像
docker load -i "hostguard-images-linux-amd64-latest.tar"

# 启动服务
docker compose up -d
docker compose ps

5、首次登录获取初始密码

空数据库首次启动时，HostGuard 会创建 admin 管理员，并将随机初始化密码写入宿主机数据目录：

sudo cat backend/data/bootstrap-password

使用 admin、初始化密码和页面图形验证码登录。密码文件仅允许文件所有者读写；已有账号不会因为重启服务而被重置。首次登录后，在“用户中心”设置专用密码，新密码至少需要 12 个字符。

五、使用域名和 HTTPS 访问

对外管理时，可以使用宿主机 Nginx 提供 HTTPS。仓库已提供 deploy/hostguard.nginx.conf，访问链路为：

浏览器 HTTPS :443
  → 宿主机 Nginx
  → 127.0.0.1:19443 前端
  → 127.0.0.1:19080 后端 API

部署前准备好域名解析、宿主机 Nginx 和有效 TLS 证书。然后编辑配置，将 hostguard.example.com 和证书路径替换为实际值：

sudo cp deploy/hostguard.nginx.conf /etc/nginx/conf.d/hostguard.conf
sudo nginx -t
sudo systemctl reload nginx