### 安裝 # 克隆倉庫 git clone https://github.com/gitstq/DevGuard-CLI.git cd DevGuard-CLI # 安裝（推薦使用可編輯模式） pip install -e . # 或者直接安裝 pip install . ### 啟動你的第一次掃描 # 執行 baseline 全域輕量掃描（推薦首次使用） devguard scan --profile baseline # 查看版本資訊 devguard version # 執行內建自檢，確認一切正常 devguard selftest 恭喜！你已經完成了第一次開發環境供應鏈安全掃描。🎉 ## 詳細使用指南 ### 掃描模式詳解 | 模式 | 指令 | 說明 | 適用場景 | |------|------|------|----------| | **baseline** | `--profile baseline` | 輕量全域掃描，檢查全域套件管理器和擴充套件目錄 | 日常快速體檢 | | **project** | `--profile project --root ./my-project` | 專案級掃描，解析 lockfile 和依賴清單 | 專案安全稽核 | | **deep** | `--profile deep` | 深度全盤掃描，覆蓋整個 Home 目錄 | 全面安全評估 | ### 常用指令速查 # 基礎掃描 devguard scan --profile baseline # 掃描指定專案並生成 HTML 報告 devguard scan --profile project --root ./my-project --output-format html --output-file report.html # 深度掃描，使用自訂威脅情報，僅輸出發現 devguard scan --profile deep --root $HOME --exposure-catalog ./catalog.json --findings-only # 預覽掃描範圍（不實際掃描） devguard roots --profile baseline # 只掃描特定生態 devguard scan --profile project --root ./my-project --ecosystem npm --ecosystem pypi # 生成 SARIF 報告（用於 GitHub Code Scanning） devguard scan --profile project --root ./my-project --output-format sarif --output-file results.sarif # 生成 JSON 結構化報告 devguard scan --profile baseline --output-format json --output-file report.json # 限制掃描時長（適用於 CI/CD） devguard scan --profile project --root ./my-project --max-duration 60 # 關閉彩色輸出 devguard scan --profile baseline --no-color # 使用 python -m 方式呼叫 python -m devguard_cli scan --profile baseline ### 完整參數說明 | 參數 | 縮寫 | 說明 | 預設值 | |------|------|------|--------| | `--profile` | `-p` | 掃描模式：baseline / project / deep | `baseline` | | `--root` | `-r` | 掃描根目錄（可重複指定） | 由 profile 決定 | | `--ecosystem` | `-e` | 指定掃描生態（可重複指定） | 全部生態 | | `--exposure-catalog` | — | 自訂暴露目錄 JSON 檔案路徑 | 內建目錄 | | `--findings-only` | — | 僅輸出安全發現，跳過套件列表 | `false` | | `--output-format` | `-f` | 輸出格式：ndjson / sarif / json / html | `ndjson` | | `--output-file` | `-o` | 輸出檔案路徑（不指定則輸出到 stdout） | stdout | | `--max-duration` | — | 最大掃描時長（秒） | `300` | | `--no-color` | — | 關閉彩色終端輸出 | `false` | ### 自訂暴露目錄（Exposure Catalog） 你可以建立自訂的威脅情報 JSON 檔案，用於匹配特定套件： { "catalog_version": "1.0.0", "entries": [ { "id": "CUSTOM-001", "name": "my-custom-rule", "ecosystem": "npm", "package_pattern": "^suspicious-package$", "version_pattern": ".*", "severity": "high", "finding_type": "malware", "description": "此套件包含惡意程式碼" } ] } 使用方式： devguard scan --profile project --root ./my-project --exposure-catalog ./my-catalog.json ### 典型場景示例 **場景一：日常安全巡檢** # 每天上班第一件事，快速掃描全域環境 devguard scan --profile baseline **場景二：專案交付前安全稽核** # 專案上線前，生成 HTML 報告留檔 devguard scan --profile project --root ./my-project \ --output-format html --output-file security-audit.html **場景三：CI/CD 管線整合** # GitHub Actions 示例 - name: Supply Chain Security Scan run: | pip install -e . devguard scan --profile project --root . \ --output-format sarif --output-file results.sarif \ --max-duration 120 --no-color **場景四：深度安全評估** # 全面掃描整個開發環境，結合自訂威脅情報 devguard scan --profile deep \ --exposure-catalog ./threat-intel.json \ --output-format json --output-file full-scan.json ## 設計思路與迭代規劃 ### 設計哲學 1. **開發者優先**：一切從開發者的實際工作流程出發，不做花俏的 GUI，專注 CLI 體驗 2. **零侵入**：不安裝任何第三方依賴，不修改系統配置，不收集隱私資料 3. **可組合**：透過標準輸出格式（NDJSON、SARIF）與現有工具鏈無縫銜接 4. **漸進式**：三級掃描模式讓使用者從輕量到深度逐步探索，不會一上來就被海量資訊淹沒 ### 架構概覽 CLI (argparse) └── ScanEngine ├── ScanProfile (baseline / project / deep) ├── Collectors (npm, pypi, gomod, rubygems, composer, mcp, editor_ext, browser_ext, homebrew) ├── ExposureMatcher (內建 + 自訂威脅情報) ├── OutputFormatter (NDJSON / SARIF / JSON / HTML) └── TUI (ANSI 彩色終端輸出) ### 迭代規劃 - [x] **v0.1.0** — 核心掃描引擎，九大生態採集器，三級掃描模式，四種輸出格式 - [ ] **v0.2.0** — 增量掃描、快取機制、更多內建威脅情報條目 - [ ] **v0.3.0** — 外掛系統、自訂採集器、Web Dashboard - [ ] **v1.0.0** — 穩定 API、完整文件、社群生態 ## 安裝與部署指南 ### 從原始碼安裝 git clone https://github.com/gitstq/DevGuard-CLI.git cd DevGuard-CLI pip install -e . ### 驗證安裝 devguard version # 應輸出 DevGuard-CLI v0.1.0 devguard selftest # 所有測試項應顯示 PASS ### 解除安裝 pip uninstall devguard-cli ## 貢獻指南 我們歡迎並感謝所有形式的貢獻！無論是提交 Bug、改進文件、還是貢獻程式碼。 ### 快速開始 # 1. Fork 並克隆倉庫 git clone https://github.com/你的使用者名稱/DevGuard-CLI.git cd DevGuard-CLI # 2. 安裝開發環境 pip install -e . # 3. 執行測試 python -m pytest tests/ # 4. 執行自檢 devguard selftest ### 程式碼規範 - 遵循 **PEP 8** 編碼規範 - 程式碼註解使用英文 - **零第三方依賴**原則：所有功能必須使用 Python 標準函式庫實作 - 相容 **Python 3.8+** ### 提交 Pull Request 1. Fork 本倉庫 2. 建立功能分支（`git checkout -b feature/my-feature`） 3. 提交你的變更（`git commit -m 'Add some feature'`） 4. 推送到遠端分支（`git push origin feature/my-feature`） 5. 建立 Pull Request ## 開源協議 本專案基於 **MIT License** 開源。 MIT License Copyright (c) 2024 DevGuard 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.

Made with ❤️ by DevGuard Contributors

English

DevGuard-CLI — Lightweight Developer Endpoint Supply Chain Security Scanner

One command to comprehensively audit your development environment's supply chain security posture.

## Introduction ### What is DevGuard-CLI? DevGuard-CLI is a **supply chain security scanner built specifically for developers**. It rapidly scans all package manager ecosystems, editor extensions, browser extensions, and MCP server configurations on your local development machine, precisely identifying potential security risks. ### Why Do You Need It? A modern developer's environment is essentially a "supply chain jungle" — npm, PyPI, Go Modules, RubyGems, Composer, Homebrew, plus VS Code / Cursor / Windsurf editor extensions, Chromium / Firefox browser extensions, and a growing number of MCP server configurations. These components form the backbone of your daily development workflow, but they simultaneously represent potential attack surfaces for supply chain attacks. Traditional security scanning tools either focus on CI/CD pipelines or require complex deployment configurations. Coverage for the **developer's personal endpoint** — a critical node — is virtually nonexistent. DevGuard-CLI was born to fill this exact gap. ### What Makes It Different? - **Zero dependencies**: Built entirely with Python's standard library. `pip install .` and you're good to go — no third-party packages introduced - **9 ecosystem coverage**: From npm to Homebrew, from editor extensions to browser extensions — one tool covers them all - **3-tier scan modes**: baseline (lightweight global), project (project-level), deep (full-disk scan) — choose what fits your needs - **Built-in threat intelligence**: Out-of-the-box exposure catalog matching to identify known malicious packages and supply chain attacks - **Multi-format output**: NDJSON, SARIF, JSON, and HTML — seamlessly integrates with downstream tooling - **CI/CD friendly**: Automatically returns non-zero exit codes when critical/high vulnerabilities are found ## Core Features - 🔍 **9 Ecosystem Scanning** — Covers npm/pnpm/yarn/bun, PyPI, Go Modules, RubyGems, Composer, **MCP server configurations**, editor extensions (VS Code / Cursor / Windsurf), browser extensions (Chromium / Firefox), and Homebrew - 🎯 **3-Tier Scan Modes** — **baseline** (lightweight global scan, completes in seconds), **project** (project-directory scan, precise targeting), **deep** (full-disk scan covering the entire Home directory) - 🛡️ **Exposure Catalog Matching** — Built-in threat intelligence database with support for custom exposure catalogs. Precisely identifies known malicious packages, typosquatting, backdoors, and supply chain attacks - 📊 **4 Output Formats** — **NDJSON** (stream-processing friendly), **SARIF** (native GitHub Code Scanning support), **JSON** (structured reports), **HTML** (visualizable security reports) - 🎨 **TUI Color Terminal Dashboard** — Pure ANSI-based colorful terminal output. Scan results at a glance with severity-based highlighting - 🖥️ **Cross-Platform Support** — Runs flawlessly on Linux, macOS, and Windows - 🔄 **CI/CD Integration Friendly** — Automatically returns non-zero exit codes for critical/high findings. Supports pipeline-specific flags like `--findings-only` and `--max-duration` - ⚡ **Zero External Dependencies** — Pure Python standard library implementation. Install and run without polluting your project's dependency tree - 🧪 **Built-in Self-Test** — `devguard selftest` verifies all modules are functioning correctly with a single command ## Quick Start ### Prerequisites - **Python 3.8+** (supports 3.8 / 3.9 / 3.10 / 3.11 / 3.12) - **Operating System**: Linux / macOS / Windows - **No other dependencies required** ### Installation # Clone the repository git clone https://github.com/gitstq/DevGuard-CLI.git cd DevGuard-CLI # Install (editable mode recommended) pip install -e . # Or install directly pip install . ### Run Your First Scan # Run a baseline lightweight global scan (recommended for first-time users) devguard scan --profile baseline # Check version info devguard version # Run built-in self-tests to verify everything is working devguard selftest Congratulations! You've just completed your first development environment supply chain security scan. 🎉 ## Detailed Usage Guide ### Scan Profiles Explained | Profile | Command | Description | Use Case | |---------|---------|-------------|----------| | **baseline** | `--profile baseline` | Lightweight global scan of global package managers and extension directories | Daily quick health checks | | **project** | `--profile project --root ./my-project` | Project-level scan parsing lockfiles and dependency manifests | Project security audits | | **deep** | `--profile deep` | Full-disk scan covering the entire Home directory | Comprehensive security assessments | ### Command Cheat Sheet # Basic scan devguard scan --profile baseline # Scan a specific project and generate an HTML report devguard scan --profile project --root ./my-project --output-format html --output-file report.html # Deep scan with custom threat intelligence, findings only devguard scan --profile deep --root $HOME --exposure-catalog ./catalog.json --findings-only # Preview scan scope (without actually scanning) devguard roots --profile baseline # Scan specific ecosystems only devguard scan --profile project --root ./my-project --ecosystem npm --ecosystem pypi # Generate SARIF report (for GitHub Code Scanning) devguard scan --profile project --root ./my-project --output-format sarif --output-file results.sarif # Generate JSON structured report devguard scan --profile baseline --output-format json --output-file report.json # Limit scan duration (for CI/CD) devguard scan --profile project --root ./my-project --max-duration 60 # Disable colored output devguard scan --profile baseline --no-color # Invoke via python -m python -m devguard_cli scan --profile baseline ### Full Parameter Reference | Parameter | Shorthand | Description | Default | |-----------|-----------|-------------|---------| | `--profile` | `-p` | Scan profile: baseline / project / deep | `baseline` | | `--root` | `-r` | Root directory to scan (repeatable) | Determined by profile | | `--ecosystem` | `-e` | Specific ecosystem to scan (repeatable) | All ecosystems | | `--exposure-catalog` | — | Path to custom exposure catalog JSON file | Built-in catalog | | `--findings-only` | — | Output only findings, skip package records | `false` | | `--output-format` | `-f` | Output format: ndjson / sarif / json / html | `ndjson` | | `--output-file` | `-o` | Output file path (defaults to stdout) | stdout | | `--max-duration` | — | Maximum scan duration in seconds | `300` | | `--no-color` | — | Disable colored terminal output | `false` | ### Custom Exposure Catalog Create your own threat intelligence JSON file to match specific packages: { "catalog_version": "1.0.0", "entries": [ { "id": "CUSTOM-001", "name": "my-custom-rule", "ecosystem": "npm", "package_pattern": "^suspicious-package$", "version_pattern": ".*", "severity": "high", "finding_type": "malware", "description": "This package contains malicious code" } ] } Usage: devguard scan --profile project --root ./my-project --exposure-catalog ./my-catalog.json ### Typical Usage Scenarios **Scenario 1: Daily Security Check** # First thing every morning — quick scan of your global environment devguard scan --profile baseline **Scenario 2: Pre-Release Security Audit** # Before shipping, generate an HTML report for your records devguard scan --profile project --root ./my-project \ --output-format html --output-file security-audit.html **Scenario 3: CI/CD Pipeline Integration** # GitHub Actions example - name: Supply Chain Security Scan run: | pip install -e . devguard scan --profile project --root . \ --output-format sarif --output-file results.sarif \ --max-duration 120 --no-color **Scenario 4: Comprehensive Security Assessment** # Full scan of your entire dev environment with custom threat intelligence devguard scan --profile deep \ --exposure-catalog ./threat-intel.json \ --output-format json --output-file full-scan.json ## Design Philosophy & Roadmap ### Design Principles 1. **Developer-first**: Everything starts from the developer's actual workflow. No flashy GUI — focused CLI experience 2. **Zero intrusion**: No third-party dependencies installed, no system configurations modified, no privacy data collected 3. **Composable**: Seamlessly integrates with existing toolchains through standard output formats (NDJSON, SARIF) 4. **Progressive**: Three scan tiers let users explore from lightweight to deep — no information overload from day one ### Architecture Overview CLI (argparse) └── ScanEngine ├── ScanProfile (baseline / project / deep) ├── Collectors (npm, pypi, gomod, rubygems, composer, mcp, editor_ext, browser_ext, homebrew) ├── ExposureMatcher (built-in + custom threat intelligence) ├── OutputFormatter (NDJSON / SARIF / JSON / HTML) └── TUI (ANSI colored terminal output) ### Roadmap - [x] **v0.1.0** — Core scan engine, 9 ecosystem collectors, 3-tier scan modes, 4 output formats - [ ] **v0.2.0** — Incremental scanning, caching mechanism, expanded built-in threat intelligence entries - [ ] **v0.3.0** — Plugin system, custom collectors, Web Dashboard - [ ] **v1.0.0** — Stable API, comprehensive documentation, community ecosystem ## Installation & Deployment Guide ### Install from Source git clone https://github.com/gitstq/DevGuard-CLI.git cd DevGuard-CLI pip install -e . ### Verify Installation devguard version # Should output: DevGuard-CLI v0.1.0 devguard selftest # All test items should show PASS ### Uninstall pip uninstall devguard-cli ## Contributing Guide We welcome and appreciate contributions of all kinds — bug reports, documentation improvements, or code contributions. ### Getting Started # 1. Fork and clone the repository git clone https://github.com/your-username/DevGuard-CLI.git cd DevGuard-CLI # 2. Set up the development environment pip install -e . # 3. Run tests python -m pytest tests/ # 4. Run self-tests devguard selftest ### Code Style - Follow **PEP 8** coding standards - Use English for code comments - **Zero third-party dependencies** principle: all features must be implemented using Python's standard library - Compatible with **Python 3.8+** ### Submitting a Pull Request 1. Fork this repository 2. Create a feature branch (`git checkout -b feature/my-feature`) 3. Commit your changes (`git commit -m 'Add some feature'`) 4. Push to the remote branch (`git push origin feature/my-feature`) 5. Create a Pull Request ## License This project is released under the **MIT License**. MIT License Copyright (c) 2024 DevGuard 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.

Made with ❤️ by DevGuard Contributors

标签：CI/CD 安全, GitHub Code Scanning, LangChain, lockfile, MCP/Editor/Browser 扩展, SARIF 报告, TUI Dashboard, 依赖清单, 依赖管理, 反取证, 多格式报告, 多生态系统, 威胁情报, 安全信息收集, 安全扫描, 安全报告, 安全漏洞检测, 安全稽核, 安全评估, 开发者工具, 数据投毒防御, 时序注入, 端点安全, 结构化查询, 自动化安全, 补丁管理, 轻量级, 逆向工具, 零依赖