|
|
--- |
|
|
title: Vulnerability Scanner MCP Server |
|
|
emoji: 🦀 |
|
|
colorFrom: pink |
|
|
colorTo: yellow |
|
|
sdk: gradio |
|
|
sdk_version: 5.49.0 |
|
|
app_file: app.py |
|
|
pinned: false |
|
|
--- |
|
|
|
|
|
Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference |
|
|
|
|
|
# Vulnerability Scanner MCP Server |
|
|
|
|
|
This repository contains a small Gradio-based MCP server that provides three tools to inspect GitHub repositories using the GitHub REST API: |
|
|
|
|
|
- Get basic repository information |
|
|
- Retrieve the decoded content of a single file |
|
|
- Scan a repository for source code files with specific extensions (returns a list of file paths) |
|
|
|
|
|
The application is implemented in `app.py` and exposes a Gradio TabbedInterface with three API endpoints: `get_repository_info`, `get_file_content`, and `scan_repository`. |
|
|
|
|
|
## Requirements |
|
|
|
|
|
The project uses Python and the dependencies listed in `requirements.txt`. Key requirements used by the app are: |
|
|
|
|
|
- gradio (with mcp support) |
|
|
- requests |
|
|
- python-dotenv |
|
|
|
|
|
On Windows with PowerShell, create a virtual environment and install requirements: |
|
|
|
|
|
```powershell |
|
|
python -m venv .venv; .\.venv\Scripts\Activate.ps1; pip install -r requirements.txt |
|
|
``` |
|
|
|
|
|
If you prefer cmd.exe use: |
|
|
|
|
|
```cmd |
|
|
python -m venv .venv && .\.venv\Scripts\activate.bat && pip install -r requirements.txt |
|
|
``` |
|
|
|
|
|
## Environment variables |
|
|
|
|
|
The application requires a GitHub personal access token to access the GitHub API. Create a `.env` file in the project root with the following variable: |
|
|
|
|
|
``` |
|
|
GITHUB_TOKEN=ghp_...your_token_here |
|
|
``` |
|
|
|
|
|
The token must have permission to read the repositories you want to inspect (public repos are readable with a token that has no special scopes; private repos require appropriate scopes). |
|
|
|
|
|
## Running the server |
|
|
|
|
|
Start the app directly with Python. The Gradio interface will launch and expose the MCP API endpoints: |
|
|
|
|
|
```powershell |
|
|
python app.py |
|
|
``` |
|
|
|
|
|
When run, the app prints startup information and launches Gradio in MCP server mode. By default Gradio will open a local web UI and also expose the MCP API endpoints used by other MCP clients. |
|
|
|
|
|
## Endpoints and usage |
|
|
|
|
|
The Gradio interface exposes three tools (functions) via the MCP server and also as interactive UI tabs: |
|
|
|
|
|
1) get_repository_info |
|
|
|
|
|
Inputs: |
|
|
- Repository Owner (e.g. `octocat`) |
|
|
- Repository Name (e.g. `Hello-World`) |
|
|
|
|
|
Output: A JSON-like text block containing repository metadata (name, full_name, description, primary_language, size_kb, stars, forks, default_branch, created_date, last_updated, is_private, clone_url). |
|
|
|
|
|
2) get_file_content |
|
|
|
|
|
Inputs: |
|
|
- Repository Owner |
|
|
- Repository Name |
|
|
- File Path (e.g. `README.md`) |
|
|
|
|
|
Output: Decoded file contents as plain text. If the file is binary or cannot be decoded, an error message is returned. |
|
|
|
|
|
3) scan_repository |
|
|
|
|
|
Inputs: |
|
|
- Repository Owner |
|
|
- Repository Name |
|
|
- File Extensions (comma-separated, default: `.py,.js,.ts,.php,.java`) |
|
|
|
|
|
Output: A list of file paths (limited to the first 50 matching files) found in the repository with the given extensions. |
|
|
|
|
|
Notes and edge-cases: |
|
|
|
|
|
- The code uses the GitHub REST API and will return HTTP error messages when repositories or files are not found or when the token lacks permissions. |
|
|
- `get_file_content` decodes base64 file content returned by the GitHub API and will return an error string for binary files. |
|
|
- `scan_repository` recursively traverses directories and limits results to avoid returning extremely large listings. |
|
|
|
|
|
## Example |
|
|
|
|
|
After starting the server, open the Gradio UI. From the UI you can call the three tools. Example programmatic calls are possible via the Gradio API endpoints; however this README focuses on interactive use through the launched UI (the functions are registered with `api_name` values matching their function names). |
|
|
|
|
|
## Development notes |
|
|
|
|
|
- The GitHub token is mandatory; the application raises ValueError if `GITHUB_TOKEN` is not present in the environment. |
|
|
- The app limits recursion results to avoid deep scans; adjust `_scan_directory_sync` if you need more files or different limits. |
|
|
|
|
|
## License |
|
|
|
|
|
This project does not include a license file in the repository. Add a LICENSE if you plan to publish or share this code. |
|
|
|
