适用的配置文件可用后,Schema Profile 检测会填充这些字段:
| 字段 | 类型 | 来源 | 含义 | 可用位置 |
|---|---|---|---|---|
cf.schema_validation.learned.violated |
Boolean |
学习得到的 Schema Profile | 被评估的请求违反学习配置文件时为 true。 |
Security Analytics 和 Custom Rules |
cf.schema_validation.uploaded.violated |
Boolean |
上传的 schema | 被评估的请求违反所提供 schema 时为 true。 |
Security Analytics 和 Custom Rules |
以下字段按请求位置标识 Schema Profile 违规的名称。
| 字段 | 类型 | 来源 | 含义 | 可用位置 |
|---|---|---|---|---|
cf.schema_validation.learned.path.violated_parameters |
Array<String> |
学习得到的 Schema Profile | 违规路径参数的名称。 | Custom Rules |
cf.schema_validation.learned.query.violated_parameters |
Array<String> |
学习得到的 Schema Profile | 违规查询参数的名称。 | Custom Rules |
cf.schema_validation.learned.headers.violated_parameters |
Array<String> |
学习得到的 Schema Profile | 违规请求标头的名称。 | Custom Rules |
cf.schema_validation.learned.cookies.violated_parameters |
Array<String> |
学习得到的 Schema Profile | 违规 cookie 的名称。 | Custom Rules |
cf.schema_validation.learned.body.violated_parameters |
Array<String> |
学习得到的 Schema Profile | 请求正文违规的 JSON 路径。 | Custom Rules |
cf.schema_validation.uploaded.path.violated_parameters |
Array<String> |
上传的 schema | 违规路径参数的名称。 | Custom Rules |
cf.schema_validation.uploaded.query.violated_parameters |
Array<String> |
上传的 schema | 违规查询参数的名称。 | Custom Rules |
cf.schema_validation.uploaded.headers.violated_parameters |
Array<String> |
上传的 schema | 违规请求标头的名称。 | Custom Rules |
cf.schema_validation.uploaded.cookies.violated_parameters |
Array<String> |
上传的 schema | 违规 cookie 的名称。 | Custom Rules |
cf.schema_validation.uploaded.body.violated_parameters |
Array<String> |
上传的 schema | 请求正文违规的 JSON 路径。 | Custom Rules |
对于正文违规,数组包含首次检测到的违规的 JSON 路径。值为 $ 表示整个正文,而没有更具体的路径。
这些字段包含请求中出现但未在 schema 中声明的、经过 URL 解码的查询参数名称。
| 字段 | 类型 | 来源 | 含义 | 可用位置 |
|---|---|---|---|---|
cf.schema_validation.learned.query.undeclared_parameters |
Array<String> |
学习得到的 Schema Profile | 请求中存在但未在 schema 中声明的查询参数名称。 | Custom Rules |
cf.schema_validation.uploaded.query.undeclared_parameters |
Array<String> |
上传的 schema | 请求中存在但未在 schema 中声明的查询参数名称。 | Custom Rules |
Profile Analysis 中的采样违规包含四个结构化字段,用于报告该请求首次检测到的违规:
| 字段 | 类型 | 含义 |
|---|---|---|
location |
String |
包含违规的请求组成部分:path、query、header、cookie 或 body。 |
error_class |
String |
用于对相似违规分组的稳定、宽泛类别。 |
error_detail |
String |
错误类别内的可选具体原因。 |
target |
String |
与违规关联的可选参数、标头、cookie,或以 $ 为前缀的 JSON 正文路径。 |
error_class 字段可以具有以下值:
| 值 | 含义 |
|---|---|
missing_required |
缺少必填参数、正文或标头。 |
invalid_type |
值的 OpenAPI 或 JSON 类型不正确。 |
invalid_encoding |
字节或文本未使用预期编码。 |
invalid_syntax |
请求语法无效,例如格式错误的 JSON。 |
invalid_media_type |
媒体类型与 schema 不匹配。 |
unsupported_media_type |
媒体类型或媒体类型参数不受支持。 |
duplicate_value |
只接受一个条目的值出现了多次。 |
too_many_values |
集合包含的值多于验证器可接受的数量。 |
constraint_violation |
值违反了 OpenAPI 或 JSON Schema 约束。 |
body_size |
由于大小或截断,无法验证请求正文。 |
当仅凭错误类别不足以说明问题时,error_detail 字段会补充上下文。当类别、位置和目标已能标识失败时,该字段为空。
错误详情值
| 详情系列 | 可能的值 |
|---|---|
| 预期类型 | expected:array、expected:boolean、expected:integer、expected:null、expected:number、expected:object、expected:string、expected:one_of |
| 编码与语法 | invalid_utf8、invalid_ascii、invalid_json、invalid_form_urlencoded |
| 媒体类型 | invalid_content_type、invalid_media_type、unsupported_media_type_parameter |
| Schema 约束 | invalid_length、invalid_object_property_count、invalid_array_item_count、not、all_of、any_of、one_of、invalid_enum_variant、forbidden_value、missing_required_property、number_too_small、number_too_big、number_not_in_range、string_length_not_in_range、different_const_value、multiple_of、pattern_no_match、value_too_deep |
| 格式约束 | format_violation:<format>,其中 <format> 标识 OpenAPI 格式。当前格式包括 uuid、email、date-time、date、time、hostname、ipv4、ipv6、uri、uri-reference、iri、iri-reference、int32、int64、uint64、byte、float 和 double。 |
target 值取决于违规位置:
| 位置 | 目标 |
|---|---|
path、query 或 cookie |
参数名称 |
header |
标头名称,例如 content-type |
body |
以 $ 为前缀的 JSON 路径,例如 $.items[0].quantity |
目标对于适用于整个请求正文的失败为空。当 Cloudflare 无法安全报告目标时,也可以为空。
已使用 API Security 的客户已可通过 Schema Learning 和 Schema Validation 使用 Schema Profiles。Cloudflare 正在向未使用 API Security 的受邀 Enterprise 客户开放封闭测试(closed beta)。有兴趣的客户可联系客户团队表达意向。封闭测试访问不代表未来计划可用性或定价。
Cloudflare 会在对应配置文件可用后评估请求。该配置文件必须适用于请求的 operation。
没有适用配置文件的请求状态为 Not evaluated(未评估)。
有关请求状态和调查步骤,请参阅 分析配置文件检测。