Kamailio 安全：基于 User-Agent 的智能准入与自动封禁

SIP 服务器如果说实在是需要映射在公网时，每天都会收到大量来自恶意扫描器的注册尝试。这些扫描器通常带有明显的 User-Agent 特征，通过在 Kamailio 边缘实施基于 User-Agent 的准入控制，可以在恶意请求到达 IPPBX 之前将其拦截，极大降低服务器负载。

Kamailio是什么，它是一个边界会话控制器，也叫SBC，你可以简单理解成，就是一个适用于IPPBX专用的防火墙，把它放在IPPBX的前端，用来阻挡来自于公网的扫描或者是攻击，因为你只把它映射出去了，实际你的IPPBX是在它身后，如果它不工作，或者是断开，攻击无法到达IPPBX；比如你IPPBX的端口是5060【一般会更改】但是你映射到公网的是9926，5060不映射出去，它是需要SBC来传递信息的；RTP同理也不映射IPPBX的出去，只映射SBC的60000-61000出去，完全可以正常通话，正常工作；

从理论上来说，只要User不符合要求，就算有账号，有密码，有IP信息，也无法进入到注册流程，因为它是前端拦截封锁；当然你不可能只用User来做唯一的安全防范，还需要配合超强密码，及Pike模块，还有基于地理等等的防范，并且必要的时候，邮件通知管理员；

一、 环境准备

本文基于 Kamailio 5.8.8版本，如果说是6.0，或者是更新的版本，需要测试；首先确保以下模块已在配置文件中加载：

loadmodule "pv.so"
loadmodule "htable.so"
loadmodule "xlog.so"
loadmodule "textops.so"

二、 定义哈希表存储结构

我们需要两张哈希表来存储配置数据和临时失败计数。

modparam("htable", "htable", "ua_matrix=>size=4")
modparam("htable", "htable", "ua_fail_count=>size=8;autoexpire=1800")
modparam("htable", "htable", "ip_ban=>size=8;autoexpire=3600")

• ua_matrix：存储开关状态和 UA 白名单规则。
• ua_fail_count：记录每个 IP 的失败次数，1800 秒后自动清零。
• ip_ban：封禁列表，3600 秒后自动解封。

三、 初始化白名单配置

在 Kamailio 启动后，需要通过 kamcmd 或脚本初始化配置。这里我们使用 kamcmd 手动写入（也可写入启动脚本）。

# 启用 UA 检测功能
kamcmd htable.sets ua_matrix ua_enabled 1

# 设置白名单正则表达式（支持多个特征用 | 分隔）
# 允许 MicroSIP、ZoIPer、Linphone 以及你自己的自定义标识
kamcmd htable.sets ua_matrix white_list "MicroSIP|ZoIPer|Linphone|MyPBX"

四、 核心路由逻辑

在 request_route 中找到 REGISTER 方法的处理分支，加入以下代码：

if (is_method("REGISTER")) {
    # 如果是来自本地回环或内网IP，跳过检测
    if ($si == "127.0.0.1" || $si == "192.168.1.1") {
        # 直接转发
    } else {
        # 1. 检查 IP 是否已被封禁
        if ($sht(ip_ban=>$si) != $null) {
            xlog("L_WARN", "UA_BLOCK: 已封禁 IP $si 尝试注册，直接丢弃\n");
            drop;
        }

        # 2. 检查 UA 功能是否开启
        if ($sht(ua_matrix=>ua_enabled) == 1) {
            $var(whitelist) = $sht(ua_matrix=>white_list);
            if ($var(whitelist) != $null && $var(whitelist) != "") {
                # 3. 进行正则匹配
                if (!($ua =~ $var(whitelist))) {
                    # 匹配失败，增加失败计数
                    $var(fail_count) = (int)$sht(ua_fail_count=>$si) + 1;
                    $sht(ua_fail_count=>$si) = $var(fail_count);

                    xlog("L_WARN", "UA_REJECT: IP $si UA '$ua' 不在白名单，失败次数:$var(fail_count)\n");

                    # 4. 失败次数达到3次，永久拉黑（自动过期）
                    if ($var(fail_count) >= 3) {
                        $sht(ip_ban=>$si) = 1;
                        $sht(ua_fail_count=>$si) = $null;
                        xlog("L_ALERT", "UA_AUTO_BAN: IP $si 因非法 UA 被自动封禁\n");
                    }

                    sl_send_reply("403", "Forbidden UA");
                    exit;
                }
            }
        }
    }

    # 合法的 UA，清除该 IP 的失败计数（如果有）
    if ($sht(ua_fail_count=>$si) != $null) {
        $sht(ua_fail_count=>$si) = $null;
    }

    # ... 后续正常的注册处理逻辑 ...
}

代码要点说明：

• $ua =~ $var(whitelist)：这是 Kamailio 的扩展正则匹配语法，直接将 UA 字符串与白名单正则进行比对。
• $sht(ua_fail_count=>$si)：以客户端 IP 为键，记录该 IP 连续使用非法 UA 的次数。
• 自动清零：当客户端某次请求使用了合法 UA 时，该 IP 的失败计数会被立即清空，避免合法用户偶尔使用旧客户端被误伤。

五、 动态维护白名单

1. 临时添加例外 UA

如果你的某个客户使用了特殊客户端，可以在运行时动态添加到白名单中，无需重启 Kamailio。

# 在原白名单基础上追加 "NewClient"
kamcmd htable.sets ua_matrix white_list "MicroSIP|ZoIPer|Linphone|MyPBX|NewClient"

2. 临时关闭 UA 检测

当需要调试或临时放行所有 UA 时：

kamcmd htable.sets ua_matrix ua_enabled 0

3. 查看当前封禁列表

kamcmd htable.dump ip_ban

4. 手动解封某个 IP

kamcmd htable.delete ip_ban 192.168.1.100

六、 进阶：通过外部脚本实现动态白名单

如果你希望实现更复杂的逻辑（例如从数据库或 Redis 读取白名单），可以将白名单检查逻辑放在 route 中，并调用 sqlops 或 http_async_client 模块。但对于绝大多数中小型部署场景，本文的哈希表方案已经足够高效和稳定。

七、 效果验证

配置完成后重启 Kamailio，使用 sipvicious 工具模拟扫描：

svmap 192.168.1.1 -p 5060

你会在 Kamailio 日志中看到类似输出：

WARN: UA_REJECT: IP 10.0.0.5 UA 'friendly-scanner' 不在白名单，失败次数:1
WARN: UA_REJECT: IP 10.0.0.5 UA 'friendly-scanner' 不在白名单，失败次数:2
WARN: UA_REJECT: IP 10.0.0.5 UA 'friendly-scanner' 不在白名单，失败次数:3
ALERT: UA_AUTO_BAN: IP 10.0.0.5 因非法 UA 被自动封禁

三次尝试后，攻击 IP 被自动拉黑，后续请求直接丢弃，不会再消耗 PBX 资源。

通过 Kamailio 的 htable 和简单的正则匹配，我们实现了一套轻量级但足够坚固的 User-Agent 准入网关。该方案具备以下优势：

• 零依赖：无需外部数据库或脚本。
• 动态管理：白名单和开关可通过 kamcmd 实时修改。
• 自动防御：连续失败自动封禁，有效缓解暴力扫描。
• 低侵入性：仅修改路由脚本，不影响现有业务逻辑。