如何编写自定义净化规则：Ammonia attribute_filter 回调与高级 API 完全参考

如何编写自定义净化规则Ammonia attribute_filter 回调与高级 API 完全参考【免费下载链接】ammoniaRepair and secure untrusted HTML项目地址: https://gitcode.com/gh_mirrors/am/ammoniaAmmonia是 Rust 生态中最主流的 HTML 净化sanitization库基于白名单机制防止 XSS、布局破坏和点击劫持。而真正发挥它威力的是它的高级 API——尤其是attribute_filter回调它让你对每一个属性做放行、删除、改写三级精细控制。本指南带你从零理解回调时机、返回值语义并串联起url_relative、set_tag_attribute_value等配套高级 API给出一套可直接套用的自定义净化规则配方。一、先理解 Ammonia 的净化流程在使用attribute_filter之前先搞清楚它在整个流程中的位置这是避免踩坑的关键步骤发生了什么你能干预的 API1️⃣ 解析按 HTML5 规范解析为 DOM与浏览器一致—2️⃣ 标签过滤移除白名单外的标签tags/clean_content_tags3️⃣ 属性过滤移除白名单外的属性generic_attributes/tag_attributes4️⃣回调改写attribute_filter对每个存活的属性依次调用attribute_filter⭐5️⃣ URL 处理校验 scheme、处理相对 URLurl_schemes/url_relative6️⃣ 序列化输出安全的 HTML 字符串— 核心结论attribute_filter只在属性已通过白名单之后才会被调用。它管不了被白名单挡掉的属性但对通过的属性拥有最终决定权。实现源码位于 src/lib.rs。二、attribute_filter 回调签名解析pub fn attribute_filtercb, CallbackFn(mut self, callback: CallbackFn) - mut Self where CallbackFn: foru Fn(str, str, u str) - OptionCowu, str Send Sync static,回调接收三个参数返回值决定属性的命运elementstr元素名如img、aattributestr属性名如src、hrefvaluestr属性当前值返回Some(value)放行可原样返回也可返回改写后的新值返回None删除该属性两个必须知道的细节只能设置一次。重复调用会触发 panic源码中写得很直白attribute_filter can be set only once见 src/lib.rs。回调执行时机早于url_relative()。官方文档明确说明Rewriting of attributes with URLs is done beforeurl_relative()。也就是说你在回调里改写的 URL 之后还会经过相对 URL 解析。官方测试url_filter_absolute/url_filter_relative就验证了这一点回调把srcimgtest改写为相对路径后RewriteWithBase再把它拼接成绝对地址见 src/lib.rs。三、三个经典实战模式模式 1按元素属性删除最常用场景允许图片但想强制禁止外链图片删除所有img的srcuse ammonia::Builder; let clean Builder::new() .attribute_filter(|element, attribute, value| { match (element, attribute) { (img, src) None, // 删除 _ Some(value.into()), // 其余放行 } }) .clean(a href/img altHome srcfoo/a); // 输出a href/img altHome/a这是官方文档中的标准示例完整代码见 src/lib.rs。模式 2改写属性值URL 补全/代理化场景把用户上传的相对图片路径统一改写为 CDN 地址let clean Builder::new() .attribute_filter(|elem, attr, value| { match (elem, attr) { (img, src) { Some(format!(https://cdn.example.com/{}, value).into()) } (a, href) { // 统一加前缀走站内路由 Some(format!(/posts/{}, value).into()) } _ Some(value.into()), } }) .clean(img srca.png); // 输出img srchttps://cdn.example.com/a.png模式 3内容级校验白名单 回调双层防御白名单控制哪些属性能出现回调控制值是否合法两者叠加才是完整防线let clean Builder::new() .tag_attributes(maplit::hashmap![iframe maplit::hashset![src]]) .attribute_filter(|elem, attr, value| { if elem iframe attr src { // 只允许来自可信域名的 iframe return value.starts_with(https://partner.example.com/) .then(|| value.into()); } Some(value.into()) }) .clean(iframe src\https://evil.com/x\/iframe);️ 安全提示回调里做域名白名单校验时建议解析出 host 再精确比对避免https://evil.comexample.com这类前缀绕过。四、配套高级 API 速查表attribute_filter很少孤军奋战下面这些高级 API 常与它搭配使用全部定义在 src/lib.rs 中API作用典型场景url_relative(UrlRelative)控制相对 URL透传 / 基于基准改写 / 拒绝回调改写 URL 后的第二步见 src/lib.rsset_tag_attribute_value为指定标签强制注入属性值可覆盖用户输入给所有a强制加target_blankallowed_classes/add_allowed_classes按标签白名单放行 CSS 类名评论系统只放行少数排版类generic_attribute_prefixes放行所有指定前缀的属性如data-放行前端框架的data-*属性link_rel控制a的rel属性默认noopener noreferrer关闭自动 rel 注入strip_comments是否剥离 HTML 注释保留模板注释的调试模式id_prefix给所有id加统一前缀防冲突多组件页面防 id 污染推荐组合拳let sanitizer Builder::default() // 强制给外链加 target_blank .set_tag_attribute_value(a, target, _blank) // 放行 contenteditable="false">【免费下载链接】ammoniaRepair and secure untrusted HTML项目地址: https://gitcode.com/gh_mirrors/am/ammonia创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考