# skill-scanner

> Scan skill files for malware using the VirusTotal API before they are installed. Use this skill AUTOMATICALLY whenever a new skill is created, uploaded, edited, added, installed, or otherwise introduced into the system — including skills generated by the skill-creator. Also trigger when the user explicitly asks to "scan a skill", "check a skill for malware", "virus scan", or "security check". Requires the VT_API_KEY environment variable. Supports a hybrid mode: if the BurtTheCoder/mcp-virustotal MCP server is connected, use its get_file_report tool for fast hash lookups before falling back to the script for unknown files.

- Author: Nate Ritter
- Repository: nateritter/skill-scanner
- Version: 20260205235939
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/nateritter/skill-scanner
- Web: https://mule.run/skillshub/@@nateritter/skill-scanner~skill-scanner:20260205235939

---

---
name: skill-scanner
description: >
  Scan skill files for malware using the VirusTotal API before they are installed.
  Use this skill AUTOMATICALLY whenever a new skill is created, uploaded, edited,
  added, installed, or otherwise introduced into the system — including skills
  generated by the skill-creator. Also trigger when the user explicitly asks to
  "scan a skill", "check a skill for malware", "virus scan", or "security check".
  Requires the VT_API_KEY environment variable. Supports a hybrid mode: if the
  BurtTheCoder/mcp-virustotal MCP server is connected, use its get_file_report
  tool for fast hash lookups before falling back to the script for unknown files.
---

# Skill Scanner

Scan every file in a skill directory against VirusTotal before it is trusted.

## When to Run

Run the scanner **every time** a skill is:
- Created (e.g. after `package_skill.py`)
- Uploaded by the user
- Edited or updated
- Downloaded or installed from any source

Do **not** skip the scan even if the skill was generated locally.

## Workflow: Hybrid (MCP + Script Fallback)

Choose the path based on what is available in the current environment.

### Path A — MCP Server Available (Claude Desktop / Claude Code)

If the `mcp-virustotal` MCP server is connected (the `get_file_report` tool is available):

1. For each file in the skill directory, compute its SHA-256 hash (use the script's hash helper or `shasum -a 256`).
2. Call the MCP tool `get_file_report` with `hash: "<sha256>"` for each file.
3. Interpret results:
   - If the report shows 0 malicious detections → file is **clean**.
   - If the report shows ≥1 malicious detection → **stop**, report to user.
   - If the file is **not found** in VT (no existing report) → fall back to Path B for that file only.

This path is faster and uses no upload quota for known files.

### Path B — Script Fallback (all platforms, including web/iOS)

Use when the MCP server is not connected, or for files unknown to VT.

1. Ensure `VT_API_KEY` is set in the environment. If missing, ask the user for their VirusTotal API key and export it.
2. Run the scanner script:

```bash
export VT_API_KEY="<key>"
python3 /mnt/skills/user/skill-scanner/scripts/scan_skill.py <skill-directory>
```

3. Interpret the JSON output:
   - `"passed": true` → Skill is clean. Proceed with installation or use.
   - `"passed": false` → **Stop immediately.** Report the flagged files with their verdicts and detection stats. Do not install or use the skill.
   - `"verdict": "pending"` → Analysis timed out. Inform the user and suggest re-running later or increasing `--wait`.

### Path C — Hybrid (recommended on Desktop/Code)

Combine both paths for best coverage:

1. Compute SHA-256 hashes for all files in the skill directory.
2. Batch-check hashes via MCP `get_file_report`.
3. For any file MCP reports as "not found", run the script with `--files` targeting only those unknown files:

```bash
python3 /mnt/skills/user/skill-scanner/scripts/scan_skill.py <file1> <file2> ...
```

4. Merge results. If any file is malicious from either source, block the skill.

## Script Options

| Flag | Default | Purpose |
|------|---------|---------|
| `--wait` | 120 | Max seconds to wait for VT analysis per file |
| `--threshold` | 1 | Minimum malicious detections to flag a file |

## How It Works

The script (`scripts/scan_skill.py`):
- Recursively collects all files in the skill directory (or accepts individual file paths)
- Computes SHA-256 hashes and checks VT for existing reports (avoids redundant uploads)
- Uploads unknown files to VT for fresh analysis
- Polls for results up to the `--wait` timeout
- Returns a JSON report with per-file verdicts and an overall pass/fail

## MCP Server Setup (Optional, for Desktop/Code)

Install the MCP server for hash-based lookups without uploading files:

```bash
npm install -g @burtthecoder/mcp-virustotal
```

Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "virustotal": {
      "command": "mcp-virustotal",
      "env": {
        "VIRUSTOTAL_API_KEY": "your-key-here"
      }
    }
  }
}
```

The API key is stored securely in this config file — no need to paste it per session.

## Rate Limits

Free VT API keys allow 4 requests per minute. For skills with many files, the scan may take several minutes. The MCP path is faster since hash lookups are lightweight. Consider `--wait 180` for larger skills using the script path.

## Handling Failures

- **No API key and no MCP**: Prompt the user to provide their VirusTotal API key or set up the MCP server.
- **Upload errors**: Report the specific file and error. Suggest the user check their API key or VT account status.
- **Timeouts**: Suggest re-running with a longer `--wait` or checking the VT website directly using the SHA-256 hash.
- **Malicious detections**: Show the user the file name, SHA-256, and detection stats. Do not proceed with the skill.