Wazuh Server API 认证与授权机制深度解析JWT、RBAC、限流防护与安全头【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuhWazuh Server API 的所有访问都建立在JWT 认证 RBAC 授权双层防线之上并辅以登录失败 IP 封锁、每分钟请求限流和安全响应头等额外保护。本文基于当前仓库文档 authentication.md 并结合api/与framework/wazuh/rbac/的真实源码完整讲清认证流程、令牌生命周期、权限判定逻辑与各保护项的可调参数帮助你既能在生产环境中正确配置与调用 API也能在集成开发中准确诊断 401/403/429 类故障的根因。JWT 认证体系总览原文档给出的核心事实均可在源码中得到一一对应除POST /security/user/authenticate外的所有端点都要求携带 JWT 令牌请求头必须为Authorization: Bearer JWT_TOKEN。令牌短生命周期默认900 秒对应 configuration.py 中的default_security_configuration {auth_token_exp_timeout: 900, rbac_mode: white}。签名使用椭圆曲线EC密钥authentication.py 中定义了JWT_ALGORITHM ES512、JWT_ISSUER wazuh密钥文件位于SECURITY_PATH下的private_key.pem/public_key.pem。令牌编解码使用 PyJWTjwt.encode/jwt.decode见 authentication.py 与 authentication.py。凭据校验落在 RBAC ORM 数据库check_user_master通过AuthenticationManager().check_user(user, password)查询见 authentication.py。集群部署中认证必须运行在 master 节点check_user、decode_token、get_security_conf均通过DistributedAPI(..., request_typelocal_master, ...)显式定向到 master 节点执行见 authentication.py 与 authentication.py。认证时序对应原文档 mermaid 流程EC 密钥对如何生成与保护generate_keypairauthentication.py在启动时按需加载或生成密钥密钥不存在时_write_new_keypair使用ec.generate_private_key(ec.SECP521R1())生成 P-521 曲线密钥对authentication.py私钥以 PKCS8 PEM 写入private_key.pem公钥以 SubjectPublicKeyInfo 写入public_key.pem文件权限收紧为0o640并尝试将属主改回wazuh用户。整个读写过程使用.keypair.lock文件锁fcntl.flock独占/共享锁防止多进程在读取—重建之间产生竞态——这一点在函数 docstring 中明确说明当revoke_tokens触发密钥重建时缓存的旧密钥不会残留。change_keypairauthentication.py负责重建密钥并调用generate_keypair.cache_clear()强制失效缓存这是令牌主动吊销后旧令牌全部失效的底层手段。令牌载荷claims结构generate_tokenauthentication.py构造的载荷是理解后续校验的关键Claim含义iss固定为wazuhaud固定为Wazuh API REST解码时必须匹配nbf/nbf_ms签发时间秒 / 毫秒精度。nbf_ms是私有 claim用于精确校验令牌是否在旧令牌黑名单之后签发expnbf auth_token_exp_timeout默认 900 秒sub用户名rbac_roles用户静态关联的角色 ID 列表rbac_mode签发时的white/black模式快照run_as是否通过 run-as授权上下文方式登录hash_auth_context仅 run-as 登录时携带为授权上下文 JSON 的blake2b16 字节摘要哈希令牌解码与失效判定decode_tokenauthentication.py执行三段校验签名与 audience 校验jwt.decode(token, public_key, algorithms[ES512], audienceWazuh API REST)任何PyJWTError统一转为Unauthorized(Invalid token)。数据库有效性校验将nbf_ms缺失时回退nbf * 1000兼容旧令牌随用户名、角色、run_as一起发往 master 节点的check_tokenauthentication.py。后者会依次确认用户仍然存在若用户未开启allow_run_as则令牌中的角色必须与其静态角色一致通过TokenManager.is_token_valid检查用户与每一个角色维度的黑名单即nbf_ms不得早于令牌吊销时间点。本地配置漂移检测解码后还会重新拉取一次security.yaml若令牌中记录的rbac_mode或过期时长与当前配置不一致直接抛出Unauthorized(Token expired)——这意味着修改rbac_mode或auth_token_exp_timeout后所有已签发令牌立即失效必须重新登录。RBAC 授权在核心逻辑执行之前判定文档明确指出 RBAC 在任何核心逻辑执行之前强制生效。从源码结构看这条链路由四部分构成expose_resources装饰器 → 策略预处理 → 资源展开与黑白模式 → 请求作用域上下文。expose_resources 装饰器框架函数通过 decorator 声明自己暴露的actions与resourcesexpose_resources( actions[agent:get], resources[agent:id:{agents_list}] # 动态资源取自请求参数 agents_list ) def get_agents(...)装饰器包装后的wrapper执行顺序decorators.py_get_required_permissionsdecorators.py用正则解析资源串把{param}形式的动态资源从kwargs中取出具体值静态资源则展开为*_match_permissionsdecorators.py结合rbac_mode计算该用户最终允许的资源集合对带参数过滤的端点如按agents_list查询无权限的资源会被直接从kwargs中过滤掉——用户只会看到自己有权查看的数据而不是被整体拒绝当add_denied为真时如 broadcast 场景被过滤的资源会以WazuhPermissionError(4000)形式进入响应的failed_itemsdecorators.py。这解释了文档中403 Forbidden通常代表 RBAC 拦截而非认证失败认证失败令牌无效/过期抛出的是Unauthorized401而权限不足是装饰器内部抛出的WazuhPermissionError。white 与 black 两种模式white默认拒绝用户只有策略中effect: allow明确放行的资源。black默认放行_black_expansiondecorators.py先把请求所需资源全部展开加入允许集再按策略逐条执行_process_effect——allow取交集、deny从集合中差集移除decorators.py。rbac_mode在 configuration.py 中默认为white可在security.yaml路径常量SECURITY_CONFIG_PATH见 constants.py中改为black。资源通配符展开_expand_resourcedecorators.py负责把策略里的*变成真实资源集合agent:id:*会实时查询全部在线/离线代理group:id:*查全部分组role:id:*/policy:id:*/user:id:*/rule:id:查询 RBAC ORM 对应表node:id:*展开集群节点名。策略本身则由optimize_resourcespreprocessor.py从用户角色挂接的策略 JSON 中预处理为{action: {resource: effect}}结构并校验资源格式不支持超过两段的组合。请求作用域上下文当前用户、RBAC 模式与策略在解码后被写入contextvarsuser、rbac、broadcast等定义于 wazuh/core/common.py装饰器内通过rbac.get()读取见 decorators.py 中rbac.get()[rbac_mode]因此每个请求的权限判定互不串扰。run-as 动态授权上下文除静态角色外POST /security/user/authenticate/run_assecurity_controller.py允许携带 JSON 授权上下文登录RBACheckerauth_context.py用MATCH/MATCH$/FIND/FIND$四个函数加AND/OR/NOT逻辑运算符将上下文与角色规则做结构化匹配动态授予命中的角色。配套限制包括请求体上限AUTH_CONTEXT_MAX_PAYLOAD_SIZE 8 * 1024字节超限返回 413由 CheckAuthContextSizeMiddleware 提前拦截递归深度上限MAX_FIND_ITEM_DEPTH 8防止恶意嵌套上下文触发深度遍历auth_context.py正则匹配带 0.1 秒超时REGEX_TIME_LIMIT防止正则回溯攻击。RBAC 数据用户、角色、规则、策略、关系内置于 framework/wazuh/rbac/default/ 下的users.yaml、roles.yaml、rules.yaml、policies.yaml、relationships.yaml首次启动时导入 SQLite ORM 库API 每次启动前还会调用check_database_integrity()校验数据库完整性wazuh_manager_apid.py。访问控制参数限流与暴力破解防护文档提到的内存中维护限流状态在 middlewares.py 与 error_handler.py 中全部可查。相关默认值定义在 configuration.pyaccess: { max_login_attempts: 50, # 触发封锁前的登录尝试次数 block_time: 300, # IP 封锁时长秒 max_request_per_minute: 300 # 每分钟全局请求上限 }这些参数可在 API 配置模板 api.yaml 中通过access:段覆盖。登录端点 IP 封锁CheckBlockedIP中间件middlewares.py只拦截两个登录端点/security/user/authenticate与/security/user/authenticate/run_as的 GET/POST 请求check_blocked_ipmiddlewares.py在asyncio.Lock保护的临界区内维护ip_stats每 IP 的尝试次数与时间戳与ip_block集合若 IP 距上次记录已超过block_time秒则清除其统计并自动解封已在ip_block中的 IP 直接抛出BlockedIPException403Limit of login attempts reached...尝试次数达到max_login_attempts默认 50后加入封锁集合。注意计数发生在凭证校验之前因此是在途并发请求互相可见的预扣式设计源码 docstring 有明确说明。登录成功后settle_login_attemptmiddlewares.py会回滚一次预扣的计数并在未达阈值时移除封锁标记——即正常用户的偶发失败不会被累计成封锁。access_logmiddlewares.py在登录端点返回 403 时记录IP blocked due to exceeded number of logins attempts警告日志同时把password、key字段脱敏为****并对用户名中的控制字符做转义防日志注入。需要澄清一处细节被封 IP 实际收到的是403BlockedIPException, status403而429语义对应的是下面这个全局每分钟限流Wazuh 内部错误码6001。每分钟全局请求限流CheckRateLimitsMiddlewaremiddlewares.py基于滑动 60 秒窗口计数check_rate_limitmiddlewares.py中若距窗口起点不超过 60 秒则累加计数器否则重置超过max_request_per_minute默认 300时抛出MaxRequestsException错误码 6001。该中间件仅在配置值大于 0 时注册wazuh_manager_apid.py设为0即关闭限流。中间件装配顺序所有保护中间件在 start() 中按固定顺序挂载且多个安全中间件显式使用MiddlewarePosition.BEFORE_SECURITY即先于令牌解析执行中间件位置职责CheckRateLimitsMiddlewareBEFORE_SECURITY每分钟全局限流6001CheckExpectHeaderMiddleware默认校验Expect头与max_upload_size417CheckBlockedIPBEFORE_SECURITY登录端点 IP 封锁403CheckAuthContextSizeMiddlewareBEFORE_SECURITYrun-as 上下文体大小413WazuhAccessLoggerMiddlewareBEFORE_EXCEPTION访问日志、脱敏、封锁告警SecureHeadersMiddlewareBEFORE_EXCEPTION安全响应头ContentSizeLimitMiddleware默认请求体上限max_upload_size413这一顺序意味着未认证的攻击流量同样会消耗限流配额、触发 IP 封锁保护本身不依赖有效令牌。安全响应头SecureHeadersMiddlewaremiddlewares.py调用 Pythonsecure库对每个响应注入文档所列的三个头部代码定义在 middlewares.pyHeaderValuePurpose源码依据Content-Security-Policynone限制资源加载API 本身不承载前端资源ContentSecurityPolicy().set(none)X-Frame-OptionsDENY防止点击劫持禁止被 iframe 嵌入XFrameOptions().deny()ServerWazuh掩盖底层服务器技术指纹Server().set(Wazuh)与之配合uvicorn 启动参数中server_headerFalsewazuh_manager_apid.py关闭了默认的server: uvicorn头部避免与Server: Wazuh冲突形成信息泄露。另外传输层默认启用 HTTPSdefault_api_configuration中https.enabled: Trueconfiguration.py若manager.key/manager.crt缺失configure_sslwazuh_manager_apid.py会自动生成 2048 位 RSA 自签名证书有效期 365 天密钥文件权限收紧为0o400。令牌生命周期管理与集群部署最佳实践结合源码行为原文档Best Practices各条可以落到更具体的操作上优雅处理令牌过期exp由auth_token_exp_timeout默认 900 秒决定/security/user/me可查询当前用户信息/security/user/me/policiessecurity_controller.py直接返回处理后的 RBAC 策略与模式可用于客户端缓存自检。建议客户端在令牌临近过期时主动调POST /security/user/authenticate换新令牌。登出即吊销POST /security/user/logoutsecurity_controller.py调用revoke_current_user_tokens把当前用户及其 run-as 场景下对应的授权上下文哈希的nbf_ms写入令牌黑名单此后check_token对旧令牌的验证一律失败。管理员侧的revoke_tokens还会触发change_keypair()更换 EC 密钥对使全量令牌失效。区分 401 与 403unauthorized_error_handlererror_handler.py在登录端点统一返回Invalid credentials文案避免向攻击者泄露用户存在/不存在的信息差非登录端点的令牌问题同样只回 401。而 403 的Permission DeniedWazuhPermissionError(4000)或 IP 封锁都属于 RBAC/访问控制层语义应按权限问题排查。不要在脚本中内嵌凭据认证走 Basic 头用户名:密码 base64换取 JWTaccess_log的脱敏password→****只能防日志泄露不能替代凭据管理。集群部署确保认证到达 masterlocal_master请求类型authentication.py已从框架层保证——用户凭据校验、令牌有效性校验、security.yaml读取全部定向 master 节点因此用户/角色/策略的管理操作只需也只能对 master 执行worker 节点上调用会经集群路由转发。按安全姿态选择rbac_mode严格环境用默认whiteblack适合需要先放行、再逐条 deny的过渡期。注意修改该值会使存量令牌立即失效见上文配置漂移检测。访问控制调优对高并发集成场景可上调max_request_per_minute设 0 关闭对暴露在互联网的 API 建议调低max_login_attempts并保留block_time两者均在 api.yaml 的access:段配置改动后重启 API 进程生效配置由 read_yaml_config 读取并与默认值合并、经 JSON Schema 校验。验证与测试入口仓库内置的测试可用于交叉验证上述行为认证单测 api/test/test_authentication.py 覆盖密钥生成、令牌编解码与校验分支安全响应头中间件测试 api/test/test_middlewares.pyRBAC 装饰器行为测试 framework/wazuh/rbac/tests/端到端 RBAC 集成测试white/black 两种模式的 tavern 用例位于 api/test/integration/ 的test_rbac_white_*与test_rbac_black_*系列 YAML以及 tests/integration/test_api/。关键文件索引文件作用api/api/authentication.pyEC 密钥生成/缓存、JWT 编解码、master 节点凭据校验api/api/middlewares.py限流、IP 封锁、run-as 体大小、访问日志、安全头中间件api/api/error_handler.py401/403/417/413 等异常的统一响应格式api/api/configuration.pyauth_token_exp_timeout、rbac_mode、access默认值与配置合并api/api/configuration/api.yamlAPI 用户配置模板含access段注释示例api/scripts/wazuh_manager_apid.pyAPI 入口中间件装配顺序、SSL 自动生成、数据库完整性检查framework/wazuh/rbac/decorators.pyexpose_resources、资源展开、white/black 匹配framework/wazuh/rbac/preprocessor.py策略预处理为{action: {resource: effect}}framework/wazuh/rbac/auth_context.pyrun-as 授权上下文规则匹配器framework/wazuh/rbac/default/内置用户/角色/规则/策略/关系种子数据掌握以上内容后你可以完整复现从登录取证、权限诊断到限流调优的整个 Wazuh Server API 安全闭环每个 401/403/4296001响应都能映射到一条明确的源码路径与配置项。【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Wazuh Server API 认证与授权机制深度解析JWT、RBAC、限流防护与安全头【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuhWazuh Server API 的所有访问都建立在JWT 认证 RBAC 授权双层防线之上并辅以登录失败 IP 封锁、每分钟请求限流和安全响应头等额外保护。本文基于当前仓库文档 authentication.md 并结合api/与framework/wazuh/rbac/的真实源码完整讲清认证流程、令牌生命周期、权限判定逻辑与各保护项的可调参数帮助你既能在生产环境中正确配置与调用 API也能在集成开发中准确诊断 401/403/429 类故障的根因。JWT 认证体系总览原文档给出的核心事实均可在源码中得到一一对应除POST /security/user/authenticate外的所有端点都要求携带 JWT 令牌请求头必须为Authorization: Bearer JWT_TOKEN。令牌短生命周期默认900 秒对应 configuration.py 中的default_security_configuration {auth_token_exp_timeout: 900, rbac_mode: white}。签名使用椭圆曲线EC密钥authentication.py 中定义了JWT_ALGORITHM ES512、JWT_ISSUER wazuh密钥文件位于SECURITY_PATH下的private_key.pem/public_key.pem。令牌编解码使用 PyJWTjwt.encode/jwt.decode见 authentication.py 与 authentication.py。凭据校验落在 RBAC ORM 数据库check_user_master通过AuthenticationManager().check_user(user, password)查询见 authentication.py。集群部署中认证必须运行在 master 节点check_user、decode_token、get_security_conf均通过DistributedAPI(..., request_typelocal_master, ...)显式定向到 master 节点执行见 authentication.py 与 authentication.py。认证时序对应原文档 mermaid 流程EC 密钥对如何生成与保护generate_keypairauthentication.py在启动时按需加载或生成密钥密钥不存在时_write_new_keypair使用ec.generate_private_key(ec.SECP521R1())生成 P-521 曲线密钥对authentication.py私钥以 PKCS8 PEM 写入private_key.pem公钥以 SubjectPublicKeyInfo 写入public_key.pem文件权限收紧为0o640并尝试将属主改回wazuh用户。整个读写过程使用.keypair.lock文件锁fcntl.flock独占/共享锁防止多进程在读取—重建之间产生竞态——这一点在函数 docstring 中明确说明当revoke_tokens触发密钥重建时缓存的旧密钥不会残留。change_keypairauthentication.py负责重建密钥并调用generate_keypair.cache_clear()强制失效缓存这是令牌主动吊销后旧令牌全部失效的底层手段。令牌载荷claims结构generate_tokenauthentication.py构造的载荷是理解后续校验的关键Claim含义iss固定为wazuhaud固定为Wazuh API REST解码时必须匹配nbf/nbf_ms签发时间秒 / 毫秒精度。nbf_ms是私有 claim用于精确校验令牌是否在旧令牌黑名单之后签发expnbf auth_token_exp_timeout默认 900 秒sub用户名rbac_roles用户静态关联的角色 ID 列表rbac_mode签发时的white/black模式快照run_as是否通过 run-as授权上下文方式登录hash_auth_context仅 run-as 登录时携带为授权上下文 JSON 的blake2b16 字节摘要哈希令牌解码与失效判定decode_tokenauthentication.py执行三段校验签名与 audience 校验jwt.decode(token, public_key, algorithms[ES512], audienceWazuh API REST)任何PyJWTError统一转为Unauthorized(Invalid token)。数据库有效性校验将nbf_ms缺失时回退nbf * 1000兼容旧令牌随用户名、角色、run_as一起发往 master 节点的check_tokenauthentication.py。后者会依次确认用户仍然存在若用户未开启allow_run_as则令牌中的角色必须与其静态角色一致通过TokenManager.is_token_valid检查用户与每一个角色维度的黑名单即nbf_ms不得早于令牌吊销时间点。本地配置漂移检测解码后还会重新拉取一次security.yaml若令牌中记录的rbac_mode或过期时长与当前配置不一致直接抛出Unauthorized(Token expired)——这意味着修改rbac_mode或auth_token_exp_timeout后所有已签发令牌立即失效必须重新登录。RBAC 授权在核心逻辑执行之前判定文档明确指出 RBAC 在任何核心逻辑执行之前强制生效。从源码结构看这条链路由四部分构成expose_resources装饰器 → 策略预处理 → 资源展开与黑白模式 → 请求作用域上下文。expose_resources 装饰器框架函数通过 decorator 声明自己暴露的actions与resourcesexpose_resources( actions[agent:get], resources[agent:id:{agents_list}] # 动态资源取自请求参数 agents_list ) def get_agents(...)装饰器包装后的wrapper执行顺序decorators.py_get_required_permissionsdecorators.py用正则解析资源串把{param}形式的动态资源从kwargs中取出具体值静态资源则展开为*_match_permissionsdecorators.py结合rbac_mode计算该用户最终允许的资源集合对带参数过滤的端点如按agents_list查询无权限的资源会被直接从kwargs中过滤掉——用户只会看到自己有权查看的数据而不是被整体拒绝当add_denied为真时如 broadcast 场景被过滤的资源会以WazuhPermissionError(4000)形式进入响应的failed_itemsdecorators.py。这解释了文档中403 Forbidden通常代表 RBAC 拦截而非认证失败认证失败令牌无效/过期抛出的是Unauthorized401而权限不足是装饰器内部抛出的WazuhPermissionError。white 与 black 两种模式white默认拒绝用户只有策略中effect: allow明确放行的资源。black默认放行_black_expansiondecorators.py先把请求所需资源全部展开加入允许集再按策略逐条执行_process_effect——allow取交集、deny从集合中差集移除decorators.py。rbac_mode在 configuration.py 中默认为white可在security.yaml路径常量SECURITY_CONFIG_PATH见 constants.py中改为black。资源通配符展开_expand_resourcedecorators.py负责把策略里的*变成真实资源集合agent:id:*会实时查询全部在线/离线代理group:id:*查全部分组role:id:*/policy:id:*/user:id:*/rule:id:查询 RBAC ORM 对应表node:id:*展开集群节点名。策略本身则由optimize_resourcespreprocessor.py从用户角色挂接的策略 JSON 中预处理为{action: {resource: effect}}结构并校验资源格式不支持超过两段的组合。请求作用域上下文当前用户、RBAC 模式与策略在解码后被写入contextvarsuser、rbac、broadcast等定义于 wazuh/core/common.py装饰器内通过rbac.get()读取见 decorators.py 中rbac.get()[rbac_mode]因此每个请求的权限判定互不串扰。run-as 动态授权上下文除静态角色外POST /security/user/authenticate/run_assecurity_controller.py允许携带 JSON 授权上下文登录RBACheckerauth_context.py用MATCH/MATCH$/FIND/FIND$四个函数加AND/OR/NOT逻辑运算符将上下文与角色规则做结构化匹配动态授予命中的角色。配套限制包括请求体上限AUTH_CONTEXT_MAX_PAYLOAD_SIZE 8 * 1024字节超限返回 413由 CheckAuthContextSizeMiddleware 提前拦截递归深度上限MAX_FIND_ITEM_DEPTH 8防止恶意嵌套上下文触发深度遍历auth_context.py正则匹配带 0.1 秒超时REGEX_TIME_LIMIT防止正则回溯攻击。RBAC 数据用户、角色、规则、策略、关系内置于 framework/wazuh/rbac/default/ 下的users.yaml、roles.yaml、rules.yaml、policies.yaml、relationships.yaml首次启动时导入 SQLite ORM 库API 每次启动前还会调用check_database_integrity()校验数据库完整性wazuh_manager_apid.py。访问控制参数限流与暴力破解防护文档提到的内存中维护限流状态在 middlewares.py 与 error_handler.py 中全部可查。相关默认值定义在 configuration.pyaccess: { max_login_attempts: 50, # 触发封锁前的登录尝试次数 block_time: 300, # IP 封锁时长秒 max_request_per_minute: 300 # 每分钟全局请求上限 }这些参数可在 API 配置模板 api.yaml 中通过access:段覆盖。登录端点 IP 封锁CheckBlockedIP中间件middlewares.py只拦截两个登录端点/security/user/authenticate与/security/user/authenticate/run_as的 GET/POST 请求check_blocked_ipmiddlewares.py在asyncio.Lock保护的临界区内维护ip_stats每 IP 的尝试次数与时间戳与ip_block集合若 IP 距上次记录已超过block_time秒则清除其统计并自动解封已在ip_block中的 IP 直接抛出BlockedIPException403Limit of login attempts reached...尝试次数达到max_login_attempts默认 50后加入封锁集合。注意计数发生在凭证校验之前因此是在途并发请求互相可见的预扣式设计源码 docstring 有明确说明。登录成功后settle_login_attemptmiddlewares.py会回滚一次预扣的计数并在未达阈值时移除封锁标记——即正常用户的偶发失败不会被累计成封锁。access_logmiddlewares.py在登录端点返回 403 时记录IP blocked due to exceeded number of logins attempts警告日志同时把password、key字段脱敏为****并对用户名中的控制字符做转义防日志注入。需要澄清一处细节被封 IP 实际收到的是403BlockedIPException, status403而429语义对应的是下面这个全局每分钟限流Wazuh 内部错误码6001。每分钟全局请求限流CheckRateLimitsMiddlewaremiddlewares.py基于滑动 60 秒窗口计数check_rate_limitmiddlewares.py中若距窗口起点不超过 60 秒则累加计数器否则重置超过max_request_per_minute默认 300时抛出MaxRequestsException错误码 6001。该中间件仅在配置值大于 0 时注册wazuh_manager_apid.py设为0即关闭限流。中间件装配顺序所有保护中间件在 start() 中按固定顺序挂载且多个安全中间件显式使用MiddlewarePosition.BEFORE_SECURITY即先于令牌解析执行中间件位置职责CheckRateLimitsMiddlewareBEFORE_SECURITY每分钟全局限流6001CheckExpectHeaderMiddleware默认校验Expect头与max_upload_size417CheckBlockedIPBEFORE_SECURITY登录端点 IP 封锁403CheckAuthContextSizeMiddlewareBEFORE_SECURITYrun-as 上下文体大小413WazuhAccessLoggerMiddlewareBEFORE_EXCEPTION访问日志、脱敏、封锁告警SecureHeadersMiddlewareBEFORE_EXCEPTION安全响应头ContentSizeLimitMiddleware默认请求体上限max_upload_size413这一顺序意味着未认证的攻击流量同样会消耗限流配额、触发 IP 封锁保护本身不依赖有效令牌。安全响应头SecureHeadersMiddlewaremiddlewares.py调用 Pythonsecure库对每个响应注入文档所列的三个头部代码定义在 middlewares.pyHeaderValuePurpose源码依据Content-Security-Policynone限制资源加载API 本身不承载前端资源ContentSecurityPolicy().set(none)X-Frame-OptionsDENY防止点击劫持禁止被 iframe 嵌入XFrameOptions().deny()ServerWazuh掩盖底层服务器技术指纹Server().set(Wazuh)与之配合uvicorn 启动参数中server_headerFalsewazuh_manager_apid.py关闭了默认的server: uvicorn头部避免与Server: Wazuh冲突形成信息泄露。另外传输层默认启用 HTTPSdefault_api_configuration中https.enabled: Trueconfiguration.py若manager.key/manager.crt缺失configure_sslwazuh_manager_apid.py会自动生成 2048 位 RSA 自签名证书有效期 365 天密钥文件权限收紧为0o400。令牌生命周期管理与集群部署最佳实践结合源码行为原文档Best Practices各条可以落到更具体的操作上优雅处理令牌过期exp由auth_token_exp_timeout默认 900 秒决定/security/user/me可查询当前用户信息/security/user/me/policiessecurity_controller.py直接返回处理后的 RBAC 策略与模式可用于客户端缓存自检。建议客户端在令牌临近过期时主动调POST /security/user/authenticate换新令牌。登出即吊销POST /security/user/logoutsecurity_controller.py调用revoke_current_user_tokens把当前用户及其 run-as 场景下对应的授权上下文哈希的nbf_ms写入令牌黑名单此后check_token对旧令牌的验证一律失败。管理员侧的revoke_tokens还会触发change_keypair()更换 EC 密钥对使全量令牌失效。区分 401 与 403unauthorized_error_handlererror_handler.py在登录端点统一返回Invalid credentials文案避免向攻击者泄露用户存在/不存在的信息差非登录端点的令牌问题同样只回 401。而 403 的Permission DeniedWazuhPermissionError(4000)或 IP 封锁都属于 RBAC/访问控制层语义应按权限问题排查。不要在脚本中内嵌凭据认证走 Basic 头用户名:密码 base64换取 JWTaccess_log的脱敏password→****只能防日志泄露不能替代凭据管理。集群部署确保认证到达 masterlocal_master请求类型authentication.py已从框架层保证——用户凭据校验、令牌有效性校验、security.yaml读取全部定向 master 节点因此用户/角色/策略的管理操作只需也只能对 master 执行worker 节点上调用会经集群路由转发。按安全姿态选择rbac_mode严格环境用默认whiteblack适合需要先放行、再逐条 deny的过渡期。注意修改该值会使存量令牌立即失效见上文配置漂移检测。访问控制调优对高并发集成场景可上调max_request_per_minute设 0 关闭对暴露在互联网的 API 建议调低max_login_attempts并保留block_time两者均在 api.yaml 的access:段配置改动后重启 API 进程生效配置由 read_yaml_config 读取并与默认值合并、经 JSON Schema 校验。验证与测试入口仓库内置的测试可用于交叉验证上述行为认证单测 api/test/test_authentication.py 覆盖密钥生成、令牌编解码与校验分支安全响应头中间件测试 api/test/test_middlewares.pyRBAC 装饰器行为测试 framework/wazuh/rbac/tests/端到端 RBAC 集成测试white/black 两种模式的 tavern 用例位于 api/test/integration/ 的test_rbac_white_*与test_rbac_black_*系列 YAML以及 tests/integration/test_api/。关键文件索引文件作用api/api/authentication.pyEC 密钥生成/缓存、JWT 编解码、master 节点凭据校验api/api/middlewares.py限流、IP 封锁、run-as 体大小、访问日志、安全头中间件api/api/error_handler.py401/403/417/413 等异常的统一响应格式api/api/configuration.pyauth_token_exp_timeout、rbac_mode、access默认值与配置合并api/api/configuration/api.yamlAPI 用户配置模板含access段注释示例api/scripts/wazuh_manager_apid.pyAPI 入口中间件装配顺序、SSL 自动生成、数据库完整性检查framework/wazuh/rbac/decorators.pyexpose_resources、资源展开、white/black 匹配framework/wazuh/rbac/preprocessor.py策略预处理为{action: {resource: effect}}framework/wazuh/rbac/auth_context.pyrun-as 授权上下文规则匹配器framework/wazuh/rbac/default/内置用户/角色/规则/策略/关系种子数据掌握以上内容后你可以完整复现从登录取证、权限诊断到限流调优的整个 Wazuh Server API 安全闭环每个 401/403/4296001响应都能映射到一条明确的源码路径与配置项。【免费下载链接】wazuhWazuh - The Open Source Security Platform. Unified XDR and SIEM protection for endpoints and cloud workloads.项目地址: https://gitcode.com/GitHub_Trending/wa/wazuh创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
