简体中文

DevGuard-CLI — 轻量级开发者端点供应链安全扫描引擎

一行命令，全面体检你的开发环境供应链安全态势。

项目介绍

DevGuard-CLI 是什么？

DevGuard-CLI 是一款专为开发者打造的端点供应链安全扫描工具。它能在你的本地开发机上快速扫描所有包管理器生态、编辑器扩展、浏览器扩展以及 MCP 服务器配置，精准识别潜在的安全风险。

为什么需要它？

现代开发者的工作环境堪称一个"供应链丛林"——npm、PyPI、Go Modules、RubyGems、Composer、Homebrew，再加上 VS Code / Cursor / Windsurf 的编辑器扩展、Chromium / Firefox 的浏览器扩展，以及越来越多的 MCP 服务器配置……这些组件构成了你日常开发的基础设施，却也同时成为供应链攻击的潜在攻击面。

传统的安全扫描工具要么聚焦于 CI/CD 流水线，要么需要复杂的部署配置，对于开发者个人终端这个关键节点的覆盖几乎为零。DevGuard-CLI 正是为了填补这一空白而生。

差异化亮点

零依赖：纯 Python 标准库实现，pip install . 即可使用，不引入任何第三方包
九大生态全覆盖：从 npm 到 Homebrew，从编辑器扩展到浏览器扩展，一个工具搞定
三级扫描模式：baseline（轻量全局）、project（项目级）、deep（深度全盘），按需选择
内置威胁情报：开箱即用的暴露目录匹配，识别已知恶意包和供应链攻击
多格式输出：NDJSON、SARIF、JSON、HTML 四种格式，无缝对接各类下游工具
CI/CD 友好：扫描发现高危漏洞时自动返回非零退出码，可直接嵌入流水线

核心特性

🔍 九大生态扫描 — 覆盖 npm/pnpm/yarn/bun、PyPI、Go Modules、RubyGems、Composer、MCP 服务器配置、编辑器扩展（VS Code / Cursor / Windsurf）、浏览器扩展（Chromium / Firefox）、Homebrew
🎯 三级扫描模式 — baseline（全局轻量扫描，秒级完成）、project（项目目录级扫描，精准定位）、deep（深度全盘扫描，覆盖整个 Home 目录）
🛡️ 暴露目录匹配 — 内置威胁情报库，支持自定义 exposure catalog，精准识别已知恶意包、typosquatting、后门和供应链攻击
📊 四种输出格式 — NDJSON（流式处理友好）、SARIF（GitHub Code Scanning 原生支持）、JSON（结构化报告）、HTML（可视化安全报告）
🎨 TUI 彩色终端仪表盘 — 纯 ANSI 实现的彩色终端输出，扫描结果一目了然，severity 分级高亮
🖥️ 跨平台支持 — 完美运行于 Linux、macOS、Windows 三大平台
🔄 CI/CD 集成友好 — 发现 critical/high 级别漏洞自动返回非零退出码，支持 --findings-only、--max-duration 等流水线专用参数
⚡ 零外部依赖 — 纯 Python 标准库实现，安装即用，不污染项目依赖树
🧪 内置自检 — devguard selftest 一键验证所有模块功能正常

快速开始

环境要求

Python 3.8+（支持 3.8 / 3.9 / 3.10 / 3.11 / 3.12）
操作系统：Linux / macOS / Windows
无其他依赖

安装

# 克隆仓库
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

设计思路与迭代规划

设计哲学

开发者优先：一切从开发者的实际工作流出发，不做花哨的 GUI，专注 CLI 体验
零侵入：不安装任何第三方依赖，不修改系统配置，不收集隐私数据
可组合：通过标准输出格式（NDJSON、SARIF）与现有工具链无缝衔接
渐进式：三级扫描模式让用户从轻量到深度逐步探索，不会一上来就被海量信息淹没

架构概览

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 彩色终端输出)

迭代规划

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

Fork 本仓库
创建功能分支（git checkout -b feature/my-feature）
提交你的改动（git commit -m 'Add some feature'）
推送到远程分支（git push origin feature/my-feature）
创建 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

繁體中文

DevGuard-CLI — 輕量級開發者端點供應鏈安全掃描引擎

一行指令，全面體檢你的開發環境供應鏈安全態勢。

專案介紹

DevGuard-CLI 是什麼？

DevGuard-CLI 是一款專為開發者打造的端點供應鏈安全掃描工具。它能在你的本地開發機上快速掃描所有套件管理器生態、編輯器擴充套件、瀏覽器擴充套件以及 MCP 伺服器配置，精準識別潛在的安全風險。

為什麼需要它？

現代開發者的工作環境堪稱一個「供應鏈叢林」——npm、PyPI、Go Modules、RubyGems、Composer、Homebrew，再加上 VS Code / Cursor / Windsurf 的編輯器擴充套件、Chromium / Firefox 的瀏覽器擴充套件，以及越來越多的 MCP 伺服器配置……這些元件構成了你日常開發的基礎設施，卻也同時成為供應鏈攻擊的潛在攻擊面。

傳統的安全掃描工具要麼聚焦於 CI/CD 管線，要麼需要複雜的部署配置，對於開發者個人終端這個關鍵節點的覆蓋幾乎為零。DevGuard-CLI 正是為了填補這一空白而生。

差異化亮點

零依賴：純 Python 標準函式庫實作，pip install . 即可使用，不引入任何第三方套件
九大生態全覆蓋：從 npm 到 Homebrew，從編輯器擴充套件到瀏覽器擴充套件，一個工具搞定
三級掃描模式：baseline（輕量全域）、project（專案級）、deep（深度全盤），按需選擇
內建威脅情報：開箱即用的暴露目錄匹配，識別已知惡意套件和供應鏈攻擊
多格式輸出：NDJSON、SARIF、JSON、HTML 四種格式，無縫對接各類下游工具
CI/CD 友善：掃描發現高危漏洞時自動回傳非零退出碼，可直接嵌入管線

核心特性

🔍 九大生態掃描 — 覆蓋 npm/pnpm/yarn/bun、PyPI、Go Modules、RubyGems、Composer、MCP 伺服器配置、編輯器擴充套件（VS Code / Cursor / Windsurf）、瀏覽器擴充套件（Chromium / Firefox）、Homebrew
🎯 三級掃描模式 — baseline（全域輕量掃描，秒級完成）、project（專案目錄級掃描，精準定位）、deep（深度全盤掃描，覆蓋整個 Home 目錄）
🛡️ 暴露目錄匹配 — 內建威脅情報庫，支援自訂 exposure catalog，精準識別已知惡意套件、typosquatting、後門和供應鏈攻擊
📊 四種輸出格式 — NDJSON（串流處理友善）、SARIF（GitHub Code Scanning 原生支援）、JSON（結構化報告）、HTML（視覺化安全報告）
🎨 TUI 彩色終端儀表板 — 純 ANSI 實作的彩色終端輸出，掃描結果一目了然，severity 分級高亮
🖥️ 跨平台支援 — 完美運行於 Linux、macOS、Windows 三大平台
🔄 CI/CD 整合友善 — 發現 critical/high 級別漏洞自動回傳非零退出碼，支援 --findings-only、--max-duration 等管線專用參數
⚡ 零外部依賴 — 純 Python 標準函式庫實作，安裝即用，不汙染專案依賴樹
🧪 內建自檢 — devguard selftest 一鍵驗證所有模組功能正常

快速開始

環境需求

Python 3.8+（支援 3.8 / 3.9 / 3.10 / 3.11 / 3.12）
作業系統：Linux / macOS / Windows
無其他依賴

安裝

# 克隆倉庫
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

設計思路與迭代規劃

設計哲學

開發者優先：一切從開發者的實際工作流程出發，不做花俏的 GUI，專注 CLI 體驗
零侵入：不安裝任何第三方依賴，不修改系統配置，不收集隱私資料
可組合：透過標準輸出格式（NDJSON、SARIF）與現有工具鏈無縫銜接
漸進式：三級掃描模式讓使用者從輕量到深度逐步探索，不會一上來就被海量資訊淹沒

架構概覽

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 彩色終端輸出)

迭代規劃

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

Fork 本倉庫
建立功能分支（git checkout -b feature/my-feature）
提交你的變更（git commit -m 'Add some feature'）
推送到遠端分支（git push origin feature/my-feature）
建立 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

Developer-first: Everything starts from the developer's actual workflow. No flashy GUI — focused CLI experience
Zero intrusion: No third-party dependencies installed, no system configurations modified, no privacy data collected
Composable: Seamlessly integrates with existing toolchains through standard output formats (NDJSON, SARIF)
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

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

Fork this repository
Create a feature branch (git checkout -b feature/my-feature)
Commit your changes (git commit -m 'Add some feature')
Push to the remote branch (git push origin feature/my-feature)
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

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
devguard_cli		devguard_cli
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
setup.cfg		setup.cfg
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

简体中文

项目介绍

DevGuard-CLI 是什么？

为什么需要它？

差异化亮点

核心特性

快速开始

环境要求

安装

启动你的第一次扫描

详细使用指南

扫描模式详解

常用命令速查

完整参数说明

自定义暴露目录（Exposure Catalog）

典型场景示例

设计思路与迭代规划

设计哲学

架构概览

迭代规划

安装与部署指南

从源码安装

验证安装

卸载

贡献指南

快速开始

代码规范

提交 Pull Request

开源协议

繁體中文

專案介紹

DevGuard-CLI 是什麼？

為什麼需要它？

差異化亮點

核心特性

快速開始

環境需求

安裝

啟動你的第一次掃描

詳細使用指南

掃描模式詳解

常用指令速查

完整參數說明

自訂暴露目錄（Exposure Catalog）

典型場景示例

設計思路與迭代規劃

設計哲學

架構概覽

迭代規劃

安裝與部署指南

從原始碼安裝

驗證安裝

解除安裝

貢獻指南

快速開始

程式碼規範

提交 Pull Request

開源協議

English

Introduction

What is DevGuard-CLI?

Why Do You Need It?

What Makes It Different?

Core Features

Quick Start

Prerequisites

Installation

Run Your First Scan

Detailed Usage Guide

Scan Profiles Explained

Command Cheat Sheet

Full Parameter Reference

Custom Exposure Catalog

Typical Usage Scenarios

Design Philosophy & Roadmap

Design Principles

Packages