# LoomScan v5.9 🕷️

LoomScan

快速开始 · 安装 · 功能 · 架构 · 完整指南

## 🕷️ 什么是 LoomScan？ LoomScan 是一个**免费、离线、多语言的静态分析 pipeline**，能够检测 **24 种编程语言**中的 bug、安全漏洞和代码质量问题。它使用 **区间 Type-2 模糊推理系统** (IT2-FIS) 将来自 42+ 个检测引擎的扫描结果聚合为基于置信区间的决策——没有其他 SAST 工具能做到这一点。 蜘蛛吉祥物 ("Loomy") 编织着分析的网络，其动态进度条会显示扫描阶段，并支持在现代终端（Kitty、iTerm2、WezTerm、VS Code、Ghostty）上进行内联图像渲染。 ### 为什么选择 LoomScan？ | 能力 | LoomScan | Semgrep | SonarQube | Qodana | |---|:---:|:---:|:---:|:---:| | **FIS 置信区间** | ✅ | ❌ | ❌ | ❌ | | **通过执行进行 LLM 验证** | ✅ | ❌ | ❌ | ❌ | | **反事实变异** | ✅ | ❌ | ❌ | ❌ | | **蜕变测试** | ✅ | ❌ | ❌ | ❌ | | **知识图谱 + 影响范围** | ✅ | ❌ | ❌ | ❌ | | **从 git 历史自动挖掘规则** | ✅ | ❌ | ❌ | ❌ | | **规范挖掘（自适应模式）** | ✅ | ❌ | ❌ | ❌ | | **9 级严格度（PHPStan 风格）** | ✅ | ❌ | ❌ | ❌ | | **`--uncertain` 标志（30-70% 区间）** | ✅ | ❌ | ❌ | ❌ | | **免费 + 离线** | ✅ | ✅ CE | ⚠️ CE 限制 | ❌ 付费 | | **语言** | **24** | 30+ | 30+ | 60+ | | **规则** | **2,095** | 3,000+ | 5,000+ | 3,000+ | | **自动修复模式** | **107** | ~50 | ~200 | ~300+ | | **密钥检测** | **275** | 200+ | 企业版 | ✅ | ## 🚀 快速开始 ``` # 安装 pip install loomscan # 一键快速开始（创建 config，运行扫描，显示摘要） loomscan quickstart /path/to/your/code ``` 就是这样。LoomScan 将会： 1. ✅ 创建一个 `.loomscan.yaml` 配置文件 2. 🔍 运行全面扫描（所有 42 个引擎） 3. 📊 按严重程度显示扫描结果摘要 4. 📋 打印后续步骤 ``` ================================================== LoomScan Quick Start — Scan Complete ================================================== Total findings: 14 Critical: 0 High: 1 Medium: 3 Low: 10 Decision: warn ================================================== 📋 Next steps: 1. View detailed findings: loomscan check --full --summary 2. View JSON output: loomscan check --full --json 3. Generate dashboard: loomscan dashboard --repo . 4. Run quality gate: loomscan gate --full --preset balanced 5. Apply auto-fixes: loomscan fix --apply ``` ## 📦 安装 LoomScan 采用 **3 级安装模式** —— 从基础开始，根据需要添加功能： ### 第 1 级：核心（5 秒，纯 Python，随处运行） ``` pip install loomscan ``` - 包含全部 2,095 条规则（v5.4 中为 1,995 条，现在包含框架污点包达到 2,095 条），78 个 CLI 命令，以及 IT2-FIS 大脑 - 无需编译，不依赖 Rust，不依赖 tree-sitter - 适用于 Linux、macOS、Windows（Python 3.9+） ### 第 2 级：完整分析（添加 tree-sitter 以支持 CPG/def-use 链） ``` pip install loomscan[full] ``` - 包含第 1 级的所有内容，此外还有： - 适用于 8 种语言的 tree-sitter 语法（深度 CPG/污点跟踪） - 使用 Hypothesis 进行基于属性的测试 - 使用 pip-audit 进行供应链 CVE 检查 ### 第 3 级：性能（添加 Rust 核心以实现 10-50 倍更快的扫描） ``` pip install loomscan[fast] ``` - 包含第 2 级的所有内容，此外还有： - `loomscan-regex` Rust 核心（YAML 规则扫描速度提升 10-50 倍） - 预编译的二进制 wheel —— 无需 Rust 编译器 ### 验证您的安装 ``` loomscan doctor ``` ``` LoomScan v5.9.0 — health check Python: 3.12.1 (x86_64) Platform: Linux 6.5.0 Tier 1 — Core (always required): [OK] click, rich, yaml, jsonschema, numpy, scikit-fuzzy Tier 2 — Full analysis (tree-sitter, optional): [OK] tree_sitter_python, tree_sitter_javascript, ... → All 8 tree-sitter grammars installed Tier 3 — Rust core (10-50x faster scanning, optional): [OK] loomscan-regex active → YAML engine: Rust core (10-50x faster) YAML engine: Rust core active: True Rule packs: 40 packs, 2095 total rules ``` ## ✨ 功能 ### 10 个独特的差异化优势（没有任何竞争对手具备这些） | # | 功能 | 作用 | |---|---|---| | 1 | **🧠 IT2-FIS 大脑** | 包含 50 条规则的 Type-2 模糊推理。生成置信*区间*（而非点分数）。将严重性、置信度、影响范围、可利用性聚合为 BLOCK/WARN/PASS/UNCERTAIN。 | | 2 | **🤖 LLM 验证** | LLM 提出假设（“函数在输入 None 时崩溃”）；LoomScan 通过*执行*进行验证。仅报告已确认的 bug。由 PRM 把关。 | | 3 | **🔄 反事实变异** | 对代码进行变异（删除行、注入守卫语句）并重新运行检测器。如果扫描结果消失 → 真阳性（提升）。如果仍然存在 → 假阳性（降级）。支持 9 种语言。 | | 4 | **🔬 蜕变测试** | 无预测机制的 bug 检测：`sort(sort(x)) == sort(x)`。捕获任何预测机制都无法捕获的语义 bug。支持 JS/Java/Go。 | | 5 | **🕸️ 知识图谱** | 构建代码库图谱（1,400+ 个节点）。`loomscan impact --changed file.py` 可显示影响范围。 | | 6 | **⛏️ 规则自动挖掘** | `loomscan mine` 扫描 git 历史记录以查找修复 bug 的 commit，并自动生成 Semgrep 规则。您修复过的每一个 bug 都会成为一条永久规则。 | | 7 | **📐 规范挖掘** | `loomscan spec` 从您的代码库中挖掘 API 使用模式并标记偏差。自适应 —— 从您的代码中学习。 | | 8 | **🎯 `--uncertain` 标志** | 仅显示置信度为 30-70% 的扫描结果 —— 那些值得人工审查的发现。 | | 9 | **📊 9 级严格度** | 受 PHPStan 启发的级别（1-9）。级别 1 = 仅严重问题；级别 9 = 所有问题。 | | 10 | **⚡ Rust 核心** | 可选的 Rust 正则表达式引擎，可将 YAML 规则扫描速度提高 10-50 倍。提供预编译的 wheel。 | ### 蜘蛛吉祥物 + 进度条 LoomScan 以 "Loomy" 为特色 —— 这是一只动画 ASCII 蜘蛛吉祥物，会在扫描时编织一张网。在现代终端（Kitty、iTerm2、WezTerm、VS Code、Ghostty）上，Loomy 会通过内联图像协议渲染为真实的 PNG 图像。进度条会显示全部 12 个扫描阶段及实时的扫描结果数量。 ``` # 为 CI/CD 禁用吉祥物 + 进度条 loomscan check --full --no-tui # 或使用 env var LOOMSCAN_NO_TUI=1 loomscan check --full ``` ### 检测覆盖范围 | 类别 | 数量 | 详情 | |----------|-------|---------| | **YAML 规则包** | 2,095 | 涵盖 24 种语言的 40 个规则包（v5.4 中为 1,995 条） | | **自动修复模式** | 107 | Python、JS、K8s、Docker、Rust、Java、Go、Kotlin、SQL、Bash、Dart、Swift、Scala | | **密钥模式** | 275 | AWS、GitHub、Stripe、Slack、OpenAI、GCP、Azure 以及其他 200+ 项服务 | | **污点接收点** | 88 | eval、exec、system、SQL、render、反序列化、路径遍历 | | **过程间知识库** | 200 | Python (18)、JavaScript (78)、Java (30)、Go (69)、C++ (5) | | **类型状态协议** | 5 | file、connection、payment、session、transaction | | **CPG 查询** | 6 | 污点流、def-use 链、跨函数污点、未使用的变量、认证模式、复杂度 | | **CLI 命令** | 78 | check、gate、impact、lsp、bot、playground、monorepo、mine、spec、rules、fix、... | ## 🏗️ 架构 ``` graph TB subgraph "Input" A[Git Diff / Full Repo] end subgraph "L0: Fast Layer (<5s)" B1[Regex SAST] B2[Secret Detection
275 patterns] B3[IaC Scanner
Docker/K8s/Terraform] B4[Commit Risk] end subgraph "L1-L4: Deep Layers" C1[L1: Property Testing
Hypothesis] C2[L2: Test Coverage] C3[L3: Invariants
Daikon-style] C4[L4: Fuzzing
Atheris] end subgraph "L5-L8: Advanced Layers" D1[L5: Policy
OPA/Rego] D2[L6: Symbolic
Z3/Kani] D3[L7: Simulation] D4[L8: Autofix
107 patterns] end subgraph "Research Engines" E1[CPG + Cross-file Taint] E2[Typestate Analysis] E3[Metamorphic Testing] E4[Counterfactual Mutation] E5[Spec Mining] E6[Knowledge Graph] E7[Interprocedural Taint] E8[LLM-Verify] end subgraph "🧠 IT2-FIS Brain" F1[50 Fuzzy Rules] F2[Confidence Intervals] F3[Karnik-Mendel Reduction] F4[BLOCK / WARN / PASS / UNCERTAIN] end subgraph "Output" G1[TUI + Loomy Mascot 🕷️] G2[JSON] G3[SARIF + threadFlow] G4[HTML Dashboard] G5[CycloneDX SBOM] end A --> B1 & B2 & B3 & B4 A --> C1 & C2 & C3 & C4 A --> D1 & D2 & D3 & D4 A --> E1 & E2 & E3 & E4 & E5 & E6 & E7 & E8 B1 & B2 & B3 & B4 --> F1 C1 & C2 & C3 & C4 --> F1 D1 & D2 & D3 & D4 --> F1 E1 & E2 & E3 & E4 & E5 & E6 & E7 & E8 --> F1 F1 --> F2 --> F3 --> F4 F4 --> G1 & G2 & G3 & G4 & G5 style F1 fill:#ff6b6b,color:#fff style F2 fill:#ff6b6b,color:#fff style F3 fill:#ff6b6b,color:#fff style F4 fill:#ff6b6b,color:#fff ``` ### Pipeline 流程 ``` ┌─────────────────────────────────────────────────────────────────┐ │ LoomScan Pipeline │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ L0 │ │ L1-L4 │ │ L5-L8 │ │ Research│ │ │ │ Fast │ │ Deep │ │ Advanced│ │ Engines │ │ │ │ <5s │ │ │ │ │ │ │ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │ │ │ │ │ │ │ └────────────┴────────────┴────────────┘ │ │ │ │ │ ┌────▼────┐ │ │ │ IT2-FIS │ ← 50 fuzzy rules │ │ │ Brain │ ← Confidence intervals │ │ └────┬────┘ │ │ │ │ │ ┌──────────┼──────────┐ │ │ ▼ ▼ ▼ │ │ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │ BLOCK │ │ WARN │ │ PASS │ │ │ │ (1) │ │ (0) │ │ (0) │ │ │ └────────┘ └────────┘ └────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ## 🌍 支持的语言 (24) | 语言 | 规则 | CPG | 污点 | 类型状态 | 自动修复 | |----------|:-----:|:---:|:-----:|:---------:|:-------:| | **Python** | 250 | ✅ | ✅ | ✅ | ✅ | | **JavaScript/TS** | 312 | ✅ | ✅ | ✅ | ✅ | | **Java** | 222 | ✅ | ✅ | ✅ | ✅ | | **C/C++** | 94 | ✅ | ⚠️ | ✅ | ✅ | | **Go** | 49 | ✅ | ⚠️ | ✅ | ✅ | | **Rust** | 61 | ⚠️ | ⚠️ | ❌ | ✅ | | **PHP** | 102 | ❌ | ❌ | ❌ | ✅ | | **Ruby** | 79 | ❌ | ❌ | ❌ | ✅ | | **C#** | 51 | ❌ | ❌ | ❌ | ❌ | | **Swift** | 30 | ❌ | ❌ | ❌ | ✅ | | **Scala** | 30 | ❌ | ❌ | ❌ | ✅ | | **Kotlin** | 50 | ❌ | ❌ | ❌ | ✅ | | **SQL** | 91 | ❌ | ❌ | ❌ | ✅ | | **Bash** | 92 | ❌ | ❌ | ❌ | ✅ | | **Dart** | 30 | ❌ | ❌ | ❌ | ✅ | | **Lua** | 35 | ❌ | ❌ | ❌ | ❌ | | **R** | 35 | ❌ | ❌ | ❌ | ❌ | | **Haskell** | 30 | ❌ | ❌ | ❌ | ❌ | | **Elixir** | 30 | ❌ | ❌ | ❌ | ❌ | | **Objective-C** | 30 | ❌ | ❌ | ❌ | ❌ | | **Groovy** | 30 | ❌ | ❌ | ❌ | ❌ | | **Julia** | 30 | ❌ | ❌ | ❌ | ❌ | | **Perl** | 30 | ❌ | ❌ | ❌ | ❌ | | **COBOL** | 25 | ❌ | ❌ | ❌ | ❌ | ## 🖥️ IDE 集成 ### VS Code ``` # 从 VSIX 安装（repo 中预构建） code --install-extension editor/vscode-loomscan/loomscan-0.2.0.vsix ``` 功能： - 通过 LSP 进行实时诊断 - 悬停查看规则文档 + 修复建议 - 代码操作（“应用 LoomScan 修复”） - 17 种语言激活 ### JetBrains (IntelliJ, PyCharm, WebStorm 等) ``` # 从源代码构建（CI 自动构建） cd editor/intellij-loomscan ./gradlew buildPlugin # 安装：Settings → Plugins → ⚙️ → Install from Disk → build/distributions/*.zip ``` ### LSP Server（任何编辑器） ``` loomscan lsp --repo . ``` 适用于 Neovim、Emacs、Sublime Text、Helix 以及任何兼容 LSP 的编辑器。 ## 📊 CLI 命令 (78)

点击展开完整命令列表

| 类别 | 命令 | |----------|----------| | **核心** | `check`, `quickstart`, `gate`, `dashboard`, `fix`, `doctor` | | **IDE** | `lsp`, `watch` | | **分析** | `cpg`, `taint`, `typestate`, `metamorphic`, `differential`, `deadcode`, `duplicates`, `hotspot`, `pii`, `architecture`, `doc-audit`, `nullness`, `contracts`, `concurrency`, `crypto`, `flawfinder`, `malicious`, `rca`, `impact`, `spec` | | **规则** | `rules`, `mine`, `rules-config`, `rule-lint`, `similar` | | **CI/CD** | `bot`, `pre-commit`, `sbom`, `history-scan`, `missing-patches`, `update-cves`, `maven-cve`, `supply-chain`, `ffi-check` | | **质量** | `strict`, `profile`, `baseline`, `suppressions`, `tuning`, `precision`, `feedback`, `issue`, `runs`, `cache`, `coverage`, `toxicity`, `trace`, `optimize`, `gnn`, `dashboard`, `behavioral`, `code-quality`, `config-scan`, `consistency`, `business-logic`, `source-discovery`, `modern`, `iac`, `js-multiline`, `js-quality`, `ast-analysis`, `symbolic`, `taint-analysis` |

### 最常用的命令 ``` # 扫描 git diff（快速，适用于 PR） loomscan check # 完整 repo 扫描 loomscan check --full # 分组摘要（紧凑输出） loomscan check --full --summary # JSON 输出（适用于 CI/CD） loomscan check --full --json # SARIF 输出（适用于 GitHub Code Scanning） loomscan check --full --sarif --output loomscan.sarif # 仅显示不确定的发现（30-70% 置信度） loomscan check --full --uncertain # Quality gate（SonarQube 风格） loomscan gate --full --preset strict # Blast radius 分析 loomscan impact --changed src/app.py # 应用自动修复 loomscan fix --apply # 生成 HTML 仪表板 loomscan dashboard --repo . # 在 git 历史上运行规则自动挖掘 loomscan mine --repo . --max-commits 100 # 运行 spec 挖掘（自适应 API 模式学习） loomscan spec --repo . ``` ## 🔧 配置 在您的仓库根目录中创建一个 `.loomscan.yaml`（或运行 `loomscan quickstart`）： ``` # LoomScan 配置 strictness: 5 # 1-9 (PHPStan-style) # 启用/禁用引擎 layers: L0_fast: enabled: true L1_property: enabled: false # requires hypothesis L4_fuzz: enabled: false # requires atheris # Quality gate 阈值 gate: max_critical: 0 max_high: 5 min_coverage: 80 # Monorepo workspaces（可选） workspaces: - "apps/*" - "packages/*" - "!apps/legacy" # FP learning（默认：关闭） fp_learn_mode: false ``` ## 📈 GitHub Actions 集成 ``` # .github/workflows/loomscan.yml name: LoomScan on: pull_request: branches: [main, master] push: branches: [main, master] jobs: loomscan: runs-on: ubuntu-latest permissions: contents: read security-events: write steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-python@v5 with: python-version: '3.12' - run: pip install loomscan - run: loomscan check --sarif --output loomscan.sarif --full --strictness 5 || true - uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: loomscan.sarif - name: Fail on critical only if: always() run: | python3 -c " import json with open('loomscan.sarif') as f: data = json.load(f) for run in data.get('runs', []): for result in run.get('results', []): sev = result.get('properties', {}).get('severity', '').lower() if sev == 'critical': print(f'CRITICAL: {result.get(\"ruleId\")}') exit(1) print('No critical findings') " ``` ## 🧪 测试套件 ``` # 运行所有测试 python -m pytest tests/ -q # 当前状态：915 通过，37 跳过，0 失败 ``` | 测试类别 | 数量 | 目的 | |---|---|---| | 回归探针 (v4.3-v4.14) | 150+ | 防止历史 bug 再次出现 | | 冒烟测试 (v4.33-v5.9) | 350+ | 对每个功能进行 E2E 验证 | | 引擎测试 | 200+ | 单个引擎的正确性 | | 集成测试 | 100+ | 跨引擎结果印证 | | 精度测试 | 100+ | FIS 聚合 + 贝叶斯 | ## 📚 文档 - **[GUIDE.md](GUIDE.md)** — 完整的 1,300 行用户指南（安装、所有 78 个命令、配置、示例） - **[RESEARCH_BUSINESS_LOGIC.md](RESEARCH_BUSINESS_LOGIC.md)** — 业务逻辑检测研究 - **[RESEARCH_FRONTIER_SOLUTIONS.md](RESEARCH_FRONTIER_SOLUTIONS.md)** — 前沿检测技术 - **[RESEARCH_MULTI_LANGUAGE_BL.md](RESEARCH_MULTI_LANGUAGE_BL.md)** — 多语言业务逻辑研究 ## 📄 许可证 MIT — 查看 [LICENSE](LICENSE) ## 🙏 致谢 - **Flawfinder** — C/C++ 危险函数数据库 - **Kunlun-M** — 过程间污点分析知识库 - **Semgrep** — YAML 规则包格式兼容性 - **Daikon** — 不变量检测灵感 - **PHPStan** — 9 级严格度模型 - **SonarQube** — 质量门禁 + 热点概念 - **CodeQL** — CPG + def-use 链灵感

LoomScan — Weaving a web of analysis 🕷️

GitHub · PyPI · Documentation

```

标签：DLL 劫持, Python, 可视化界面, 大语言模型, 安全漏洞扫描, 无后门, 模糊逻辑, 逆向工具, 错误基检测, 静态代码分析, 静态应用安全测试