Calsoft-Pvt-Ltd/calvigil
GitHub: Calsoft-Pvt-Ltd/calvigil
一款集成依赖扫描、Semgrep SAST 及 AI 代码审计的多语言开源安全扫描工具，支持容器镜像分析与本地 LLM 离线运行。
Stars: 0 | Forks: 0
# calvigil
一款开源、AI 驱动的漏洞扫描器 CLI，支持 **Go**、**Java**、**Python** 和 **Node.js** 项目。
## 功能特性
- **依赖扫描** — 根据多个 CVE 数据库检查您的 lock 文件：
- [OSV.dev](https://osv.dev)（主要来源，批量 API，无速率限制）
- [NVD](https://nvd.nist.gov/)（NIST 国家漏洞数据库）
- [GitHub Advisory Database](https://github.com/advisories)
- **AI 驱动的代码分析** — 使用 OpenAI GPT-4 或本地 Ollama 模型检测 OWASP Top 10 漏洞：
- SQL 注入、命令注入、XSS
- 硬编码 secrets 和 API keys
- 不安全的加密算法、TLS 配置错误
- 路径遍历、不安全的反序列化
- CORS 配置错误等
- **提供商选择**：`--provider openai`、`--provider ollama` 或 `--provider auto`（默认）
- **本地 LLM 支持 — Ollama 集成**：
- 使用 `llama3`、`codellama`、`mistral` 等模型完全离线运行 AI 分析
- 兼容 OpenAI 的 API，原生 Ollama 回退
- 自动检测：如果 Ollama 可达，则优先于 OpenAI
- 通过 CLI 标志（`--ollama-url`、`--ollama-model`）或配置/环境变量进行配置
- **容器镜像扫描**：
- 扫描 Docker/OCI 镜像中的已知漏洞
- 由 [syft](https://github.com/anchore/syft) 提供支持，用于 SBOM 提取
- 支持 Docker 镜像、归档文件和目录
- 针对 OSV、NVD 和 GitHub Advisory 进行全量漏洞匹配
- **SAST 引擎 — Semgrep CE 集成** 及自定义规则包：
- 30 条内置安全规则，涵盖 OWASP Top 10 + 特定语言模式
- 针对 Go、Python、Java 和 JavaScript/TypeScript 的自定义规则包
- 使用 `--semgrep-rules` 引入您自己的规则
- **标准合规性**：
- **PURL** (Package URL) — 标准包标识符 (`pkg:npm/@babel/core@7.0.0`)
- **CycloneDX v1.5** — 包含组件、漏洞和 PURL 的 SBOM/VDR 格式
- **OpenVEX v0.2.0** — 包含状态和理由的漏洞可利用性交换格式
- **多生态系统支持**（按生态系统图标分组输出）：
- **Go** 🐹：`go.mod`
- **Java** ☕：`pom.xml`、`build.gradle`、`build.gradle.kts`
- **Python** 🐍：`requirements.txt`、`Pipfile.lock`、`poetry.lock`
- **Node.js** 📗：`package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`
- **多种输出格式**：终端表格、JSON、SARIF v2.1.0、CycloneDX v1.5、OpenVEX v0.2.0、HTML、PDF
## 安装
### 预构建二进制文件
从 [GitHub Releases](https://github.com/Calsoft-Pvt-Ltd/calvigil/releases) 下载最新版本。
**macOS：**
```
# Apple Silicon (M1/M2/M3)
curl -Lo calvigil.tar.gz https://github.com/Calsoft-Pvt-Ltd/calvigil/releases/latest/download/calvigil-darwin-arm64.tar.gz
tar xzf calvigil.tar.gz && sudo mv calvigil /usr/local/bin/
# Intel
curl -Lo calvigil.tar.gz https://github.com/Calsoft-Pvt-Ltd/calvigil/releases/latest/download/calvigil-darwin-amd64.tar.gz
tar xzf calvigil.tar.gz && sudo mv calvigil /usr/local/bin/
```
**Linux：**
```
curl -Lo calvigil.tar.gz https://github.com/Calsoft-Pvt-Ltd/calvigil/releases/latest/download/calvigil-linux-amd64.tar.gz
tar xzf calvigil.tar.gz && sudo mv calvigil /usr/local/bin/
```
**Debian / Ubuntu (.deb)：**
```
curl -Lo calvigil.deb https://github.com/Calsoft-Pvt-Ltd/calvigil/releases/latest/download/calvigil__amd64.deb
sudo dpkg -i calvigil.deb
```
**RHEL / CentOS / Fedora (.rpm)：**
```
curl -Lo calvigil.rpm https://github.com/Calsoft-Pvt-Ltd/calvigil/releases/latest/download/calvigil--1.x86_64.rpm
sudo rpm -i calvigil.rpm
```
**Windows：**
从 [Releases](https://github.com/Calsoft-Pvt-Ltd/calvigil/releases) 下载 `calvigil-windows-amd64.zip`，解压并添加到您的 PATH。
### 从源码构建
```
git clone https://github.com/Calsoft-Pvt-Ltd/calvigil.git
cd calvigil
make build
```
二进制文件将位于 `./bin/calvigil`。
### Go Install
```
go install github.com/Calsoft-Pvt-Ltd/calvigil@latest
```
## 快速开始
```
# 扫描当前目录（仅依赖扫描 — 无需 API key）
calvigil scan --skip-ai
# 扫描特定项目
calvigil scan /path/to/project
# 使用 AI 分析进行完整扫描（需要 OpenAI API key）
calvigil config set openai-key sk-...
calvigil scan
# 使用本地 Ollama 模型（无需 API key）
calvigil scan --provider ollama --ollama-model llama3
# 自动检测：如果 Ollama 可达则使用，否则使用 OpenAI
calvigil scan --provider auto
# 扫描容器镜像漏洞（需要 syft）
calvigil scan-image nginx:latest
calvigil scan-image python:3.12-slim --format json
# 输出为 JSON
calvigil scan --format json
# 输出为 SARIF（用于 GitHub Code Scanning、VS Code 等）
calvigil scan --format sarif --output results.sarif
# 输出为 CycloneDX SBOM
calvigil scan --format cyclonedx --output sbom.json
# 输出为 OpenVEX
calvigil scan --format openvex --output vex.json
# 面向管理层的 HTML 报告
calvigil scan --format html --output report.html
# PDF 报告（需要 Chrome 或 Chromium）
calvigil scan --format pdf --output report.pdf
# 使用自定义 Semgrep 规则运行
calvigil scan --semgrep-rules ./my-rules/
# 跳过 Semgrep SAST 分析
calvigil scan --skip-semgrep
# 仅显示高危和严重漏洞
calvigil scan --severity high
# 详细输出
calvigil scan -v
```
## 配置
配置存储在 `~/.calvigil.json` 中。环境变量优先级更高。
### API Keys
```
# OpenAI（使用 OpenAI provider 进行 AI 代码分析时需要）
calvigil config set openai-key sk-...
# 或：export OPENAI_API_KEY=sk-...
# OpenAI 模型（默认：gpt-4）
calvigil config set openai-model gpt-4-turbo
# Ollama URL（默认：http://localhost:11434）
calvigil config set ollama-url http://localhost:11434
# 或：export OLLAMA_URL=http://localhost:11434
# Ollama 模型（例如 llama3, codellama, mistral）
calvigil config set ollama-model llama3
# 或：export OLLAMA_MODEL=llama3
# NVD API key（可选，可提高速率限制）
calvigil config set nvd-key xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# 或：export NVD_API_KEY=...
# GitHub token（可选，用于 GitHub Advisory Database）
calvigil config set github-token ghp_...
# 或：export GITHUB_TOKEN=...
```
### 查看配置
```
calvigil config get openai-model
```
## CLI 参考
```
calvigil [command]
Available Commands:
scan Scan a project for security vulnerabilities
scan-image Scan a container image for vulnerabilities
config Manage scanner configuration
version Print the version
help Help about any command
Scan Flags:
-f, --format string Output format: table, json, sarif, cyclonedx, openvex, html, pdf (default "table")
-o, --output string Write output to file (default: stdout)
-s, --severity string Minimum severity: critical, high, medium, low
--skip-ai Skip AI-powered code analysis
--skip-deps Skip dependency vulnerability scanning
--skip-semgrep Skip Semgrep SAST analysis
--semgrep-rules string Path to custom Semgrep rule directory
--provider string AI provider: openai, ollama, or auto (default "auto")
--ollama-url string Ollama server URL (default: http://localhost:11434)
--ollama-model string Ollama model name (e.g. llama3, codellama, mistral)
-v, --verbose Enable verbose output
Scan-Image Flags:
-f, --format string Output format: table, json, sarif, cyclonedx, openvex, html, pdf (default "table")
-o, --output string Write output to file (default: stdout)
-s, --severity string Minimum severity: critical, high, medium, low
-v, --verbose Enable verbose output
```
## 工作原理
```
┌─────────────┐ ┌──────────────┐ ┌───────────────┐ ┌──────────────┐ ┌──────────────┐
│ Detect │────▶│ Parse & │────▶│ Match │────▶│ AI Enrich │────▶│ Report │
│ Ecosystems │ │ PURL Gen │ │ Against CVEs │ │ & Analyze │ │ Results │
└─────────────┘ └──────────────┘ └───────────────┘ └──────────────┘ └──────────────┘
│ │
┌──────────────┐ │ ┌──────────────┐
│ AI Code │─────────────┘ │ Semgrep CE │
│ Analysis │ │ SAST Engine │
└──────────────┘ └──────────────┘
```
1. **检测**：遍历项目目录以查找依赖清单文件（go.mod、pom.xml、package-lock.json 等）
2. **解析 & PURL**：提取包名称和版本，根据 [PURL 规范](https://github.com/package-url/purl-spec)生成 Package URLs (PURL)
3. **匹配**：查询 OSV、NVD 和 GitHub Advisory 数据库以查找已知 CVE
4. **分析**：对源代码运行正则表达式模式匹配 + AI 分析（OpenAI 或 Ollama）
5. **Semgrep SAST**：运行带有内置或自定义规则包的 Semgrep CE 进行静态分析
6. **丰富**：AI 丰富层添加影响、置信度、修复建议和抑制理由
7. **报告**：以请求的格式（表格、JSON、SARIF、CycloneDX、OpenVEX、HTML 或 PDF）输出结果
## 支持的漏洞模式（代码分析）
| ID | 模式 | 严重程度 |
|----|---------|----------|
| SEC-001 | SQL 注入（格式化字符串） | HIGH |
| SEC-002 | SQL 注入（字符串拼接） | HIGH |
| SEC-003 | 命令注入 | CRITICAL |
| SEC-004 | 路径遍历 | HIGH |
| SEC-005 | 硬编码 Secrets | HIGH |
| SEC-006 | AWS 访问密钥 | CRITICAL |
| SEC-007 | 弱加密（MD5/SHA1） | MEDIUM |
| SEC-008 | 跨站脚本攻击（XSS） | HIGH |
| SEC-009 | 不安全的 HTTP | LOW |
| SEC-010 | TLS 验证已禁用 | CRITICAL |
| SEC-011 | 不安全的反序列化 | HIGH |
| SEC-012 | 宽松的 CORS | MEDIUM |
## Semgrep CE 集成
扫描器集成了 [Semgrep CE](https://semgrep.dev/) 用于静态应用程序安全测试。安装 Semgrep 后，扫描器将自动使用它：
```
pip install semgrep
# 使用捆绑规则包扫描（OWASP Top 10 + 特定语言）
calvigil scan /path/to/project
# 使用您自己的自定义规则扫描
calvigil scan --semgrep-rules ./my-rules/ /path/to/project
# 完全跳过 Semgrep
calvigil scan --skip-semgrep /path/to/project
```
**内置规则包**（位于 `rules/semgrep/`）：
- `owasp-top10.yaml` — 18 条规则：SQL 注入、命令注入、路径遍历、硬编码 secrets、不安全的 TLS、弱加密、XSS、不安全的反序列化、SSRF
- `language-specific.yaml` — 12 条规则：Go（不安全指针、HTTP 无超时、循环中的 defer）、Python（Flask 调试模式、绑定 0.0.0.0）、JS（eval、CORS 通配符、JWT 无验证）、Java（XXE、ECB 模式）
## 标准与输出格式
| 格式 | 标志 | 规范 | 用例 |
|--------|------|------|----------|
| Table | `--format table` | — | 人类可读的终端输出（按生态系统分组） |
| JSON | `--format json` | — | 机器可读，CI/CD 流水线，脚本 |
| SARIF | `--format sarif` | v2.1.0 | GitHub Code Scanning，VS Code，IDE 集成 |
| CycloneDX | `--format cyclonedx` | v1.5 | 包含组件、PURL 和漏洞的 SBOM/VDR |
| OpenVEX | `--format openvex` | v0.2.0 | 包含状态/理由的漏洞可利用性交换 |
| HTML | `--format html` | — | 面向管理层的报告，包含严重程度图表、徽章和 AI 丰富信息 |
| PDF | `--format pdf` | — | 适合 MIS/管理层阅读的打印就绪 PDF 报告（需要 Chrome 或 Chromium） |
### PURL (Package URL)
所有包均使用 [PURL](https://github.com/package-url/purl-spec) 标准标识符进行识别：
| 生态系统 | 示例 PURL |
|-----------|-------------|
| Go | `pkg:golang/github.com/hashicorp/vault@v1.15.2` |
| npm | `pkg:npm/@babel/helpers@7.15.4` |
| PyPI | `pkg:pypi/requests@2.28.0` |
| Maven | `pkg:maven/org.apache.logging.log4j/log4j-core@2.17.0` |
## Ollama（本地 LLM）支持
使用 [Ollama](https://ollama.ai/) 和 `llama3`、`codellama` 或 `mistral` 等模型，完全离线运行 AI 驱动的分析。
```
# 安装 Ollama 并拉取模型
ollama pull llama3
# 使用 Ollama 扫描
calvigil scan --provider ollama --ollama-model llama3
# 使用远程 Ollama 服务器
calvigil scan --provider ollama --ollama-url http://gpu-server:11434 --ollama-model codellama
# 自动模式（默认）：如果 Ollama 可达则使用，否则使用 OpenAI
calvigil scan
```
**提供商选择（`--provider`）**：
- `auto`（默认）：优先尝试 Ollama（如果已配置且可达），回退到 OpenAI
- `ollama`：仅使用 Ollama（如果不可达则失败）
- `openai`：仅使用 OpenAI（需要 API key）
## 容器镜像扫描
使用 [syft](https://github.com/anchore/syft) 扫描 Docker/OCI 容器镜像中的漏洞：
```
# 安装 syft
brew install syft # macOS
# 或：curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh
# 扫描 Docker 镜像
calvigil scan-image nginx:latest
# 使用特定输出格式扫描
calvigil scan-image python:3.12-slim --format json
calvigil scan-image node:20 --format sarif --output results.sarif
# 扫描本地归档或目录
calvigil scan-image docker-archive:image.tar
calvigil scan-image dir:/path/to/rootfs
# 按严重程度筛选
calvigil scan-image alpine:3.18 --severity high
```
镜像扫描器：
1. 使用 **syft** 从容器镜像中提取 SBOM
2. 将包映射到支持的生态系统（npm、PyPI、Go、Maven、Ruby、Rust、Debian、Alpine、RPM）
3. 针对 **OSV**、**NVD** 和 **GitHub Advisory** 数据库匹配所有包
4. 以任何受支持的格式（表格、JSON、SARIF、CycloneDX、OpenVEX）报告结果
## 许可证
Apache License 2.0 — 详见 [LICENSE](LICENSE)
标签：AI应用开发, AI风险缓解, CISA项目, CLI 工具, CVE, CycloneDX, DevSecOps, Docker, EVTX分析, GNU通用公共许可证, Go, GPT-4, LLM, LLM评估, LLM防护, Node.js, Ollama, OpenAI, OWASP Top 10, Python, Ruby工具, SAST, SBOM, Semgrep, SQL 注入, Unmanaged PE, Web截图, WordPress安全扫描, XSS, 上游代理, 人工智能, 人工智能安全, 依赖项检查, 内存规避, 加密, 合规性, 安全防御评估, 容器安全, 数字签名, 无后门, 日志审计, 漏洞情报, 漏洞扫描器, 用户模式Hook绕过, 盲注攻击, 硬件无关, 硬编码密钥, 网络安全, 隐私保护