skillguard-core 0.1.2__py3-none-any.whl

skillguard_core/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.2"

skillguard_core/cli.py

@@ -0,0 +1,170 @@
+import json
+import os
+import sys
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import asdict
+from pathlib import Path
+
+import tqdm
+import typer
+
+from skillguard_core.config import get_settings
+from skillguard_core.engines.cisco import CiscoScannerEngine
+from skillguard_core.engines.skillspector import SkillspectorEngine
+from skillguard_core.ingest.fetcher import discover_skills
+from skillguard_core.pipeline.scan import ScanReport, ScanService
+from skillguard_core.sarif import to_sarif, to_sarif_batch
+
+app = typer.Typer(no_args_is_help=True)
+
+EXIT_CODES = {"safe": 0, "caution": 1, "dangerous": 2, "inconclusive": 3}
+
+
+@app.command(hidden=True)
+def _version():
+    """Show version."""
+    from skillguard_core import __version__
+
+    typer.echo(f"skillguard-core {__version__}")
+
+
+def _engines() -> list:
+    settings = get_settings()
+    return [
+        SkillspectorEngine(binary=settings.skillspector_bin, timeout_s=settings.scan_timeout_s),
+        CiscoScannerEngine(binary=settings.cisco_bin, policy=settings.cisco_policy, timeout_s=settings.scan_timeout_s),
+    ]
+
+
+def _is_skills_dir(target: str) -> bool:
+    try:
+        path = Path(target).expanduser().resolve()
+        return path.is_dir() and not (path / "SKILL.md").exists() and any(
+            d.is_dir() and (d / "SKILL.md").exists() for d in path.iterdir()
+        )
+    except OSError:
+        return False
+
+
+def _format_report(report, json_output: bool, sarif: bool):
+    if sarif:
+        return json.dumps(to_sarif(report), indent=2)
+    if json_output:
+        return json.dumps(asdict(report), indent=2)
+    lines = [f"{report.skill_name}: {report.verdict.upper()} (score {report.fused_score})"]
+    if report.llm_reviewed:
+        lines.append(f"  [llm] verdict '{report.llm_verdict}', confidence {report.llm_confidence:.0%}: {report.llm_rationale}")
+    elif report.llm_skipped_reason:
+        lines.append(f"  [info] --use-llm skipped: {report.llm_skipped_reason}")
+    for f in report.findings:
+        lines.append(f"  [{f.severity}] {f.engine}/{f.rule_id}: {f.title} ({f.file_path})")
+    return "\n".join(lines)
+
+
+@app.command()
+def scan(
+    target: str = typer.Argument(...),
+    use_llm: bool = False,
+    json_output: bool = typer.Option(False, "--json"),
+    sarif: bool = typer.Option(False, "--sarif"),
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Stream results as each skill is scanned"),
+    workers: int = typer.Option(os.cpu_count() or 1, "--workers", "-w", help="Parallel scan workers (default: CPU count)"),
+) -> None:
+    """Scan a skill directory, git URL, or zip URL."""
+    if json_output and sarif:
+        typer.echo("error: --json and --sarif are mutually exclusive", err=True)
+        raise typer.Exit(3)
+    service = ScanService(engines=_engines(), reviewer=_try_get_reviewer(use_llm))
+
+    if _is_skills_dir(target):
+        if json_output or sarif:
+            try:
+                reports = service.scan_directory(target, use_llm=use_llm, max_workers=workers)
+            except Exception as exc:  # noqa: BLE001
+                typer.echo(f"error: {exc}", err=True)
+                raise typer.Exit(3)
+            if json_output:
+                typer.echo(json.dumps([asdict(r) for r in reports], indent=2))
+            else:
+                typer.echo(json.dumps(to_sarif_batch(reports), indent=2))
+            raise typer.Exit(max(EXIT_CODES.get(r.verdict, 0) for r in reports))
+
+        skill_dirs = discover_skills(Path(target))
+        results: dict[int, ScanReport] = {}
+        with tqdm.tqdm(total=len(skill_dirs), unit="skill", file=sys.stderr) as pbar, \
+                ThreadPoolExecutor(max_workers=workers) as pool:
+            futures = {pool.submit(service.scan_target, str(d.path), use_llm=use_llm): i for i, d in enumerate(skill_dirs)}
+            for future in as_completed(futures):
+                idx = futures[future]
+                report = _safe_scan(future, skill_dirs[idx])
+                results[idx] = report
+                tag = _verdict_tag(report.verdict)
+                pbar.set_description(f"{tag} {report.skill_name}")
+                if verbose:
+                    tqdm.tqdm.write(_format_report(report, False, False), file=sys.stderr)
+                    tqdm.tqdm.write("", file=sys.stderr)
+                pbar.update(1)
+        reports = [results[i] for i in range(len(skill_dirs))]
+        _print_summary(reports)
+        raise typer.Exit(max(EXIT_CODES.get(r.verdict, 0) for r in reports))
+
+    try:
+        report = service.scan_target(target, use_llm=use_llm)
+    except Exception as exc:  # noqa: BLE001
+        typer.echo(f"error: {exc}", err=True)
+        raise typer.Exit(3)
+    typer.echo(_format_report(report, json_output, sarif))
+    raise typer.Exit(EXIT_CODES.get(report.verdict, 3))
+
+
+def _safe_scan(future, d) -> ScanReport:
+    try:
+        return future.result()
+    except Exception as exc:  # noqa: BLE001
+        return ScanReport(
+            skill_name=d.name, origin="local", source_url="", version_ref="",
+            content_hash="", engines=[], fused_score=0, severity="unknown",
+            verdict="inconclusive", llm_skipped_reason=str(exc),
+        )
+
+
+def _verdict_tag(verdict: str) -> str:
+    tags = {"dangerous": "⚠ ", "caution": "⚡", "safe": "✓ ", "inconclusive": "? "}
+    return tags.get(verdict, "  ")
+
+
+def _get_reviewer():
+    from skillguard_core.semantic.reviewer import build_reviewer
+
+    return build_reviewer()
+
+
+def _try_get_reviewer(use_llm: bool):
+    if not use_llm:
+        return None
+    try:
+        return _get_reviewer()
+    except ImportError:
+        typer.echo(
+            "error: --use-llm requires the 'ai' extra. Install with: pipx install skillguard-core[ai]",
+            err=True,
+        )
+        raise typer.Exit(3)
+
+
+def _print_summary(reports: list[ScanReport]):
+    verdict_colors = {"dangerous": typer.colors.RED, "caution": typer.colors.YELLOW, "safe": typer.colors.GREEN}
+    verdicts = Counter(r.verdict for r in reports)
+    total = len(reports)
+    typer.echo()
+    for verdict in ("dangerous", "caution", "safe"):
+        count = verdicts.get(verdict, 0)
+        if count:
+            color = verdict_colors.get(verdict)
+            typer.secho(f"  {verdict.upper():<12} {count:>3}/{total}", fg=color)
+    typer.echo(f"  {'total':<12} {total:>3}")
+    typer.echo()
+    for r in sorted(reports, key=lambda r: (EXIT_CODES.get(r.verdict, 99), r.skill_name)):
+        tag = _verdict_tag(r.verdict)
+        typer.secho(f"  {tag} {r.skill_name} (score {r.fused_score})", fg=verdict_colors.get(r.verdict))

skillguard_core/config.py

@@ -0,0 +1,28 @@
+from functools import lru_cache
+
+from dotenv import load_dotenv
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+load_dotenv()
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_prefix="SKILLGUARD_", env_file=".env", extra="ignore")
+
+    ingest_max_bytes: int = 100 * 1024 * 1024
+    ingest_max_zip_members: int = 10_000
+    scan_timeout_s: int = 300
+    skillspector_bin: str = "skillspector"
+    cisco_bin: str = "skill-scanner"
+    cisco_policy: str = "balanced"
+    semantic_model: str = "claude-sonnet-4-5"
+    anthropic_api_key: str = ""
+    llm_api_key: str = ""
+    llm_base_url: str = ""
+    danger_min: int = 70
+    caution_min: int = 30
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

skillguard_core/engines/base.py

@@ -0,0 +1,54 @@
+import hashlib
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+SEVERITIES = ("low", "medium", "high", "critical")
+SEVERITY_ALIASES = {
+    "info": "low",
+    "minor": "low",
+    "warning": "medium",
+    "severe": "high",
+    "crit": "critical",
+}
+
+Runner = Callable[..., subprocess.CompletedProcess]
+
+
+def normalize_severity(value: str | None) -> str:
+    v = (value or "").strip().lower()
+    v = SEVERITY_ALIASES.get(v, v)
+    return v if v in SEVERITIES else "medium"
+
+
+def truncate_evidence(text: str | None, limit: int = 400) -> str:
+    if not text:
+        return ""
+    text = text.strip()
+    return text[:limit] + ("…" if len(text) > limit else "")
+
+
+def make_fingerprint(engine: str, rule_id: str, file_path: str, title: str) -> str:
+    raw = f"{engine}|{rule_id}|{file_path}|{title}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:32]
+
+
+@dataclass(slots=True)
+class EngineFinding:
+    engine: str
+    rule_id: str
+    category: str
+    title: str
+    severity: str
+    file_path: str = ""
+    evidence: str = ""
+    fingerprint: str = ""
+
+
+@dataclass(slots=True)
+class EngineResult:
+    engine: str
+    score: int | None = None
+    findings: list[EngineFinding] = field(default_factory=list)
+    error: str | None = None
+    duration_ms: int = 0

skillguard_core/engines/cisco.py

@@ -0,0 +1,68 @@
+import json
+import subprocess
+import time
+from pathlib import Path
+
+from skillguard_core.engines.base import (
+    EngineFinding,
+    EngineResult,
+    Runner,
+    make_fingerprint,
+    normalize_severity,
+    truncate_evidence,
+)
+
+
+class CiscoScannerEngine:
+    name = "cisco"
+
+    def __init__(
+        self,
+        binary: str = "skill-scanner",
+        policy: str = "balanced",
+        timeout_s: int = 300,
+        runner: Runner = subprocess.run,
+    ):
+        self.binary = binary
+        self.policy = policy
+        self.timeout_s = timeout_s
+        self.runner = runner
+
+    def scan(self, path: Path) -> EngineResult:
+        started = time.monotonic()
+        cmd = [self.binary, "scan", str(path), "--policy", self.policy, "--format", "json"]
+        try:
+            proc = self.runner(cmd, capture_output=True, text=True, timeout=self.timeout_s)
+        except subprocess.TimeoutExpired:
+            return EngineResult(engine=self.name, error=f"timeout after {self.timeout_s}s", duration_ms=self._ms(started))
+        except OSError as exc:
+            return EngineResult(engine=self.name, error=f"runner failed: {exc}", duration_ms=self._ms(started))
+        stdout = (proc.stdout or "").strip()
+        if not stdout:
+            tail = (proc.stderr or "").strip()[-2000:]
+            return EngineResult(engine=self.name, error=f"no json output: {tail}", duration_ms=self._ms(started))
+        try:
+            data = json.loads(stdout)
+        except json.JSONDecodeError as exc:
+            return EngineResult(engine=self.name, error=f"invalid json: {exc}", duration_ms=self._ms(started))
+        return self._parse(data, started)
+
+    def _parse(self, data: dict, started: float) -> EngineResult:
+        findings: list[EngineFinding] = []
+        for f in data.get("findings") or []:
+            finding = EngineFinding(
+                engine=self.name,
+                rule_id=str(f.get("id") or f.get("rule_id") or ""),
+                category=str(f.get("category") or ""),
+                title=str(f.get("title") or f.get("description") or ""),
+                severity=normalize_severity(f.get("severity")),
+                file_path=str(f.get("path") or f.get("file") or ""),
+                evidence=truncate_evidence(f.get("snippet") or f.get("evidence")),
+            )
+            finding.fingerprint = make_fingerprint(self.name, finding.rule_id, finding.file_path, finding.title)
+            findings.append(finding)
+        return EngineResult(engine=self.name, score=None, findings=findings, duration_ms=self._ms(started))
+
+    @staticmethod
+    def _ms(started: float) -> int:
+        return int((time.monotonic() - started) * 1000)

skillguard_core/engines/fusion.py

@@ -0,0 +1,49 @@
+from dataclasses import dataclass
+
+from skillguard_core.engines.base import EngineResult
+
+SEVERITY_SCORES = {"critical": 95, "high": 80, "medium": 50, "low": 20}
+
+
+@dataclass(slots=True)
+class FusedVerdict:
+    score: int
+    severity: str
+    verdict: str
+    engine_errors: dict[str, str]
+
+
+def engine_score(result: EngineResult) -> int:
+    score = 0
+    if result.score is not None:
+        score = max(0, min(100, result.score))
+    if result.findings:
+        score = max(score, *(SEVERITY_SCORES.get(f.severity, 0) for f in result.findings))
+    return score
+
+
+def score_to_severity(score: int) -> str:
+    if score >= 90:
+        return "critical"
+    if score >= 70:
+        return "high"
+    if score >= 30:
+        return "medium"
+    if score > 0:
+        return "low"
+    return "none"
+
+
+def fuse(results: list[EngineResult], danger_min: int = 70, caution_min: int = 30) -> FusedVerdict:
+    errors = {r.engine: r.error for r in results if r.error}
+    valid = [r for r in results if r.error is None]
+    if not valid:
+        return FusedVerdict(score=0, severity="unknown", verdict="inconclusive", engine_errors=errors)
+    score = max(engine_score(r) for r in valid)
+    if score >= danger_min:
+        verdict = "dangerous"
+    elif score >= caution_min:
+        verdict = "caution"
+    else:
+        verdict = "safe"
+    return FusedVerdict(score=score, severity=score_to_severity(score), verdict=verdict, engine_errors=errors)

skillguard_core/engines/skillspector.py

@@ -0,0 +1,75 @@
+import json
+import subprocess
+import tempfile
+import time
+from pathlib import Path
+
+from skillguard_core.engines.base import (
+    EngineFinding,
+    EngineResult,
+    Runner,
+    make_fingerprint,
+    normalize_severity,
+    truncate_evidence,
+)
+
+
+class SkillspectorEngine:
+    name = "skillspector"
+
+    def __init__(self, binary: str = "skillspector", timeout_s: int = 300, runner: Runner = subprocess.run):
+        self.binary = binary
+        self.timeout_s = timeout_s
+        self.runner = runner
+
+    def scan(self, path: Path) -> EngineResult:
+        started = time.monotonic()
+        with tempfile.TemporaryDirectory() as td:
+            report_path = Path(td) / "report.json"
+            cmd = [
+                self.binary, "scan", str(path),
+                "--no-llm", "--format", "json", "--output", str(report_path),
+            ]
+            try:
+                proc = self.runner(cmd, capture_output=True, text=True, timeout=self.timeout_s)
+            except subprocess.TimeoutExpired:
+                return EngineResult(engine=self.name, error=f"timeout after {self.timeout_s}s", duration_ms=self._ms(started))
+            except OSError as exc:
+                return EngineResult(engine=self.name, error=f"runner failed: {exc}", duration_ms=self._ms(started))
+            if not report_path.exists():
+                tail = (proc.stderr or proc.stdout or "").strip()[-2000:]
+                return EngineResult(engine=self.name, error=f"no report produced: {tail}", duration_ms=self._ms(started))
+            try:
+                data = json.loads(report_path.read_text())
+            except (json.JSONDecodeError, OSError) as exc:
+                return EngineResult(engine=self.name, error=f"cannot read report: {exc}", duration_ms=self._ms(started))
+        return self._parse(data, started)
+
+    def _parse(self, data: dict, started: float) -> EngineResult:
+        findings: list[EngineFinding] = []
+        items = data.get("issues") or data.get("findings") or []
+        for f in items:
+            loc = f.get("location") or {}
+            finding = EngineFinding(
+                engine=self.name,
+                rule_id=str(f.get("rule_id") or f.get("id") or ""),
+                category=str(f.get("category") or ""),
+                title=str(f.get("title") or f.get("pattern") or f.get("finding") or f.get("description") or ""),
+                severity=normalize_severity(f.get("severity")),
+                file_path=str(f.get("file") or loc.get("file") or f.get("path") or ""),
+                evidence=truncate_evidence(f.get("snippet") or f.get("code_snippet") or f.get("evidence") or f.get("finding")),
+            )
+            finding.fingerprint = make_fingerprint(self.name, finding.rule_id, finding.file_path, finding.title)
+            findings.append(finding)
+        risk = data.get("risk_assessment") or {}
+        score = data.get("risk_score") or risk.get("score")
+        return EngineResult(
+            engine=self.name,
+            score=int(score) if score is not None else None,
+            findings=findings,
+            duration_ms=self._ms(started),
+        )
+
+    @staticmethod
+    def _ms(started: float) -> int:
+        return int((time.monotonic() - started) * 1000)

skillguard_core/ingest/fetcher.py

@@ -0,0 +1,151 @@
+import hashlib
+import io
+import subprocess
+import tempfile
+import zipfile
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+import httpx
+
+
+class IngestLimitExceeded(RuntimeError):
+    pass
+
+
+@dataclass(slots=True)
+class Fetched:
+    path: Path
+    origin: str
+    source_url: str
+    version_ref: str
+
+
+def content_hash(root: Path) -> str:
+    digest = hashlib.sha256()
+    for file_path in sorted(p for p in root.rglob("*") if p.is_file() and not p.is_symlink()):
+        rel = file_path.relative_to(root).as_posix()
+        file_hash = hashlib.sha256(file_path.read_bytes()).hexdigest()
+        digest.update(f"{rel}:{file_hash}\n".encode())
+    return digest.hexdigest()
+
+
+def fetch(
+    target: str,
+    *,
+    tmp_root: Path,
+    max_bytes: int,
+    max_zip_members: int = 10_000,
+    client: httpx.Client | None = None,
+    git_runner: Callable[..., subprocess.CompletedProcess] = subprocess.run,
+    timeout_s: int = 120,
+) -> Fetched:
+    tmp_root.mkdir(parents=True, exist_ok=True)
+    if "://" not in target and not target.endswith(".git"):
+        local = Path(target).expanduser().resolve()
+        if not local.is_dir():
+            raise FileNotFoundError(f"not a directory: {target}")
+        if not (local / "SKILL.md").exists():
+            raise FileNotFoundError(f"no SKILL.md found in '{target}'")
+        return Fetched(path=local, origin="local", source_url=str(local), version_ref="")
+
+    workdir = Path(tempfile.mkdtemp(dir=tmp_root))
+    if target.endswith(".zip") or "/zipball/" in target:
+        _download_zip(target, workdir, max_bytes, max_zip_members, client, timeout_s)
+        return Fetched(
+            path=_unwrap_single_dir(workdir), origin="zip", source_url=target, version_ref=""
+        )
+
+    version_ref = _git_clone(target, workdir, git_runner, timeout_s)
+    return Fetched(
+        path=workdir / "repo", origin="git", source_url=target, version_ref=version_ref
+    )
+
+
+def discover_skills(root: Path) -> list[Fetched]:
+    root = root.expanduser().resolve()
+    if not root.is_dir():
+        raise FileNotFoundError(f"not a directory: {root}")
+    subdirs = sorted(
+        d for d in root.iterdir() if d.is_dir() and (d / "SKILL.md").exists()
+    )
+    if (root / "SKILL.md").exists():
+        subdirs.insert(0, root)
+    if not subdirs:
+        raise FileNotFoundError(f"no SKILL.md found in '{root}'")
+    return [
+        Fetched(path=d, origin="local", source_url=str(d), version_ref="")
+        for d in subdirs
+    ]
+
+
+def _download_zip(
+    url: str,
+    dest: Path,
+    max_bytes: int,
+    max_zip_members: int,
+    client: httpx.Client | None,
+    timeout_s: int,
+) -> None:
+    own_client = client is None
+    client = client or httpx.Client(follow_redirects=True, timeout=timeout_s)
+    try:
+        data = bytearray()
+        with client.stream("GET", url) as response:
+            response.raise_for_status()
+            for chunk in response.iter_bytes():
+                data.extend(chunk)
+                if len(data) > max_bytes:
+                    raise IngestLimitExceeded(f"download exceeds {max_bytes} bytes")
+        buf = io.BytesIO(bytes(data))
+        with zipfile.ZipFile(buf) as zf:
+            members = zf.infolist()
+            if len(members) > max_zip_members:
+                raise IngestLimitExceeded(
+                    f"zip has {len(members)} members (cap {max_zip_members})"
+                )
+            total = sum(m.file_size for m in members)
+            if total > max_bytes:
+                raise IngestLimitExceeded(
+                    f"uncompressed size {total} exceeds {max_bytes} bytes"
+                )
+            for member in members:
+                member_path = Path(member.filename)
+                if member_path.is_absolute() or ".." in member_path.parts:
+                    raise IngestLimitExceeded(f"unsafe zip entry: {member.filename}")
+            zf.extractall(dest)
+    finally:
+        if own_client:
+            client.close()
+
+
+def _git_clone(
+    url: str,
+    workdir: Path,
+    runner: Callable[..., subprocess.CompletedProcess],
+    timeout_s: int,
+) -> str:
+    dest = workdir / "repo"
+    clone = runner(
+        ["git", "clone", "--depth", "1", url, str(dest)],
+        capture_output=True,
+        text=True,
+        timeout=timeout_s,
+    )
+    if clone.returncode != 0:
+        raise RuntimeError(f"git clone failed: {(clone.stderr or '').strip()[-2000:]}")
+    rev = runner(
+        ["git", "-C", str(dest), "rev-parse", "HEAD"],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    return rev.stdout.strip()
+
+
+def _unwrap_single_dir(workdir: Path) -> Path:
+    entries = list(workdir.iterdir())
+    if len(entries) == 1 and entries[0].is_dir():
+        return entries[0]
+    return workdir