glyph-scan 0.1.0__tar.gz

glyph_scan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Haseeb Khalid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

glyph_scan-0.1.0/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: glyph-scan
+Version: 0.1.0
+Summary: MCP security scanner — read the runes before your agent steps on them — find vulnerabilities in AI agent tool configurations
+Author-email: Haseeb Khalid <haseebkhalid1507@gmail.com>
+License: MIT
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: click>=8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file

glyph_scan-0.1.0/README.md

@@ -0,0 +1,204 @@
+# 🔮 Glyph
+
+**Read the runes before your agent steps on them.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Tests](https://img.shields.io/badge/tests-45%20passing-brightgreen.svg)]()
+
+An MCP security scanner that finds tool poisoning, credential leaks, and insecure transports in your AI agent configurations — before attackers do.
+
+---
+
+## The Problem
+
+MCP (Model Context Protocol) is how AI agents connect to tools. Claude Desktop, Cursor, pi, Windsurf — they all use it. There are now **16,000+ MCP servers** in the ecosystem.
+
+[66% of them have security findings.](https://agentseal.org/blog/mcp-server-security-findings)
+
+Tool poisoning — hiding malicious instructions in tool descriptions — has a **91% success rate** against production AI agents. The [first malicious MCP server](https://semgrep.dev/blog/2025/so-the-first-malicious-mcp-server-has-been-found-on-npm-what-does-this-mean-for-mcp-security/) was found on npm in September 2025, silently BCC'ing every email to an attacker.
+
+Nobody audits these servers before connecting. Glyph does.
+
+---
+
+## What It Does
+
+🔴 **Tool Poisoning Detection** — Finds hidden instructions, prompt injection, unicode tricks, base64 payloads, and behavioral directives buried in tool descriptions
+
+🔴 **Credential Exposure** — Catches hardcoded API keys (OpenAI, AWS, GitHub, Anthropic), tokens, and secrets that should be in environment variables
+
+🟡 **Transport Security** — Flags MCP servers running over plain HTTP, missing TLS, or lacking authentication
+
+🔵 **Live Scanning** — Connects to real MCP servers via JSON-RPC, pulls actual tool definitions, and scans them in real time
+
+---
+
+## Quick Start
+
+```bash
+pip install glyph
+```
+
+Scan a config file:
+```bash
+glyph scan ~/.config/claude/claude_desktop_config.json
+```
+
+That's it. Results in seconds.
+
+---
+
+## Usage
+
+### Static Scan — Check Config Files
+
+```bash
+# Scan a single config
+glyph scan config.json
+
+# Scan a directory (finds all .json files)
+glyph scan ~/.config/claude/
+
+# JSON output for CI/CD
+glyph scan config.json --format json
+
+# Only show high severity and above
+glyph scan config.json --severity high
+```
+
+### Live Scan — Connect to Real Servers
+
+```bash
+# Connect to servers defined in config, pull live tool definitions, scan
+glyph live config.json
+
+# Custom timeout for slow server startups
+glyph live config.json --timeout 60
+```
+
+Live scanning spawns each stdio server, performs the MCP handshake, requests tool definitions via `tools/list`, scans the actual descriptions, then terminates the connection. No tools are executed — just inspected.
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Clean — no findings |
+| `1` | Findings detected |
+| `2` | Critical findings detected |
+
+Use in CI: `glyph scan config.json || echo "Security issues found"`
+
+---
+
+## Detection Rules
+
+| Rule | Severity | What It Catches |
+|------|----------|----------------|
+| `tool-poisoning` | 🔴 CRITICAL/HIGH | Hidden instructions in tool descriptions, prompt injection patterns, unicode obfuscation, base64 payloads, system prompt overrides, excessive description length |
+| `credential-exposure` | 🔴 CRITICAL | Hardcoded OpenAI, AWS, GitHub, Anthropic keys and tokens. Allows env var references (`${VAR}`) |
+| `transport-security` | 🟡 HIGH/MEDIUM | HTTP without TLS, SSE without encryption, network transports missing authentication |
+
+---
+
+## Example Output
+
+```
+🔒 Glyph — MCP Security Scanner
+
+Scanning: config.json
+Found 3 servers
+
+━━━ Findings ━━━
+
+🔴 CRITICAL: Hardcoded OpenAI API Key
+   Rule: credential-exposure
+   Location: server "gpt-tools"
+   Fix: Use environment variable reference ${OPENAI_API_KEY} instead
+
+🟡 HIGH: Potential tool poisoning detected
+   Rule: tool-poisoning
+   Location: tool "email_helper" in server "utils"
+   Fix: Review tool description for hidden instructions
+
+🟡 HIGH: Insecure transport
+   Rule: transport-security
+   Location: server "remote-api"
+   Fix: Use HTTPS instead of HTTP
+
+━━━ Summary ━━━
+Scanned: 1 config, 3 servers
+Findings: 1 critical, 2 high, 0 medium, 0 low
+Status: FAIL (CRITICAL)
+```
+
+---
+
+## How Live Scanning Works
+
+Glyph implements a minimal MCP client that performs the standard JSON-RPC handshake:
+
+```
+Glyph → Server:  initialize (identify as scanner)
+Server → Glyph:  capabilities + server info
+
+Glyph → Server:  tools/list (enumerate all tools)  
+Server → Glyph:  tool definitions (name, description, schema)
+
+Glyph:            Scan descriptions → Report findings → Disconnect
+```
+
+No tools are invoked. Glyph only inspects definitions — it never executes tool calls.
+
+---
+
+## Roadmap
+
+- [ ] **Permission Audit Rule** — Flag dangerous capability combinations (filesystem + network = exfiltration risk)
+- [ ] **Supply Chain Rule** — Detect typosquatting and known malicious MCP packages
+- [ ] **Semantic Analysis** — Sentence embeddings to catch sophisticated poisoning that bypasses pattern matching
+- [ ] **LLM Classification** — Optional deep analysis using LLM for context-aware threat detection
+- [ ] **GitHub Action** — `glyph-action` for CI/CD pipeline integration
+- [ ] **SARIF Output** — Standard format for security tool integration
+- [ ] **SSE/HTTP Transport** — Live scanning for network-based MCP servers
+- [ ] **MCP Server Mode** — Run Glyph itself as an MCP server so AI agents can scan their own configs
+
+---
+
+## ⚠️ Security Notice
+
+Glyph's live scanning spawns MCP servers defined in config files. **A malicious config can contain arbitrary commands.** Only scan configs you trust, or run Glyph inside a container/sandbox:
+
+```bash
+# Sandboxed scan (recommended for untrusted configs)
+docker run --rm -v $(pwd)/config.json:/scan/config.json glyph scan /scan/config.json
+```
+
+Static scanning (`glyph scan`) only reads JSON files — no code execution. Live scanning (`glyph live`) spawns processes. Know the difference.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/HaseebKhalid1507/glyph.git
+cd glyph
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+---
+
+## Contributing
+
+Issues and PRs welcome. If you find a new MCP attack pattern, open an issue.
+
+---
+
+## Author
+
+Built by [Haseeb Khalid](https://github.com/HaseebKhalid1507) — security engineer, agent builder, rune reader.
+
+## License
+
+MIT

glyph_scan-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project]
+name = "glyph-scan"
+version = "0.1.0"
+description = "MCP security scanner — read the runes before your agent steps on them — find vulnerabilities in AI agent tool configurations"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "Haseeb Khalid", email = "haseebkhalid1507@gmail.com"}]
+dependencies = ["click>=8.0"]
+
+[project.scripts]
+glyph = "glyph.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

glyph_scan-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

glyph_scan-0.1.0/src/glyph/__init__.py

@@ -0,0 +1,3 @@
+"""Glyph — MCP Security Scanner"""
+
+__version__ = "0.1.0"

glyph_scan-0.1.0/src/glyph/cli.py

@@ -0,0 +1,277 @@
+"""Glyph CLI interface."""
+import sys
+import json
+from pathlib import Path
+import click
+
+from .engine.analyzer import AnalysisEngine
+from .reporter.human import HumanReporter
+from .reporter.json_report import JsonReporter
+from .parser.claude import ClaudeDesktopParser
+from .rules.tool_poisoning import ToolPoisoningRule
+from .rules.credential_exposure import CredentialExposureRule
+from .rules.transport_security import TransportSecurityRule
+from .models.finding import Severity
+from .models.config import Tool, TransportType
+from .connector.stdio import StdioConnector
+
+
+def get_all_rules():
+    """Get all available security rules."""
+    return [
+        ToolPoisoningRule(),
+        CredentialExposureRule(),
+        TransportSecurityRule()
+    ]
+
+
+def discover_configs(target_path: Path) -> list[Path]:
+    """Discover MCP config files in target path."""
+    if target_path.is_file():
+        return [target_path]
+    elif target_path.is_dir():
+        # Find all JSON files in directory
+        json_files = []
+        for pattern in ["*.json"]:
+            json_files.extend(target_path.glob(pattern))
+        return sorted(json_files)
+    else:
+        return []
+
+
+def parse_config_file(file_path: Path):
+    """Parse a configuration file, auto-detecting format."""
+    # For now we only support Claude Desktop format
+    parser = ClaudeDesktopParser()
+    return parser.parse_file(file_path)
+
+
+def filter_by_severity(results, min_severity: Severity):
+    """Filter scan results to only include findings of minimum severity or higher."""
+    filtered_results = []
+    
+    for result in results:
+        filtered_findings = [
+            f for f in result.findings 
+            if f.severity >= min_severity
+        ]
+        
+        # Create new result with filtered findings
+        from .models.result import ScanResult
+        filtered_result = ScanResult(
+            config=result.config,
+            findings=filtered_findings,
+            rules_applied=result.rules_applied,
+            scan_time=result.scan_time
+        )
+        filtered_results.append(filtered_result)
+    
+    return filtered_results
+
+
+@click.group()
+def cli():
+    """Glyph — MCP Security Scanner"""
+    pass
+
+
+@cli.command()
+@click.argument('target', type=click.Path(exists=True, path_type=Path))
+@click.option('--format', 'output_format', 
+              type=click.Choice(['human', 'json'], case_sensitive=False),
+              default='human',
+              help='Output format (default: human)')
+@click.option('--severity',
+              type=click.Choice(['critical', 'high', 'medium', 'low', 'info'], case_sensitive=False),
+              help='Only show findings of this severity or higher')
+def scan(target, output_format, severity):
+    """Scan MCP configuration files for security issues."""
+    
+    # Parse severity filter if provided
+    min_severity = None
+    if severity:
+        min_severity = Severity(severity.lower())
+    
+    # Discover config files
+    config_files = discover_configs(target)
+    if not config_files:
+        click.echo(f"Error: No configuration files found in {target}", err=True)
+        sys.exit(2)
+    
+    # Parse configurations
+    configs = []
+    for file_path in config_files:
+        try:
+            config = parse_config_file(file_path)
+            if config:
+                configs.append(config)
+            else:
+                click.echo(f"Warning: Could not parse {file_path}", err=True)
+        except Exception as e:
+            click.echo(f"Error parsing {file_path}: {e}", err=True)
+            continue
+    
+    if not configs:
+        click.echo("Error: No valid configuration files found", err=True)
+        sys.exit(2)
+    
+    # Run analysis
+    rules = get_all_rules()
+    engine = AnalysisEngine(rules)
+    results = engine.analyze_all(configs)
+    
+    # Apply severity filter if specified
+    if min_severity:
+        results = filter_by_severity(results, min_severity)
+    
+    # Generate report
+    if output_format.lower() == 'json':
+        reporter = JsonReporter()
+        report = reporter.generate(results)
+        click.echo(report)
+        
+        # Extract exit code from JSON report for proper CLI behavior
+        try:
+            report_data = json.loads(report)
+            exit_code = report_data.get('summary', {}).get('exit_code', 0)
+            sys.exit(exit_code)
+        except:
+            sys.exit(0)
+    else:
+        reporter = HumanReporter()
+        report = reporter.generate(results)
+        click.echo(report)
+        
+        # Determine exit code from findings
+        has_critical = any(
+            f.severity == Severity.CRITICAL 
+            for result in results 
+            for f in result.findings
+        )
+        has_findings = any(result.findings for result in results)
+        
+        if has_critical:
+            sys.exit(2)
+        elif has_findings:
+            sys.exit(1)
+        else:
+            sys.exit(0)
+
+
+@cli.command()
+@click.argument('config_file', type=click.Path(exists=True, path_type=Path))
+@click.option('--format', 'output_format', 
+              type=click.Choice(['human', 'json'], case_sensitive=False),
+              default='human',
+              help='Output format (default: human)')
+@click.option('--timeout', 
+              default=30,
+              help='Timeout in seconds for server connections (default: 30)')
+@click.option('--severity',
+              type=click.Choice(['critical', 'high', 'medium', 'low', 'info'], case_sensitive=False),
+              help='Only show findings of this severity or higher')
+def live(config_file, output_format, timeout, severity):
+    """Connect to MCP servers and scan with live tool definitions."""
+    
+    # Parse severity filter if provided
+    min_severity = None
+    if severity:
+        min_severity = Severity(severity.lower())
+    
+    # Parse the config file
+    try:
+        config = parse_config_file(config_file)
+        if not config:
+            click.echo(f"Error: Could not parse {config_file}", err=True)
+            sys.exit(2)
+    except Exception as e:
+        click.echo(f"Error parsing {config_file}: {e}", err=True)
+        sys.exit(2)
+    
+    # Connect to stdio servers and pull live tools
+    live_servers = []
+    for server in config.servers:
+        if server.transport.type == TransportType.STDIO:
+            if not server.transport.command:
+                click.echo(f"Warning: Server '{server.name}' has stdio transport but no command", err=True)
+                continue
+            
+            # Prepare command with args
+            command = server.transport.command.copy() if server.transport.command else []
+            if server.transport.args:
+                command.extend(server.transport.args)
+            
+            click.echo(f"Connecting to {server.name}...")
+            try:
+                connector = StdioConnector(command, env=server.env_vars, timeout=timeout)
+                raw_tools = connector.connect()
+                
+                # Convert raw tools to Tool objects
+                tools = []
+                for raw_tool in raw_tools:
+                    tool = Tool(
+                        name=raw_tool.get("name", "unknown"),
+                        description=raw_tool.get("description", ""),
+                        server_name=server.name,
+                        schema=raw_tool.get("inputSchema", {})
+                    )
+                    tools.append(tool)
+                
+                # Update server with live tools
+                server.tools = tools
+                click.echo(f"✓ Connected to {server.name}, pulled {len(tools)} tools")
+                
+            except Exception as e:
+                click.echo(f"Warning: Failed to connect to {server.name}: {e}", err=True)
+                # Continue with next server
+        
+        live_servers.append(server)
+    
+    # Update config with enriched servers
+    config.servers = live_servers
+    
+    # Run analysis on the enriched config
+    rules = get_all_rules()
+    engine = AnalysisEngine(rules)
+    results = [engine.analyze(config)]
+    
+    # Apply severity filter if specified
+    if min_severity:
+        results = filter_by_severity(results, min_severity)
+    
+    # Generate report
+    if output_format.lower() == 'json':
+        reporter = JsonReporter()
+        report = reporter.generate(results)
+        click.echo(report)
+        
+        # Extract exit code from JSON report for proper CLI behavior
+        try:
+            report_data = json.loads(report)
+            exit_code = report_data.get('summary', {}).get('exit_code', 0)
+            sys.exit(exit_code)
+        except:
+            sys.exit(0)
+    else:
+        reporter = HumanReporter()
+        report = reporter.generate(results)
+        click.echo(report)
+        
+        # Determine exit code from findings
+        has_critical = any(
+            f.severity == Severity.CRITICAL 
+            for result in results 
+            for f in result.findings
+        )
+        has_findings = any(result.findings for result in results)
+        
+        if has_critical:
+            sys.exit(2)
+        elif has_findings:
+            sys.exit(1)
+        else:
+            sys.exit(0)
+
+
+if __name__ == "__main__":
+    cli()

glyph_scan-0.1.0/src/glyph/connector/__init__.py

@@ -0,0 +1 @@
+"""MCP server connectors."""