shieldbot-mcp 1.0.0__tar.gz

shieldbot_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: shieldbot-mcp
+Version: 1.0.0
+Summary: AI-powered security code review MCP server for Claude Code — combines Semgrep (5,000+ rules), bandit, detect-secrets, pip-audit, and npm-audit
+Project-URL: Homepage, https://github.com/BalaSriharsha/shieldbot
+Project-URL: Repository, https://github.com/BalaSriharsha/shieldbot
+Project-URL: Bug Tracker, https://github.com/BalaSriharsha/shieldbot/issues
+License: MIT
+Keywords: anthropic,claude,code-review,mcp,sast,security,semgrep,vulnerability
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: bandit>=1.7.0
+Requires-Dist: detect-secrets>=1.4.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pip-audit>=2.6.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: ruff>=0.1.0
+Requires-Dist: semgrep>=1.50.0
+Provides-Extra: dev
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# shieldbot-mcp
+
+AI-powered security code review MCP server for Claude Code.
+
+Combines **Semgrep (5,000+ rules)**, bandit, ruff, detect-secrets, pip-audit, and npm-audit with Claude's security expertise to deliver prioritized, actionable security reports.
+
+## Install
+
+```bash
+pip install shieldbot-mcp
+```
+
+Or run directly via `uvx` (recommended for MCP):
+```bash
+uvx shieldbot-mcp
+```
+
+## Usage with Claude Code
+
+Install the plugin:
+```
+/plugin install shieldbot
+```
+
+Then ask Claude naturally:
+- *"scan this repo for security issues"*
+- *"check for hardcoded secrets"*
+- *"audit my dependencies for CVEs"*
+
+Or use the slash command:
+```
+/shieldbot-scan .
+/shieldbot-scan /path/to/repo --min-severity high
+/shieldbot-scan . --git-history
+```
+
+## MCP tools exposed
+
+| Tool | Description |
+|------|-------------|
+| `scan_repository` | Full parallel security scan → JSON report |
+| `check_scanner_tools` | Check which scanners are installed |
+
+## Add to any MCP client
+
+```json
+{
+  "mcpServers": {
+    "shieldbot": {
+      "command": "uvx",
+      "args": ["shieldbot-mcp"]
+    }
+  }
+}
+```
+
+## Scanners
+
+| Scanner | Coverage |
+|---------|---------|
+| Semgrep 5,000+ rules | OWASP Top 10, CWE Top 25, injection, XSS, SSRF, taint |
+| bandit | Python security |
+| ruff | Python quality + security |
+| detect-secrets | API keys, passwords, tokens |
+| pip-audit | Python CVEs (PyPI Advisory DB) |
+| npm audit | Node.js CVEs |
+
+## Publish to PyPI
+
+```bash
+pip install hatchling build twine
+python -m build
+twine upload dist/*
+```
+
+## License
+
+MIT

shieldbot_mcp-1.0.0/README.md

@@ -0,0 +1,78 @@
+# shieldbot-mcp
+
+AI-powered security code review MCP server for Claude Code.
+
+Combines **Semgrep (5,000+ rules)**, bandit, ruff, detect-secrets, pip-audit, and npm-audit with Claude's security expertise to deliver prioritized, actionable security reports.
+
+## Install
+
+```bash
+pip install shieldbot-mcp
+```
+
+Or run directly via `uvx` (recommended for MCP):
+```bash
+uvx shieldbot-mcp
+```
+
+## Usage with Claude Code
+
+Install the plugin:
+```
+/plugin install shieldbot
+```
+
+Then ask Claude naturally:
+- *"scan this repo for security issues"*
+- *"check for hardcoded secrets"*
+- *"audit my dependencies for CVEs"*
+
+Or use the slash command:
+```
+/shieldbot-scan .
+/shieldbot-scan /path/to/repo --min-severity high
+/shieldbot-scan . --git-history
+```
+
+## MCP tools exposed
+
+| Tool | Description |
+|------|-------------|
+| `scan_repository` | Full parallel security scan → JSON report |
+| `check_scanner_tools` | Check which scanners are installed |
+
+## Add to any MCP client
+
+```json
+{
+  "mcpServers": {
+    "shieldbot": {
+      "command": "uvx",
+      "args": ["shieldbot-mcp"]
+    }
+  }
+}
+```
+
+## Scanners
+
+| Scanner | Coverage |
+|---------|---------|
+| Semgrep 5,000+ rules | OWASP Top 10, CWE Top 25, injection, XSS, SSRF, taint |
+| bandit | Python security |
+| ruff | Python quality + security |
+| detect-secrets | API keys, passwords, tokens |
+| pip-audit | Python CVEs (PyPI Advisory DB) |
+| npm audit | Node.js CVEs |
+
+## Publish to PyPI
+
+```bash
+pip install hatchling build twine
+python -m build
+twine upload dist/*
+```
+
+## License
+
+MIT

shieldbot_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "shieldbot-mcp"
+version = "1.0.0"
+description = "AI-powered security code review MCP server for Claude Code — combines Semgrep (5,000+ rules), bandit, detect-secrets, pip-audit, and npm-audit"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+keywords = ["security", "mcp", "code-review", "sast", "claude", "anthropic", "semgrep", "vulnerability"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Topic :: Security",
+    "Topic :: Software Development :: Quality Assurance",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "pydantic>=2.0.0",
+    "jinja2>=3.0.0",
+    "anyio>=4.0.0",
+    "GitPython>=3.1.0",
+    # Scanners (installed separately or via extras)
+    "semgrep>=1.50.0",
+    "bandit>=1.7.0",
+    "ruff>=0.1.0",
+    "detect-secrets>=1.4.0",
+    "pip-audit>=2.6.0",
+]
+
+[project.optional-dependencies]
+dev = ["hatchling", "pytest", "pytest-asyncio"]
+
+[project.scripts]
+shieldbot-mcp = "shieldbot.server:main"
+
+[project.urls]
+Homepage = "https://github.com/BalaSriharsha/shieldbot"
+Repository = "https://github.com/BalaSriharsha/shieldbot"
+"Bug Tracker" = "https://github.com/BalaSriharsha/shieldbot/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["shieldbot"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/shieldbot",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]

shieldbot_mcp-1.0.0/shieldbot/__init__.py

@@ -0,0 +1,3 @@
+"""Shieldbot - Security scanner for the Claude Code agent."""
+
+__version__ = "1.0.0"

shieldbot_mcp-1.0.0/shieldbot/config.py

@@ -0,0 +1,61 @@
+"""Configuration constants for shieldbot."""
+
+from __future__ import annotations
+
+# Claude model to use
+CLAUDE_MODEL = "claude-sonnet-4-6"
+
+# Semgrep rulesets always applied regardless of detected language
+SEMGREP_ALWAYS_RULESETS = [
+    "p/owasp-top-ten",
+    "p/secrets",
+    "p/cwe-top-25",
+    "p/sql-injection",
+    "p/command-injection",
+    "p/ssrf",
+]
+
+# Additional rulesets keyed by detected language
+SEMGREP_LANGUAGE_RULESETS: dict[str, list[str]] = {
+    "python": ["p/security-audit", "p/python", "p/django", "p/flask", "p/bandit"],
+    "javascript": ["p/security-audit", "p/javascript", "p/react", "p/express", "p/xss"],
+    "typescript": ["p/security-audit", "p/typescript", "p/react"],
+    "java": ["p/security-audit", "p/java"],
+    "go": ["p/security-audit", "p/go"],
+    "ruby": ["p/security-audit", "p/ruby", "p/rails"],
+    "php": ["p/security-audit", "p/php"],
+    "kotlin": ["p/security-audit"],
+    "scala": ["p/security-audit"],
+    "c": ["p/security-audit"],
+    "cpp": ["p/security-audit"],
+    "csharp": ["p/security-audit"],
+    "rust": ["p/security-audit"],
+}
+
+# Scanner priority for deduplication (lower = higher priority, keeps its data)
+SCANNER_PRIORITY: dict[str, int] = {
+    "semgrep": 0,
+    "bandit": 1,
+    "ruff": 2,
+    "detect-secrets": 3,
+    "gitleaks": 3,
+    "pip-audit": 4,
+    "npm-audit": 4,
+}
+
+# Semgrep subprocess settings
+SEMGREP_TIMEOUT_PER_FILE = 300   # seconds
+SEMGREP_MAX_MEMORY_MB = 2000
+SEMGREP_JOBS = 4
+SEMGREP_OVERALL_TIMEOUT = 600    # 10 minutes total
+
+# Scanners that are optional (warn but don't fail if missing)
+OPTIONAL_SCANNERS = {"ruff", "gitleaks"}
+
+# Max lines of code snippet to store per finding
+MAX_SNIPPET_LINES = 10
+
+# Severity thresholds for exit codes
+EXIT_CODE_MEDIUM = 1
+EXIT_CODE_HIGH = 2
+EXIT_CODE_CRITICAL = 3

shieldbot_mcp-1.0.0/shieldbot/models.py

@@ -0,0 +1,108 @@
+"""Pydantic data models for shieldbot security findings and reports."""
+
+from __future__ import annotations
+
+import hashlib
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+
+class Severity(str, Enum):
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+SEVERITY_ORDER = {
+    Severity.CRITICAL: 0,
+    Severity.HIGH: 1,
+    Severity.MEDIUM: 2,
+    Severity.LOW: 3,
+    Severity.INFO: 4,
+}
+
+
+class FindingCategory(str, Enum):
+    INJECTION = "injection"
+    SECRETS = "secrets"
+    CRYPTOGRAPHY = "cryptography"
+    AUTHENTICATION = "authentication"
+    ACCESS_CONTROL = "access_control"
+    DEPENDENCY_CVE = "dependency_cve"
+    DESERIALIZATION = "deserialization"
+    PATH_TRAVERSAL = "path_traversal"
+    XSS = "xss"
+    SSRF = "ssrf"
+    CODE_QUALITY = "code_quality"
+    MISCONFIGURATION = "misconfiguration"
+    OTHER = "other"
+
+
+class Finding(BaseModel):
+    id: str = ""
+    scanner: str
+    rule_id: str
+    title: str
+    description: str
+    severity: Severity
+    category: FindingCategory
+    file_path: str
+    line_start: int
+    line_end: Optional[int] = None
+    column: Optional[int] = None
+    code_snippet: Optional[str] = None
+    cve_id: Optional[str] = None
+    cwe_id: Optional[str] = None
+    owasp_category: Optional[str] = None
+    remediation: Optional[str] = None
+    references: List[str] = Field(default_factory=list)
+    confidence: str = "medium"
+    is_false_positive: bool = False
+    duplicate_of: Optional[str] = None
+
+    def model_post_init(self, __context: Any) -> None:
+        if not self.id:
+            raw = f"{self.rule_id}:{self.file_path}:{self.line_start}"
+            self.id = hashlib.sha256(raw.encode()).hexdigest()[:16]
+
+
+class ScanResult(BaseModel):
+    scanner: str
+    success: bool
+    findings: List[Finding] = Field(default_factory=list)
+    raw_output: Dict[str, Any] = Field(default_factory=dict)
+    error_message: Optional[str] = None
+    duration_seconds: float = 0.0
+    files_scanned: int = 0
+
+
+class ClaudeAnalysis(BaseModel):
+    executive_summary: str
+    risk_score: int = Field(ge=0, le=100)
+    risk_label: str
+    prioritized_findings: List[str] = Field(default_factory=list)
+    false_positive_ids: List[str] = Field(default_factory=list)
+    attack_narrative: Optional[str] = None
+    top_remediations: List[Dict[str, Any]] = Field(default_factory=list)
+    recommended_focus: str = ""
+
+
+class SecurityReport(BaseModel):
+    report_id: str
+    repo_path: str
+    scan_timestamp: datetime = Field(default_factory=datetime.utcnow)
+    scan_duration_seconds: float = 0.0
+    languages_detected: List[str] = Field(default_factory=list)
+    scanners_run: List[str] = Field(default_factory=list)
+    total_findings: int = 0
+    findings_by_severity: Dict[str, int] = Field(default_factory=dict)
+    findings_by_category: Dict[str, int] = Field(default_factory=dict)
+    all_findings: List[Finding] = Field(default_factory=list)
+    scan_results: List[ScanResult] = Field(default_factory=list)
+    claude_analysis: Optional[ClaudeAnalysis] = None
+    report_version: str = "1.0.0"

shieldbot_mcp-1.0.0/shieldbot/reporters/__init__.py

@@ -0,0 +1 @@
+"""Report output formatters."""

shieldbot_mcp-1.0.0/shieldbot/reporters/console_reporter.py

@@ -0,0 +1,208 @@
+"""Rich terminal reporter for shieldbot security reports."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich import box
+
+from shieldbot.models import Finding, SecurityReport, Severity
+
+console = Console()
+
+_SEVERITY_COLORS = {
+    Severity.CRITICAL: "bold red",
+    Severity.HIGH: "red",
+    Severity.MEDIUM: "yellow",
+    Severity.LOW: "cyan",
+    Severity.INFO: "dim",
+}
+
+_RISK_LABEL_COLORS = {
+    "Critical": "bold red",
+    "High": "red",
+    "Medium": "yellow",
+    "Low": "cyan",
+    "Clean": "bold green",
+}
+
+
+def print_report(report: SecurityReport, min_severity: Severity = Severity.INFO) -> None:
+    """Print a full security report to the terminal."""
+    console.print()
+
+    # ── Header ──────────────────────────────────────────────────────────
+    console.print(Panel(
+        f"[bold white]AUTOBOT SECURITY SCAN REPORT[/bold white]\n"
+        f"Repo: [dim]{report.repo_path}[/dim]\n"
+        f"Scanned: [dim]{report.scan_timestamp.strftime('%Y-%m-%d %H:%M:%S UTC')}[/dim]  "
+        f"Duration: [dim]{report.scan_duration_seconds:.1f}s[/dim]",
+        border_style="blue",
+        expand=False,
+    ))
+
+    # ── Risk score banner ────────────────────────────────────────────────
+    if report.claude_analysis:
+        risk_color = _RISK_LABEL_COLORS.get(report.claude_analysis.risk_label, "white")
+        score = report.claude_analysis.risk_score
+        label = report.claude_analysis.risk_label
+        console.print(f"\n[bold]RISK SCORE:[/bold] [{risk_color}]{score}/100  [{label.upper()}][/{risk_color}]\n")
+    else:
+        # Compute naive risk from finding counts
+        crit = report.findings_by_severity.get("critical", 0)
+        high = report.findings_by_severity.get("high", 0)
+        if crit > 0:
+            console.print("\n[bold red]RISK: CRITICAL findings present — immediate action required[/bold red]\n")
+        elif high > 0:
+            console.print("\n[bold red]RISK: HIGH findings detected[/bold red]\n")
+        else:
+            console.print("\n[bold yellow]RISK: Review findings below[/bold yellow]\n")
+
+    # ── Scanner summary table ────────────────────────────────────────────
+    table = Table(title="Scan Summary", box=box.ROUNDED, show_header=True, header_style="bold blue")
+    table.add_column("Scanner", style="cyan")
+    table.add_column("Critical", style="bold red", justify="right")
+    table.add_column("High", style="red", justify="right")
+    table.add_column("Medium", style="yellow", justify="right")
+    table.add_column("Low", style="cyan", justify="right")
+    table.add_column("Info", style="dim", justify="right")
+    table.add_column("Status")
+
+    for result in report.scan_results:
+        # Count by severity for this scanner
+        counts: dict[str, int] = {s.value: 0 for s in Severity}
+        for f in result.findings:
+            if not f.duplicate_of:
+                counts[f.severity.value] += 1
+
+        status = "[green]OK[/green]" if result.success else f"[red]ERROR[/red]"
+        if result.error_message and not result.success:
+            status = f"[red]{result.error_message[:40]}[/red]"
+
+        table.add_row(
+            result.scanner,
+            str(counts["critical"]) if counts["critical"] else "-",
+            str(counts["high"]) if counts["high"] else "-",
+            str(counts["medium"]) if counts["medium"] else "-",
+            str(counts["low"]) if counts["low"] else "-",
+            str(counts["info"]) if counts["info"] else "-",
+            status,
+        )
+
+    console.print(table)
+    console.print()
+
+    # ── Executive summary ────────────────────────────────────────────────
+    if report.claude_analysis and report.claude_analysis.executive_summary:
+        console.print(Panel(
+            report.claude_analysis.executive_summary,
+            title="[bold]Executive Summary (Claude Analysis)[/bold]",
+            border_style="blue",
+        ))
+        console.print()
+
+    # ── Findings ─────────────────────────────────────────────────────────
+    min_order = {
+        Severity.CRITICAL: 0, Severity.HIGH: 1,
+        Severity.MEDIUM: 2, Severity.LOW: 3, Severity.INFO: 4,
+    }
+    min_sev_order = min_order[min_severity]
+
+    canonical = [f for f in report.all_findings if not f.duplicate_of]
+    canonical.sort(key=lambda f: min_order.get(f.severity, 9))
+
+    shown = [f for f in canonical if min_order.get(f.severity, 9) <= min_sev_order]
+
+    if not shown:
+        console.print("[green]No findings at or above the selected severity threshold.[/green]")
+    else:
+        console.print(f"[bold]Findings ({len(shown)} shown, min severity: {min_severity.value})[/bold]\n")
+        for f in shown:
+            _print_finding(f, report)
+
+    # ── Top remediations ─────────────────────────────────────────────────
+    if report.claude_analysis and report.claude_analysis.top_remediations:
+        console.print(Panel(
+            _format_remediations(report.claude_analysis.top_remediations),
+            title="[bold]Top Remediation Priorities (Claude)[/bold]",
+            border_style="green",
+        ))
+
+    console.print()
+    _print_footer(report)
+
+
+def _print_finding(f: Finding, report: SecurityReport) -> None:
+    color = _SEVERITY_COLORS.get(f.severity, "white")
+    fp_note = " [dim](possible false positive)[/dim]" if f.is_false_positive else ""
+    if (
+        report.claude_analysis
+        and f.id in report.claude_analysis.false_positive_ids
+    ):
+        fp_note = " [dim italic](Claude: likely false positive)[/dim italic]"
+
+    title = f"[{color}][{f.severity.value.upper()}] {f.title}[/{color}]{fp_note}"
+
+    body_lines = [
+        f"[dim]Rule:[/dim]    {f.rule_id}",
+        f"[dim]File:[/dim]    {f.file_path}:{f.line_start}",
+        f"[dim]Scanner:[/dim] {f.scanner}",
+    ]
+    if f.cwe_id:
+        body_lines.append(f"[dim]CWE:[/dim]    {f.cwe_id}")
+    if f.owasp_category:
+        body_lines.append(f"[dim]OWASP:[/dim]  {f.owasp_category}")
+    if f.cve_id:
+        body_lines.append(f"[dim]CVE:[/dim]    {f.cve_id}")
+    if f.code_snippet:
+        snippet = f.code_snippet.strip()[:300]
+        body_lines.append(f"\n[dim]Code:[/dim]\n[dim]{snippet}[/dim]")
+    if f.remediation:
+        body_lines.append(f"\n[dim]Fix:[/dim]    {f.remediation[:300]}")
+
+    console.print(Panel("\n".join(body_lines), title=title, border_style=color.replace("bold ", "")))
+
+
+def _format_remediations(remediations: list) -> str:
+    lines = []
+    for i, rem in enumerate(remediations[:10], 1):
+        effort = rem.get("effort", "?")
+        title = rem.get("title", "")
+        steps = rem.get("steps", [])
+        lines.append(f"{i}. [bold]{title}[/bold]  [dim](effort: {effort})[/dim]")
+        for step in steps[:3]:
+            lines.append(f"   • {step}")
+    return "\n".join(lines)
+
+
+def _print_footer(report: SecurityReport) -> None:
+    total = report.total_findings
+    crit = report.findings_by_severity.get("critical", 0)
+    high = report.findings_by_severity.get("high", 0)
+    med = report.findings_by_severity.get("medium", 0)
+    low = report.findings_by_severity.get("low", 0)
+
+    console.print(
+        f"[dim]Total: {total} findings  |  "
+        f"[bold red]Critical: {crit}[/bold red]  "
+        f"[red]High: {high}[/red]  "
+        f"[yellow]Medium: {med}[/yellow]  "
+        f"[cyan]Low: {low}[/cyan][/dim]"
+    )
+    console.print()
+
+
+def print_tool_check(tool_statuses: dict[str, tuple[bool, str]]) -> None:
+    """Print tool availability check table."""
+    table = Table(title="Scanner Tool Status", box=box.ROUNDED, header_style="bold blue")
+    table.add_column("Tool")
+    table.add_column("Status")
+    table.add_column("Notes")
+
+    for tool, (available, note) in tool_statuses.items():
+        status = "[green]Available[/green]" if available else "[red]Not Found[/red]"
+        table.add_row(tool, status, note)
+
+    console.print(table)