AI导哈

GitHub安全扫描工具

一个用于扫描GitHub仓库安全问题的CLI工具，提供可扩展的扫描框架、多种报告格式和安全的令牌管理。

  • by securityreviewai
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 securityreviewai/mcp-security-scanner

使用说明

MCP安全分析器

用于扫描GitHub存储库以查找安全问题的CLI工具。该工具提供了一个可扩展的框架，用于分析GitHub存储库，具有可定制的扫描逻辑和多种报告格式。

特性

  • 🔐 安全令牌管理：GitHub个人访问令牌安全存储在用户配置中
  • 🔍 存储库扫描：克隆和分析GitHub存储库
  • 📊 多种报告格式：生成JSON和Markdown格式的报告
  • 🔧 可扩展架构：易于添加自定义扫描逻辑
  • 🚀 CLI接口：用户友好的命令行界面，带有进度指示器
  • 🧹 自动清理：扫描后清理临时存储库

安装

此项目使用 uv 作为包管理器。确保你有 uv 安装：

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

克隆存储库并安装依赖项：

git clone <your-repo-url>
cd mcp-security-profiler
uv sync

MCP服务器依赖关系

扫描仪使用MCP（模型上下文协议）服务器进行高级代码分析：

  • ast grep mcp：基于模式的代码搜索和分析
  • x射线mcp：代码结构分析

这些MCP服务器通过以下方式自动安装和管理 uvx 运行扫描时，不需要手动安装。扫描仪将：

  1. 首次使用时下载并缓存MCP服务器
  2. 在隔离环境中运行它们
  3. 在后续扫描中自动重用缓存版本

备注：由于MCP服务器安装在后台，第一次扫描可能需要更长的时间。

设置

1.配置环境变量

创建一个 .env 使用API凭据在项目根目录中创建文件：

cp .env.example .env

编辑 .env 文件并添加您的值：

# OpenAI API Configuration
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1

2.配置GitHub Token

在使用扫描程序之前，您需要配置您的GitHub个人访问令牌：

uv run mcp-security-profiler config --token <YOUR_GITHUB_TOKEN>

或者让它提示你：

uv run mcp-security-profiler config

创建GitHub令牌：

  1. 转到GitHub设置→ 开发人员设置→ 个人访问令牌→ 代币（经典）
  2. 点击“生成新令牌（经典）”
  3. 选择范围： repo （适用于私人回购）或 public_repo （仅适用于公共回购）
  4. 生成并复制令牌

令牌安全地存储在 ~/.mcp-security-profiler/config.json 具有受限权限。

用法

扫描存储库

uv run mcp-security-profiler scan <REPOSITORY>

这 REPOSITORY 参数接受多种格式：

  • 完整URL: https://github.com/owner/repo
  • 简短格式： owner/repo
  • Git URL： git@github.com:owner/repo.git

选项

# Generate specific report formats
uv run mcp-security-profiler scan owner/repo --format json
uv run mcp-security-profiler scan owner/repo --format markdown
uv run mcp-security-profiler scan owner/repo --format json --format markdown

# Specify output directory
uv run mcp-security-profiler scan owner/repo --output-dir ./my-reports

示例

# Scan a public repository
uv run mcp-security-profiler scan django/django

# Scan with custom output directory
uv run mcp-security-profiler scan https://github.com/pallets/flask --output-dir ./flask-scan

# Generate only JSON report
uv run mcp-security-profiler scan owner/repo -f json

报表格式

JSON报告

JSON报告包含结构化数据，包括：

  • 存储库元数据
  • 扫描时间戳和ID
  • 严重程度的详细调查结果
  • 存储库统计信息
  • 按严重程度列出的发现计数摘要

Markdown报告

Markdown报告提供了一种人类可读的格式，包括：

  • 存储库信息
  • 可视化摘要表
  • 按严重程度分组的发现
  • 对每个发现的建议
  • 文件类型分布统计

自定义扫描仪

扫描仪设计为可扩展的。您可以通过修改来添加自定义扫描逻辑 Scanner 类在 mcp_security_profiler/scanner.py.

添加自定义扫描

编辑 _run_custom_scans() 添加自定义扫描逻辑的方法：

def _run_custom_scans(self) -> List[Dict[str, Any]]:
    findings = []
    
    # Add your custom scanning logic here
    findings.extend(self._scan_for_secrets())
    findings.extend(self._scan_dependencies())
    findings.extend(self._scan_code_quality())
    findings.extend(self._scan_configurations())
    
    return findings

自定义扫描仪方法示例

def _scan_for_secrets(self) -> List[Dict[str, Any]]:
    """Scan for hardcoded secrets."""
    findings = []
    # Your implementation here
    return findings

def _scan_dependencies(self) -> List[Dict[str, Any]]:
    """Scan for vulnerable dependencies."""
    findings = []
    # Your implementation here
    return findings

项目结构

mcp-security-profiler/
├── main.py                          # Entry point
├── pyproject.toml                   # Project configuration
├── README.md                        # This file
├── PLAN.md                         # Project plan
└── mcp_security_profiler/
    ├── __init__.py                 # Package init
    ├── cli.py                      # CLI commands and interface
    ├── config.py                   # Configuration management
    ├── github_handler.py           # GitHub API operations
    ├── scanner.py                  # Scanning engine
    └── reporters.py                # Report generation

发展

从源头运行

# Run the CLI
uv run python main.py config
uv run python main.py scan owner/repo

# Or use the installed script
uv run mcp-security-profiler --help

添加依赖关系

使用 uv add 要添加新的依赖关系，请执行以下操作：

uv add package-name

CLI命令

config

为API访问配置GitHub令牌。

uv run mcp-security-profiler config --token <TOKEN>

选项：

  • --token：GitHub个人访问令牌（如果未提供，则会提示）

scan

扫描GitHub存储库以查找安全问题。

uv run mcp-security-profiler scan REPOSITORY [OPTIONS]

论据：

  • REPOSITORY：GitHub存储库（URL或所有者/仓库格式）

选项：

  • -f, --format [json|markdown]：报告格式（可以指定多个，默认：两者）
  • -o, --output-dir PATH：报告的输出目录（默认：./scan results）

安全说明

  • GitHub令牌存储在 0600 权限（仅限所有者读/写）
  • 配置目录： ~/.mcp-security-profiler/
  • 默认情况下会清理临时存储库
  • 所有GitHub API访问都使用经过身份验证的请求

故障排除

令牌问题

如果您遇到身份验证错误：

  1. 验证您的令牌是否有效
  2. 重新配置： uv run mcp-security-profiler config
  3. 确保令牌具有适当的作用域

克隆问题

如果存储库克隆失败：

  • 检查您的网络连接
  • 验证您是否有权访问存储库
  • 对于私有仓库，确保令牌具有 repo 范围

报告生成

如果未生成报告：

  • 检查输出目录中的写入权限
  • 验证输出路径是否有效
  • 检查磁盘空间

许可证

MIT许可证

版权所有（c）2025 Abhay Bhargav，安全评论。人工智能

特此免费向任何获得副本的人授予许可 本软件和相关文档文件（“软件”），以处理 在软件中不受限制，包括但不限于权利 使用、复制、修改、合并、发布、分发、再许可和/或销售 软件的副本，并允许软件的接收者 根据以下条件提供：

上述版权声明和本许可声明应包含在所有 软件的副本或实质性部分。

软件按“原样”提供，不提供任何形式的明示或明示担保 隐含的，包括但不限于适销性保证， 适用于特定目的且不造成伤害。在任何情况下 作者或版权持有人对任何索赔、损害赔偿或其他 因以下原因产生的责任，无论是在合同、侵权或其他诉讼中， 出于或与软件、使用或其他交易有关 软件。

贡献

我们欢迎为MCP Security Profiler做出贡献！以下是您可以提供帮助的方式：

报告问题

  • 错误报告：以清晰的描述、重现步骤以及预期与实际行为打开一个问题
  • 功能请求：描述功能、用例和潜在的实现方法

贡献代码

  1. 分叉存储库
  2. 创建要素分支: git checkout -b feature/your-feature-name
  3. 进行更改:
    • 编写清晰、有注释的代码
    • 遵循现有代码样式
    • 如果适用，添加测试
    • 根据需要更新文档
  4. 提交您的更改: git commit -m "Add feature: description"
  5. 推你的叉子: git push origin feature/your-feature-name
  6. 打开拉取请求：提供对变更的清晰描述

开发指南

  • 使用 uv 用于依赖关系管理（无pip）
  • Python代码遵循PEP 8风格指南
  • 编写描述性提交消息
  • 让PR专注于单个功能或修复
  • 如果添加新功能或更改用法，请更新README.md

行为准则

  • 尊重他人，包容他人
  • 提供建设性反馈
  • 帮助他人学习和成长

作者

Abhay Bhargav
安全审查。人工智能

MCP安全分析器由Abhay Bhargav在SecurityReview开发和维护。AI，专注于MCP服务器和应用程序的AI安全分析。

相关 MCP