@gianmarcomaz/vantyr 1.0.0

package/bin/vantyr.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+run().catch((error) => {
+    console.error(`\nUnexpected error: ${error.message}\n`);
+    process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@gianmarcomaz/vantyr",
+  "version": "1.0.0",
+  "description": "MCP security scanner — Trust Score for AI dev environments. 100% local, zero telemetry.",
+  "author": "Gianmarco Mazzella",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gianmarcomaz/vantyr.git"
+  },
+  "homepage": "https://github.com/gianmarcomaz/vantyr#readme",
+  "bugs": {
+    "url": "https://github.com/gianmarcomaz/vantyr/issues"
+  },
+  "bin": {
+    "vantyr": "./bin/vantyr.js"
+  },
+  "main": "./bin/vantyr.js",
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "security",
+    "scanner",
+    "static-analysis",
+    "ai",
+    "llm",
+    "trust-score",
+    "cli",
+    "sarif",
+    "owasp",
+    "prompt-injection"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,148 @@
+import { Command } from 'commander';
+import { fetchRepoFiles } from './fetcher/github.js';
+import { discoverLocalFiles } from './config/localScanner.js';
+import { runAllChecks } from './scanner/index.js';
+import { calculateTrustScore } from './scoring/trustScore.js';
+import { printTerminalResult } from './output/terminal.js';
+import { formatJsonResult } from './output/json.js';
+import { formatSarifResult } from './output/sarif.js';
+import chalk from 'chalk';
+
+export async function run() {
+    const program = new Command();
+
+    program
+        .name('vantyr')
+        .description('MCP security scanner — Trust Score for AI dev environments. 100% local, zero telemetry.')
+        .version('1.0.0');
+
+    program.command('scan')
+        .argument('[url]', 'GitHub repository URL to scan')
+        .option('-l, --local', 'Discover local MCP configs and rules files')
+        .option('-t, --token <pat>', 'GitHub Personal Access Token for higher rate limits')
+        .option('-j, --json', 'Output results as JSON (suppresses all other output, for CI/CD pipelines)')
+        .option('-s, --sarif', 'Output results as SARIF 2.1.0 (for GitHub Code Scanning / upload-sarif action)')
+        .option('-v, --verbose', 'List every file that was scanned before showing results')
+        .action(async (url, options) => {
+            // --json and --sarif both emit structured data to stdout, so all
+            // progress/status console.log calls must be silenced for those modes.
+            const silent = !!(options.json || options.sarif);
+            const log = (msg) => { if (!silent) console.log(msg); };
+            const logErr = (msg) => {
+                if (silent) {
+                    console.log(JSON.stringify({ error: msg }));
+                } else {
+                    console.error(chalk.red(msg));
+                }
+            };
+
+            try {
+                let files = [];
+                let sourceUrl = '';
+
+                if (options.local) {
+                    log(chalk.dim('\nDiscovering local MCP config and rules files...'));
+                    files = discoverLocalFiles();
+                    sourceUrl = 'Local Configuration & Rules';
+
+                    if (files.length === 0) {
+                        if (options.sarif) {
+                            const empty = formatSarifResult(sourceUrl, { scoreData: null, noFiles: true });
+                            console.log(JSON.stringify(empty, null, 2));
+                        } else if (options.json) {
+                            console.log(JSON.stringify({
+                                source: sourceUrl,
+                                trustScore: null,
+                                label: 'NO_FILES',
+                                message: 'No local MCP configuration or rules files found. Looked in common locations like ~/.cursor/mcp.json, claude_desktop_config.json, etc.',
+                                findings: []
+                            }, null, 2));
+                        } else {
+                            log(chalk.yellow('\nNo local MCP configuration or rules files found.'));
+                            log(chalk.dim('Looked in common locations like ~/.cursor/mcp.json, claude_desktop_config.json, etc.'));
+                        }
+                        return;
+                    }
+                    log(chalk.green(`Found ${files.length} local configuration/rules files.`));
+                    if (options.verbose) {
+                        log('');
+                        log(chalk.dim('Files:'));
+                        for (const f of files) {
+                            log(chalk.dim(`  ${f.path}`));
+                        }
+                    }
+                    log('');
+                } else {
+                    if (!url) {
+                        throw new Error('Missing GitHub URL argument. Usage: vantyr scan <github-url>');
+                    }
+
+                    // Accept URLs with .git suffix or trailing paths (e.g. copied from browser)
+                    const normalizedUrl = url.replace(/\.git$/, '').replace(/\/(tree|blob)\/.*$/, '').replace(/\/$/, '');
+                    const REPO_URL_REGEX = /^https:\/\/github\.com\/([\w.-]+)\/([\w.-]+)$/;
+                    const match = normalizedUrl.match(REPO_URL_REGEX);
+
+                    if (!match) {
+                        throw new Error('Invalid GitHub URL. Please use the format: https://github.com/owner/repo');
+                    }
+
+                    const [, owner, repo] = match;
+                    sourceUrl = normalizedUrl;
+
+                    log(chalk.dim(`\nFetching repository files from GitHub (${owner}/${repo})...`));
+                    const fetchResult = await fetchRepoFiles(owner, repo, options.token);
+                    files = fetchResult.files;
+
+                    if (files.length === 0) {
+                        throw new Error('No scannable source files found in the repository. The repository may be empty or contain only unsupported file types.');
+                    }
+                    log(chalk.green(`Fetched ${files.length} files successfully.`));
+                    if (fetchResult.capped) {
+                        log(chalk.yellow(`   ⚠ Large repository: ${fetchResult.totalFound} eligible files found but only the first 100 were scanned. Results may not reflect the full codebase. Consider reviewing skipped files manually.`));
+                    }
+                    if (options.verbose) {
+                        log('');
+                        log(chalk.dim(`Files scanned (${files.length}):`));
+                        for (const f of files) {
+                            log(chalk.dim(`  ${f.path}`));
+                        }
+                    }
+                    log('');
+                }
+
+                // Run analyzers
+                const checks = runAllChecks(files);
+
+                // Calculate Trust Score
+                const scoreData = calculateTrustScore(checks);
+
+                // Output — mutually exclusive structured formats, terminal is default
+                if (options.sarif) {
+                    const result = formatSarifResult(sourceUrl, { scoreData });
+                    console.log(JSON.stringify(result, null, 2));
+                } else if (options.json) {
+                    const result = formatJsonResult(sourceUrl, { scoreData });
+                    console.log(JSON.stringify(result, null, 2));
+                } else {
+                    printTerminalResult(sourceUrl, { scoreData, checks });
+                }
+
+                // Exit Code (using process.exitCode to allow async drain)
+                if (scoreData.trustScore < 50) {
+                    process.exitCode = 1;
+                }
+
+            } catch (err) {
+                logErr(`\nError: ${err.message}\n`);
+                process.exitCode = 1;
+            }
+        });
+
+    // Parse arguments or show help
+    if (process.argv.length < 3) {
+        program.help();
+        return;
+    }
+
+    await program.parseAsync(process.argv);
+}

package/src/config/localScanner.js

@@ -0,0 +1,50 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+
+/**
+ * Discovers and reads local MCP configuration files and rule files.
+ * @returns {Array<{path: string, content: string}>}
+ */
+export function discoverLocalFiles() {
+    const homedir = os.homedir();
+    const cwd = process.cwd();
+    const isWindows = os.platform() === 'win32';
+    const appData = process.env.APPDATA || path.join(homedir, 'AppData', 'Roaming');
+
+    // 1. MCP Config locations
+    const configLocations = [
+        path.join(homedir, '.cursor', 'mcp.json'),
+        path.join(homedir, '.codeium', 'windsurf', 'mcp_config.json'),
+        isWindows 
+            ? path.join(appData, 'Claude', 'claude_desktop_config.json')
+            : path.join(homedir, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+        path.join(cwd, '.vscode', 'mcp.json'),
+        path.join(cwd, '.cursor', 'mcp.json')
+    ];
+
+    // 2. Rules files in current directory
+    const ruleFiles = [
+        '.cursorrules',
+        '.windsurfrules',
+        '.clinerules',
+        'CLAUDE.md',
+        'copilot-instructions.md'
+    ].map(f => path.join(cwd, f));
+
+    const allPaths = [...configLocations, ...ruleFiles];
+    const files = [];
+
+    for (const filePath of allPaths) {
+        try {
+            if (fs.existsSync(filePath)) {
+                const content = fs.readFileSync(filePath, 'utf-8');
+                files.push({ path: filePath, content });
+            }
+        } catch (err) {
+            // Silently skip unreadable files
+        }
+    }
+
+    return files;
+}

package/src/fetcher/github.js

@@ -0,0 +1,155 @@
+const ALLOWED_EXTENSIONS = new Set([
+    ".js", ".ts", ".jsx", ".tsx", ".py", ".go", ".rs",
+    ".json", ".yaml", ".yml", ".toml", ".env", ".md",
+]);
+
+const SKIP_DIRS = new Set([
+    "node_modules", ".git", "dist", "build", "vendor",
+    "__pycache__", ".next", ".nuxt", "coverage", ".venv",
+]);
+
+const MAX_FILE_SIZE = 100 * 1024; // 100KB
+
+/**
+ * Fetch the file tree and contents from a GitHub repository.
+ * @param {string} owner - Repo owner
+ * @param {string} repo - Repo name
+ * @param {string} token - Optional GitHub personal access token
+ * @returns {Promise<Array<{path: string, content: string}>>}
+ */
+export async function fetchRepoFiles(owner, repo, token) {
+    // 1. Get the default branch
+    const repoData = await githubGet(`/repos/${owner}/${repo}`, token);
+    const branch = repoData.default_branch || "main";
+
+    // 2. Get the recursive file tree
+    const treeData = await githubGet(
+        `/repos/${owner}/${repo}/git/trees/${branch}?recursive=1`,
+        token
+    );
+
+    if (!treeData.tree || !Array.isArray(treeData.tree)) {
+        throw new Error("Could not fetch repository file tree. Check that the repository exists and is accessible.");
+    }
+
+const REQUIRED_FILES = new Set([".gitignore", ".env", ".env.local"]);
+
+    // 3. Filter files
+    const filePaths = treeData.tree
+        .filter((item) => {
+            if (item.type !== "blob") return false;
+            if (item.size && item.size > MAX_FILE_SIZE) return false;
+
+            const filename = item.path.split("/").pop();
+            const isRequired = REQUIRED_FILES.has(filename);
+
+            // Check extension (if not explicitly required)
+            if (!isRequired) {
+                const ext = getExtension(item.path);
+                if (!ALLOWED_EXTENSIONS.has(ext)) return false;
+            }
+
+            // Check for skipped directories
+            const parts = item.path.split("/");
+            for (const part of parts) {
+                if (SKIP_DIRS.has(part)) return false;
+            }
+
+            return true;
+        })
+        .map((item) => item.path);
+
+    // 4. Fetch file contents (max 100 files to stay within timeout)
+    const FILE_LIMIT = 100;
+    const capped = filePaths.length > FILE_LIMIT;
+    const limitedPaths = filePaths.slice(0, FILE_LIMIT);
+    const files = [];
+
+    // Fetch in batches of 5 to respect rate limits
+    for (let i = 0; i < limitedPaths.length; i += 5) {
+        const batch = limitedPaths.slice(i, i + 5);
+        const results = await Promise.all(
+            batch.map(async (path) => {
+                try {
+                    const data = await githubGet(
+                        `/repos/${owner}/${repo}/contents/${encodeURIComponent(path)}?ref=${branch}`,
+                        token
+                    );
+                    if (data.encoding === "base64" && data.content) {
+                        const content = Buffer.from(data.content, "base64").toString("utf-8");
+                        return { path, content };
+                    }
+                    return null;
+                } catch (err) {
+                    return null;
+                }
+            })
+        );
+        files.push(...results.filter(Boolean));
+    }
+
+    return { files, capped, totalFound: filePaths.length };
+}
+
+/**
+ * Make a GET request to the GitHub API using native fetch.
+ */
+async function githubGet(path, token) {
+    const headers = {
+        "User-Agent": "MCP-Certify/1.0",
+        "Accept": "application/vnd.github.v3+json",
+    };
+    
+    if (token) {
+        headers["Authorization"] = `Bearer ${token}`;
+    }
+
+    const url = `https://api.github.com${path}`;
+    
+    try {
+        const response = await fetch(url, { headers });
+
+        if (!response.ok) {
+            if (response.status === 404) {
+                // Determine if it was a repo 404 or a file 404
+                const isRepoPath = path.startsWith('/repos/') && !path.includes('/contents/') && !path.includes('/git/trees/');
+                if (isRepoPath) {
+                    const parts = path.split('/');
+                    throw new Error(`Repository not found: ${parts[2]}/${parts[3]}. Check that the URL is correct and the repository is public.`);
+                }
+                throw new Error(`GitHub API error 404: Not Found (${path})`);
+            }
+            
+            if (response.status === 403 || response.status === 429) {
+                const limit = response.headers.get("x-ratelimit-limit");
+                const remaining = response.headers.get("x-ratelimit-remaining");
+                
+                if (remaining === "0") {
+                    throw new Error(`GitHub API rate limit exceeded (${limit} req/hr). Use the --token <github-pat> flag for authenticated access (5000 req/hr). Generate a token at: https://github.com/settings/tokens`);
+                }
+                
+                const data = await response.json().catch(() => ({}));
+                if (data.message?.toLowerCase().includes('private')) {
+                    throw new Error('Repository is private or requires authentication. Use --token <github-pat> to access private repositories.');
+                }
+                
+                throw new Error(`GitHub API error ${response.status}: ${data.message || 'Forbidden'}`);
+            }
+            
+            const body = await response.text().catch(() => '');
+            throw new Error(`GitHub API error ${response.status}: ${body.slice(0, 300) || response.statusText}`);
+        }
+
+        return response.json();
+    } catch (err) {
+        if (err.code === 'ENOTFOUND' || err.code === 'ECONNREFUSED') {
+            throw new Error('Could not connect to GitHub API. Check your internet connection.');
+        }
+        throw err;
+    }
+}
+
+function getExtension(filePath) {
+    const dot = filePath.lastIndexOf(".");
+    return dot >= 0 ? filePath.slice(dot) : "";
+}

package/src/output/json.js

@@ -0,0 +1,64 @@
+/**
+ * JSON output formatter for vantyr.
+ * Produces a stable, machine-readable structure suitable for CI/CD pipelines,
+ * dashboards, or downstream tooling.
+ */
+
+const CATEGORY_NAMES = {
+    NE: 'Network Exposure',
+    CI: 'Command Injection',
+    CL: 'Credential Leaks',
+    TP: 'Tool Poisoning',
+    SC: 'Spec Compliance',
+    IV: 'Input Validation',
+};
+
+/**
+ * @param {string} sourceUrl
+ * @param {{ scoreData: object }} results
+ * @returns {object}
+ */
+export function formatJsonResult(sourceUrl, { scoreData }) {
+    const { trustScore, categories, totalFindings, stats, passCount, scoreCapped } = scoreData;
+
+    let label = 'CERTIFIED';
+    if (trustScore < 50) label = 'FAILED';
+    else if (trustScore < 80) label = 'WARNING';
+
+    // Flatten all findings into a single array with category metadata attached
+    const allFindings = Object.entries(categories).flatMap(([key, cat]) =>
+        cat.findings.map(f => ({
+            category: key,
+            categoryName: CATEGORY_NAMES[key] || key,
+            severity: f.severity,
+            file: f.file || null,
+            line: f.line || null,
+            snippet: f.snippet || '',
+            message: f.message || '',
+            remediation: f.remediation || '',
+        }))
+    );
+
+    return {
+        source: sourceUrl,
+        trustScore,
+        label,
+        scoreCapped: scoreCapped || false,
+        categories: Object.fromEntries(
+            Object.entries(categories).map(([key, cat]) => [
+                key,
+                {
+                    name: CATEGORY_NAMES[key] || key,
+                    score: cat.score,
+                    passed: cat.score >= 80,
+                    findingCount: cat.findings.length,
+                    findings: cat.findings,
+                },
+            ])
+        ),
+        stats,
+        passCount,
+        totalFindings,
+        findings: allFindings,
+    };
+}