secscan-mcp 0.1.2__py3-none-any.whl

secscan_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Security scanner MCP server."""
+
+__version__ = "0.1.2"

secscan_mcp/engines/__init__.py

@@ -0,0 +1,41 @@
+"""Scanner engine registry."""
+
+from __future__ import annotations
+
+from secscan_mcp.engines.bandit import BanditEngine
+from secscan_mcp.engines.base import Engine
+from secscan_mcp.engines.checkov import CheckovEngine
+from secscan_mcp.engines.custom import CustomSecretsEngine
+from secscan_mcp.engines.git_history import GitHistoryEngine
+from secscan_mcp.engines.gitleaks import GitleaksEngine
+from secscan_mcp.engines.osv import OsvEngine
+from secscan_mcp.engines.semgrep import SemgrepEngine
+from secscan_mcp.normalize import Category
+
+SECRET_ENGINES: list[Engine] = [
+    CustomSecretsEngine(),
+    GitHistoryEngine(),
+    GitleaksEngine(),
+]
+
+SAST_ENGINES: list[Engine] = [
+    SemgrepEngine(),
+    BanditEngine(),
+]
+
+DEPENDENCY_ENGINES: list[Engine] = [
+    OsvEngine(),
+]
+
+IAC_ENGINES: list[Engine] = [
+    CheckovEngine(),
+]
+
+ALL_ENGINES: list[Engine] = SECRET_ENGINES + SAST_ENGINES + DEPENDENCY_ENGINES + IAC_ENGINES
+
+ENGINES_BY_CATEGORY: dict[Category, list[Engine]] = {
+    Category.SECRET: SECRET_ENGINES,
+    Category.SAST: SAST_ENGINES,
+    Category.DEPENDENCY: DEPENDENCY_ENGINES,
+    Category.IAC: IAC_ENGINES,
+}

secscan_mcp/engines/_util.py

@@ -0,0 +1,39 @@
+"""Shared helpers for engine adapters."""
+
+from __future__ import annotations
+
+import json
+import logging
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def command_exists(name: str) -> bool:
+    return shutil.which(name) is not None
+
+
+def run_command(
+    cmd: list[str],
+    *,
+    cwd: Path,
+    timeout: int,
+) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        cmd,
+        cwd=cwd,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        check=False,
+    )
+
+
+def parse_json(stdout: str) -> Any:
+    text = stdout.strip()
+    if not text:
+        return None
+    return json.loads(text)

secscan_mcp/engines/bandit.py

@@ -0,0 +1,81 @@
+"""Bandit Python SAST adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from secscan_mcp.engines._util import command_exists, parse_json, run_command
+from secscan_mcp.normalize import Category, Finding, Severity, make_finding_id, map_severity
+
+
+class BanditEngine:
+    name = "bandit"
+    category = Category.SAST
+
+    def is_installed(self) -> bool:
+        return command_exists("bandit")
+
+    def run(self, root: Path, *, timeout: int) -> list[Finding]:
+        cmd = ["bandit", "-r", str(root), "-f", "json", "-q"]
+        proc = run_command(cmd, cwd=root, timeout=timeout)
+        if proc.returncode not in (0, 1):
+            msg = proc.stderr.strip() or f"bandit exited {proc.returncode}"
+            raise RuntimeError(msg)
+        return _parse_bandit(proc.stdout, root)
+
+
+def _parse_bandit(stdout: str, root: Path) -> list[Finding]:
+    data: Any = parse_json(stdout) if stdout.strip() else {}
+    if not isinstance(data, dict):
+        return []
+    results = data.get("results", [])
+    findings: list[Finding] = []
+    for item in results:
+        if not isinstance(item, dict):
+            continue
+        rule_id = str(item.get("test_id") or item.get("test_name") or "bandit")
+        rel = _relative(str(item.get("filename") or ""), root)
+        line = int(item.get("line_number") or 0)
+        severity = map_severity(str(item.get("issue_severity")), default=Severity.MEDIUM)
+        findings.append(
+            Finding(
+                id=make_finding_id(
+                    engine="bandit",
+                    rule_id=rule_id,
+                    file=rel,
+                    line=line,
+                    category=Category.SAST,
+                ),
+                category=Category.SAST,
+                severity=severity,
+                title=str(item.get("issue_text") or rule_id),
+                file=rel,
+                line=line,
+                rule_id=rule_id,
+                engine="bandit",
+                code_snippet=str(item.get("code") or ""),
+                cwe=_bandit_cwe(item),
+                remediation="See Bandit documentation for this test.",
+                confidence=str(item.get("issue_confidence") or "medium").lower(),
+            )
+        )
+    return findings
+
+
+def _bandit_cwe(item: dict[str, Any]) -> str | None:
+    issue_cwe = item.get("issue_cwe")
+    if isinstance(issue_cwe, dict):
+        cid = issue_cwe.get("id")
+        return str(cid) if cid is not None else None
+    return None
+
+
+def _relative(file_path: str, root: Path) -> str:
+    if not file_path:
+        return ""
+    path = Path(file_path)
+    try:
+        return str(path.resolve().relative_to(root.resolve()))
+    except ValueError:
+        return file_path

secscan_mcp/engines/base.py

@@ -0,0 +1,21 @@
+"""Engine adapter protocol."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Protocol
+
+from secscan_mcp.normalize import Category, Finding
+
+
+class Engine(Protocol):
+    name: str
+    category: Category
+
+    def is_installed(self) -> bool:
+        """Return True if the scanner CLI is available."""
+        ...
+
+    def run(self, root: Path, *, timeout: int) -> list[Finding]:
+        """Run the scanner against root and return normalized findings."""
+        ...

secscan_mcp/engines/checkov.py

@@ -0,0 +1,74 @@
+"""Checkov IaC scanner adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from secscan_mcp.engines._util import command_exists, parse_json, run_command
+from secscan_mcp.normalize import Category, Finding, Severity, make_finding_id, map_severity
+
+
+class CheckovEngine:
+    name = "checkov"
+    category = Category.IAC
+
+    def is_installed(self) -> bool:
+        return command_exists("checkov")
+
+    def run(self, root: Path, *, timeout: int) -> list[Finding]:
+        cmd = ["checkov", "-d", str(root), "--output", "json", "--quiet"]
+        proc = run_command(cmd, cwd=root, timeout=timeout)
+        if proc.returncode not in (0, 1):
+            msg = proc.stderr.strip() or f"checkov exited {proc.returncode}"
+            raise RuntimeError(msg)
+        return _parse_checkov(proc.stdout, root)
+
+
+def _parse_checkov(stdout: str, root: Path) -> list[Finding]:
+    data: Any = parse_json(stdout) if stdout.strip() else []
+    if isinstance(data, list) and data and isinstance(data[0], dict):
+        payload = data[0]
+    elif isinstance(data, dict):
+        payload = data
+    else:
+        return []
+
+    findings: list[Finding] = []
+    for failed in payload.get("results", {}).get("failed_checks", []) or []:
+        if not isinstance(failed, dict):
+            continue
+        rule_id = str(failed.get("check_id") or "checkov")
+        rel = _relative(str(failed.get("file_path") or ""), root)
+        line = int(failed.get("file_line_range", [0])[0]) if failed.get("file_line_range") else 0
+        findings.append(
+            Finding(
+                id=make_finding_id(
+                    engine="checkov",
+                    rule_id=rule_id,
+                    file=rel,
+                    line=line,
+                    category=Category.IAC,
+                ),
+                category=Category.IAC,
+                severity=map_severity(str(failed.get("severity")), default=Severity.MEDIUM),
+                title=str(failed.get("check_name") or rule_id),
+                file=rel,
+                line=line,
+                rule_id=rule_id,
+                engine="checkov",
+                remediation=str(failed.get("guideline") or ""),
+                confidence="medium",
+            )
+        )
+    return findings
+
+
+def _relative(file_path: str, root: Path) -> str:
+    if not file_path:
+        return ""
+    path = Path(file_path)
+    try:
+        return str(path.resolve().relative_to(root.resolve()))
+    except ValueError:
+        return file_path

secscan_mcp/engines/custom.py

@@ -0,0 +1,90 @@
+"""Custom regex-based secret scanner (no external CLI)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from secscan_mcp.normalize import (
+    Category,
+    Finding,
+    Severity,
+    make_finding_id,
+    map_severity,
+    redact_snippet,
+)
+from secscan_mcp.rules.loader import load_secret_rules
+
+_SKIP_DIRS = {
+    ".git",
+    ".venv",
+    "venv",
+    "node_modules",
+    "__pycache__",
+    ".ruff_cache",
+    ".mypy_cache",
+    "dist",
+    "build",
+}
+
+
+class CustomSecretsEngine:
+    name = "custom"
+    category = Category.SECRET
+
+    def is_installed(self) -> bool:
+        return True
+
+    def run(self, root: Path, *, timeout: int) -> list[Finding]:
+        del timeout  # unused; scan is in-process
+        rules = load_secret_rules()
+        findings: list[Finding] = []
+        for file_path in _iter_text_files(root):
+            try:
+                content = file_path.read_text(encoding="utf-8", errors="ignore")
+            except OSError:
+                continue
+            rel = str(file_path.relative_to(root))
+            for rule in rules:
+                pattern = rule["pattern"]
+                for match in pattern.finditer(content):
+                    line = content[: match.start()].count("\n") + 1
+                    snippet = redact_snippet(match.group(0))
+                    rule_id = str(rule["id"])
+                    findings.append(
+                        Finding(
+                            id=make_finding_id(
+                                engine="custom",
+                                rule_id=rule_id,
+                                file=rel,
+                                line=line,
+                                category=Category.SECRET,
+                            ),
+                            category=Category.SECRET,
+                            severity=map_severity(
+                                str(rule.get("severity", "high")),
+                                default=Severity.HIGH,
+                            ),
+                            title=str(rule.get("title", rule_id)),
+                            file=rel,
+                            line=line,
+                            rule_id=rule_id,
+                            engine="custom",
+                            code_snippet=snippet,
+                            remediation=str(rule.get("remediation", "")),
+                            confidence="medium",
+                        )
+                    )
+        return findings
+
+
+def _iter_text_files(root: Path) -> list[Path]:
+    files: list[Path] = []
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if any(part in _SKIP_DIRS for part in path.parts):
+            continue
+        if path.suffix.lower() in {".png", ".jpg", ".jpeg", ".gif", ".woff", ".woff2", ".ico"}:
+            continue
+        files.append(path)
+    return files

secscan_mcp/engines/git_history.py

@@ -0,0 +1,174 @@
+"""Git commit history secret scanner (requires git, no external CLI)."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from secscan_mcp.engines._util import command_exists, run_command
+from secscan_mcp.normalize import (
+    Category,
+    Finding,
+    Severity,
+    make_finding_id,
+    map_severity,
+    redact_snippet,
+)
+from secscan_mcp.rules.loader import load_secret_rules
+
+_DEFAULT_MAX_COMMITS = int(os.environ.get("SECSCAN_GIT_MAX_COMMITS", "500"))
+_COMMIT_PREFIX = "COMMIT:"
+_HUNK_RE = re.compile(r"^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@")
+
+
+@dataclass(frozen=True)
+class _CommitContext:
+    sha: str
+    date: str
+    subject: str
+
+
+class GitHistoryEngine:
+    name = "git_history"
+    category = Category.SECRET
+
+    def is_installed(self) -> bool:
+        return command_exists("git")
+
+    def run(self, root: Path, *, timeout: int, include_git_history: bool = False) -> list[Finding]:
+        if not include_git_history:
+            return []
+        if not _is_git_repo(root):
+            return []
+
+        rules = load_secret_rules()
+        max_commits = _DEFAULT_MAX_COMMITS
+        proc = run_command(
+            [
+                "git",
+                "log",
+                "-p",
+                "--all",
+                f"-n{max_commits}",
+                "--no-color",
+                "--no-ext-diff",
+                f"--format={_COMMIT_PREFIX}%H|%aI|%s",
+            ],
+            cwd=root,
+            timeout=timeout,
+        )
+        if proc.returncode != 0:
+            msg = proc.stderr.strip() or proc.stdout.strip() or f"git log exited {proc.returncode}"
+            raise RuntimeError(msg)
+
+        return _parse_git_log(proc.stdout, rules)
+
+
+def _is_git_repo(root: Path) -> bool:
+    proc = run_command(["git", "rev-parse", "--git-dir"], cwd=root, timeout=30)
+    return proc.returncode == 0
+
+
+def _parse_git_log(raw: str, rules: list[dict[str, object]]) -> list[Finding]:
+    findings: list[Finding] = []
+    commit = _CommitContext(sha="", date="", subject="")
+    current_file = ""
+    new_line = 0
+
+    for line in raw.splitlines():
+        if line.startswith(_COMMIT_PREFIX):
+            commit = _parse_commit_line(line)
+            current_file = ""
+            new_line = 0
+            continue
+
+        if line.startswith("diff --git "):
+            current_file = _parse_diff_path(line)
+            new_line = 0
+            continue
+
+        hunk_match = _HUNK_RE.match(line)
+        if hunk_match:
+            new_line = int(hunk_match.group(1))
+            continue
+
+        if not line.startswith("+") or line.startswith("+++"):
+            if line.startswith("-") and not line.startswith("---"):
+                continue
+            if line.startswith(" ") and current_file:
+                new_line += 1
+            continue
+
+        added = line[1:]
+        if not current_file or not commit.sha:
+            continue
+
+        for rule in rules:
+            pattern = rule["pattern"]
+            if not isinstance(pattern, re.Pattern):
+                continue
+            match = pattern.search(added)
+            if match is None:
+                continue
+            rule_id = str(rule["id"])
+            short_sha = commit.sha[:7]
+            findings.append(
+                Finding(
+                    id=make_finding_id(
+                        engine="git_history",
+                        rule_id=rule_id,
+                        file=current_file,
+                        line=new_line,
+                        category=Category.SECRET,
+                    ),
+                    category=Category.SECRET,
+                    severity=map_severity(
+                        str(rule.get("severity", "high")),
+                        default=Severity.HIGH,
+                    ),
+                    title=f"{rule.get('title', rule_id)} in git history ({short_sha})",
+                    file=current_file,
+                    line=new_line,
+                    rule_id=rule_id,
+                    engine="git_history",
+                    code_snippet=redact_snippet(match.group(0)),
+                    remediation=_history_remediation(rule, commit),
+                    confidence="medium",
+                )
+            )
+        new_line += 1
+
+    return findings
+
+
+def _parse_commit_line(line: str) -> _CommitContext:
+    payload = line[len(_COMMIT_PREFIX) :]
+    parts = payload.split("|", 2)
+    if len(parts) < 3:
+        return _CommitContext(sha=payload, date="", subject="")
+    return _CommitContext(sha=parts[0], date=parts[1], subject=parts[2])
+
+
+def _parse_diff_path(line: str) -> str:
+    # diff --git a/path b/path
+    parts = line.split()
+    if len(parts) >= 4 and parts[2].startswith("a/"):
+        return parts[2][2:]
+    if len(parts) >= 3 and parts[-1].startswith("b/"):
+        return parts[-1][2:]
+    return ""
+
+
+def _history_remediation(rule: dict[str, object], commit: _CommitContext) -> str:
+    base = str(rule.get("remediation", "")).strip()
+    short_sha = commit.sha[:7] if commit.sha else "unknown"
+    history = (
+        f"Found in commit {short_sha}"
+        + (f" ({commit.date})" if commit.date else "")
+        + (f': "{commit.subject}"' if commit.subject else "")
+        + ". Secrets in git history remain exposed even after deletion from the working tree. "
+        "Rotate the credential and rewrite history (e.g. git filter-repo) or treat the secret as compromised."
+    )
+    return f"{base} {history}".strip() if base else history

secscan_mcp/engines/gitleaks.py

@@ -0,0 +1,108 @@
+"""Gitleaks secret scanner adapter."""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from secscan_mcp.engines._util import command_exists, parse_json, run_command
+from secscan_mcp.normalize import (
+    Category,
+    Finding,
+    Severity,
+    make_finding_id,
+    map_severity,
+    redact_secret,
+    redact_snippet,
+)
+
+
+class GitleaksEngine:
+    name = "gitleaks"
+    category = Category.SECRET
+
+    def is_installed(self) -> bool:
+        return command_exists("gitleaks")
+
+    def run(self, root: Path, *, timeout: int, include_git_history: bool = False) -> list[Finding]:
+        with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as tmp:
+            report_path = Path(tmp.name)
+
+        cmd = [
+            "gitleaks",
+            "detect",
+            "--source",
+            str(root),
+            "--report-format",
+            "json",
+            "--report-path",
+            str(report_path),
+        ]
+        if not include_git_history:
+            cmd.append("--no-git")
+
+        proc = run_command(cmd, cwd=root, timeout=timeout)
+        if proc.returncode not in (0, 1):  # 1 = leaks found
+            msg = proc.stderr.strip() or proc.stdout.strip() or f"gitleaks exited {proc.returncode}"
+            raise RuntimeError(msg)
+
+        raw = report_path.read_text(encoding="utf-8") if report_path.exists() else "[]"
+        report_path.unlink(missing_ok=True)
+        return _parse_gitleaks(raw, root)
+
+
+def _parse_gitleaks(raw: str, root: Path) -> list[Finding]:
+    data: Any = parse_json(raw) if raw.strip() else []
+    if isinstance(data, dict):
+        items = data.get("findings") or data.get("results") or []
+    elif isinstance(data, list):
+        items = data
+    else:
+        items = []
+
+    findings: list[Finding] = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        file_path = _relative_path(item.get("File") or item.get("file") or "", root)
+        line = int(item.get("StartLine") or item.get("startLine") or item.get("line") or 0)
+        rule_id = str(item.get("RuleID") or item.get("ruleID") or item.get("rule") or "gitleaks")
+        secret = str(item.get("Secret") or item.get("secret") or "")
+        snippet = redact_snippet(str(item.get("Match") or item.get("match") or secret))
+        title = str(item.get("Description") or item.get("description") or rule_id)
+        severity = map_severity(
+            str(item.get("Severity") or item.get("severity")), default=Severity.HIGH
+        )
+        findings.append(
+            Finding(
+                id=make_finding_id(
+                    engine="gitleaks",
+                    rule_id=rule_id,
+                    file=file_path,
+                    line=line,
+                    category=Category.SECRET,
+                ),
+                category=Category.SECRET,
+                severity=severity,
+                title=title,
+                file=file_path,
+                line=line,
+                rule_id=rule_id,
+                engine="gitleaks",
+                code_snippet=snippet or redact_secret(secret),
+                remediation="Remove the secret and rotate credentials; use environment variables or a secret manager.",
+                confidence="high",
+            )
+        )
+    return findings
+
+
+def _relative_path(file_path: str, root: Path) -> str:
+    if not file_path:
+        return ""
+    path = Path(file_path)
+    try:
+        return str(path.resolve().relative_to(root.resolve()))
+    except ValueError:
+        return file_path