devguard-scanner 0.1.0__py3-none-any.whl

devguard/cli.py

@@ -0,0 +1,302 @@
+"""DevGuard command-line interface. Files in the scanned project are analyzed as data and never executed."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from devguard import RULESET_VERSION, __version__
+from devguard.core.config import ConfigError, default_output_dir, is_within, load_config, parse_size
+from devguard.core.models import Severity
+
+EXIT_OK, EXIT_FINDINGS, EXIT_USAGE, EXIT_PARTIAL, EXIT_AI = 0, 1, 2, 3, 4
+
+DESCRIPTION = (
+    "DevGuard scans an untrusted code workspace BEFORE you open, install, or run it. "
+    "Files are analyzed as data and are never executed."
+)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="devguard", description=DESCRIPTION)
+    p.add_argument("--version", action="version", version=f"devguard {__version__} (ruleset {RULESET_VERSION})")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("scan", help="Scan a directory (read-only; nothing is executed).", description=DESCRIPTION)
+    s.add_argument("path", type=Path)
+    s.add_argument("--output-dir", type=Path, help="Report directory (default: per-user data dir, outside the target).")
+    s.add_argument(
+        "--format",
+        action="append",
+        choices=["md", "json", "sarif"],
+        dest="formats",
+        help="Report format; repeatable (default: md and json).",
+    )
+    s.add_argument("--json", action="store_true", help="Print the JSON report to stdout (summary goes to stderr).")
+    s.add_argument("--config", type=Path, help="Config file (must be outside the target).")
+    s.add_argument("--exclude", action="append", default=[], help="Glob to exclude; repeatable.")
+    s.add_argument("--include-vendored", action="store_true", help="Deep-scan node_modules, vendor, virtualenvs.")
+    s.add_argument("--max-file-size", help="Per-file read limit, e.g. 2M.")
+    s.add_argument("--max-files", type=int)
+    s.add_argument("--timeout", type=float, help="Scan time budget in seconds.")
+    s.add_argument("--fail-on", choices=[v.value for v in Severity if v is not Severity.INFO])
+    s.add_argument(
+        "--allow-output-in-target",
+        action="store_true",
+        help="Permit an output directory inside the target (it is then excluded from the scan).",
+    )
+    s.add_argument("-v", "--verbose", action="store_true")
+    s.add_argument("-q", "--quiet", action="store_true")
+    ai = s.add_argument_group("AI investigation (optional, off by default)")
+    ai.add_argument("--ai", action="store_true", help="Run the AI investigator after the deterministic scan.")
+    ai.add_argument("--ai-profile", help="AI profile name from your user config.")
+    ai.add_argument("--no-ai-tools", action="store_true", help="AI may only annotate findings; no file access.")
+    ai.add_argument("--yes-send-code", action="store_true", help="Consent to sending redacted excerpts (CI).")
+    ai.add_argument("--ai-required", action="store_true", help="Exit 4 if the AI stage cannot complete.")
+    ai.add_argument("--no-ai-cache", action="store_true")
+
+    r = sub.add_parser("rules", help="List the rule catalogue.")
+    r.add_argument("--json", action="store_true")
+    e = sub.add_parser("explain", help="Explain a rule.")
+    e.add_argument("rule_id")
+
+    a = sub.add_parser("ai", help="AI provider utilities.")
+    asub = a.add_subparsers(dest="ai_command", required=True)
+    asub.add_parser("providers", help="List installed providers and configured profiles.")
+    t = asub.add_parser("test", help="Run plugin contract checks against a profile (synthetic data only).")
+    t.add_argument("--ai-profile")
+    t.add_argument("--config", type=Path)
+
+    m = sub.add_parser("mcp", help="Model Context Protocol server.")
+    msub = m.add_subparsers(dest="mcp_command", required=True)
+    serve = msub.add_parser("serve", help="Serve DevGuard tools over MCP (stdio).")
+    serve.add_argument("--root", action="append", type=Path, default=[], help="Allowed scan root; repeatable.")
+    serve.add_argument(
+        "--expose-investigation-tools",
+        action="store_true",
+        help="Also expose read_file/search/decode/file_info (read-only).",
+    )
+    serve.add_argument("--config", type=Path)
+
+    sub.add_parser("doctor", help="Check the installation and configuration.")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "scan":
+            return _scan(args)
+        if args.command == "rules":
+            return _rules(args)
+        if args.command == "explain":
+            return _explain(args)
+        if args.command == "ai":
+            return _ai(args)
+        if args.command == "mcp":
+            from devguard.mcp.server import serve
+
+            cfg = load_config(args.config, None)
+            roots = args.root or [Path(p) for p in cfg.mcp.get("allowed_roots", [])]
+            return serve(roots, expose_investigation=args.expose_investigation_tools, config=cfg)
+        if args.command == "doctor":
+            return _doctor()
+    except ConfigError as exc:
+        print(f"devguard: configuration error: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    return EXIT_USAGE
+
+
+def _scan(args: argparse.Namespace) -> int:
+    from devguard.core.service import ScanError, ScanRequest, scan_detailed
+    from devguard.report.terminal import print_summary
+    from devguard.report.writer import render, write_reports
+
+    target: Path = args.path
+    if not target.exists() or not target.is_dir():
+        print(f"devguard: not a directory: {target}", file=sys.stderr)
+        return EXIT_USAGE
+    limits = {
+        "max_file_size": parse_size(args.max_file_size) if args.max_file_size else None,
+        "max_files": args.max_files,
+        "timeout_s": args.timeout,
+    }
+    overrides = {
+        "exclude": args.exclude or None,
+        "include_vendored": args.include_vendored or None,
+        "fail_on": args.fail_on,
+        "output_dir": args.output_dir,
+        "formats": args.formats,
+        "limits": limits,
+    }
+    out_dir = args.output_dir or None
+    if out_dir is not None and is_within(out_dir, target) and not args.allow_output_in_target:
+        print(
+            "devguard: --output-dir is inside the scan target; pass --allow-output-in-target to permit it",
+            file=sys.stderr,
+        )
+        return EXIT_USAGE
+    if out_dir is not None and is_within(out_dir, target):
+        overrides["output_dir"] = None  # validated above; config check would refuse it
+    cfg = load_config(args.config, target, overrides)
+    out_dir = out_dir or cfg.output_dir or default_output_dir(target)
+    skip = [out_dir] if is_within(out_dir, target) else []
+    try:
+        outcome = scan_detailed(ScanRequest(target=target, config=cfg, skip_dirs=skip))
+    except ScanError as exc:
+        print(f"devguard: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    result = outcome.result
+    if args.ai:
+        from devguard.ai.run import interactive_ask, run_ai
+
+        result.ai = run_ai(
+            outcome,
+            cfg.ai,
+            profile=args.ai_profile,
+            tools_enabled=not args.no_ai_tools,
+            assume_consent=args.yes_send_code,
+            use_cache=not args.no_ai_cache,
+            ask=interactive_ask,
+        )
+    formats = cfg.formats or ["md", "json"]
+    paths = write_reports(result, out_dir, formats, cfg.keep_runs)
+    summary_stream = sys.stderr if args.json else sys.stdout
+    if args.json:
+        sys.stdout.write(render(result, "json"))
+    if not args.quiet:
+        print_summary(result, paths, summary_stream, verbose=args.verbose)
+    if args.ai and args.ai_required and result.ai.status != "completed":
+        return EXIT_AI
+    if any(f.severity.rank >= cfg.fail_on.rank for f in result.findings):
+        return EXIT_FINDINGS
+    if result.status != "complete":
+        return EXIT_PARTIAL
+    return EXIT_OK
+
+
+def _rules(args: argparse.Namespace) -> int:
+    from devguard.core.service import default_analyzers
+    from devguard.rules.catalog import CATALOG
+
+    default_analyzers()  # registers every rule
+    import devguard.correlate.chains  # noqa: F401 - registers chain rules
+
+    metas = sorted(CATALOG.values(), key=lambda m: m.id)
+    if args.json:
+        print(
+            json.dumps(
+                [
+                    {
+                        "id": m.id,
+                        "title": m.title,
+                        "severity": m.severity.value,
+                        "confidence": m.confidence.value,
+                        "category": m.category,
+                        "threats": list(m.threat_refs),
+                    }
+                    for m in metas
+                ],
+                indent=2,
+            )
+        )
+        return EXIT_OK
+    for m in metas:
+        print(f"{m.id:<36} {m.severity.value:<8} {m.title}")
+    print(f"\n{len(metas)} rules (ruleset {RULESET_VERSION})")
+    return EXIT_OK
+
+
+def _explain(args: argparse.Namespace) -> int:
+    from devguard.core.service import default_analyzers
+    from devguard.rules.catalog import CATALOG
+
+    default_analyzers()
+    import devguard.correlate.chains  # noqa: F401
+
+    m = CATALOG.get(args.rule_id)
+    if m is None:
+        print(f"devguard: unknown rule {args.rule_id}", file=sys.stderr)
+        return EXIT_USAGE
+    print(f"{m.id}: {m.title}\n")
+    print(f"Severity: {m.severity.value}   Confidence: {m.confidence.value}   Category: {m.category}")
+    print(f"Threat catalog: {', '.join(m.threat_refs)}   Defined in: {m.origin}\n")
+    print(f"Why it matters:\n  {m.explanation}\n")
+    if m.benign_context:
+        print(f"Could be benign if:\n  {m.benign_context}\n")
+    print(f"Next step:\n  {m.next_step}")
+    return EXIT_OK
+
+
+def _ai(args: argparse.Namespace) -> int:
+    from devguard.ai.registry import AIConfig, ProviderError, available_entry_points, load_provider
+
+    cfg = load_config(getattr(args, "config", None), None)
+    try:
+        ai_cfg = AIConfig.model_validate(cfg.ai)
+    except Exception as exc:
+        print(f"devguard: invalid [ai] configuration: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    if args.ai_command == "providers":
+        print("Installed providers:")
+        for name, origin in sorted(available_entry_points().items()):
+            print(f"  {name:<20} {origin}")
+        print("\nConfigured profiles:")
+        if not ai_cfg.profiles:
+            print("  none (add [ai.profiles.NAME] to your user config)")
+        for name, prof in sorted(ai_cfg.profiles.items()):
+            default = " (default)" if name == ai_cfg.default_profile else ""
+            where = prof.plugin if prof.provider == "python" else prof.provider
+            print(f"  {name:<20} {where} model={prof.model or '-'}{default}")
+        return EXIT_OK
+    from devguard.ai.testing import run_contract
+
+    try:
+        loaded = load_provider(ai_cfg, args.ai_profile, None)
+    except ProviderError as exc:
+        print(f"devguard: {exc}", file=sys.stderr)
+        return EXIT_USAGE
+    print(f"Testing profile {loaded.profile_name} ({loaded.origin}) with synthetic data only…")
+    report = run_contract(loaded.provider, loaded.profile.model)
+    for p in report.passed:
+        print(f"  PASS  {p}")
+    for n in report.notes:
+        print(f"  NOTE  {n}")
+    for f in report.failures:
+        print(f"  FAIL  {f}")
+    return EXIT_OK if report.ok else EXIT_FINDINGS
+
+
+def _doctor() -> int:
+    import importlib.util
+    import platform
+
+    from devguard.ai.registry import AIConfig, available_entry_points
+    from devguard.core.config import user_config_dir
+
+    print(f"devguard {__version__}, ruleset {RULESET_VERSION}, Python {platform.python_version()}")
+    cfg_file = user_config_dir() / "config.toml"
+    print(f"User config: {cfg_file} ({'found' if cfg_file.is_file() else 'not found'})")
+    try:
+        cfg = load_config(None, None)
+        ai_cfg = AIConfig.model_validate(cfg.ai)
+        print(f"AI profiles: {', '.join(sorted(ai_cfg.profiles)) or 'none'}")
+        import os
+
+        for name, prof in sorted(ai_cfg.profiles.items()):
+            for key, ref in prof.secrets.items():
+                state = "set" if ref.startswith("env:") and os.environ.get(ref[4:]) else "NOT SET"
+                print(f"  {name}.{key} ({ref.split(':')[0]}): {state}")
+    except Exception as exc:
+        print(f"Configuration problem: {exc}")
+    for mod, extra in (("anthropic", "anthropic"), ("openai", "openai"), ("mcp", "mcp")):
+        ok = importlib.util.find_spec(mod) is not None
+        print(f"Optional extra [{extra}]: {'installed' if ok else 'not installed'}")
+    print("Providers: " + ", ".join(sorted(available_entry_points())))
+    return EXIT_OK
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

devguard/core/config.py

@@ -0,0 +1,147 @@
+"""Scan configuration.
+
+Sources, lowest to highest precedence: defaults → user config file → --config file → CLI flags.
+Files inside the scan target are never read as configuration (SAFE-011, CFG-001).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from devguard.core.models import Severity
+
+
+class ConfigError(Exception):
+    """Invalid configuration or a configuration path that violates policy."""
+
+
+class Limits(BaseModel):
+    max_file_size: int = 2 * 1024 * 1024
+    max_files: int = 50_000
+    max_total_bytes: int = 500 * 1024 * 1024
+    max_depth: int = 40
+    timeout_s: float = 300.0
+    max_regex_text: int = 1024 * 1024
+
+
+class ScanConfig(BaseModel):
+    limits: Limits = Field(default_factory=Limits)
+    exclude: list[str] = Field(default_factory=list)
+    include_vendored: bool = False
+    fail_on: Severity = Severity.HIGH
+    output_dir: Path | None = None
+    formats: list[str] = Field(default_factory=lambda: ["md", "json"])
+    keep_runs: bool = True
+    ai: dict[str, Any] = Field(default_factory=dict)
+    mcp: dict[str, Any] = Field(default_factory=dict)
+
+    def summary(self) -> dict[str, Any]:
+        return {
+            "limits": self.limits.model_dump(),
+            "user_exclusions": list(self.exclude),
+            "include_vendored": self.include_vendored,
+            "fail_on": self.fail_on.value,
+        }
+
+
+def user_config_dir() -> Path:
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+        return Path(base) / "devguard"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "devguard"
+    return Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "devguard"
+
+
+def user_data_dir() -> Path:
+    if sys.platform == "win32":
+        base = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+        return Path(base) / "devguard"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "devguard"
+    return Path(os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share") / "devguard"
+
+
+def is_within(path: Path, root: Path) -> bool:
+    try:
+        path.resolve().relative_to(root.resolve())
+    except ValueError:
+        return False
+    return True
+
+
+def default_output_dir(target: Path) -> Path:
+    resolved = target.resolve()
+    digest = hashlib.sha256(str(resolved).encode()).hexdigest()[:8]
+    return user_data_dir() / "reports" / f"{resolved.name or 'root'}-{digest}"
+
+
+def _read_toml(path: Path, target: Path | None) -> dict[str, Any]:
+    if target is not None and is_within(path, target):
+        raise ConfigError(
+            f"Refusing to read configuration from inside the scan target: {path}. "
+            "A scanned repository must not be able to change DevGuard's policy."
+        )
+    try:
+        with path.open("rb") as fh:
+            return tomllib.load(fh)
+    except FileNotFoundError as exc:
+        raise ConfigError(f"Config file not found: {path}") from exc
+    except tomllib.TOMLDecodeError as exc:
+        raise ConfigError(f"Invalid TOML in {path}: {exc}") from exc
+
+
+def load_config(
+    explicit: Path | None,
+    target: Path | None,
+    overrides: dict[str, Any] | None = None,
+) -> ScanConfig:
+    data: dict[str, Any] = {}
+    user_file = user_config_dir() / "config.toml"
+    if user_file.is_file():
+        data = _merge(data, _read_toml(user_file, target))
+    if explicit is not None:
+        data = _merge(data, _read_toml(explicit.expanduser(), target))
+    scan_section = data.get("scan", {})
+    merged: dict[str, Any] = {
+        **scan_section,
+        "ai": data.get("ai", {}),
+        "mcp": data.get("mcp", {}),
+    }
+    if overrides:
+        limits_over = overrides.pop("limits", None)
+        merged = _merge(merged, {k: v for k, v in overrides.items() if v is not None})
+        if limits_over:
+            merged["limits"] = _merge(merged.get("limits", {}), {k: v for k, v in limits_over.items() if v})
+    try:
+        cfg = ScanConfig.model_validate(merged)
+    except Exception as exc:
+        raise ConfigError(f"Invalid configuration: {exc}") from exc
+    if target is not None and cfg.output_dir is not None and is_within(cfg.output_dir, target):
+        raise ConfigError("Output directory must be outside the scan target.")
+    return cfg
+
+
+def _merge(base: dict[str, Any], extra: dict[str, Any]) -> dict[str, Any]:
+    out = dict(base)
+    for key, value in extra.items():
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = _merge(out[key], value)
+        else:
+            out[key] = value
+    return out
+
+
+def parse_size(text: str) -> int:
+    units = {"k": 1024, "m": 1024**2, "g": 1024**3}
+    t = text.strip().lower().removesuffix("b")
+    if t and t[-1] in units:
+        return int(float(t[:-1]) * units[t[-1]])
+    return int(t)