grim-mcp 0.2.0__py3-none-any.whl

grim/__init__.py

@@ -0,0 +1,3 @@
+"""GRIM — security audit orchestrator for code, deps, exposure, and active compromise."""
+
+__version__ = "0.2.0"

grim/__main__.py

@@ -0,0 +1,211 @@
+"""GRIM CLI entry point.
+
+Usage:
+  grim version
+  grim mcp                                  # run MCP server (stdio)
+  grim list                                 # list tools
+  grim scan PATH [--format md|json] [--out FILE] [--tools ...] [--no-network] [--deep]
+  grim tool NAME --path P [--path-b P2] [--format md|json]
+  grim diff A B [--format md|json] [--deep]
+  grim plan PATH [--no-network] [--deep]
+  grim sbom PATH [--format cyclonedx|spdx] [--out FILE]
+  grim ledger PATH [--ledger FILE] [--tools ...]
+  grim iocs PATH [--deep]
+  grim update-feeds [--url URL]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .core.report import render_markdown, render_summary_line
+from .tools import TOOLS, call_tool
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="grim", description="GRIM — security audit for code, deps, exposure, drift")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("version", help="print version")
+    sub.add_parser("mcp", help="run MCP server over stdio")
+    sub.add_parser("list", help="list available tools")
+
+    p_scan = sub.add_parser("scan", help="one-shot audit of a path or archive")
+    p_scan.add_argument("path")
+    p_scan.add_argument("--format", choices=["md", "json"], default="md")
+    p_scan.add_argument("--out", default=None)
+    p_scan.add_argument("--tools", default=None, help="subset: exposure,secrets,code,deps,iocs")
+    p_scan.add_argument("--no-network", action="store_true")
+    p_scan.add_argument("--deep", action="store_true", help="nested archives + IoC hash matching")
+
+    p_tool = sub.add_parser("tool", help="run a single tool")
+    p_tool.add_argument("name")
+    p_tool.add_argument("--path", default=None)
+    p_tool.add_argument("--path-a", default=None)
+    p_tool.add_argument("--path-b", default=None)
+    p_tool.add_argument("--format", choices=["md", "json"], default="md")
+    p_tool.add_argument("--raw", action="store_true", help="print raw JSON result payload")
+
+    p_diff = sub.add_parser("diff", help="diff two artifacts (baseline vs current)")
+    p_diff.add_argument("path_a")
+    p_diff.add_argument("path_b")
+    p_diff.add_argument("--format", choices=["md", "json"], default="md")
+    p_diff.add_argument("--deep", action="store_true")
+
+    p_plan = sub.add_parser("plan", help="show the audit plan for a target")
+    p_plan.add_argument("path")
+    p_plan.add_argument("--no-network", action="store_true")
+    p_plan.add_argument("--deep", action="store_true")
+
+    p_sbom = sub.add_parser("sbom", help="emit CycloneDX/SPDX SBOM")
+    p_sbom.add_argument("path")
+    p_sbom.add_argument("--format", choices=["cyclonedx", "spdx"], default="cyclonedx")
+    p_sbom.add_argument("--out", default=None)
+
+    p_ledger = sub.add_parser("ledger", help="merge a scan into the persistent findings ledger")
+    p_ledger.add_argument("path")
+    p_ledger.add_argument("--ledger", default=None)
+    p_ledger.add_argument("--tools", default=None)
+    p_ledger.add_argument("--deep", action="store_true")
+
+    p_iocs = sub.add_parser("iocs", help="match file hashes against the IoC store")
+    p_iocs.add_argument("path")
+    p_iocs.add_argument("--deep", action="store_true")
+
+    p_feeds = sub.add_parser("update-feeds", help="sync the IoC store from a feed URL")
+    p_feeds.add_argument("--url", default=None)
+    p_feeds.add_argument("--ioc-path", default=None)
+
+    args = parser.parse_args(argv)
+
+    if args.command in (None, "version"):
+        print(f"grim {__version__}")
+        return 0
+    if args.command == "mcp":
+        from .mcp.server import run_server
+
+        run_server()
+        return 0
+    if args.command == "list":
+        for name, meta in TOOLS.items():
+            print(f"{name:16s} {meta['description']}")
+        return 0
+    if args.command == "scan":
+        tool_args = {"path": args.path}
+        if args.tools:
+            tool_args["tools"] = [t.strip() for t in args.tools.split(",") if t.strip()]
+        if args.no_network:
+            tool_args["network"] = False
+        if args.deep:
+            tool_args["deep"] = True
+        payload = call_tool("scan", tool_args)
+        return _emit(payload, args.format, args.out)
+    if args.command == "tool":
+        if args.name not in TOOLS:
+            print(f"unknown tool: {args.name}", file=sys.stderr)
+            return 2
+        tool_args = _build_tool_args(args.name, args)
+        payload = call_tool(args.name, tool_args)
+        if args.raw:
+            print(json.dumps(payload, indent=2, default=str))
+            return 0 if payload.get("ok") else 1
+        return _emit(payload, args.format, None)
+    if args.command == "diff":
+        payload = call_tool("diff_artifacts", {"path_a": args.path_a, "path_b": args.path_b,
+                                               "deep": bool(args.deep)})
+        return _emit(payload, args.format, None)
+    if args.command == "plan":
+        return _print_json(call_tool("plan", {"path": args.path,
+                                              "network": not args.no_network,
+                                              "deep": args.deep}))
+    if args.command == "sbom":
+        payload = call_tool("sbom", {"path": args.path, "format": args.format})
+        if not payload.get("ok"):
+            print(f"error: {payload.get('error')}", file=sys.stderr)
+            return 1
+        text = json.dumps(payload["bom"], indent=2, default=str)
+        if args.out:
+            with open(args.out, "w", encoding="utf-8") as fh:
+                fh.write(text)
+            print(f"wrote {args.out} ({payload['component_count']} components)")
+        else:
+            print(text)
+        return 0
+    if args.command == "ledger":
+        tool_args: dict = {"path": args.path, "deep": bool(args.deep)}
+        if args.ledger:
+            tool_args["ledger_path"] = args.ledger
+        if args.tools:
+            tool_args["tools"] = [t.strip() for t in args.tools.split(",") if t.strip()]
+        return _print_json(call_tool("ledger", tool_args))
+    if args.command == "iocs":
+        payload = call_tool("scan_iocs", {"path": args.path, "deep": bool(args.deep)})
+        return _emit(payload, "md", None)
+    if args.command == "update-feeds":
+        tool_args = {"url": args.url, "ioc_path": args.ioc_path}
+        return _print_json(call_tool("update_feeds", {k: v for k, v in tool_args.items() if v}))
+    parser.print_help()
+    return 1
+
+
+def _print_json(payload: dict) -> int:
+    print(json.dumps(payload, indent=2, default=str))
+    return 0 if payload.get("ok") else 1
+
+
+def _build_tool_args(name: str, args: argparse.Namespace) -> dict:
+    schema_props = TOOLS[name]["schema"].get("properties", {})
+    provided = {
+        "path": args.path,
+        "path_a": args.path_a,
+        "path_b": args.path_b,
+    }
+    return {k: v for k, v in provided.items() if k in schema_props and v is not None}
+
+
+def _emit(payload: dict, fmt: str, out: str | None) -> int:
+    if not payload.get("ok"):
+        print(f"error: {payload.get('error')}", file=sys.stderr)
+        return 1
+    if fmt == "json":
+        text = json.dumps(payload, indent=2, default=str)
+    else:
+        findings = [_to_finding(d) for d in payload.get("findings", [])]
+        text = render_markdown(findings, payload.get("meta", {}))
+        text += "\n" + render_summary_line(findings) + "\n"
+    if out:
+        with open(out, "w", encoding="utf-8") as fh:
+            fh.write(text)
+        print(f"wrote {out} ({render_summary_line([_to_finding(d) for d in payload.get('findings', [])])})")
+    else:
+        print(text)
+    return 0
+
+
+def _to_finding(d: dict):
+    from .core.findings import Finding
+
+    return Finding(
+        id=d.get("id", ""),
+        severity=d.get("severity", "info"),
+        confidence=float(d.get("confidence", 0.5)),
+        category=d.get("category", ""),
+        owasp=d.get("owasp", ""),
+        title=d.get("title", ""),
+        description=d.get("description", ""),
+        location=d.get("location", {}),
+        evidence=d.get("evidence", ""),
+        remediation=d.get("remediation", ""),
+        references=d.get("references", []),
+        engine=d.get("engine", "grim"),
+        first_seen=d.get("first_seen", ""),
+        tags=d.get("tags", []),
+        mitre=d.get("mitre", []),
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

grim/core/attack.py

@@ -0,0 +1,78 @@
+"""MITRE ATT&CK tagging for GRIM findings.
+
+Maps finding signals (tags, category, title) to ATT&CK technique IDs so reports can
+be correlated with threat-intel tooling. Pure lookup, no network, no deps.
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from .findings import Finding
+
+# (signal substrings matched against tags/category/title, technique id, name)
+RULES: list[tuple[tuple[str, ...], str, str]] = [
+    (("webshell", "web shell", "webshell indicator"), "T1505.003", "Server Software Component: Web Shell"),
+    (("polyglot",), "T1505.003", "Server Software Component: Web Shell"),
+    (("upload", "cwe-434", "arbitrary file"), "T1190", "Exploit Public-Facing Application"),
+    (("elf", "native executable", "pe binary"), "T1204.002", "User Execution: Malicious File"),
+    (("stager", "downloader", "payload host", "c2"), "T1105", "Ingress Tool Transfer"),
+    (("piped shell", "curl | sh"), "T1059.004", "Command and Scripting Interpreter: Unix Shell"),
+    (("shell", "command execution", "exec.command", "child_process", "process.start"), "T1059", "Command and Scripting Interpreter"),
+    (("eval", "dynamic code execution", "deserialization"), "T1059", "Command and Scripting Interpreter"),
+    (("sql", "injection"), "T1190", "Exploit Public-Facing Application"),
+    (("xxe", "xml parsing"), "T1190", "Exploit Public-Facing Application"),
+    (("secrets", "cwe-798", "credential", "environment file", ".env"), "T1552.001", "Unsecured Credentials: Credentials In Files"),
+    (("dependencies", "supply chain", "cwe-1395"), "T1195.002", "Supply Chain Compromise: Compromise Software Supply Chain"),
+    (("drift", "changed"), "T1565.001", "Data Manipulation: Stored Data Manipulation"),
+    (("removed", "cleanup"), "T1070.004", "Indicator Removal: File Deletion"),
+    (("encoded", "obfuscat", "gzinflate", "str_rot13"), "T1027", "Obfuscated Files or Information"),
+    (("miner", "resource hijack"), "T1496", "Resource Hijacking"),
+    (("log", "cwe-532"), "T1552.001", "Unsecured Credentials: Credentials In Files"),
+    (("backup", "cwe-530", "dump"), "T1552.001", "Unsecured Credentials: Credentials In Files"),
+    (("exposed .git", "vcs", "cwe-538"), "T1213", "Data from Information Repositories"),
+    (("ioc", "known malware"), "T1204.002", "User Execution: Malicious File"),
+    (("hardcoded-ip", "suspicious"), "T1071.001", "Application Layer Protocol: Web Protocols"),
+]
+
+
+def techniques_for(finding: Finding) -> list[tuple[str, str]]:
+    """Return ordered, de-duplicated (id, name) techniques for a finding."""
+    haystack = " ".join(
+        [finding.category.lower(), finding.title.lower(), " ".join(finding.tags).lower()]
+    )
+    out: list[tuple[str, str]] = []
+    seen: set[str] = set()
+    for signals, tid, name in RULES:
+        if tid in seen:
+            continue
+        if any(sig in haystack for sig in signals):
+            seen.add(tid)
+            out.append((tid, name))
+    return out
+
+
+def enrich_one(finding: Finding) -> Finding:
+    for tid, _name in techniques_for(finding):
+        if tid not in finding.mitre:
+            finding.mitre.append(tid)
+        tag = f"attack:{tid}"
+        if tag not in finding.tags:
+            finding.tags.append(tag)
+    return finding
+
+
+def enrich(findings: Iterable[Finding]) -> list[Finding]:
+    """In-place MITRE tagging; returns the list for convenience."""
+    out = list(findings)
+    for f in out:
+        enrich_one(f)
+    return out
+
+
+def catalog() -> list[dict[str, str]]:
+    """All techniques GRIM can emit, for documentation/discovery."""
+    seen: dict[str, str] = {}
+    for _signals, tid, name in RULES:
+        seen.setdefault(tid, name)
+    return [{"id": k, "name": v} for k, v in sorted(seen.items())]

grim/core/detector.py

@@ -0,0 +1,159 @@
+"""Stack detection: identify project type(s) from manifests and file patterns."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+MANIFESTS = {
+    "package.json": "node",
+    "composer.json": "php",
+    "requirements.txt": "python",
+    "pyproject.toml": "python",
+    "Pipfile": "python",
+    "go.mod": "go",
+    "Gemfile": "ruby",
+    "pom.xml": "java",
+    "build.gradle": "java",
+}
+
+JS_FRAMEWORKS = {
+    "next": "nextjs",
+    "nuxt": "nuxt",
+    "astro": "astro",
+    "react": "react",
+    "vue": "vue",
+    "svelte": "svelte",
+    "@angular/core": "angular",
+    "express": "express",
+    "fastify": "fastify",
+}
+
+PHP_FRAMEWORKS = {
+    "laravel/framework": "laravel",
+    "symfony/symfony": "symfony",
+    "cakephp/cakephp": "cakephp",
+}
+
+CONFIG_MARKERS = {
+    "next.config.js": "nextjs",
+    "next.config.mjs": "nextjs",
+    "nuxt.config.ts": "nuxt",
+    "astro.config.mjs": "astro",
+    "angular.json": "angular",
+}
+
+MAX_DEPTH = 4
+SKIP_DIRS = {".git", "node_modules", "vendor", ".venv", "venv", "__pycache__", "dist", "build"}
+
+
+def detect_stack(path: str) -> dict:
+    """Return {stacks: [{language, framework, manifest, path}], web_dirs: [...]}."""
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"path not found: {path}")
+
+    stacks: list[dict] = []
+    manifests_found: list[str] = []
+    web_dirs: list[str] = []
+    lockfiles: list[str] = []
+
+    if p.is_file():
+        manifests_found.append(p.name)
+    else:
+        for root, dirs, files in os.walk(p):
+            rel = os.path.relpath(root, p)
+            depth = 0 if rel == "." else rel.count(os.sep) + 1
+            dirs[:] = [d for d in dirs if d not in SKIP_DIRS and depth < MAX_DEPTH]
+            base = os.path.basename(root).lower()
+            if base in {"public", "public_html", "www", "htdocs", "web"}:
+                web_dirs.append(str(Path(root)))
+            for fn in files:
+                if fn in MANIFESTS:
+                    manifests_found.append(str(Path(root) / fn))
+                if fn in CONFIG_MARKERS:
+                    manifests_found.append(str(Path(root) / fn))
+                if fn.endswith(".lock") and fn in {"composer.lock", "package-lock.json", "yarn.lock", "pnpm-lock.yaml"}:
+                    lockfiles.append(str(Path(root) / fn))
+
+    for m in manifests_found:
+        mp = Path(m)
+        lang = MANIFESTS.get(mp.name)
+        framework = None
+        if lang is None and mp.name in CONFIG_MARKERS:
+            framework = CONFIG_MARKERS[mp.name]
+            lang = "node"
+        if mp.name == "package.json":
+            framework = framework or _js_framework(mp)
+        if mp.name == "composer.json":
+            framework = _php_framework(mp)
+
+        stacks.append(
+            {
+                "language": lang or "unknown",
+                "framework": framework,
+                "manifest": m,
+            }
+        )
+
+    # Static site detection
+    if not stacks:
+        for candidate in ["index.html", "index.htm"]:
+            if (p / candidate).is_file() if p.is_dir() else False:
+                stacks.append({"language": "static", "framework": "html", "manifest": candidate})
+
+    return {
+        "path": str(p),
+        "is_archive": p.is_file() and _looks_archive(p.name),
+        "stacks": _dedupe_stacks(stacks),
+        "web_dirs": web_dirs[:20],
+        "lockfiles": lockfiles[:20],
+    }
+
+
+def _js_framework(package_json: Path) -> str | None:
+    try:
+        data = json.loads(package_json.read_text(encoding="utf-8", errors="ignore"))
+    except Exception:
+        return None
+    deps = {}
+    deps.update(data.get("dependencies") or {})
+    deps.update(data.get("devDependencies") or {})
+    for key, fw in JS_FRAMEWORKS.items():
+        if key in deps:
+            return fw
+    return None
+
+
+def _php_framework(composer_json: Path) -> str | None:
+    try:
+        data = json.loads(composer_json.read_text(encoding="utf-8", errors="ignore"))
+    except Exception:
+        return None
+    deps = {}
+    deps.update(data.get("require") or {})
+    deps.update(data.get("require-dev") or {})
+    for key, fw in PHP_FRAMEWORKS.items():
+        if key in deps:
+            return fw
+    return None
+
+
+def _dedupe_stacks(stacks: list[dict]) -> list[dict]:
+    seen = set()
+    out = []
+    for s in stacks:
+        key = (s["language"], s["framework"])
+        if key in seen:
+            continue
+        seen.add(key)
+        out.append(s)
+    return out
+
+
+def _looks_archive(name: str) -> bool:
+    lowered = name.lower()
+    return lowered.endswith(
+        (".tar", ".tar.gz", ".tgz", ".tar.bz2", ".tar.xz", ".zip", ".7z", ".rar", ".gz", ".bz2", ".xz")
+    )

grim/core/findings.py

@@ -0,0 +1,111 @@
+"""Finding model, ranking, and dedupe for GRIM."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from typing import Any, Iterable
+
+SEVERITY_ORDER = {"critical": 4, "high": 3, "medium": 2, "low": 1, "info": 0}
+SEVERITY_EMOJI = {"critical": "!!", "high": "!", "medium": "+", "low": "-", "info": "."}
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+@dataclass
+class Finding:
+    id: str
+    severity: str
+    confidence: float
+    category: str
+    owasp: str
+    title: str
+    description: str = ""
+    location: dict[str, Any] = field(default_factory=dict)
+    evidence: str = ""
+    remediation: str = ""
+    references: list[str] = field(default_factory=list)
+    engine: str = "grim"
+    first_seen: str = field(default_factory=_now)
+    tags: list[str] = field(default_factory=list)
+    mitre: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        d = asdict(self)
+        d["severity_rank"] = SEVERITY_ORDER.get(self.severity, 0)
+        return d
+
+    def fingerprint(self) -> str:
+        key = json.dumps(
+            [
+                self.severity,
+                self.category,
+                self.location.get("file", self.location.get("url", "")),
+                self.location.get("line", 0),
+                self.title,
+            ],
+            sort_keys=True,
+        )
+        return hashlib.sha256(key.encode()).hexdigest()[:16]
+
+
+SEVERITY_CVSS_BANDS = [
+    (9.0, "critical"),
+    (7.0, "high"),
+    (4.0, "medium"),
+    (0.1, "low"),
+    (0.0, "info"),
+]
+
+
+def cvss_to_severity(score: float) -> str:
+    for threshold, sev in SEVERITY_CVSS_BANDS:
+        if score >= threshold:
+            return sev
+    return "info"
+
+
+def rank(findings: Iterable[Finding]) -> list[Finding]:
+    """Dedupe and sort by severity x confidence, then by location."""
+    seen: dict[str, Finding] = {}
+    for f in findings:
+        fp = f.fingerprint()
+        if fp in seen:
+            existing = seen[fp]
+            # keep the higher-confidence version, merge tags
+            if f.confidence > existing.confidence:
+                existing.confidence = f.confidence
+                existing.evidence = f.evidence or existing.evidence
+            for t in f.tags:
+                if t not in existing.tags:
+                    existing.tags.append(t)
+            continue
+        seen[fp] = f
+    ordered = sorted(
+        seen.values(),
+        key=lambda f: (
+            -SEVERITY_ORDER.get(f.severity, 0),
+            -f.confidence,
+            str(f.location.get("file", f.location.get("url", ""))),
+            int(f.location.get("line", 0) or 0),
+        ),
+    )
+    return ordered
+
+
+def summarize(findings: Iterable[Finding]) -> dict[str, Any]:
+    counts: dict[str, int] = {k: 0 for k in SEVERITY_ORDER}
+    total = 0
+    for f in findings:
+        counts[f.severity] = counts.get(f.severity, 0) + 1
+        total += 1
+    return {"total": total, "by_severity": counts}
+
+
+def make_id(prefix: str, title: str, location: str = "") -> str:
+    digest = hashlib.sha1(f"{prefix}|{title}|{location}".encode()).hexdigest()[:6].upper()
+    return f"GRIM-{prefix}-{digest}"