PacketFence 安全事件 MAC 自动检测测试套件解析:基于 VirtualSwitch 的自动隔离与恢复验证
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 的描述,本套件的核心验证链路是:
- 创建一个带有
MAC触发器(^00:0c:29:aa:bb:09)的自定义安全事件; - 连接配置文件(Connection Profile)开启
autoregister: enabled,使设备在 RADIUS 认证期间通过find_or_create自动创建节点,并触发node_discovered事件; - 安全事件引擎在节点发现时评估 MAC 触发器,命中后将设备自动放入隔离 VLAN;
- 关闭事件、删除触发器配置、将节点角色改为
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_vsautoregister:"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:1device.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 分两步:
- 搜索事件:
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。 - 关闭事件:
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,流程为:
DELETE config/security_event/{{id}},断言 200;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)。流程:
POST /api/v1/node_categories/search按角色名查询category_id;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 套件已生成基础配置。
关键技术要点总结
-
MAC 触发器是正则语义:
%TRIGGER_TYPE_TO_CONDITION_TYPE中mac映射为regex条件(lib/pf/factory/condition/security_event.pm),因此可以用^前缀锚定等方式精细控制匹配范围,本套件正是利用这一点让测试设备 MAC 精确命中。 -
autoregister 是自动隔离的前提:没有
autoregister: enabled,设备认证时不会自动建节点,也就不会产生node_discovered触发评估链。该开关的判定实现在 lib/pf/role.pm,节点创建走 DAL 层的find_or_create(lib/pf/node.pm)。 -
关闭事件自动触发 reevaluate_access:
close_security_eventAPI(lib/pf/UnifiedApi/Controller/Nodes.pm)在security_event_force_close成功后调用pf::enforcement::reevaluate_access($mac, "admin_modify"),这是 VLAN 得以重新计算、设备能够从隔离状态恢复的技术基础。 -
执行顺序是测试语义的一部分:先插线验证自动隔离,再拔线、删配置、改角色,最后重新插线验证恢复——每一步的先后关系都保证断言互不干扰,Teardown 的批量关闭与节点删除则保证环境可重复。
-
VirtualSwitch 提供可编程的接入网仿真:通过
virtualswitch_plug_device、virtualswitch_unplug_device、virtualswitch_device_status三个执行器(t/venom/lib/virtualswitch/)即可模拟真实的"插线—认证—查询端口状态"过程,无需真实交换机和物理设备即可做端到端 NAC 行为验证。