Skip to content

EkaEva/locallens

BranchesTags

Repository files navigation

LocalLens

本地优先的 AI 代码安全审计工具

检测密钥泄露 · 发现安全漏洞 · 代码不离开本机

Rust License: MIT

为什么选择 LocalLens？

特性 说明
🔒 隐私优先 代码完全在本地扫描，不上传云端，不调用外部 API
🔍 双引擎检测 密钥检测（正则 + 熵值 + 验证器）+ SAST 漏洞检测（tree-sitter AST + 正则）
🏗️ IaC 安全 Terraform / CloudFormation / Kubernetes / Dockerfile / Helm 配置风险检测
📦 依赖扫描 解析 package.json / go.mod / requirements.txt，查询 OSV API 获取 CVE
🧠 AI 误报过滤 通过 Ollama 本地运行 LLM，智能判断真阳性/假阳性
🔌 MCP Server 集成 Claude Code、Cursor 等 AI 编码代理，实时扫描
📦 可扩展规则 YAML 编写自定义检测规则，支持社区贡献规则包

与现有工具对比：

工具 密钥检测 SAST IaC 依赖扫描 本地运行 AI 过滤 AI 修复 MCP 集成
gitleaks / trufflehog ✅ ❌ ❌ ❌ ✅ ❌ ❌ ❌
Semgrep / CodeQL ❌ ✅ ❌ ❌ ✅ ❌ ❌ ❌
Snyk ✅ ✅ ✅ ✅ ❌ ❌ ✅* ❌
LocalLens ✅ ✅ ✅ ✅ ✅ ✅ ✅ ✅

*Snyk Autofix 需云端，LocalLens 修复完全本地

安装

# 从源码构建
git clone https://github.com/EkaEva/locallens.git
cd locallens
cargo install --path .

快速开始

# 扫描当前目录
locallens scan .

# 扫描指定项目
locallens scan /path/to/project

# 使用内置规则 + 自定义规则
locallens scan . --rules ./my-rules

# JSON 输出（适合 CI/CD）
locallens scan . --output json

# 发现高危问题则返回非零退出码
locallens scan . --fail-on high

命令参考

locallens scan [PATH] [OPTIONS]

选项:
  --no-secrets          禁用密钥检测
  --no-sast             禁用 SAST 漏洞检测
  --triage              启用 AI 误报过滤（需 Ollama）
  --severity <LEVEL>    最低报告级别: critical, high, medium, low, info
  --fail-on <LEVEL>     发现该级别及以上问题则退出码为 1
  --output <FORMAT>     输出格式: terminal, json, sarif
  --output-file <PATH>  输出到文件
  --rules <PATH>        自定义规则目录（可重复指定）
  --exclude <PATTERN>   排除路径模式（可重复指定）
  --ollama-url <URL>    Ollama API 地址（默认 http://localhost:11434）
  --ollama-model <MODEL> Ollama 模型（默认 codellama:7b）
  --max-file-size <N>   跳过大于 N 字节的文件（默认 1MB）
  --staged              只扫描 git staged 文件（pre-commit 用）
  --baseline <PATH>     基线结果文件：仅显示新增发现
  --no-iac              禁用 IaC 安全检测
  --no-deps             禁用依赖漏洞扫描
  --git-history         扫描 Git 历史（所有提交）
  --provider <PROVIDER> LLM 提供者: ollama, openai（默认 ollama）
  --api-key <KEY>       云 LLM API 密钥（OpenAI 等）
  --auto-fix            生成 AI 修复建议（需 --triage）

项目配置（.locallens.yml）

在项目根目录创建 .locallens.yml 文件，自定义扫描行为：

# 启用/禁用特定规则
enable_rules:
  - aws-access-key-id
  - github-token
disable_rules:
  - generic-api-key

# 最低报告级别
severity_threshold: medium

# 触发非零退出码的级别
fail_on: high

# 排除路径
exclude:
  - "**/vendor/**"
  - "**/third_party/**"

# 允许列表（抑制已知误报）
allowlist:
  ignore_rules:
    - generic-api-key
  ignore_paths:
    - "**/test/**"
  ignore_fingerprints:
    - abc123def456

# AI Triage 配置
triage:
  enabled: false
  ollama_url: "http://localhost:11434"
  ollama_model: "codellama:7b"
  skip_confidence: high  # 跳过高置信度发现的 LLM 调用

# 扫描器配置
scanner:
  max_file_size: 2097152  # 2MB
  enable_secrets: true
  enable_sast: true

基线扫描（--baseline）

对比历史扫描结果，只显示新增发现：

# 生成基线
locallens scan . --output json > baseline.json

# 后续扫描只看新增
locallens scan . --baseline baseline.json

基于 finding fingerprint（SHA-256 of rule_id + file_path + line_start + matched_text）去重。

内置检测规则

密钥检测（10 条规则）

规则 级别 CWE OWASP 检测方式
AWS Access Key ID 🔴 严重 CWE-798 A07:2021 AKIA... 前缀 + 熵值 ≥ 3.0 + 校验和验证
AWS Secret Access Key 🔴 严重 CWE-798 A07:2021 40 字符 Base64 + 熵值 ≥ 4.0
GitHub Token 🔴 严重 CWE-798 A07:2021 ghp_ / gho_ / ghs_ 前缀 + 熵值
GitHub OAuth Token 🔴 严重 CWE-798 A07:2021 gho_ 前缀 + 熵值
Stripe Secret Key 🔴 严重 CWE-798 A07:2021 sk_live_ 前缀 + 熵值
Private Key 🔴 严重 CWE-321 A02:2021 -----BEGIN PRIVATE KEY-----
Database URL 🟠 高 CWE-798 A07:2021 内嵌密码的连接字符串
Slack Token 🟠 高 CWE-798 A07:2021 xoxb- / xoxp- 前缀
Google API Key 🟠 高 CWE-798 A07:2021 AIza 前缀
JWT Token 🟠 高 CWE-798 A07:2021 eyJ...eyJ... 三段结构 + 结构验证
Generic API Key 🟡 中 CWE-798 A07:2021 api_key = "..." 赋值模式 + 熵值

SAST 漏洞检测（19 条规则）

命令注入

规则 语言 级别
eval() 使用 Python 🟠 高
exec() 使用 Python 🟠 高
os.system() 调用 Python 🟠 高
subprocess(shell=True) Python 🟠 高
child_process.exec() JS/TS 🟠 高
system() 调用 Ruby 🟠 高

SQL 注入

规则 语言 级别
字符串拼接 SQL Python 🟠 高
f-string 构建 SQL Python 🟠 高
字符串拼接 SQL JS/TS 🟠 高

跨站脚本（XSS）

规则 语言 级别
dangerouslySetInnerHTML JS/TS 🟠 高
innerHTML 赋值 JS/TS 🟠 高
document.write() JS/TS 🟡 中

不安全反序列化

规则 语言 级别
pickle.loads() Python 🟠 高
yaml.load() 无 SafeLoader Python 🟠 高
Marshal.load() Ruby 🟠 高

加密误用

规则 语言 级别
MD5 哈希 Python 🟡 中
SHA-1 哈希 Python 🟡 中
禁用 SSL 证书验证 Python 🟠 高
rejectUnauthorized: false JS/TS 🟠 高

检测效果示例

$ locallens scan ./src

  LocalLens Security Audit Report

  4 finding(s) in 23 files scanned (1.2s)

  SECRETS
  ┌──────┬───────────────────┬──────────────────────────┬───────┬──────────┐
  │  ID  │ Rule              │ File                     │ Line  │ Severity │
  ├──────┼───────────────────┼──────────────────────────┼───────┼──────────┤
  │ S-01 │ aws-access-key-id │ src/config/settings.py   │ 42    │ CRITICAL │
  │ S-02 │ github-token      │ src/auth/github.py       │ 15    │ CRITICAL │
  └──────┴───────────────────┴──────────────────────────┴───────┴──────────┘

  SAST
  ┌──────┬──────────────────────────────┬──────────────────────────┬───────┬──────────┐
  │  ID  │ Rule                         │ File                     │ Line  │ Severity │
  ├──────┼──────────────────────────────┼──────────────────────────┼───────┼──────────┤
  │ V-01 │ python-subprocess-shell-true │ src/utils/runner.py      │ 88    │ HIGH     │
  │ V-02 │ python-os-system-injection   │ src/legacy/exec.py       │ 23    │ HIGH     │
  └──────┴──────────────────────────────┴──────────────────────────┴───────┴──────────┘

  Summary: 2 critical, 2 high, 0 medium, 0 low, 0 info

自定义规则

规则使用 YAML 格式，支持三种匹配模式：

正则模式（密钥检测）

rules:
  - id: my-custom-secret
    category: Secret
    severity: High
    description: "自定义 API Key 模式"
    remediation: "迁移到环境变量"
    languages: []
    pattern:
      type: regex
      pattern: 'my_api_key_[a-zA-Z0-9]{32}'
      entropy_threshold: 3.5
    allowlist:
      paths: ["**/test/**"]
      regexes: ["my_api_key_example"]

Tree-sitter 模式（AST 级漏洞检测）

rules:
  - id: python-sql-injection
    category: Sast
    severity: High
    description: "SQL 查询使用字符串拼接"
    remediation: "使用参数化查询"
    languages: ["python"]
    pattern:
      type: tree_sitter
      query: '(call function: (attribute attribute: (identifier) @method) arguments: (argument_list (binary_operator) @injection))'
      capture_name: "injection"
    allowlist:
      paths: ["**/test/**"]

混合模式（正则预过滤 + AST 确认）

rules:
  - id: react-xss
    category: Sast
    severity: High
    description: "React XSS 风险"
    remediation: "使用 DOMPurify 消毒"
    languages: ["javascript", "typescript"]
    pattern:
      type: combined
      regex: 'dangerouslySetInnerHTML'
      tree_sitter_query: '(jsx_attribute property: (property_identifier) @prop)'
      capture_name: "prop"

多模型 LLM 支持（Phase 8）

除了默认的 Ollama，现在支持 OpenAI 兼容 API（覆盖 vLLM、LM Studio、llama.cpp server、OpenAI）：

# 使用 Ollama（默认，本地优先）
locallens scan . --triage

# 使用 OpenAI API
locallens scan . --triage --provider openai --api-key sk-xxx --ollama-model gpt-4

# 使用 vLLM 本地服务（OpenAI 兼容）
locallens scan . --triage --provider openai --ollama-url http://localhost:8000 --ollama-model codellama

AI 自动修复（Phase 8）

为每个发现生成代码修复建议：

# 扫描 + triage + 自动修复
locallens scan . --triage --auto-fix

# 使用 OpenAI 生成修复
locallens scan . --triage --auto-fix --provider openai --api-key sk-xxx

修复建议以 unified diff 格式输出，包含解释说明。不会自动修改文件，仅提供建议。

IaC 安全检测（Phase 7）

检测基础设施即代码中的安全配置问题：

规则文件 规则数 检测内容
terraform.yml 5 公开 S3、未加密 RDS、通配符 IAM、硬编码密钥
cloudformation.yml 3 公开 S3、未加密 RDS、通配符 IAM
kubernetes.yml 4 特权容器、hostPath 挂载、root 用户、无资源限制
dockerfile.yml 4 ADD 使用、root 用户、敏感 ENV、latest 标签
helm.yml 3 特权默认值、明文 HTTP、硬编码密钥 
# 扫描 IaC 配置
locallens scan . --rules rules/iac

# 禁用 IaC 检测
locallens scan . --no-iac

依赖漏洞扫描（Phase 7）

解析依赖清单并查询 OSV API 获取已知 CVE：

清单文件 生态系统
package.json npm
go.mod Go
requirements.txt PyPI 
# 自动检测并扫描依赖（需联网查询 OSV API）
locallens scan .

# 禁用依赖扫描
locallens scan . --no-deps

OSV API 不可用时自动降级，不阻塞扫描。

Git 历史扫描（Phase 7）

扫描所有历史提交中可能已泄露但已删除的密钥：

# 扫描完整 Git 历史
locallens scan . --git-history

使用 git show 读取每个提交的文件内容，无需 checkout。跨提交去重：相同密钥只报告最早出现的提交。

AI 误报过滤（Phase 3）

使用本地 LLM 审查检测结果，标记为 [TP] 真阳性 / [FP] 假阳性 / [??] 需审查：

# 需要先启动 Ollama 并拉取代码模型
ollama pull codellama:7b

# 扫描时启用 AI 过滤
locallens scan . --triage

# 指定 Ollama 地址和模型
locallens scan . --triage --ollama-url http://localhost:11434 --ollama-model codellama:7b

# 对已有结果重新过滤
locallens scan . --output json > results.json
locallens triage results.json

# 只过滤尚未处理的结果
locallens triage results.json --new-only

特性：

  • 优雅降级：Ollama 不可用时自动跳过 triage，扫描正常完成
  • 结果缓存：~/.locallens/cache/ 持久化，7 天 TTL，避免重复 LLM 调用
  • 结构化输出：LLM 返回 JSON 格式的 verdict + reasoning + adjusted_severity
  • 终端标记：表格新增 Triage 列，详情显示推理过程和调整后严重级别

Git Hook 集成（Phase 4）

# 安装 pre-commit 钩子（提交前自动扫描 staged 文件）
locallens hook install

# 指定阻止提交的最低严重级别
locallens hook install --fail-on critical

# 卸载
locallens hook uninstall

增量扫描：使用 --staged 参数只扫描 git staged 文件，大幅提升速度：

# 只扫描 staged 文件（pre-commit 钩子内部使用）
locallens scan --staged

# SARIF 输出（对接 GitHub Code Scanning）
locallens scan . --output sarif > results.sarif

MCP Server（Phase 5）

将 LocalLens 作为 MCP 工具集成到 AI 编码代理中，实现实时安全扫描：

# 启动 MCP Server（stdio 模式）
locallens mcp

Claude Code 配置：

{
  "mcpServers": {
    "locallens": {
      "command": "locallens",
      "args": ["mcp"]
    }
  }
}

Cursor 配置：

{
  "mcp": {
    "servers": {
      "locallens": {
        "command": "locallens",
        "args": ["mcp"]
      }
    }
  }
}

GitHub Action（Phase 9）

在 CI/CD 中自动运行安全扫描并上传 SARIF 到 GitHub Code Scanning：

# .github/workflows/security-scan.yml
name: LocalLens Security Scan
on: [push, pull_request]
permissions:
  security-events: write
  contents: read

jobs:
  locallens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install LocalLens
        run: cargo install --git https://github.com/EkaEva/locallens.git
      - name: Run scan
        run: locallens scan . --output sarif --output-file results.sarif
        continue-on-error: true
      - name: Upload SARIF
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
          category: locallens

也可使用 Docker-based Action：

- uses: EkaEva/locallens@main
  with:
    path: '.'
    severity: 'low'
    fail-on: 'high'

规则管理（Phase 9）

# 列出所有可用规则
locallens rules list

# 按类别过滤
locallens rules list --category secret

# 按严重级别过滤
locallens rules list --severity critical

# JSON 输出
locallens rules list --json

# 创建自定义规则
locallens rules create my-api-key \
  --category secret \
  --severity high \
  --pattern 'my_api_key_[a-zA-Z0-9]{32}' \
  --entropy 3.5 \
  --description "My custom API key pattern" \
  --remediation "Move to environment variable"

历史趋势追踪（Phase 9）

每次扫描自动保存结果到 .locallens/history/，可查看安全趋势：

# 查看最近 10 次扫描的趋势
locallens trend

# 查看最近 20 次
locallens trend --last 20

# 详细分类趋势
locallens trend --detailed

# JSON 输出（对接 Dashboard）
locallens trend --json

安全评分（Phase 9）

每次扫描自动计算项目安全评分（A-F），基于加权扣分：

严重级别 扣分
Critical 25 分/个
High 10 分/个
Medium 4 分/个
Low 1 分/个
Info 0 分/个
评分 等级 含义
90-100 A 优秀：无 Critical/High，少量 Medium
75-89 B 良好：无 Critical，少量 High
50-74 C 一般：存在 High 问题
25-49 D 较差：存在 Critical 问题
0-24 F 危险：大量 Critical 问题

评分在终端和 JSON 输出中自动显示。

跨函数污点追踪（Phase 10）

追踪用户输入到危险函数的完整数据流，检测跨函数的注入漏洞：

# 启用污点追踪
locallens scan . --taint

# 结合其他检测
locallens scan . --taint --triage

追踪能力：

  • 自动识别用户输入源：input()、request.args、req.query、process.argv 等
  • 追踪变量赋值链（最多 3 跳）：user_input → processed → eval(processed)
  • 识别危险汇点：eval()、exec()、os.system()、innerHTML 等
  • 支持 Python、JavaScript/TypeScript、Go、Ruby

策略即代码（Phase 10）

定义安全策略，在 CI/CD 中强制执行安全标准：

# 检查策略合规
locallens policy check . --policy policies/default.yml

# 检查多个策略文件
locallens policy check . --policy policies/

# JSON 输出
locallens policy check . --policy policies/default.yml --output json

策略文件示例（policies/default.yml）：

name: production-security
description: Security policy for production deployments

rules:
  - id: no-critical-findings
    check:
      type: max_findings
      severity: critical
      max: 0
    action: block
    message: No critical findings allowed in production

  - id: no-secret-leaks
    check:
      type: block_category
      category: secret
    action: block
    message: No secret leaks allowed

  - id: min-security-score
    check:
      type: min_score
      score: 75
    action: block
    message: Security score must be at least 75

  - id: min-security-grade
    check:
      type: min_grade
      grade: B
    action: warn
    message: Security grade should be at least B

策略检查类型：

检查类型 说明
max_findings 限制某严重级别的最大发现数
block_rule_ids 禁止特定规则 ID 的发现
min_score 最低安全评分
min_grade 最低安全等级
block_category 禁止某类别的所有发现
max_findings_in_path 限制特定路径的最大发现数

项目架构

locallens/
├── crates/
│   ├── locallens-core/     # 核心类型 · 文件遍历 · 规则引擎 · 扫描编排 · Git 历史 · 策略引擎
│   ├── locallens-secrets/  # 密钥检测（正则 + Shannon 熵 + 结构验证器 + 编码解码）
│   ├── locallens-sast/     # SAST 漏洞检测（tree-sitter AST + 正则回退 + 污点追踪 + IaC 检测）
│   ├── locallens-triage/   # LLM 误报过滤（Ollama / OpenAI 兼容 API 客户端）
│   ├── locallens-deps/     # 依赖漏洞扫描（OSV API + manifest 解析）
│   ├── locallens-report/   # 输出格式化（终端富文本 · JSON · SARIF）
│   ├── locallens-mcp/      # MCP Server（JSON-RPC 2.0 over stdio）
│   └── locallens-cli/      # CLI 命令行入口
├── rules/
│   ├── secrets/            # 密钥检测规则（AWS · GitHub · Stripe · 通用）
│   ├── sast/               # SAST 规则（命令注入 · SQL注入 · XSS · 反序列化 · 加密误用 · AI 代码）
│   └── iac/                 # IaC 规则（Terraform · CloudFormation · Kubernetes · Dockerfile · Helm）
├── policies/               # 安全策略文件
├── prompts/                # LLM 提示词模板
└── tests/
    └── fixtures/           # 测试用例（含已知漏洞的示例代码）

技术细节

误报降低策略

LocalLens 采用多层过滤降低误报：

  1. Shannon 熵值过滤 — 高熵值字符串更可能是真实密钥，低熵值（如变量名）被过滤
  2. 结构验证器 — AWS Key 校验和验证、JWT 结构验证、私钥格式验证
  3. 白名单机制 — 路径 glob 排除（**/test/**）+ 正则排除（AWS 文档示例 Key）
  4. 污点提示 — 启发式判断危险函数参数是否来自用户输入，字符串字面量降级置信度
  5. 跨函数污点追踪 — 追踪用户输入到危险函数的完整数据流，检测跨函数注入漏洞
  6. AI 误报过滤 — 本地 LLM 审查每个发现，返回真阳性/假阳性/需审查判定
  7. Triage 预过滤 — 高置信度发现自动标记为真阳性，跳过 LLM 调用，节省时间

支持的编程语言

语言 密钥检测 SAST (tree-sitter) SAST (正则回退)
Python ✅ ✅ ✅
JavaScript ✅ ✅ ✅
TypeScript ✅ ✅ ✅
Go ✅ ✅ ✅
Rust ✅ ✅ ✅
Java ✅ ✅ ✅
Ruby ✅ ✅ ✅
其他 ✅ ❌ ✅

开发路线

  • Phase 1 — 密钥检测：正则 + Shannon 熵 + 结构验证器 + YAML 规则
  • Phase 2 — SAST 漏洞检测：tree-sitter AST 分析 + 正则回退 + 污点提示
  • Phase 3 — AI 误报过滤：Ollama 本地 LLM 智能判断真阳性/假阳性
  • Phase 4 — Git Hook + CI 集成：pre-commit 钩子、SARIF 输出、增量扫描
  • Phase 5 — MCP Server：Claude Code / Cursor 实时安全扫描集成
  • Phase 6 — 性能与基础设施：并行扫描、项目配置、基线扫描、批量 triage、CWE 映射
  • Phase 7 — 扩展检测：IaC 规则、依赖扫描、AI 代码安全规则、编码密钥、Git 历史
  • Phase 8 — 多模型 AI + 自动修复：多模型 LLM、AI 自动修复、Triage 预过滤
  • Phase 9 — IDE 集成与生态：GitHub Action、规则管理命令、历史趋势追踪、安全评分
  • Phase 10 — 深度分析：跨函数污点追踪、策略即代码、安全评分

详细路线图见 ROADMAP.md

许可证

MIT

About

Local-first AI code security audit tool. Detect secrets and vulnerabilities in your code without ever leaving your machine.LocalLens | 本地优先的 AI 代码安全审计工具 — 检测代码中的密钥泄露与安全漏洞，代码不离开本机

Topics

rust cli security privacy ai static-analysis owasp code-audit local-first secret-scanning llm ollama ai-triage

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages