基于OpenResty的WAF原理与实践教学文档

第1章 OpenResty基础

1.1 OpenResty简介

OpenResty是基于Nginx扩展的强大Web平台，通过引入Lua脚本语言实现对Nginx的功能扩展。相比传统的Nginx C模块开发，OpenResty具有以下优势：

• 开发效率高：Lua语言抽象程度高，相比C语言能更快速地实现相同功能
• 调试方便：修改Lua代码后无需重启Nginx服务即可生效
• 维护简单：Lua代码比C代码更易读和维护
• 动态执行：支持动态加载和执行Lua脚本

OpenResty的核心组件包括：

• Nginx Lua模块：使Nginx能够执行Lua脚本
• LuaJIT：高性能Lua解释器
• 丰富的第三方模块库

1.2 OpenResty与Nginx的关系

OpenResty本质上是一个增强版的Nginx发行版，主要区别在于：

1. 扩展语言：原生Nginx使用C语言扩展，OpenResty使用Lua
2. 开发模式：OpenResty支持热加载，开发效率更高
3. 生态系统：OpenResty提供了更丰富的Web开发工具和框架

1.3 OpenResty处理阶段

OpenResty基于Nginx的处理阶段模型，但增加了Lua处理能力：

init_by_lua*       → 初始化阶段
init_worker_by_lua* → worker初始化阶段
ssl_certificate_by_lua* → SSL证书处理阶段
set_by_lua*        → 变量设置阶段
rewrite_by_lua*    → 重写阶段
access_by_lua*     → 访问控制阶段
content_by_lua*    → 内容生成阶段
header_filter_by_lua* → 响应头过滤阶段
body_filter_by_lua* → 响应体过滤阶段
log_by_lua*        → 日志记录阶段
exit_worker_by_lua* → worker退出阶段(1.19.3+)

WAF系统通常工作在access_by_lua阶段，在此阶段检测并拦截恶意请求。

第2章 Lua与MoonScript

2.1 Lua语言特性

Lua是OpenResty的主要扩展语言，特点包括：

• 轻量级脚本语言
• 高性能（通过LuaJIT）
• 易于嵌入
• 支持协程
• 通过元表实现面向对象特性

2.2 MoonScript简介

MoonScript是Lua的高级抽象语言，类似于CoffeeScript之于JavaScript：

• 语法更简洁
• 支持类等面向对象特性
• 通过缩进代替大括号
• 需要编译为Lua代码执行

2.2.1 MoonScript安装与使用

1. 安装MoonScript：

sudo luarocks install moonscript

2. 示例MoonScript代码(app.moon)：

lapis = require "lapis"

class extends lapis.Application
  "/": => "Welcome to Lapis #{require "lapis.version"}!"

3. 编译为Lua：

moonc app.moon

2.3 MoonScript与Lua性能对比

• MoonScript编译后的Lua代码性能与手写Lua代码相当
• 性能瓶颈通常不在语言层面，而在业务逻辑实现
• 适合用于WAF规则编写和业务逻辑描述

第3章 OpenResty Web框架

3.1 Lapis框架

Lapis是基于OpenResty的Web框架，特点包括：

• 支持MoonScript和Lua
• 提供脚手架工具
• 内置路由、模板等功能
• 自动生成Nginx配置

3.1.1 Lapis生成的Nginx配置示例

env LAPIS_ENVIRONMENT=development;

worker_processes 1;
error_log stderr notice;
daemon off;
pid logs/nginx.pid;

events {
  worker_connections 1024;
}

http {
  include mime.types;
  
  server {
    listen 8080;
    lua_code_cache off;
    
    location / {
      default_type text/html;
      content_by_lua_block {
        require("lapis").serve("app")
      }
    }
    
    location /static/ {
      alias static/;
    }
    
    location /favicon.ico {
      alias static/favicon.ico;
    }
  }
}

3.2 其他Lua Web框架

1. Lor：国产轻量级Web框架
2. Vanila：国产全栈Web框架
3. Orange：基于Lor的API网关产品

第4章 基于OpenResty的WAF实现

4.1 WAF系统架构

基于OpenResty的WAF通常包含以下组件：

1. 规则引擎：检测恶意请求的核心逻辑
2. 拦截模块：对恶意请求的处理（拒绝/跳转）
3. 管理界面：规则配置和系统管理
4. 日志系统：记录攻击事件

4.2 WAF实现要点

1. 执行阶段选择：

   • 最佳实践：access_by_lua阶段
   • 原因：在内容生成前拦截恶意请求，减少资源消耗

2. 规则实现方式：

   • 黑白名单
   • 正则匹配
   • 行为分析
   • 机器学习模型

3. 性能优化：

   • 使用LuaJIT
   • 合理使用缓存
   • 避免阻塞操作

4.3 WAF开发实践

4.3.1 基本拦截示例

-- 在access_by_lua阶段执行的简单WAF逻辑
local waf = require "waf"

-- 初始化WAF规则
waf.init()

-- 检查请求
local is_malicious, action = waf.check(ngx.var.request_uri, ngx.req.get_headers())

if is_malicious then
    if action == "deny" then
        ngx.exit(ngx.HTTP_FORBIDDEN)
    elseif action == "redirect" then
        ngx.redirect("https://example.com/warning")
    end
end

4.3.2 规则管理

-- 示例规则表
local rules = {
    {
        id = 1,
        description = "SQL Injection Detection",
        pattern = [[(?:union(?:\s+all)?\s+select|select\s+\w+\s+from|insert\s+into|update\s+\w+\s+set|delete\s+from)]],
        action = "deny",
        score = 10
    },
    -- 更多规则...
}

-- 规则匹配函数
local function match_rules(value)
    for _, rule in ipairs(rules) do
        if ngx.re.match(value, rule.pattern, "ijo") then
            return true, rule
        end
    end
    return false, nil
end

第5章 性能优化与最佳实践

5.1 性能优化技巧

1. 使用LuaJIT：启用JIT编译提升性能
2. 缓存规则：避免每次请求都加载规则
3. 合理使用正则：预编译正则表达式
4. 减少内存分配：复用变量和表
5. 使用共享内存：ngx.shared.DICT跨worker共享数据

5.2 最佳实践

1. 阶段选择：

   • 简单检查：access_by_lua
   • 复杂处理：content_by_lua

2. 错误处理：

   • 使用pcall/xpcall捕获异常
   • 避免WAF崩溃影响正常服务

3. 日志记录：

   • 记录攻击详情
   • 使用log_by_lua阶段记录

4. 版本选择：

   • 生产环境使用稳定版本
   • 新功能先在测试环境验证

第6章 高级功能与未来发展

6.1 OpenResty新特性

1. exit_worker_by_lua (1.19.3+)：

   • worker退出时执行清理任务
   • 资源释放、统计信息保存等

2. ngx.balancer模块增强：

   • recreate_request() API
   • 在balancer阶段改写请求信息

6.2 WAF扩展方向

1. 机器学习集成：

   • 异常检测模型
   • 行为分析

2. 云原生支持：

   • Kubernetes集成
   • 动态扩缩容

3. 可视化分析：

   • 攻击态势展示
   • 实时监控

附录A：资源与工具

1. 官方资源：

   • OpenResty官网：https://openresty.org/
   • Lua官方：https://www.lua.org/
   • MoonScript：https://moonscript.org/

2. 开发工具：

   • LuaRocks：Lua包管理器
   • moonc：MoonScript编译器
   • Lapis CLI：Lapis脚手架工具

3. 学习资源：

   • OpenResty最佳实践
   • Programming in Lua
   • MoonScript官方文档