PacketFence 安全事件 MAC 自动检测测试套件解析:基于 VirtualSwitch 的自动隔离与恢复验证

原创2026-10-13 13:47:481,632 阅读
文章标签:网络安全认证鉴权身份认证网络后端前端

PacketFence 安全事件 MAC 自动检测测试套件解析:基于 VirtualSwitch 的自动隔离与恢复验证

导读

本文深入解析 PacketFence 仓库中 t/venom/test_suites/security_event_detect_mac_virtualswitch 测试套件,它验证的是基于 MAC 地址正则匹配的安全事件自动触发能力:在 RADIUS 认证过程中,设备 MAC 命中安全事件触发器后自动进入隔离 VLAN,事件关闭、触发器移除后重新接入即可恢复正常 VLAN。通过逐文件拆解 Venom 测试用例、关键 API 调用与底层实现(lib/pf/security_event.pm、lib/pf/factory/condition/security_event.pm、lib/pf/role.pm),读者可以完整掌握 PacketFence 安全事件触发器的定义、触发条件工厂映射、自动注册(autoregister)链路,以及如何用 VirtualSwitch 模拟真实接入网设备做端到端回归测试。

测试套件概览

套件目标

依据 TESTSUITE.md 的描述,本套件的核心验证链路是:

  1. 创建一个带有 MAC 触发器(^00:0c:29:aa:bb:09)的自定义安全事件;
  2. 连接配置文件(Connection Profile)开启 autoregister: enabled,使设备在 RADIUS 认证期间通过 find_or_create 自动创建节点,并触发 node_discovered 事件;
  3. 安全事件引擎在节点发现时评估 MAC 触发器,命中后将设备自动放入隔离 VLAN;
  4. 关闭事件、删除触发器配置、将节点角色改为 headless_device 后重新接入,设备应被分配正常 VLAN(4)。

这验证的是 PacketFence 的自动安全事件能力:与需要管理员手动隔离(如 security_event_manual_virtualswitch 套件)不同,MAC 触发器属于"检测类"触发,安全事件引擎在认证/发现流程中自动评估并执行 reevaluate_access 动作,无需人工干预。

文件编号约定

套件文件采用两位数字前缀编号,用于控制执行顺序,各阶段含义如下:

文件范围 阶段 说明
00-02 Setup 创建带 MAC 触发器的安全事件、启用 autoregister 的连接配置文件
06-08 Test: Auto-Isolation 通过 MAB 插拔设备,MAC 触发器自动触发
10-15 Test: Close & Remove 关闭安全事件、拔出设备、删除安全事件配置、更新节点角色
16-18 Test: Re-connect 无触发器情况下重新接入,验证恢复正常 VLAN

Teardown 文件(teardown/ 目录下 00-06)负责清理:拔设备、批量关闭事件、删除节点与连接配置文件。

前置依赖

本套件依赖 global_config_virtualswitch 套件完成环境搭建,包括:

  • 安装并配置 virtualswitch,在网络命名空间中启动;
  • 创建交换机组(switch group)与交换机,其中 VLAN 映射包含 guest=1, registration=2, printer=2, windows=3, headless_device=4, user=4, ios=4, android=5, isolation=6;
  • 配置带 RADIUS 监听器的注册接口;
  • 创建 headless_device 角色并重启相关服务。

该依赖在 global_config_virtualswitch/TESTSUITE.md 中有完整步骤说明。

阶段一:Setup——创建触发器与连接配置文件

00_create_security_event.yml:创建带 MAC 触发器的安全事件

00_create_security_event.yml 首先通过 get_login_token 获取 Web 管理 API 令牌,然后调用 POST /api/v1/config/security_events 创建安全事件:

{
  "id": "9000002",
  "desc": "MAC-based auto-isolation test",
  "enabled": "Y",
  "actions": ["reevaluate_access"],
  "vlan": "isolation",
  "triggers": [{"mac": "^00:0c:29:aa:bb:09"}],
  "max_enable": "3",
  "auto_enable": "Y",
  "priority": 1
}

各字段含义与取值参考(对应 t/venom/vars/all.yml 中的变量定义):

字段 取值 说明
id 9000002 自定义安全事件 ID,套件内通过该 ID 引用事件
desc 描述文本 事件的文字说明
enabled Y 事件启用开关
actions ["reevaluate_access"] 事件触发后执行的动作,重新评估设备接入权限(触发 VLAN 重新分配)
vlan isolation 事件关联的 VLAN 名,映射到隔离 VLAN 6
triggers [{"mac": "^00:0c:29:aa:bb:09"}] 触发器类型为 mac,值为正则表达式
max_enable 3 事件最大启用次数(VLAN 被触发的最多次数上限)
auto_enable Y 允许自动启用
priority 1 事件优先级

创建成功后,套件执行 {{.pfserver_pfcmd}} configreload hard 强制重载配置,使新安全事件立即生效(断言 result.code ShouldEqual 0)。

底层原理:触发器类型到条件类型的映射定义在 lib/pf/factory/condition/security_event.pm 的 %TRIGGER_TYPE_TO_CONDITION_TYPE 中,其中 'mac' => {type => 'regex', key => 'mac'} 说明 MAC 触发器最终编译为正则匹配条件,作用在节点信息的 mac 字段上。instantiate()(同文件 L72-L107)负责把 mac::^00:0c:29:aa:bb:09 形式的触发器解析成 pf::condition::regex 条件对象,再包装为 pf::condition::key(键为 mac)。因此 MAC 触发器天然支持正则表达式前缀匹配(如测试中的 ^ 锚定),这与 Fingerbank 设备检测等其他触发器类型(device、dhcp_fingerprint、suricata_event 等)走同一套工厂机制。

01_clean_radius_audit_log.yml:清理 RADIUS 审计日志

01_clean_radius_audit_log.yml 的目的在于清除历史认证记录,避免旧数据干扰断言。做法是把 radius_audit_log_cleanup 维护任务的清理窗口临时改为 1 秒,通过 pfcron 命令行立即执行清理,然后恢复默认 1 天窗口:

{ "status": "enabled", "window": { "interval": "1", "unit": "s" } }

执行 pfcron_command_line unit_command: radius_audit_log_cleanup 后断言输出包含 task radius_audit_log_cleanup finished,最后恢复 interval: 1, unit: "D"。

02_create_connection_profile.yml:创建启用 autoregister 的连接配置文件

02_create_connection_profile.yml 调用 POST /api/v1/config/connection_profiles 创建有线接入配置文件,关键字段:

  • id: catch_secev_detect_vs
  • autoregister: "enabled" —— 核心开关,见下文原理分析
  • filter: [{ "match": "Ethernet-NoEAP", "type": "connection_type" }],filter_match_style: "all" —— 仅匹配有线非 EAP 连接(即 MAB 场景)
  • root_module: "default_policy"
  • status: "enabled"
  • unreg_on_acct_stop: disabled(由变量注入)
  • vlan_pool_technique: "username_hash"
  • dot1x_recompute_role_from_portal: "enabled",mac_auth_recompute_role_from_portal: "disabled"

autoregister 的底层链路:autoregister 决定设备在认证时是否自动注册为节点。在 lib/pf/role.pm 的 isAutoReg 逻辑中,当配置文件 _autoregister 启用且节点状态非 pending 时返回 TRUE,从而允许 MAB 认证的设备自动完成注册。节点注册走 lib/pf/node.pm 的 pf::dal::node->find_or_create({...}),该 DAL 方法定义于 lib/pf/dal.pm。RADIUS 认证路径(lib/pf/radius.pm、L987)同样使用 find_or_create 保证节点存在。节点创建后会触发 node_discovered 内部事件,这正是安全事件引擎评估 MAC 触发器的时机。

阶段二:Test: Auto-Isolation——自动隔离验证

06_plug_device_mab.yml:MAB 接入设备

06_plug_device_mab.yml 使用 virtualswitch_plug_device 执行器模拟设备接入:

- type: virtualswitch_plug_device
  api_url: '{{.virtualswitch.api.url}}'
  interface_id: '{{.security_event_detect_mac_virtualswitch.device.interface.id}}'
  mac_address: '{{.security_event_detect_mac_virtualswitch.device.mac_address}}'
  auth_method: mab
  profile: '{{.security_event_detect_mac_virtualswitch.device.profile}}'

该执行器定义在 t/venom/lib/virtualswitch/virtualswitch_plug_device.yml,本质是向 virtualswitch 的 REST API 发送 POST /api/v1/interfaces/{{interface_id}}/plug,请求体携带 mac_address、auth_method: mab、profile。变量定义(t/venom/vars/all.yml):

  • device.mac_address: 00:0c:29:aa:bb:09(与触发器正则完全匹配)
  • device.interface.id: 1
  • device.profile: linux

随后 sleep 10 等待 RADIUS 认证与安全事件评估完成。MAB(MAC Authentication Bypass)模拟的是打印机、IP 电话等无 802.1X 客户端设备的接入方式,virtualswitch 的 plug 动作等价于真实交换机上端口插入设备后发起的认证。

触发链路:设备接入 → MAB 认证 → autoregister 触发 find_or_create 创建节点 → node_discovered 事件产生 → 安全事件引擎(lib/pf/security_event.pm 的触发处理逻辑)基于 mac 条件与 ^00:0c:29:aa:bb:09 正则比对 → 命中后执行 reevaluate_access 动作 → 设备 VLAN 切换为 isolation。其中 lib/pf/security_event.pm 使用 $pf::factory::condition::security_event::TRIGGER_TYPE_TO_CONDITION_TYPE{$type} 获取条件类型,L705-L708 调用 security_event_add 落库并触发动作执行。

08_check_device_isolated.yml:断言设备进入隔离 VLAN

08_check_device_isolated.yml 使用 virtualswitch_device_status 执行器轮询查询端口状态,最多重试 15 次、每次间隔 5 秒(共约 75 秒),并断言:

- result.virtualswitch_device_status__port_state ShouldEqual authenticated
- result.virtualswitch_device_status__vlan_assigned ShouldEqual {{.security_event_detect_mac_virtualswitch.vlan.isolation}}

其中 vlan.isolation = 6。该断言验证了安全事件被自动触发且 enforcement 生效:端口已认证但被分配到隔离 VLAN,而不是正常的 VLAN 4。轮询重试机制是为了容忍安全事件评估、动作执行与虚拟交换机状态同步之间的延迟。

阶段三:Close & Remove——关闭事件并移除触发器

10_close_security_event.yml:搜索并关闭安全事件

10_close_security_event.yml 分两步:

  1. 搜索事件:POST /api/v1/security_events/search,查询条件为 mac 等于测试设备 MAC、security_event_id 等于 9000002、status 等于 open(三者 AND 组合),带 retry: 5, delay: 3 重试。断言返回结果第一条的 security_event_id 等于事件 ID,并从中提取 items.items0.id 作为事件记录行 ID。
  2. 关闭事件:POST /api/v1/node/{{mac_address_url_encoded}}/close_security_event,请求体为 {"security_event_id": <搜索得到的行ID>},断言返回 200。

API 底层实现:该 API 由 lib/pf/UnifiedApi/Controller/Nodes.pm 的 close_security_event 方法处理:先通过 security_event_exist_id 校验事件存在且属于该 MAC(否则返回 404),随后调用 security_event_force_close 强制关闭,成功后执行 pf::enforcement::reevaluate_access($mac, "admin_modify") 重新评估设备接入权限——这正是关闭事件后设备 VLAN 能够被重新计算的关键调用。MAC 的 URL 编码形式 00%3A0c%3A29%3Aaa%3Abb%3A09 定义在 t/venom/vars/all.yml。

12_unplug_device.yml:拔出设备

12_unplug_device.yml 调用 virtualswitch_unplug_device(对应 DELETE/POST virtualswitch 接口的 unplug 动作)拔出设备,并 sleep 5 等待会话清理。注意顺序:必须先拔设备再删除安全事件配置,避免在删除配置过程中设备持续触发事件产生脏数据。

14_delete_security_event_config.yml:删除安全事件配置

14_delete_security_event_config.yml 使用 pf_api_security_event_delete 执行器删除事件配置。该执行器定义在 t/venom/lib/pf_api_security_event_delete.yml,流程为:

  1. DELETE config/security_event/{{id}},断言 200;
  2. GET config/security_event/{{id}},断言 404(确认配置已彻底删除)。

删除后 MAC 触发器即失效,为阶段四的"恢复正常 VLAN"验证铺路。

15_update_node_role.yml:更新节点角色

15_update_node_role.yml 先将节点角色改为 headless_device(该角色在 global_config_virtualswitch 中创建,VLAN 映射为 4)。流程:

  1. POST /api/v1/node_categories/search 按角色名查询 category_id;
  2. PATCH /api/v1/node/{{mac_address_url_encoded}},请求体:
{
  "category_id": "{{.get_category_id_of_role.category_id}}",
  "status": "reg"
}

status: reg 表示节点处于已注册状态。角色更新是 VLAN 计算的核心输入——headless_device 角色映射到正常 VLAN 4,与测试目标的"恢复接入"一致。

阶段四:Test: Re-connect——无触发器场景恢复正常 VLAN

16_plug_device_mab.yml 与 18_check_device_restored.yml

16_plug_device_mab.yml 与阶段二的接入方式完全相同(virtualswitch_plug_device、auth_method: mab),区别在于此刻:

  • 安全事件配置已删除(MAC 触发器不再存在);
  • 节点角色已是 headless_device(正常 VLAN 4)。

因此设备重新接入后,安全事件引擎不再产生隔离事件。18_check_device_restored.yml 同样轮询 virtualswitch_device_status(retry 15 / delay 5)并断言:

- result.virtualswitch_device_status__port_state ShouldEqual authenticated
- result.virtualswitch_device_status__vlan_assigned ShouldEqual {{.security_event_detect_mac_virtualswitch.vlan.normal}}

其中 vlan.normal = 4。这完成了"自动隔离 → 人工处理 → 自动恢复"的闭环验证:触发条件存在时设备被强制隔离,条件移除且节点恢复正常角色后,同一设备无需人工干预即可回到正常 VLAN。

Teardown:清理与资源回收

Teardown 目录下的 4 个文件按编号顺序执行,确保测试环境可重复运行:

文件 动作 说明
00_unplug_device.yml virtualswitch_unplug_device 安全拔出设备
02_close_security_events.yml POST /api/v1/nodes/bulk_close_security_events 批量关闭该 MAC 上残留的开放事件
04_delete_node.yml pf_api_node_delete 删除测试节点,重试 3 次、间隔 5 秒
06_delete_connection_profile.yml DELETE /api/v1/config/connection_profile/{{id}} 删除连接配置文件

其中 t/venom/lib/pf_api_node_delete.yml 展示了删除节点的完整断言:先 DELETE 断言返回 Deleted {{mac}} successfully,再 GET 断言 404(Unable to get resource with this identifier),确保节点确实被清除。批量关闭事件则调用 bulk_close_security_events API(lib/pf/UnifiedApi/Controller/Nodes.pm),对 items 中列出的 MAC 一次性关闭所有开放事件,避免残留事件污染后续测试。

执行编排与运行方式

本套件通过 Ansible Playbook t/venom/scenarios/security_event_virtualswitch/playbooks/run_tests.yml 编排运行。该 Playbook 按固定顺序执行一系列测试套件:

test_suites:
  - configurator
  - global_config_virtualswitch
  - security_event_acct_virtualswitch
  - security_event_manual_virtualswitch
  - security_event_detect_mac_virtualswitch
  - security_event_detect_mac_virtualswitch/teardown
  - security_event_detect_fingerbank_virtualswitch
  - security_event_delayed_virtualswitch
  - global_config_virtualswitch/teardown

每个套件通过 venom-wrapper.sh {{ venom_dir }}/test_suites/{{ item }} 执行,并使用 VENOM_COMMON_FLAGS: --output-dir={{ venom_dir }}/results/{{ item }} 为每个套件生成独立的结果目录。可以看出,security_event_detect_mac_virtualswitch 是 PacketFence 安全事件矩阵测试(手动触发、账号触发、MAC 检测、Fingerbank 检测、延迟触发)中的一环,专门覆盖检测类(detect)触发器在 VirtualSwitch 模拟环境下的完整生命周期。

运行前提:需要先运行 global_config_virtualswitch 完成 virtualswitch 安装与配置(含 RADIUS 监听、交换机/VLAN 映射、headless_device 角色创建),并确保 configurator 套件已生成基础配置。

关键技术要点总结

  1. MAC 触发器是正则语义:%TRIGGER_TYPE_TO_CONDITION_TYPE 中 mac 映射为 regex 条件(lib/pf/factory/condition/security_event.pm),因此可以用 ^ 前缀锚定等方式精细控制匹配范围,本套件正是利用这一点让测试设备 MAC 精确命中。

  2. autoregister 是自动隔离的前提:没有 autoregister: enabled,设备认证时不会自动建节点,也就不会产生 node_discovered 触发评估链。该开关的判定实现在 lib/pf/role.pm,节点创建走 DAL 层的 find_or_create(lib/pf/node.pm)。

  3. 关闭事件自动触发 reevaluate_access:close_security_event API(lib/pf/UnifiedApi/Controller/Nodes.pm)在 security_event_force_close 成功后调用 pf::enforcement::reevaluate_access($mac, "admin_modify"),这是 VLAN 得以重新计算、设备能够从隔离状态恢复的技术基础。

  4. 执行顺序是测试语义的一部分:先插线验证自动隔离,再拔线、删配置、改角色,最后重新插线验证恢复——每一步的先后关系都保证断言互不干扰,Teardown 的批量关闭与节点删除则保证环境可重复。

  5. VirtualSwitch 提供可编程的接入网仿真:通过 virtualswitch_plug_device、virtualswitch_unplug_device、virtualswitch_device_status 三个执行器(t/venom/lib/virtualswitch/)即可模拟真实的"插线—认证—查询端口状态"过程,无需真实交换机和物理设备即可做端到端 NAC 行为验证。

登录后查看全文
packetfence