使用说明
ao镜头
静态分析和安全审计 澳大利亚 过程。
在Lua代码进入生产环境之前捕获其中的常见漏洞——无保护绕过、确定性违规、缺少授权、不安全的JSON处理等等。
安装
npm install -g ao-lens
或者直接与npx一起使用：
npx ao-lens audit ./ao/
快速开始
# Audit a file
ao-lens audit process.lua --pretty
# Audit a directory
ao-lens audit ./ao/ --pretty
# Parse structure (handlers, functions, state access)
ao-lens parse process.lua --json
# Generate IPC topology diagram
ao-lens graph ./ao/ --mermaid
# List loaded detection rules
ao-lens rules --skills-dir ./skills
输出示例
============================================================
SECURITY AUDIT REPORT
============================================================
[CRITICAL] NIL_GUARD_REQUIRED (line 15)
msg.From == State.Owner passes when both are nil
[HIGH] JSON_DECODE_NO_PCALL (line 23)
json.decode without pcall — malformed input crashes handler
[HIGH] NO_FROZEN_CHECK (line 15)
Mutating handler without State.Frozen check
RESULT: FAIL
Critical: 1 High: 2 Medium: 0 Low: 0
============================================================
它捕获了什么
ao镜头包括25+内置安全检查和20个可扩展规则：
关键的
| 检查 | 它捕捉到了什么 |
|---|---|
NIL_GUARD_REQUIRED |
msg.From == State.Owner 当两者均为零时通过(nil == nil 是 true 在Lua） |
OWNER_NEVER_INITIALIZED |
State.Owner 从不设置——任何人都可以通过所有身份验证检查 |
LOCAL_STATE_SHADOW |
local State = {} 默默地笼罩着全球国家 |
UNSAFE_OWNER_OR_PATTERN |
State.Owner = State.Owner or msg.From --第一个来电者获胜 |
STATE_OVERWRITE_ON_REPLAY |
State = {...} 没有 or 警卫在重播时擦除状态 |
高
| 检查 | 它捕捉到了什么 |
|---|---|
NO_AUTH_CHECK |
处理程序在不检查的情况下更改状态 msg.From |
NO_FROZEN_CHECK |
无紧急停止检查的诱变处理程序 |
JSON_DECODE_NO_PCALL |
json.decode() 没有pcall——输入错误时崩溃 |
JSON_ENCODE_NO_PCALL |
json.encode() 没有pcall——循环引用时崩溃 |
DETERMINISM_VIOLATION |
os.time(), math.random() --重播时中断状态 |
中等/低
缺少模式验证、条件身份验证、错误消息中的信息泄漏， 0 用作falsy、nil连接等。
GitHub行动
将ao镜头添加到CI管道中：
- uses: credentum/ao-lens@v0.1.0
with:
path: 'ao/'
fail-on-high: 'true'
如果发现严重或高严重性问题，则该操作以代码1退出。
MCP服务器
ao镜头运行方式 主控程序 服务器，让AI编码助手直接访问语义分析。
设置
添加到您的MCP配置中（克劳德代码、游标等）：
{
"mcpServers": {
"ao-lens": {
"command": "npx",
"args": ["-y", "ao-lens-mcp"]
}
}
}
或者直接运行：
ao-lens-mcp
可用工具
| 工具 | 说明 |
|---|---|
analyze_file |
解析文件——提取处理程序、函数、全局变量、状态访问 |
analyze_handler |
按名称详细分析处理程序 |
list_handlers |
列出所有带有动作标签和严格性的处理程序 |
security_audit |
运行具有严重性排名的完整安全审计 |
check_determinism |
检查重播安全违规行为 |
find_state_mutations |
查找全部 State.* 跨文件写入 |
find_state_usage |
跟踪对特定状态字段的读取/写入 |
get_function_details |
函数参数、体分析、调用 |
get_handler_body |
具有身份验证模式和状态访问的处理程序源 |
query_handlers |
按身份验证、冻结、突变、严格性过滤处理程序 |
map_architecture |
跨文件IPC拓扑（json/mameraly/summary） |
自定义检测规则
ao镜头从YAML技能文件中加载检测规则。回购附带了7个规则文件，涵盖了最常见的AO安全陷阱。
使用规则
# Use the included rules
ao-lens audit process.lua --skills-dir ./skills --pretty
# Point to your own rules
ao-lens audit process.lua --skills-dir /path/to/your/skills --pretty
# Or set via environment variable
AO_LENS_SKILLS_DIR=./skills ao-lens audit process.lua --pretty
包含的规则文件
| 文件 | 规则 | 封面 |
|---|---|---|
skill_ao_determinism |
4 | os.time, math.random, os.date, io.* |
skill_ao_authorization |
3 | 第一个调用者获胜，nil==nil绕过，缺少认证 |
skill_ao_json_safety |
2 | json.decode/encode，不带pcall |
skill_ao_frozen_state |
2 | 缺少紧急停止，未初始化冻结 |
skill_lua_nil_safety |
3 | nil concat崩溃，0-is-truth，嵌套表访问 |
skill_ao_handler_patterns |
3 | hasMatchingTag没有body认证，无发送目标 |
skill_ao_replay_safe_init |
3 | State = {} 擦除重播，全局无 or |
制定自己的规则
在 skills/ao/ 目录：
skill_id: skill_my_project
title: "My Project Rules"
domain: lua/ao
tech_stack: [lua, ao]
anti_patterns:
- id: MY_CUSTOM_CHECK
description: "Description of the problem"
severity: high # critical | high | medium | low
detection:
type: regex
pattern: "some\\.dangerous\\.pattern"
bad_code: |
-- What not to do
some.dangerous.pattern()
good_code: |
-- What to do instead
safe.alternative()
检测类型：
regex--匹配源代码中的模式。可选的requires_context检查周围的线条是否有防护图案。handler_analysis--通过匹配处理程序名称和正文内容body_matches,handler_name_contains,handler_name_not_contains.
程序化使用
import { LuaParser } from 'ao-lens';
const parser = new LuaParser();
const result = parser.parse(sourceCode, 'process.lua');
console.log(result.handlers); // Handler definitions
console.log(result.state_analysis); // State mutations, ao.sends, determinism issues
console.log(result.stats); // Summary counts
CLI参考
ao-lens <command> [path] [options]
Commands:
audit <path> Run security audit (default)
parse <path> Parse and extract structure
graph <path> Generate IPC topology
rules List loaded detection rules
diff Compare baseline vs current audit
Options:
--pretty Human-readable output
--json JSON output
--mermaid Mermaid diagram (graph command)
--ci Exit 1 on critical/high issues
--skills-dir Path to custom detection rules
--handlers Scope to specific handlers
技术
贡献
问题和拉取请求欢迎访问 github/credittum/ao-lens.
在当地发展：
git clone https://github.com/credentum/ao-lens.git
cd ao-lens
npm install
npm run build
npm test
