banhack233

一行安装

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/neko233-com/banhack233/main/scripts/install.sh | sh

Windows 管理员 PowerShell：

iwr -useb https://raw.githubusercontent.com/neko233-com/banhack233/main/scripts/install.ps1 | iex

Linux/macOS 安装后先看状态；已经是 root 可省略 sudo：

sudo banhack233 status

Windows 使用管理员 PowerShell 执行 & "$env:ProgramFiles\banhack233\banhack233.exe" status；安装器不会添加 PATH。

默认 dry_run=true，只告警、不真封禁。安装器创建配置但不自动启动首次安装的守护进程；先检查配置、安装自启动、观察 dry-run，再切生产。

海外与双语团队：从 v0.2.3 开始，notifications.language="en" 开启英文通知，notifications.timezone="UTC" 使用统一时区；支持渠道单独覆盖语言。已有配置保持原行为。见海外入门、完整英文配置、通知指南。

说明文档：HTML 中文 · English HTML · 开发与发布 · 版本记录 · 下载 Release。网页仅在正式版本检查、构建及发布成功后更新，版本号以网页标识为准。

深入文档

仓库文档可能包含未发布内容；线上 HTML 对应网页标明的正式版本，见 更新记录。

Telegram 与每日自动更新

配置方法见 通知渠道与重试、升级与回滚。公司出口加入 ignore_ips；公网 SSH 无法识别远程网卡 MAC 地址。

以下用于已有 Linux systemd 服务的迁移。首次安装请先完成入门部署。

sudo banhack233 safe-ssh -write
sudo banhack233 config-check
sudo systemctl restart banhack233
sudo banhack233 auto-update -enable
sudo banhack233 auto-update -status

项目定位

banhack233 是 Go 编写的主机防护工具，集合 fail2ban / sshguard 风格防爆破、系统巡检、保活、通知和自启动，主要解决这些问题：

• 服务器需要 SSH 密码登录，甚至需要 root 密码登录，但仍然要防爆破。
• 需要自动扫 SSH 登录失败日志，超过阈值后封禁 IP。
• 需要开机自启动、通知告警、安全巡检、默认每 1 小时审计一次。
• 需要为长时间空闲的 SSH 会话配置保活；实际连通性仍受网络和客户端状态影响。
• 需要 Linux、macOS、Windows 尽量自适应。

English docs: README-EN.md

类似软件

banhack233 不是逐项复制某一个项目，而是面向常见主机场景组合能力。类似或参考的软件/能力包括：

1. fail2ban：日志扫描、阈值判断、封禁攻击 IP。
2. sshguard：SSH 暴力破解防护。
3. denyhosts：登录失败来源识别与阻断思路。
4. crowdsec：安全事件检测、封禁、告警生态。
5. ClamAV / rkhunter / chkrootkit：Linux 恶意文件、rootkit、入侵痕迹检查思路。
6. nftables / iptables / PF / Windows 防火墙：本项目调用的后端；ufw 属于相关防火墙管理工具，没有独立适配器。

功能

1. 系统安全巡检：SSH 策略、防火墙后端、系统更新/重启需求、通知渠道等。
2. SSH 登录失败扫描：支持 auth.log、secure、Windows OpenSSH event log。
3. SSH 范围封禁：Linux nft/iptables、Windows 本地目标端口跟随 ssh_ports（默认 [22]）；macOS 需管理员维护 PF 过滤规则。
4. root 密码登录支持：不强制禁 root，不强制禁密码登录。
5. SSH 安全基线：禁空密码、低重试、短登录宽限、保留强密码场景。
6. SSH 24 小时保活：默认只改 SSH keepalive，不改系统 TCP sysctl。
7. TCP 系统保活高级项：必须显式 -tcp 才会写全局 TCP keepalive/conntrack 参数。
8. 多渠道通知：Telegram、Discord、Slack、飞书/Lark、通用 webhook、TLS 邮箱；独立投递与持久重试队列。
9. TLS SMTP、独立认证用户名、环境变量密码；主机/端口预设不代表服务商认证一定可用，详见SMTP 边界。
10. Linux 恶意程序巡检：挖矿进程、可疑临时目录执行、LD_PRELOAD、cron/systemd 持久化痕迹。
11. 保守清理：手动扫描显式启用 direct_kill=true 或 -kill 才可结束已知入侵程序名；诊断与定时巡检始终只读。
12. 开机自启动：Linux systemd、macOS launchd、Windows schtasks。
13. 安全默认值：dry_run=true、start_at_end=true、ignore_ips 白名单、direct_kill=false。
14. 默认只计密码错误，按用户分组；成功登录清零并给予 10 分钟宽限。同一读取批次内成功登录优先于封禁，Windows 事件 ID 防止重复计数。
15. 每日正式版本自动更新、校验、重启检查和回滚备份，见 升级手册。
16. 中英文通知、渠道独立语言、UTC/IANA 时区，默认阈值全球一致。

是否能作为杀毒软件

可以作为轻量 Linux 主机杀毒/入侵排查辅助，但不是完整商业杀毒或 EDR。

它能做：

1. 检查常见挖矿程序特征：xmrig、kdevtmpfsi、kinsing、watchbog、stratum+tcp 等。
2. 检查可疑临时目录执行：/tmp、/var/tmp、/dev/shm、/run/user。
3. 检查 LD_PRELOAD 劫持痕迹。
4. 检查 cron、systemd 中的可疑持久化命令。
5. 发现后通知。
6. 显式开启时直接 kill 可疑进程。

它不能保证：

1. 覆盖所有病毒样本。
2. 替代 ClamAV/YARA/商业 EDR。
3. 修复所有 rootkit 或内核级后门。
4. 对业务进程做 100% 无误报判断。

因此默认只扫描和通知。自动处置必须显式开启。

支持平台

Windows 已实现事件游标和本地目标端口封禁。macOS 仍需配置 PF 和日志来源；构建及自动测试不能代替目标主机验收，见 平台边界。

Linux 默认配置路径：

/etc/banhack233/config.json
/var/lib/banhack233/state.json

macOS 默认配置路径：

/usr/local/etc/banhack233/config.json
/usr/local/var/banhack233/state.json

Windows 默认配置路径：

%ProgramData%\banhack233\config.json
%ProgramData%\banhack233\state.json

Windows 安装和系统任务需要管理员 PowerShell。

快速开始

以下用于 Linux systemd。先检查生成的配置，并将实际公司出口加入 ignore_ips；海外团队可设置英文通知。Windows/macOS 使用各自的服务管理方式。

1. 安装：

curl -fsSL https://raw.githubusercontent.com/neko233-com/banhack233/main/scripts/install.sh | sh

2. 查看状态：

sudo banhack233 status

3. 检查主机安全建议：

sudo banhack233 doctor

4. 扫描 Linux 恶意程序/挖矿程序：

sudo banhack233 malware-scan

5. 开启 SSH 24 小时保活：

sudo banhack233 keepalive -write

6. 开启开机自启动：

sudo banhack233 install-autostart

7. 观察一段时间后开启真实封禁：

sudo banhack233 enable-production -config /etc/banhack233/config.json
sudo systemctl restart banhack233

enable-production 只修改 dry_run=false，保留其他配置；之后重启守护进程。可选脚本 scripts/enable-production.sh 还会修改 SSH 策略，需单独审阅。手工等价方式：

sudo sed -i 's/"dry_run": true/"dry_run": false/' /etc/banhack233/config.json
sudo systemctl restart banhack233

常用命令

完整参数见 命令参考。test 是真实扫描，生产模式可修改防火墙；config-check、status、doctor 不结束进程。

查看整体状态

sudo banhack233 status

输出包含：

• 版本。
• 配置路径。
• 是否 dry-run。
• 是否从日志末尾开始监控。
• 自启动后端和状态。
• 规则数量。
• 当前审计结果。

安全审计

sudo banhack233 doctor

会检查：

• SSH 密码登录策略。
• root 登录策略。
• 空密码是否禁止。
• SSH 最大尝试次数。
• SSH 登录宽限时间。
• 防火墙后端是否可用。
• 系统是否需要重启。
• 是否仍在 dry-run。
• 通知渠道是否开启。

不会把 Redis、MySQL、自研 TCP 服务等业务端口当默认问题。业务软件由业务自己决定是否公开。

恶意程序 / 挖矿程序扫描

sudo banhack233 malware-scan

默认只扫描，不 kill、不移动文件。

手动临时 kill：

sudo banhack233 malware-scan -kill

配置自动清理：

{
  "malware": {
    "direct_kill": true
  }
}

direct_kill 是唯一清理配置，默认 false，只影响手动 malware-scan；定时巡检不杀进程。临时目录、挖矿工具名或命令参数中的关键词本身不足以触发清理；先核对报告。

报告：

• 每次 malware-scan 都会输出控制台报告，并写报告文件。
• 文件名格式：{名字}.yyyy-MM-dd_HH-mm-ss.txt。
• 默认名字：malware-scan。
• 自定义名字：banhack233 malware-scan -name ssh-box-1。
• 默认目录：/var/lib/banhack233/reports。
• 默认保留最近 50 份，按最后修改时间 LRU 淘汰。

完整配置：

{
  "malware": {
    "enabled": true,
    "direct_kill": false,
    "report_dir": "/var/lib/banhack233/reports",
    "report_keep": 50
  }
}

生产环境建议先保持 direct_kill=false，观察报告后再开启。

预览 SSH 配置

sudo banhack233 secure-ssh

预览要写入的 SSH 配置，不会改系统。

应用 SSH 基线

sudo banhack233 secure-ssh -write -force

默认策略支持：

• PasswordAuthentication yes
• PermitRootLogin yes
• PermitEmptyPasswords no
• MaxAuthTries 3
• LoginGraceTime 20s

注意：如果你当前只靠 SSH 管理服务器，执行前建议保留一个已登录 session，避免误配置导致无法连回。

SSH 24 小时保活

sudo banhack233 keepalive -write

默认只写入 SSH 配置，不修改系统 TCP keepalive / conntrack 参数，避免影响业务 TCP 长连接、HTTP、数据库连接池等服务。

会写入：

/etc/ssh/sshd_config.d/99-banhack233-keepalive.conf

SSH 配置：

PasswordAuthentication yes
PermitRootLogin yes
TCPKeepAlive yes
ClientAliveInterval 60
ClientAliveCountMax 1440
PermitEmptyPasswords no
MaxAuthTries 3
LoginGraceTime 30s

含义：SSH 每 60 秒保活一次，连续 1440 次，约 24 小时。

TCP 系统保活高级项

默认不修改 TCP 系统参数。如果你明确知道服务器需要全局 TCP keepalive / conntrack 调整，可手动加 -tcp：

sudo banhack233 keepalive -write -tcp

这会额外写入：

/etc/sysctl.d/99-banhack233-keepalive.conf

TCP 系统配置为：

net.ipv4.tcp_keepalive_time = 60
net.ipv4.tcp_keepalive_intvl = 30
net.ipv4.tcp_keepalive_probes = 10
net.netfilter.nf_conntrack_tcp_timeout_established = 432000

含义：

• TCP keepalive 60 秒开始探测。
• 探测间隔 30 秒。
• 连续 10 次失败才认为断开。
• conntrack established 超时 5 天。

这能防止系统、NAT、conntrack 太快清理业务长连接，但属于全局内核参数，会影响整台机器上的 TCP/HTTP/数据库/代理等连接行为。生产服务器建议先评估业务连接模型，再决定是否启用。

如果业务服务代码自己设置了 5 分钟 idle timeout，需要同时修改应用层心跳或超时配置。

开机自启动

Linux:

sudo banhack233 install-autostart
systemctl status banhack233

macOS:

sudo banhack233 install-autostart
sudo launchctl print system/com.neko233.banhack233

Windows:

banhack233.exe install-autostart
schtasks /Query /TN banhack233

查看封禁列表

sudo banhack233 ban-list

Linux 优先使用 nft，没有则使用 iptables。

解封 IP

sudo banhack233 unban 203.0.113.10

公司共用公网 IP / 白名单

公网 SSH 无法获取客户端电脑的 MAC 地址；MAC 只在本地链路内有效。同一个 NAT 出口下，即使按用户名累计失败，防火墙封 IP 仍会影响所有同事。需要识别具体设备时，使用每台设备独立的 SSH 密钥/证书；密码登录和 root 登录仍受支持。

当前默认只计 Failed password，按 IP+用户名分组，并在成功登录后清零和宽限；Invalid user、公钥失败、连接数量不计数。共享用户名仍共享计数，最终封禁仍针对来源 IP，公司出口应加入白名单。本程序不安装“每分钟连接次数”丢弃规则。

旧配置保持不变。原默认规则可用 safe-ssh -write 迁移后重启，自定义规则需逐项核对。密码专用表达式如下：

"patterns": ["Failed password for(?: invalid user)? (?P<user>\\S+) from <HOST>"]

为公司出口添加永久白名单，支持单个 IPv4/IPv6 地址或 CIDR 网段：

sudo banhack233 whitelist 203.0.113.10 198.51.100.0/24
sudo systemctl restart banhack233
sudo banhack233 whitelist

命令保留现有配置和白名单；自定义配置路径用 banhack233 whitelist -config /path/config.json 203.0.113.10。等价配置为 "ignore_ips": ["127.0.0.1", "::1", "203.0.113.10"]。重启后白名单不再累计失败；生产模式会解除状态文件中对应的已有自动封禁并清除计数。没有状态记录的遗留规则，可先用 unban 手动解除。

ban_time 到期后，守护进程会在下一轮扫描实际解封；多条规则封同一个 IP 时，等待所有规则到期。自定义封禁命令需自行实现解封。dry_run=true 不修改已有防火墙规则。

不希望某条规则封 IP 时，将该规则的 "action": "auto" 改为 "action": "notify"，再重启。该规则达到阈值后只告警，ban_time 用作告警冷却时间；通知明确显示“未封禁”，生产模式也会解除该规则已有的自动封禁（同 IP 仍被其他规则封禁时除外）。其他规则继续按各自配置执行。

如果服务器还运行 Fail2ban、SSHGuard、云防火墙或 SSH 连接频率限制，需要分别添加相同白名单。banhack233 whitelist 只管理本项目；这些独立拦截不受其控制。尤其是“同 IP 每分钟最多 N 次新连接”的规则，正确密码/密钥也可能触发，应为可信办公出口设置 SSH 端口例外并持久化。

切换生产模式

sudo banhack233 enable-production -config /etc/banhack233/config.json
sudo systemctl restart banhack233

切换生产模式只改 dry_run，保留 GeoIP、日志、批量通知和白名单。

测试一次扫描

这是执行一次扫描，不是配置语法检查。使用 隔离日志回放 验证匹配，避免与守护进程共享状态。

sudo banhack233 test

仅在触发封禁或审计告警时发送通知。

测试通知发送

sudo banhack233 notify-test
sudo banhack233 notify-test -channel feishu,email
sudo banhack233 notify-test -message "自定义测试内容"

向配置中已启用的渠道发送测试消息：控制台、飞书、Discord、Slack、通用 webhook、邮箱。

配置文件

示例：configs/config.json.example

核心字段：

{
  "interval": "30s",
  "audit_interval": "1h",
  "state_path": "/var/lib/banhack233/state.json",
  "dry_run": true,
  "start_at_end": true,
  "ignore_ips": [
    "127.0.0.1",
    "::1"
  ],
  "rules": [
    {
      "name": "ssh-auth-failure",
      "log_paths": [
        "/var/log/auth.log",
        "/var/log/secure"
      ],
      "patterns": [
        "Failed password for(?: invalid user)? (?P<user>\\S+) from <HOST>"
      ],
      "reset_patterns": [
        "Accepted (?:password|publickey|keyboard-interactive) for (?P<user>\\S+) from <HOST>"
      ],
      "max_attempts": 5,
      "find_time": "10m",
      "ban_time": "1h",
      "action": "auto",
      "count_by_user": true,
      "success_grace": "10m"
    }
  ],
  "malware": {
    "enabled": true,
    "direct_kill": false,
    "report_dir": "/var/lib/banhack233/reports",
    "report_keep": 50
  },
  "ssh_ports": [
    22
  ]
}

字段说明：

通知策略

notifications.language 支持 en / zh-CN，notifications.timezone 支持 UTC / Local / IANA 时区；各渠道可单独设置语言。缺省仍为中文、本机时区。详见语言与时区。

支持这些通知：

webhooks[] 适合接企业内部通知网关、告警平台、OpenClaw 类聚合通知服务。

飞书通知

配置：

{
  "notifications": {
    "console": true,
    "feishu": {
      "enabled": true,
      "url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxxx",
      "secret": "your-feishu-sign-secret",
      "location_language": "zh-CN"
    }
  }
}

飞书使用 交互卡片（msg_type=interactive，JSON 2.0），按告警类型自动配色：封禁红色、模拟封禁/巡检橙色、测试蓝色。

若机器人开启「签名校验」，配置 secret；程序自动附带 timestamp 和 sign（HmacSHA256 + Base64，见飞书文档）。未开启时可省略 secret。

各渠道统一按告警类型包装：飞书交互卡片、Discord embed、Slack Block Kit、邮箱 HTML 卡片（含纯文本兜底）、控制台边框文本、json webhook 结构化字段。

通知字段统一为：规则、来源 IP、归属地、处理方式、封禁原因、封禁持续时间、时间。nft / iptables / windows-firewall 会显示在“处理方式”。

location_language 控制归属地翻译。飞书这类中文渠道建议 zh-CN，会额外显示“归属地中文”。如果没有可翻译内容，则仍显示原文。

测试通知（推荐，直接向已启用渠道发测试消息）：

sudo banhack233 notify-test
sudo banhack233 notify-test -channel feishu,email
sudo banhack233 notify-test -message "自定义测试内容"

notify-test 会按配置依次测试：控制台、飞书、Discord、Slack、通用 webhook、邮箱；-channel 可只测指定渠道。

扫描测试（仅在触发封禁或审计告警时才会发通知）：

sudo banhack233 test

Discord 通知

配置：

{
  "notifications": {
    "discord": {
      "enabled": true,
      "url": "https://discord.com/api/webhooks/xxx/yyy"
    }
  }
}

Discord 使用 embed 卡片，字段展示规则、IP、处理方式等信息。

Slack 通知

配置：

{
  "notifications": {
    "slack": {
      "enabled": true,
      "url": "https://hooks.slack.com/services/xxx/yyy/zzz"
    }
  }
}

Slack 使用 Block Kit 区块消息，含标题、字段分区与时间脚注。

通用 webhook 通知

配置：

{
  "notifications": {
    "webhooks": [
      {
        "name": "internal-alert",
        "enabled": true,
        "url": "https://example.com/webhook",
        "format": "json",
        "headers": {
          "Authorization": "Bearer token"
        }
      }
    ]
  }
}

format 支持：

邮箱通知

配置：

{
  "notifications": {
    "email": {
      "enabled": true,
      "from": "alert@qq.com",
      "to": "admin@example.com",
      "password": "smtp-authorization-code",
      "smtp_host": "",
      "smtp_port": 0
    }
  }
}

自动识别 SMTP：

QQ、163 通常需要 SMTP 授权码，不是网页登录密码。预设只选主机和端口；Gmail 需要可用的应用密码。当前使用 TLS 上的 SMTP PLAIN，不实现 Outlook OAuth2，可改用兼容 SMTP 中继或其他通知渠道。详见认证要求与独立 SMTP 用户名。

防爆破工作流演示

1. 先 dry-run 安装：

curl -fsSL https://raw.githubusercontent.com/neko233-com/banhack233/main/scripts/install.sh | sh
sudo banhack233 install-autostart

2. 查看是否捕获攻击：

sudo banhack233 status
journalctl -u banhack233 -n 100 --no-pager

3. 确认白名单：

"ignore_ips": ["127.0.0.1", "::1", "你的办公出口 IP"]

4. 开启真实封禁：

sudo sed -i 's/"dry_run": true/"dry_run": false/' /etc/banhack233/config.json
sudo systemctl restart banhack233

5. 查看封禁：

sudo banhack233 ban-list

TCP 业务长连接高级项演示

默认不建议修改系统 TCP 参数。只有确认业务需要全局 TCP keepalive / conntrack 调整时，才执行：

sudo banhack233 keepalive -write -tcp

验证：

sysctl net.ipv4.tcp_keepalive_time \
  net.ipv4.tcp_keepalive_intvl \
  net.ipv4.tcp_keepalive_probes \
  net.netfilter.nf_conntrack_tcp_timeout_established

启用 -tcp 后期望：

net.ipv4.tcp_keepalive_time = 60
net.ipv4.tcp_keepalive_intvl = 30
net.ipv4.tcp_keepalive_probes = 10
net.netfilter.nf_conntrack_tcp_timeout_established = 432000

不启用 -tcp 时，这些系统参数保持原样。

如果客户端仍 5 分钟掉线，检查：

• 业务服务是否有应用层 idle timeout。
• 业务协议是否有心跳包。
• 云厂商负载均衡是否有 idle timeout。
• 代理、网关、防火墙是否有自己的空闲连接回收。

root 密码登录说明

本项目支持 root 密码登录，不强制禁止。

推荐最低基线：

PermitRootLogin yes
PasswordAuthentication yes
PermitEmptyPasswords no
MaxAuthTries 3
LoginGraceTime 30s
TCPKeepAlive yes
ClientAliveInterval 60
ClientAliveCountMax 1440

同时建议：

• root 密码足够强。
• 开启飞书或邮箱通知。
• dry_run=false 前先观察。
• 办公出口 IP 写入 ignore_ips。

排障

安装慢

按离线校验安装传入正确平台/架构资产，执行前对照同一 Release 的 SHA256SUMS.txt。也可在安装/更新进程中配置可信代理。安装器每次下载最多等待 10 分钟；下载或校验失败保留旧程序。

SSH 还是断

先确认系统配置：

sshd -T | egrep 'clientalive|tcpkeepalive'

再确认是否有：

• 云负载均衡 idle timeout。
• 业务网关 idle timeout。
• 应用层主动断开。

如果你明确启用了 banhack233 keepalive -write -tcp，再额外检查：

sysctl net.ipv4.tcp_keepalive_time net.netfilter.nf_conntrack_tcp_timeout_established

没有封禁

检查：

sudo banhack233 status
sudo banhack233 test
sudo banhack233 ban-list

如果 dry_run=true，不会真封禁。

飞书没收到

检查：

sudo banhack233 notify-test -channel feishu
journalctl -u banhack233 -n 100 --no-pager

确认 webhook 地址正确；若机器人开启签名校验，配置 secret；确认机器人未被禁用。

开发

go test ./...
go vet ./...
sh build-all.sh

仓库已全部使用 Go，不含 Python。附带两个独立小工具（各自 go.mod，不参与主模块构建）：

cd tools/remotessh && go build     # SSH 运维：diag / exec / put（密码走 SSH_PASS 环境变量）
cd tools/integration && go build   # Linux 防火墙集成自检（需 root + nft，先停守护进程）

HTML 文档生成器也使用独立 Go module：

cd tools/docs
go test ./...
go run . -root ../.. -out ../../site -version dev -commit local -serve 127.0.0.1:8088

普通分支 push 和 PR 不触发 Actions。准备好发布说明并完成本地检查后，推送正式 vX.Y.Z 标签，工作流依次完成 CI、六平台打包、正式 Release 和 GitHub Pages。旧标签不能覆盖最新文档，任何前置步骤失败都不会部署新网页。详见 开发与发布。