Syphio-HQ/syphio-rules

## 什么是 Syphio？ **Syphio Rules** 在 Shopify 生态系统中定义了一个新的类别： 它不是代码检查器。 它不是格式化工具。 它不是语法验证器。 Syphio 旨在回答一个更深层次的问题： 本仓库包含了 Syphio 的**公共标准**： - 规则定义 - 运行时分析概念 - 评分方法 - 架构原则 - 引擎契约 ## 为何 Syphio 存在 Shopify 工具链历史上专注于**语法正确性**。 这是必要的——但还不够。 ### 语法 vs 运行时智能 | 能力 | 传统工具 | Syphio | | ------------------------ | -------- | ------ | | Liquid 语法验证 | ✓ | ✓ | | 主题结构验证 | ✓ | ✓ | | 运行时成本估算 | ✗ | ✓ | | 循环放大检测 | ✗ | ✓ | | 渲染热点路径分析 | ✗ | ✓ | | 上下文感知 XSS 检测 | 有限 | ✓ | | TTFB 影响建模 | ✗ | ✓ | | 架构级洞察 | 有限 | ✓ | | 评分系统 (0–100) | ✗ | ✓ | **Theme Check 验证结构。** **Syphio 评估后果。** ## 核心概念 Liquid 不仅仅是一种模板语言。 它是一个**运行时系统**，具备： - 控制流 - 数据流 - 执行成本 - 渲染深度 - 安全边界 Syphio 将 Liquid 视为**执行图**，而非静态文本。 ## 架构概览 Syphio 围绕多层次分析模型构建： 1. 解析 Liquid 和主题文件 2. 构建标准化 AST 3. 构造语义图 4. 估算运行时成本 5. 跟踪数据流和污点 6. 评估规则 7. 生成发现结果和评分 → 完整架构： [`docs/architecture.md`](./docs/architecture.md) ## 规则领域 Syphio 将规则组织为反映真实工程关注的领域： | 领域 | 目的 | | ---------------- | -------------------------------- | | Liquid | 渲染逻辑和控制流 | | Security | XSS、不安全输出、信任边界 | | Performance | TTFB、循环、渲染成本 | | Accessibility | 前端商店可用性 | | SEO | 结构化可发现性 | | Hydrogen | 无头商店前端模式 | | Storefront API | 查询成本和过度获取 | | Theme Architecture | 可维护性和结构 | | Data Flow | 变量传播和追踪 | | Quality | 一致性和可靠性 | → 完整分类法： [`docs/categories.md`](./docs/categories.md) ## 评分系统 Syphio 引入了一个归一化的 **0–100 分**，反映： - 安全风险 - 运行时成本 - 算法复杂度 - 架构质量 该评分不是装饰性的——它是**治理信号**。 → 完整评分模型： [`docs/scoring-system.md`](./docs/scoring-system.md) ## 示例发现 Syphio 旨在检测以下模式： - 具有乘法成本的嵌套 Liquid 循环 - HTML 或 JavaScript 上下文中的不安全输出 - 热执行路径内的渲染调用 - 关键模板中的昂贵过滤链 - 高成本的 Storefront API 使用 - 静默的性能退化 查看示例： - [`examples/basic-theme/product-grid.liquid`](./examples/basic-theme/product-grid.liquid) - [`examples/basic-theme/unsafe-output.liquid`](./examples/basic-theme/unsafe-output.liquid) ## 单体仓库结构 ``` syphio-rules/ ├── docs/ ├── rules/ ├── packages/ │ ├── shared-types/ │ ├── syphio-engine/ │ └── config/ ├── examples/ └── assets/ ``` ## 包 ### `packages/shared-types` 定义核心契约： - AST 结构 - 规则接口 - 发现结果模型 - 评分原语 ### `packages/syphio-engine` 实现公共分析引擎： - 解析抽象 - AST 工具 - 语义图构造 - 成本建模 - 污点追踪 - 规则执行 ### `packages/config` 定义： - 默认分类 - 评分权重 - 共享配置标准 ## 规则如何工作 每条规则在结构化分析工件上操作，而非原始文本。 规则可以检查： - AST 节点 - 控制流和数据流图 - 执行成本估算 - 污点传播 - 输出上下文 ## 规则契约 规则定义： - 标识符 - 类别 - 严重性 - 描述 - 检测逻辑 - 修复指导 → 作者指南： [`docs/rule-authoring.md`](./docs/rule-authoring.md) ## 发现结果模型 Syphio 检测到的每个问题都是一个结构化的发现结果，包含： - 规则 ID - 分类 - 严重性 - 位置 - 解释 - 影响 - 修复 - 分数贡献 → 详情： [`docs/findings-model.md`](./docs/findings-model.md) ## 公共引擎契约 本仓库公开： - 规则定义 - 分析模型 - 评分系统 - 引擎契约 执行工具（CLI、集成、平台功能）可能单独分发。 → 契约： [`docs/public-engine-contract.md`](./docs/public-engine-contract.md) ## 设计原则 ### 以运行时为先 所有规则必须关联到真实的执行影响。 ### 可解释性 每个发现结果必须可理解且有充分理由。 ### 伴随后果的严重性 严重性反映业务影响，而不仅仅是正确性。 ### 确定性 分析必须稳定且可重现。 ### 企业级准备 为 CI 流水线、代理机构和大型商店设计。 ## 专业路线图 ### 阶段 1 — 基础 - 单体仓库架构 - 技术原则 - 规则分类 - 引擎契约 ### 阶段 2 — 引擎核心 - AST 标准化 - 语义图构造 - 成本模型 - 污点分析 ### 阶段 3 — 规则包 - Liquid 规则 - 安全规则 - 性能规则 - 架构规则 ### 阶段 4 — 开发者平台 - CLI（私有分发） - CI 集成 - 报告格式 - 策略执行 ### 阶段 5 — 生态系统 - 编辑器集成 - 规则预设 - 自动修复引擎 - 合作伙伴工具 ## 定位 Syphio 不是： - 代码格式化器 - 代码检查器 - 语法检查器 Syphio 是： 这就是它的类别。 ## 贡献 在此阶段，贡献聚焦于： - 架构讨论 - 规则设计 - 评分模型优化 - 分析方法 → 指南： [`docs/contributing.md`](./docs/contributing.md) ## 许可证 MIT

标签：Liquid, SEO检索词, TTFB建模, 上下文感知XSS, 主题审计, 云计算, 前端安全, 安全性, 开源规则, 循环放大检测, 性能评估, 架构标准, 标准规范, 渲染热点分析, 自动化payload嵌入, 自动化攻击, 规则引擎, 评分系统, 质量保证, 运行时分析