VulnScan-CLI

轻量级终端代码安全漏洞智能检测引擎
Lightweight Terminal Code Security Vulnerability Detection Engine

语言 / Language: 简体中文 | 繁體中文 | English

🎉 项目介绍

VulnScan-CLI 是一款轻量级的终端代码安全漏洞智能检测引擎。它专注于为开发者提供快速、精准的静态代码安全扫描能力，帮助你在开发流程中尽早发现潜在的安全风险。

为什么选择 VulnScan-CLI？

零核心依赖 — 仅依赖 Python 标准库，安装即用，不引入任何第三方包
广泛的语言支持 — 覆盖 23 种主流编程语言，一个工具搞定多语言项目
专业的漏洞检测 — 内置 10 大漏洞检测器、70+ 条检测规则，覆盖 OWASP Top 10
灵活的报告输出 — 支持 JSON、HTML、Markdown、SARIF 2.1.0 等多种格式
交互式仪表盘 — 基于 rich 的 TUI 仪表盘，扫描结果一目了然

✨ 核心特性

🔍 10 大漏洞检测器

检测器	说明	OWASP 分类	CWE 编号
SQL 注入检测	识别动态 SQL 拼接、ORM 不安全用法等	A03:2021 - Injection	CWE-89
XSS 跨站脚本检测	发现反射型/存储型 XSS 漏洞	A03:2021 - Injection	CWE-79
命令注入检测	检测操作系统命令注入风险	A03:2021 - Injection	CWE-78
路径遍历检测	识别不安全的文件路径操作	A01:2021 - Broken Access Control	CWE-22
硬编码密钥检测	扫描代码中的密码、API Key 等敏感信息	A02:2021 - Cryptographic Failures	CWE-798
不安全加密检测	发现弱加密算法和哈希函数的使用	A02:2021 - Cryptographic Failures	CWE-327
缓冲区溢出检测	识别 C/C++ 中的内存安全隐患	A03:2021 - Injection	CWE-120
不安全反序列化检测	检测危险的序列化/反序列化操作	A08:2021 - Software and Data Integrity Failures	CWE-502
SSRF 检测	发现服务端请求伪造漏洞	A10:2021 - SSRF	CWE-918
依赖漏洞检查	分析项目依赖中的已知漏洞	A06:2021 - Vulnerable and Outdated Components	CWE-733

🌍 支持 23 种编程语言

Python、JavaScript、TypeScript、Java、Kotlin、Scala、Groovy、Go、Rust、PHP、Ruby、C、C++、C#、Swift、Shell（Bash/Zsh/Fish）、SQL、HTML、CSS、Lua、Perl、R

📊 五级严重性评分

等级	分值范围	说明
🔴 Critical	9.0 - 10.0	严重漏洞，需立即修复
🟠 High	7.0 - 8.9	高危漏洞，应尽快修复
🟡 Medium	4.0 - 6.9	中危漏洞，建议修复
🔵 Low	1.0 - 3.9	低危漏洞，酌情处理
⚪ Info	0.0 - 0.9	信息提示，供参考

📋 OWASP Top 10 覆盖与 CWE 映射

所有检测规则均映射到 OWASP Top 10 (2021) 分类和 MITRE CWE 标准，方便与团队安全规范对齐。

📄 多格式报告输出

JSON — 结构化数据，便于程序处理和 CI/CD 集成
HTML — 可视化报告，适合团队评审和存档
Markdown — 轻量文本报告，适合 Git 提交和 Issue 跟踪
SARIF 2.1.0 — 标准化格式，无缝对接 GitHub Code Scanning

🎨 TUI 交互式仪表盘

安装 rich 库后，可通过 --tui 参数启用交互式终端仪表盘，实时展示扫描进度和结果统计。

📦 零核心依赖

核心功能仅使用 Python 标准库实现，无需安装任何第三方依赖即可运行。TUI 仪表盘为可选功能，按需安装 rich 即可。

🚀 批量扫描

支持对单个文件或整个目录进行批量扫描，自动递归遍历子目录，智能跳过无关文件。

🔧 可配置的规则与排除模式

通过配置文件或命令行参数自定义扫描行为，包括启用/禁用检测器、设置排除目录和文件模式等。

📡 GitHub Code Scanning 集成

通过 SARIF 格式输出，可直接在 GitHub Actions 中集成，将扫描结果展示在 GitHub Code Scanning 面板中。

🚀 快速开始

环境要求

Python 3.9 或更高版本

安装方式

方式一：通过 pip 安装（推荐）

pip install vulnscan-cli

方式二：从源码安装

git clone https://github.com/gitstq/VulnScan-CLI.git
cd VulnScan-CLI
pip install .

方式三：安装开发版本（含 TUI 支持）

pip install vulnscan-cli[tui]

快速上手

# 扫描当前目录
vulnscan scan .

# 扫描指定项目
vulnscan scan ./my-project

# 生成 HTML 报告
vulnscan scan ./my-project --format html --output report.html

# 查看支持的语言
vulnscan list-languages

# 查看所有检测规则
vulnscan list-rules

# 启用 TUI 交互式仪表盘
vulnscan scan ./my-project --tui

📖 详细使用指南

命令行参数一览

参数	缩写	说明	默认值
`--format`	`-f`	输出格式：`console`、`json`、`html`、`markdown`、`sarif`	`console`
`--output`	`-o`	输出文件路径（不指定则输出到 stdout）	-
`--severity`	-	最低报告严重性等级：`Critical`、`High`、`Medium`、`Low`、`Info`	`Info`
`--exclude`	-	排除文件或目录模式（逗号分隔）	-
`--include`	-	只扫描匹配的文件模式（逗号分隔）	-
`--no-dep-check`	-	跳过依赖漏洞检查	`false`
`--config`	-	指定配置文件路径	-
`--rules`	-	指定自定义规则文件路径（JSON 格式）	-
`--cwe`	-	按 CWE 编号过滤漏洞（逗号分隔）	-
`--confidence`	-	最低置信度阈值（0.0-1.0）	`0.0`
`--tui`	-	启用 TUI 交互式仪表盘	`false`
`--stdin`	-	从标准输入读取代码	`false`
`-l` / `--language`	-	指定输入代码的语言（配合 `--stdin` 使用）	-
`--no-color`	-	禁用彩色输出	`false`
`--quiet`	-	静默模式，只输出漏洞结果	`false`
`--verbose`	-	详细输出模式	`false`
`--workers`	-	并行扫描工作线程数	`1`
`--max-file-size`	-	最大扫描文件大小（字节）	`1048576`
`--context-lines`	-	代码上下文行数	`2`

管道输入（stdin）用法

# 从 stdin 扫描 Python 代码
cat file.py | vulnscan scan --stdin -l python -

# 配合其他命令使用
grep -r "eval(" ./src | vulnscan scan --stdin -l javascript -

严重性过滤示例

# 只报告严重和高危漏洞
vulnscan scan ./src --severity Critical,High

# 只报告中危及以上漏洞
vulnscan scan ./src --severity Medium

# 按 CWE 编号过滤
vulnscan scan ./src --cwe CWE-89,CWE-79

配置文件

在项目根目录创建 .vulnscan.json 文件：

{
  "scan": {
    "max_file_size": 1048576,
    "context_lines": 3,
    "follow_symlinks": false
  },
  "exclude": {
    "directories": ["node_modules", ".git", "vendor"],
    "extensions": [".min.js", ".min.css"],
    "patterns": ["*.test.js", "*.spec.ts"]
  },
  "severity": {
    "minimum_severity": "Low",
    "confidence_threshold": 0.3
  },
  "detectors": {
    "sql_injection": true,
    "xss": true,
    "command_injection": true,
    "path_traversal": true,
    "hardcoded_secrets": true,
    "insecure_crypto": true,
    "buffer_overflow": true,
    "deserialization": true,
    "ssrf": true,
    "dependency_check": false
  }
}

配置文件搜索顺序：

命令行 --config 指定的路径
当前目录下的 .vulnscan.json
用户主目录下的 ~/.vulnscan/config.json
内置默认配置

GitHub Actions 集成（SARIF）

在 .github/workflows/vulnscan.yml 中添加：

name: VulnScan Security Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  vulnscan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install VulnScan-CLI
        run: pip install vulnscan-cli

      - name: Run VulnScan
        run: vulnscan scan ./src --format sarif --output results.sarif

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

💡 设计思路与迭代规划

设计理念

为什么选择零依赖？

在安全工具领域，信任是核心。零核心依赖意味着：

可审计性 — 所有代码逻辑完全透明，不存在隐藏的供应链风险
便携性 — 在任何 Python 环境中即可运行，无需担心依赖冲突
轻量化 — 安装包体积极小，启动速度快，适合 CI/CD 流水线
可靠性 — 不受第三方库版本更新或停止维护的影响

基于模式匹配的检测方法

VulnScan-CLI 采用基于正则表达式和 AST 模式匹配的检测方法，这种方法的优点是：

误报率可控，规则可精确调优
检测速度快，适合大规模代码库扫描
规则易于理解和自定义
不需要复杂的模型训练和推理

未来规划

AI 驱动的智能检测 — 结合大语言模型实现上下文感知的漏洞检测，降低误报率
CI/CD 集成插件 — 提供 Jenkins、GitLab CI、CircleCI 等主流 CI/CD 平台的官方插件
IDE 插件 — 开发 VS Code、JetBrains 系列的实时检测插件
自定义规则市场 — 建立社区驱动的规则共享平台，支持自定义规则包的发布和订阅
增量扫描 — 基于 Git diff 实现增量扫描，只检查变更的代码
漏洞修复建议 — 为检测到的漏洞提供自动修复建议和代码补丁

📦 打包与部署指南

pip 安装

# 从 PyPI 安装
pip install vulnscan-cli

# 安装含 TUI 支持的版本
pip install vulnscan-cli[tui]

从源码安装

git clone https://github.com/gitstq/VulnScan-CLI.git
cd VulnScan-CLI
pip install -e .          # 开发模式安装
pip install .             # 正式安装
pip install .[tui]        # 含 TUI 支持的安装

Docker 使用

# 使用 Docker 运行扫描
docker run --rm -v $(pwd):/app/src gitstq/vulnscan-cli scan /app/src

# 生成 HTML 报告并挂载输出目录
docker run --rm -v $(pwd):/app/src -v $(pwd)/reports:/app/reports \
  gitstq/vulnscan-cli scan /app/src --format html --output /app/reports/report.html

CI/CD 集成

GitHub Actions

- name: Security Scan
  run: |
    pip install vulnscan-cli
    vulnscan scan ./src --format sarif --output results.sarif

GitLab CI

security_scan:
  stage: test
  script:
    - pip install vulnscan-cli
    - vulnscan scan ./src --format json --output vulnscan-report.json
  artifacts:
    paths:
      - vulnscan-report.json

Jenkins Pipeline

stage('Security Scan') {
    steps {
        sh 'pip install vulnscan-cli'
        sh 'vulnscan scan ./src --format html --output vulnscan-report.html'
    }
}

🤝 贡献指南

我们欢迎并感谢所有形式的贡献！无论是提交 Bug 报告、改进文档，还是贡献代码。

提交 Pull Request

Fork 本仓库
创建特性分支：git checkout -b feature/your-feature
提交改动：git commit -m "feat: add your feature"
推送分支：git push origin feature/your-feature
发起 Pull Request

提交 Issue

Bug 报告 — 请包含复现步骤、预期行为和实际行为
功能建议 — 请详细描述使用场景和期望的功能
规则贡献 — 欢迎提交新的检测规则，请附带测试用例

代码风格

遵循 PEP 8 编码规范
使用类型注解（Type Hints）
编写 docstring 文档
确保所有提交通过测试

📄 开源协议

本项目基于 MIT License 开源。

MIT License

Copyright (c) 2024 VulnScan-CLI Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🎉 專案介紹

VulnScan-CLI 是一款輕量級的終端程式碼安全漏洞智慧偵測引擎。它致力於為開發者提供快速、精準的靜態程式碼安全掃描能力，協助你在開發流程中及早發現潛在的安全風險。

為什麼選擇 VulnScan-CLI？

零核心依賴 — 僅依賴 Python 標準函式庫，安裝即用，不引入任何第三方套件
廣泛的語言支援 — 涵蓋 23 種主流程式語言，一個工具搞定多語言專案
專業的漏洞偵測 — 內建 10 大漏洞偵測器、70+ 條偵測規則，涵蓋 OWASP Top 10
靈活的報告輸出 — 支援 JSON、HTML、Markdown、SARIF 2.1.0 等多種格式
互動式儀表板 — 基於 rich 的 TUI 儀表板，掃描結果一目瞭然

✨ 核心特性

🔍 10 大漏洞偵測器

偵測器	說明	OWASP 分類	CWE 編號
SQL 注入偵測	識別動態 SQL 拼接、ORM 不安全用法等	A03:2021 - Injection	CWE-89
XSS 跨站腳本偵測	發現反射型/儲存型 XSS 漏洞	A03:2021 - Injection	CWE-79
命令注入偵測	偵測作業系統命令注入風險	A03:2021 - Injection	CWE-78
路徑遍歷偵測	識別不安全的檔案路徑操作	A01:2021 - Broken Access Control	CWE-22
硬編碼密鑰偵測	掃描程式碼中的密碼、API Key 等敏感資訊	A02:2021 - Cryptographic Failures	CWE-798
不安全加密偵測	發現弱加密演算法和雜湊函式的使用	A02:2021 - Cryptographic Failures	CWE-327
緩衝區溢出偵測	識別 C/C++ 中的記憶體安全隱患	A03:2021 - Injection	CWE-120
不安全反序列化偵測	偵測危險的序列化/反序列化操作	A08:2021 - Software and Data Integrity Failures	CWE-502
SSRF 偵測	發現伺服端請求偽造漏洞	A10:2021 - SSRF	CWE-918
依賴漏洞檢查	分析專案依賴中的已知漏洞	A06:2021 - Vulnerable and Outdated Components	CWE-733

🌍 支援 23 種程式語言

Python、JavaScript、TypeScript、Java、Kotlin、Scala、Groovy、Go、Rust、PHP、Ruby、C、C++、C#、Swift、Shell（Bash/Zsh/Fish）、SQL、HTML、CSS、Lua、Perl、R

📊 五級嚴重性評分

等級	分值範圍	說明
🔴 Critical	9.0 - 10.0	嚴重漏洞，需立即修復
🟠 High	7.0 - 8.9	高危漏洞，應盡快修復
🟡 Medium	4.0 - 6.9	中危漏洞，建議修復
🔵 Low	1.0 - 3.9	低危漏洞，酌情處理
⚪ Info	0.0 - 0.9	資訊提示，供參考

📋 OWASP Top 10 涵蓋與 CWE 映射

所有偵測規則均映射到 OWASP Top 10 (2021) 分類和 MITRE CWE 標準，方便與團隊安全規範對齊。

📄 多格式報告輸出

JSON — 結構化資料，便於程式處理和 CI/CD 整合
HTML — 視覺化報告，適合團隊審查和存檔
Markdown — 輕量文字報告，適合 Git 提交和 Issue 追蹤
SARIF 2.1.0 — 標準化格式，無縫對接 GitHub Code Scanning

🎨 TUI 互動式儀表板

安裝 rich 函式庫後，可透過 --tui 參數啟用互動式終端儀表板，即時展示掃描進度和結果統計。

📦 零核心依賴

核心功能僅使用 Python 標準函式庫實現，無需安裝任何第三方依賴即可運行。TUI 儀表板為可選功能，按需安裝 rich 即可。

🚀 批次掃描

支援對單一檔案或整個目錄進行批次掃描，自動遞迴遍歷子目錄，智慧跳過無關檔案。

🔧 可配置的規則與排除模式

透過設定檔或命令列參數自訂掃描行為，包括啟用/停用偵測器、設定排除目錄和檔案模式等。

📡 GitHub Code Scanning 整合

透過 SARIF 格式輸出，可直接在 GitHub Actions 中整合，將掃描結果展示在 GitHub Code Scanning 面板中。

🚀 快速開始

環境需求

Python 3.9 或更高版本

安裝方式

方式一：透過 pip 安裝（推薦）

pip install vulnscan-cli

方式二：從原始碼安裝

git clone https://github.com/gitstq/VulnScan-CLI.git
cd VulnScan-CLI
pip install .

方式三：安裝開發版本（含 TUI 支援）

pip install vulnscan-cli[tui]

快速上手

# 掃描當前目錄
vulnscan scan .

# 掃描指定專案
vulnscan scan ./my-project

# 生成 HTML 報告
vulnscan scan ./my-project --format html --output report.html

# 查看支援的語言
vulnscan list-languages

# 查看所有偵測規則
vulnscan list-rules

# 啟用 TUI 互動式儀表板
vulnscan scan ./my-project --tui

📖 詳細使用指南

命令列參數一覽

參數	縮寫	說明	預設值
`--format`	`-f`	輸出格式：`console`、`json`、`html`、`markdown`、`sarif`	`console`
`--output`	`-o`	輸出檔案路徑（不指定則輸出至 stdout）	-
`--severity`	-	最低報告嚴重性等級：`Critical`、`High`、`Medium`、`Low`、`Info`	`Info`
`--exclude`	-	排除檔案或目錄模式（逗號分隔）	-
`--include`	-	只掃描匹配的檔案模式（逗號分隔）	-
`--no-dep-check`	-	跳過依賴漏洞檢查	`false`
`--config`	-	指定設定檔路徑	-
`--rules`	-	指定自訂規則檔案路徑（JSON 格式）	-
`--cwe`	-	按 CWE 編號過濾漏洞（逗號分隔）	-
`--confidence`	-	最低置信度閾值（0.0-1.0）	`0.0`
`--tui`	-	啟用 TUI 互動式儀表板	`false`
`--stdin`	-	從標準輸入讀取程式碼	`false`
`-l` / `--language`	-	指定輸入程式碼的語言（配合 `--stdin` 使用）	-
`--no-color`	-	停用彩色輸出	`false`
`--quiet`	-	靜默模式，只輸出漏洞結果	`false`
`--verbose`	-	詳細輸出模式	`false`
`--workers`	-	平行掃描工作執行緒數	`1`
`--max-file-size`	-	最大掃描檔案大小（位元組）	`1048576`
`--context-lines`	-	程式碼上下文行數	`2`

管道輸入（stdin）用法

# 從 stdin 掃描 Python 程式碼
cat file.py | vulnscan scan --stdin -l python -

# 配合其他命令使用
grep -r "eval(" ./src | vulnscan scan --stdin -l javascript -

嚴重性過濾範例

# 只報告嚴重和高危漏洞
vulnscan scan ./src --severity Critical,High

# 只報告中危及以上漏洞
vulnscan scan ./src --severity Medium

# 按 CWE 編號過濾
vulnscan scan ./src --cwe CWE-89,CWE-79

設定檔

在專案根目錄建立 .vulnscan.json 檔案：

{
  "scan": {
    "max_file_size": 1048576,
    "context_lines": 3,
    "follow_symlinks": false
  },
  "exclude": {
    "directories": ["node_modules", ".git", "vendor"],
    "extensions": [".min.js", ".min.css"],
    "patterns": ["*.test.js", "*.spec.ts"]
  },
  "severity": {
    "minimum_severity": "Low",
    "confidence_threshold": 0.3
  },
  "detectors": {
    "sql_injection": true,
    "xss": true,
    "command_injection": true,
    "path_traversal": true,
    "hardcoded_secrets": true,
    "insecure_crypto": true,
    "buffer_overflow": true,
    "deserialization": true,
    "ssrf": true,
    "dependency_check": false
  }
}

設定檔搜尋順序：

命令列 --config 指定的路徑
當前目錄下的 .vulnscan.json
使用者家目錄下的 ~/.vulnscan/config.json
內建預設設定

GitHub Actions 整合（SARIF）

在 .github/workflows/vulnscan.yml 中新增：

name: VulnScan Security Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  vulnscan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install VulnScan-CLI
        run: pip install vulnscan-cli

      - name: Run VulnScan
        run: vulnscan scan ./src --format sarif --output results.sarif

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

💡 設計理念與迭代規劃

設計理念

為什麼選擇零依賴？

在安全工具領域，信任是核心。零核心依賴意味著：

可稽核性 — 所有程式碼邏輯完全透明，不存在隱藏的供應鏈風險
可攜性 — 在任何 Python 環境中即可運行，無需擔心依賴衝突
輕量化 — 安裝包體積極小，啟動速度快，適合 CI/CD 流水線
可靠性 — 不受第三方函式庫版本更新或停止維護的影響

基於模式匹配的偵測方法

VulnScan-CLI 採用基於正規表示式和 AST 模式匹配的偵測方法，這種方法的優點是：

誤報率可控，規則可精確調校
偵測速度快，適合大規模程式碼庫掃描
規則易於理解和自訂
不需要複雜的模型訓練和推論

未來規劃

AI 驅動的智慧偵測 — 結合大型語言模型實現上下文感知的漏洞偵測，降低誤報率
CI/CD 整合外掛 — 提供 Jenkins、GitLab CI、CircleCI 等主流 CI/CD 平台的官方外掛
IDE 外掛 — 開發 VS Code、JetBrains 系列的即時偵測外掛
自訂規則市集 — 建立社群驅動的規則共享平台，支援自訂規則包的發布和訂閱
增量掃描 — 基於 Git diff 實現增量掃描，只檢查變更的程式碼
漏洞修復建議 — 為偵測到的漏洞提供自動修復建議和程式碼補丁

📦 打包與部署指南

pip 安裝

# 從 PyPI 安裝
pip install vulnscan-cli

# 安裝含 TUI 支援的版本
pip install vulnscan-cli[tui]

從原始碼安裝

git clone https://github.com/gitstq/VulnScan-CLI.git
cd VulnScan-CLI
pip install -e .          # 開發模式安裝
pip install .             # 正式安裝
pip install .[tui]        # 含 TUI 支援的安裝

Docker 使用

# 使用 Docker 執行掃描
docker run --rm -v $(pwd):/app/src gitstq/vulnscan-cli scan /app/src

# 生成 HTML 報告並掛載輸出目錄
docker run --rm -v $(pwd):/app/src -v $(pwd)/reports:/app/reports \
  gitstq/vulnscan-cli scan /app/src --format html --output /app/reports/report.html

CI/CD 整合

GitHub Actions

- name: Security Scan
  run: |
    pip install vulnscan-cli
    vulnscan scan ./src --format sarif --output results.sarif

GitLab CI

security_scan:
  stage: test
  script:
    - pip install vulnscan-cli
    - vulnscan scan ./src --format json --output vulnscan-report.json
  artifacts:
    paths:
      - vulnscan-report.json

Jenkins Pipeline

stage('Security Scan') {
    steps {
        sh 'pip install vulnscan-cli'
        sh 'vulnscan scan ./src --format html --output vulnscan-report.html'
    }
}

🤝 貢獻指南

我們歡迎並感謝所有形式的貢獻！無論是提交 Bug 回報、改進文件，還是貢獻程式碼。

提交 Pull Request

Fork 本儲存庫
建立特性分支：git checkout -b feature/your-feature
提交變更：git commit -m "feat: add your feature"
推送分支：git push origin feature/your-feature
發起 Pull Request

提交 Issue

Bug 回報 — 請包含重現步驟、預期行為和實際行為
功能建議 — 請詳細描述使用場景和期望的功能
規則貢獻 — 歡迎提交新的偵測規則，請附帶測試案例

程式碼風格

遵循 PEP 8 編碼規範
使用型別註解（Type Hints）
撰寫 docstring 文件
確保所有提交通過測試

📄 開源協議

本專案基於 MIT License 開源。

MIT License

Copyright (c) 2024 VulnScan-CLI Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🎉 Project Introduction

VulnScan-CLI is a lightweight terminal code security vulnerability detection engine. It is designed to provide developers with fast and accurate static code security scanning, helping you catch potential security risks early in the development lifecycle.

Why VulnScan-CLI?

Zero core dependencies — Built entirely on the Python standard library. No third-party packages required.
Broad language support — Covers 23 mainstream programming languages. One tool for your polyglot projects.
Professional vulnerability detection — 10 built-in detectors with 70+ detection rules, covering OWASP Top 10.
Flexible report output — Supports JSON, HTML, Markdown, and SARIF 2.1.0 formats.
Interactive dashboard — TUI dashboard powered by rich for at-a-glance scan results.

✨ Core Features

🔍 10 Vulnerability Detectors

Detector	Description	OWASP Category	CWE ID
SQL Injection	Detects dynamic SQL concatenation, unsafe ORM usage, etc.	A03:2021 - Injection	CWE-89
XSS	Finds reflected and stored cross-site scripting vulnerabilities	A03:2021 - Injection	CWE-79
Command Injection	Detects OS command injection risks	A03:2021 - Injection	CWE-78
Path Traversal	Identifies unsafe file path operations	A01:2021 - Broken Access Control	CWE-22
Hardcoded Secrets	Scans for passwords, API keys, and other sensitive data	A02:2021 - Cryptographic Failures	CWE-798
Insecure Crypto	Finds usage of weak cryptographic algorithms and hash functions	A02:2021 - Cryptographic Failures	CWE-327
Buffer Overflow	Identifies memory safety issues in C/C++ code	A03:2021 - Injection	CWE-120
Insecure Deserialization	Detects dangerous serialization/deserialization operations	A08:2021 - Software and Data Integrity Failures	CWE-502
SSRF	Discovers server-side request forgery vulnerabilities	A10:2021 - SSRF	CWE-918
Dependency Check	Analyzes known vulnerabilities in project dependencies	A06:2021 - Vulnerable and Outdated Components	CWE-733

🌍 23 Programming Languages Supported

Python, JavaScript, TypeScript, Java, Kotlin, Scala, Groovy, Go, Rust, PHP, Ruby, C, C++, C#, Swift, Shell (Bash/Zsh/Fish), SQL, HTML, CSS, Lua, Perl, R

📊 5-Level Severity Scoring

Level	Score Range	Description
🔴 Critical	9.0 - 10.0	Critical vulnerability, fix immediately
🟠 High	7.0 - 8.9	High severity, fix as soon as possible
🟡 Medium	4.0 - 6.9	Medium severity, recommended to fix
🔵 Low	1.0 - 3.9	Low severity, fix at your discretion
⚪ Info	0.0 - 0.9	Informational, for reference only

📋 OWASP Top 10 Coverage with CWE Mapping

All detection rules are mapped to OWASP Top 10 (2021) categories and MITRE CWE standards, making it easy to align with your team's security policies.

📄 Multi-Format Reports

JSON — Structured data for programmatic processing and CI/CD integration
HTML — Visual reports for team review and archiving
Markdown — Lightweight text reports for Git commits and issue tracking
SARIF 2.1.0 — Standardized format for seamless GitHub Code Scanning integration

🎨 TUI Interactive Dashboard

With the rich library installed, enable the interactive terminal dashboard via the --tui flag for real-time scan progress and result statistics.

📦 Zero Core Dependencies

Core functionality is implemented using only the Python standard library. No third-party dependencies are needed to run. The TUI dashboard is an optional feature — just install rich when you need it.

🚀 Batch Scanning

Scan individual files or entire directories with automatic recursive traversal. Smart file filtering skips irrelevant files automatically.

🔧 Configurable Rules and Exclusion Patterns

Customize scan behavior through configuration files or CLI arguments, including enabling/disabling detectors, setting exclusion directories, and file patterns.

📡 GitHub Code Scanning Integration

Export results in SARIF format for direct integration with GitHub Actions. Scan results appear in the GitHub Code Scanning panel out of the box.

🚀 Quick Start

Requirements

Python 3.9 or later

Installation

Option 1: Install via pip (Recommended)

pip install vulnscan-cli

Option 2: Install from source

git clone https://github.com/gitstq/VulnScan-CLI.git
cd VulnScan-CLI
pip install .

Option 3: Install with TUI support

pip install vulnscan-cli[tui]

Quick Commands

# Scan the current directory
vulnscan scan .

# Scan a specific project
vulnscan scan ./my-project

# Generate an HTML report
vulnscan scan ./my-project --format html --output report.html

# List supported languages
vulnscan list-languages

# List all detection rules
vulnscan list-rules

# Launch the TUI interactive dashboard
vulnscan scan ./my-project --tui

📖 Detailed Usage Guide

CLI Options Reference

Option	Short	Description	Default
`--format`	`-f`	Output format: `console`, `json`, `html`, `markdown`, `sarif`	`console`
`--output`	`-o`	Output file path (prints to stdout if omitted)	-
`--severity`	-	Minimum severity level: `Critical`, `High`, `Medium`, `Low`, `Info`	`Info`
`--exclude`	-	Exclude files or directories matching patterns (comma-separated)	-
`--include`	-	Only scan files matching patterns (comma-separated)	-
`--no-dep-check`	-	Skip dependency vulnerability checking	`false`
`--config`	-	Path to configuration file	-
`--rules`	-	Path to custom rules file (JSON format)	-
`--cwe`	-	Filter vulnerabilities by CWE ID (comma-separated)	-
`--confidence`	-	Minimum confidence threshold (0.0-1.0)	`0.0`
`--tui`	-	Enable TUI interactive dashboard	`false`
`--stdin`	-	Read code from standard input	`false`
`-l` / `--language`	-	Specify language for stdin input (use with `--stdin`)	-
`--no-color`	-	Disable colored output	`false`
`--quiet`	-	Quiet mode, only output vulnerability results	`false`
`--verbose`	-	Verbose output mode	`false`
`--workers`	-	Number of parallel scan worker threads	`1`
`--max-file-size`	-	Maximum file size to scan (bytes)	`1048576`
`--context-lines`	-	Number of code context lines	`2`

Pipe stdin Usage

# Scan Python code from stdin
cat file.py | vulnscan scan --stdin -l python -

# Combine with other commands
grep -r "eval(" ./src | vulnscan scan --stdin -l javascript -

Severity Filtering Examples

# Report only critical and high severity vulnerabilities
vulnscan scan ./src --severity Critical,High

# Report medium severity and above
vulnscan scan ./src --severity Medium

# Filter by CWE ID
vulnscan scan ./src --cwe CWE-89,CWE-79

Configuration File

Create a .vulnscan.json file in your project root:

{
  "scan": {
    "max_file_size": 1048576,
    "context_lines": 3,
    "follow_symlinks": false
  },
  "exclude": {
    "directories": ["node_modules", ".git", "vendor"],
    "extensions": [".min.js", ".min.css"],
    "patterns": ["*.test.js", "*.spec.ts"]
  },
  "severity": {
    "minimum_severity": "Low",
    "confidence_threshold": 0.3
  },
  "detectors": {
    "sql_injection": true,
    "xss": true,
    "command_injection": true,
    "path_traversal": true,
    "hardcoded_secrets": true,
    "insecure_crypto": true,
    "buffer_overflow": true,
    "deserialization": true,
    "ssrf": true,
    "dependency_check": false
  }
}

Configuration file lookup order:

Path specified via --config CLI flag
.vulnscan.json in the current directory
~/.vulnscan/config.json in the user's home directory
Built-in defaults

GitHub Actions Integration (SARIF)

Add the following to .github/workflows/vulnscan.yml:

name: VulnScan Security Check

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  vulnscan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install VulnScan-CLI
        run: pip install vulnscan-cli

      - name: Run VulnScan
        run: vulnscan scan ./src --format sarif --output results.sarif

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

💡 Design Philosophy & Roadmap

Design Philosophy

Why zero dependencies?

In the security tooling space, trust is paramount. Zero core dependencies means:

Auditability — All code logic is fully transparent with no hidden supply chain risks
Portability — Runs in any Python environment without dependency conflicts
Lightweight — Tiny install footprint, fast startup, ideal for CI/CD pipelines
Reliability — Immune to third-party library version changes or abandonment

Pattern-based detection approach

VulnScan-CLI uses regex and AST pattern matching for detection. The advantages of this approach:

Controllable false positive rate with precisely tunable rules
Fast detection speed, suitable for large-scale codebase scanning
Rules are easy to understand and customize
No complex model training or inference required

Roadmap

AI-powered detection — Leverage LLMs for context-aware vulnerability detection to reduce false positives
CI/CD integration plugins — Official plugins for Jenkins, GitLab CI, CircleCI, and other platforms
IDE plugins — Real-time detection plugins for VS Code and JetBrains IDEs
Custom rule marketplace — A community-driven rule sharing platform for publishing and subscribing to custom rule packs
Incremental scanning — Git diff-based incremental scanning to check only changed code
Vulnerability fix suggestions — Automated fix recommendations and code patches for detected vulnerabilities

📦 Packaging & Deployment

pip Install

# Install from PyPI
pip install vulnscan-cli

# Install with TUI support
pip install vulnscan-cli[tui]

Install from Source

git clone https://github.com/gitstq/VulnScan-CLI.git
cd VulnScan-CLI
pip install -e .          # Development mode
pip install .             # Production install
pip install .[tui]        # With TUI support

Docker Usage

# Run a scan with Docker
docker run --rm -v $(pwd):/app/src gitstq/vulnscan-cli scan /app/src

# Generate an HTML report with mounted output directory
docker run --rm -v $(pwd):/app/src -v $(pwd)/reports:/app/reports \
  gitstq/vulnscan-cli scan /app/src --format html --output /app/reports/report.html

CI/CD Integration

GitHub Actions

- name: Security Scan
  run: |
    pip install vulnscan-cli
    vulnscan scan ./src --format sarif --output results.sarif

GitLab CI

security_scan:
  stage: test
  script:
    - pip install vulnscan-cli
    - vulnscan scan ./src --format json --output vulnscan-report.json
  artifacts:
    paths:
      - vulnscan-report.json

Jenkins Pipeline

stage('Security Scan') {
    steps {
        sh 'pip install vulnscan-cli'
        sh 'vulnscan scan ./src --format html --output vulnscan-report.html'
    }
}

🤝 Contributing Guide

We welcome and appreciate contributions of all kinds — whether it's filing bug reports, improving documentation, or contributing code.

Submitting a Pull Request

Fork this repository
Create a feature branch: git checkout -b feature/your-feature
Commit your changes: git commit -m "feat: add your feature"
Push the branch: git push origin feature/your-feature
Open a Pull Request

Filing Issues

Bug reports — Please include reproduction steps, expected behavior, and actual behavior
Feature requests — Describe your use case and the functionality you'd like to see
Rule contributions — New detection rules are welcome. Please include test cases

Code Style

Follow PEP 8 coding conventions
Use type hints
Write docstrings
Ensure all submissions pass tests

📄 License

This project is released under the MIT License.

MIT License

Copyright (c) 2024 VulnScan-CLI Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Made with ❤️ by VulnScan-CLI Contributors

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
vulnscan_cli		vulnscan_cli
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

VulnScan-CLI

🎉 项目介绍

为什么选择 VulnScan-CLI？

✨ 核心特性

🔍 10 大漏洞检测器

🌍 支持 23 种编程语言

📊 五级严重性评分

📋 OWASP Top 10 覆盖与 CWE 映射

📄 多格式报告输出

🎨 TUI 交互式仪表盘

📦 零核心依赖

🚀 批量扫描

🔧 可配置的规则与排除模式

📡 GitHub Code Scanning 集成

🚀 快速开始

环境要求

安装方式

快速上手

📖 详细使用指南

命令行参数一览

管道输入（stdin）用法

严重性过滤示例

配置文件

GitHub Actions 集成（SARIF）

💡 设计思路与迭代规划

设计理念

未来规划

📦 打包与部署指南

pip 安装

从源码安装

Docker 使用

CI/CD 集成

🤝 贡献指南

提交 Pull Request

提交 Issue

代码风格

📄 开源协议

🎉 專案介紹

為什麼選擇 VulnScan-CLI？

✨ 核心特性

🔍 10 大漏洞偵測器

🌍 支援 23 種程式語言

📊 五級嚴重性評分

📋 OWASP Top 10 涵蓋與 CWE 映射

📄 多格式報告輸出

🎨 TUI 互動式儀表板

📦 零核心依賴

🚀 批次掃描

🔧 可配置的規則與排除模式

📡 GitHub Code Scanning 整合

🚀 快速開始

環境需求

安裝方式

快速上手

📖 詳細使用指南

命令列參數一覽

管道輸入（stdin）用法

嚴重性過濾範例

設定檔

GitHub Actions 整合（SARIF）

💡 設計理念與迭代規劃

設計理念

未來規劃

📦 打包與部署指南

pip 安裝

從原始碼安裝

Docker 使用

CI/CD 整合

🤝 貢獻指南

提交 Pull Request

提交 Issue

程式碼風格

📄 開源協議

🎉 Project Introduction

Why VulnScan-CLI?

✨ Core Features

Packages