devcristianlopez/manel

# Manel — 安全健康监控 CLI Manel 是一款专为开发环境设计的安全 CLI 工具，它在本地扫描已安装的软件（OS、工具、编程语言、数据库），从公开数据源（OSV、NVD、GitHub Advisories）查询已知漏洞，并生成安全评分（0-100）及可操作的建议。 []() []() []() []() ## 快速开始 ``` # 全局安装 npm install -g manel # 或直接运行 npx manel scan # 快速状态检查 manel status ``` ## 安装 ### 前置条件 - **Node.js 18+** — 从 [nodejs.org](https://nodejs.org/) 下载 - **npm** — 包含在 Node.js 中 - **Git** — 用于从源码安装 ``` # 检查版本 node --version # Should show v18.x.x or higher npm --version git --version ``` ### 方法 1：通过 npm 安装（推荐） ``` npm install -g manel ``` ### 方法 2：自动安装脚本 ``` # Clone 代码库 git clone https://github.com/devcristianlopez/manel.git cd manel # 运行 installer bash setup.sh # 或在 development mode 下运行（包含 test tools） bash setup.sh --dev ``` 该安装脚本会： - ✅ 检测你的操作系统 - ✅ 验证/安装 Node.js 18+ - ✅ 安装依赖 - ✅ 编译 CLI - ✅ 全局链接 `manel` 命令 - ✅ 验证安装结果 ### 方法 3：手动安装 ``` git clone https://github.com/devcristianlopez/manel.git cd manel npm install npm run build:cli npm link ``` ### 方法 4：npx（免安装） ``` npx manel scan ``` ### 可用的 npm 脚本 ``` npm run install:global # Compile and install globally npm run uninstall:global # Uninstall globally npm run setup # Run bash setup.sh npm run uninstall # Run bash uninstall.sh ``` ### 验证安装 ``` manel --version manel status ``` ### 支持的操作系统 - ✅ Linux (Ubuntu, Debian, Fedora, Arch) - ✅ macOS - ⚠️ Windows（需手动安装） ## 卸载 ### 方法 1：卸载脚本（推荐） ``` # 如果您在项目目录中 bash uninstall.sh # 或使用项目路径 /path/to/manel/uninstall.sh ``` 脚本选项： ``` bash uninstall.sh --help # Show help bash uninstall.sh --yes # Skip confirmations bash uninstall.sh --all # Also remove installation directory ``` ### 方法 2：npm ``` npm uninstall -g manel ``` ### 方法 3：手动卸载 ``` # 移除全局 link npm unlink -g manel # 或直接移除 executable rm -f $(which manel) ``` ### 卸载后操作 ``` # 刷新 shell cache hash -r ``` ## 命令 | 命令 | 描述 | |---------|-------------| | `manel status` | 快速查看已安装技术的状态 | | `manel scan` | 完整扫描：漏洞 + 基线加固 + 评分 | | `manel vulnerabilities` | 仅扫描漏洞（别名：`vulns`） | | `manel hardening` | 仅执行基线加固检查 (Linux) | | `manel score` | 详细的的安全评分 | | `manel updates` | 检查可用的更新 | | `manel schema` | CLI 自省 JSON（适配 AI） | ### 使用示例 ``` # 快速状态 manel status # Full scan 并输出 JSON manel scan --format json # 仅限 Critical 和 High vulnerabilities manel vulnerabilities --severity CRITICAL,HIGH # Hardening 并输出到文件 manel hardening --output report.txt # 不带颜色的详细评分 manel score --no-color # 检查可用更新 manel updates --format json ``` ## 标准标志 所有命令均支持以下标志： | 标志 | 描述 | |------|-------------| | `-f, --format ` | 输出格式：`table`、`json`、`sarif`、`ndjson` | | `-o, --output ` | 将输出写入文件而非标准输出 | | `-s, --severity ` | 按严重程度过滤（逗号分隔） | | `--fail-on ` | 如果发现的问题 >= 指定严重程度，则以退出代码 1 退出 | | `--no-color` | 禁用 ANSI 彩色输出 | | `-q, --quiet` | 抑制非错误输出 | | `-V, --verbose` | 启用详细输出 | | `--no-interactive` | 禁用交互式提示（适用于 CI/CD） | ### 输出格式 | 格式 | 描述 | 推荐用途 | |--------|-------------|-----------------| | `table` | 带有颜色的格式化表格（默认） | 交互式终端 | | `json` | 格式化打印的 JSON | API、脚本、调试 | | `sarif` | 静态分析结果交换格式 | GitHub Code Scanning、SAST 工具 | | `ndjson` | 换行符分隔的 JSON | 管道、流式处理、批处理 | ## 退出代码 | 代码 | 含义 | |------|---------| | `0` | 成功，未发现问题 | | `1` | 检测到问题（漏洞、基线加固未通过） | | `2` | 内部错误 | | `3` | 无效输入 | ## CI/CD 示例 ### GitHub Actions ``` name: Security Scan on: [push, pull_request] jobs: security: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: '20' - run: npm install -g manel - name: Run security scan run: manel scan --format sarif --output scan-results.sarif --no-interactive - name: Upload SARIF to GitHub uses: github/codeql-action/upload-sarif@v3 if: always() with: sarif_file: scan-results.sarif ``` ### 带有 fail-on 的流水线 ``` - name: Security gate run: manel scan --fail-on high --no-interactive --format json ``` ### 仅扫描漏洞 ``` - name: Check vulnerabilities run: manel vulns --severity CRITICAL,HIGH --format ndjson | jq '.severity' ``` ## 管道示例 ``` # 提取 Critical vulnerabilities manel scan --format json | jq '.vulnerabilities[] | select(.severity == "CRITICAL")' # 按 severity 统计 vulnerabilities manel scan --format json | jq '[.vulnerabilities[].severity] | group_by(.) | map({(.[0]): length}) | add' # 过滤过时技术 manel scan --format json | jq '.technologies[] | select(.updateAvailable == true)' # 发送结果到 logging service manel scan --format ndjson | while read line; do echo "$line" | curl -X POST -d @- https://api.example.com/logs; done # 生成 SARIF report 并上传到 GitHub manel scan --format sarif -o results.sarif # 仅检查评分 manel score --format json | jq '.overall' ``` ## 安全评分 评分基于以下权重进行计算： | 类别 | 权重 | |----------|--------| | 操作系统 | 15% | | 基线加固 | 15% | | 工具 | 10% | | 依赖 | 30% | | 数据库 | 10% | | 严重漏洞 | 20% | ## 可检测的技术 - **编程语言和运行时**：Node.js, Python, Python 3, Java - **包管理器**：npm, Yarn, pnpm, pip, Maven, Gradle - **工具**：Git, Docker, Docker Compose, VS Code - **数据库**：PostgreSQL, MySQL, MariaDB, MongoDB, Redis, SQLite, pgAdmin - **操作系统**：Ubuntu, Debian, Fedora, macOS, Windows ## 自省 Schema `schema` 命令会生成一个描述整个 CLI 接口的 JSON，这对于 AI 工具和文档生成非常有用： ``` manel schema | jq '.commands[] | .name' ``` ## 本地缓存与持久化 Manel 将 API 响应和扫描结果存储在位于 `~/.manel/manel.db` 的本地 SQLite 数据库中： - **版本缓存**（24 小时 TTL）— 在重复运行时，最新版本查询将跳过网络请求 - **漏洞缓存**（24 小时 TTL）— OSV/NVD/GHSA 的结果按 `ecosystem:package:version` 进行缓存，避免触发 API 速率限制 - **扫描历史** — 每次运行 `scan`/`vulnerabilities` 都会持久化检测到的软件、发现的问题和评分，以供审计 首次运行时会查询外部 API；在 24 小时内的后续运行对于缓存数据将不再发起网络请求。可以通过 `MANEL_DB_PATH` 环境变量覆盖数据库的存储位置（适用于测试和 CI 环境）。 ## 开发 ``` # 安装依赖 npm install # 构建 CLI npm run build:cli # 在 development 模式下运行 node bin/manel-cli.js scan # 运行 tests npm test # Type checking npm run lint ``` ## 技术栈 | 层级 | 技术 | |-------|-----------| | CLI 框架 | Commander.js 15 | | 编程语言 | TypeScript 5 | | 运行时 | Node.js 18+ | | 数据库 | SQLite (better-sqlite3) | | 测试 | Vitest | | 外部 API | OSV, NVD, GitHub Security Advisories, npm registry, PyPI, endoflife.date | ## 项目结构 ``` manel/ ├── bin/ │ └── manel-cli.js # CLI entry point ├── src/ │ ├── cli/ # CLI framework │ │ ├── commands/ # Command implementations │ │ ├── output/ # Formatters (table, json, sarif, ndjson) │ │ ├── flags.ts # Shared flags │ │ ├── errors.ts # Error handling │ │ └── index.ts # Main entry point │ ├── core/ # Business logic │ │ ├── scanner/ # Software detection │ │ ├── security/ # Security engine │ │ ├── update-engine/ # Version checking │ │ ├── database/ # SQLite persistence │ │ └── index.ts # Barrel export │ └── shared/ # Shared types │ └── types.ts ├── package.json ├── tsconfig.cli.json # TypeScript config for CLI └── vitest.config.ts ``` 请参阅 [ARCHITECTURE.md](./ARCHITECTURE.md) 获取详细的技术文档。 ## 数据源 - [OSV](https://osv.dev) — 开源漏洞数据库 - [NVD](https://nvd.nist.gov) — 国家漏洞数据库 (美国) - [GitHub Security Advisories](https://github.com/advisories) — 安全公告数据库 - [End of Life](https://endoflife.date) — 软件支持周期日期 - [npm registry](https://registry.npmjs.org) — 最新的 npm 包版本 - [PyPI](https://pypi.org) — 最新的 Python 包版本 - [GitHub Releases](https://api.github.com) — 最新的 GitHub 项目发行版 ## 贡献 请参阅 [CONTRIBUTING.md](./CONTRIBUTING.md) 了解开发和贡献指南。 ## 许可证 MIT

标签：MITM代理, TypeScript, WebSocket, 依赖分析, 安全基线检查, 安全插件, 开发安全, 自动化攻击