skill-sentry-cli 2.0.0__py3-none-any.whl

skill_sentry_cli/server/routes.py

@@ -0,0 +1,191 @@
+"""Shared REST + WebSocket routes (used by demo and live backends)."""
+
+from __future__ import annotations
+
+import asyncio
+from contextlib import suppress
+from uuid import UUID
+
+from fastapi import APIRouter, Query, Request, Response, WebSocket, WebSocketDisconnect
+
+from skill_sentry_cli.core.contracts import (
+    CacheStatsResponse,
+    DeleteCacheResponse,
+    ErrorResponse,
+    ExportFormat,
+    HealthResponse,
+    MetaResponse,
+    ScanListResponse,
+    ScanRequest,
+    ScanStartResponse,
+    ScanStatus,
+    ScanStatusResponse,
+    SkillDetail,
+    Stage,
+    VerdictsResponse,
+    WSEventType,
+    WSMessage,
+    utc_now,
+)
+from skill_sentry_cli.server.backend import ScanBackend
+from skill_sentry_cli.server.errors import ApiError
+
+router = APIRouter()
+
+
+def _backend(request: Request) -> ScanBackend:
+    return request.app.state.backend
+
+
+@router.post("/scan", response_model=ScanStartResponse, status_code=202)
+async def start_scan(payload: ScanRequest, request: Request) -> ScanStartResponse:
+    return await _backend(request).start_scan(payload)
+
+
+@router.get("/scans", response_model=ScanListResponse)
+async def list_scans(
+    request: Request,
+    limit: int = Query(default=100, ge=1, le=1000),
+    offset: int = Query(default=0, ge=0),
+    status: ScanStatus | None = Query(default=None),
+) -> ScanListResponse:
+    return await _backend(request).list_scans(limit=limit, offset=offset, status=status)
+
+
+@router.get("/scan/{scan_id}", response_model=ScanStatusResponse)
+async def get_scan(scan_id: UUID, request: Request) -> ScanStatusResponse:
+    return await _backend(request).get_scan(scan_id)
+
+
+@router.get("/scan/{scan_id}/verdicts", response_model=VerdictsResponse)
+async def get_verdicts(scan_id: UUID, request: Request) -> VerdictsResponse:
+    return await _backend(request).get_verdicts(scan_id)
+
+
+@router.get("/skills/{skill_id}", response_model=SkillDetail)
+async def get_skill(skill_id: UUID, request: Request) -> SkillDetail:
+    return await _backend(request).get_skill(skill_id)
+
+
+@router.get("/skills/{skill_id}/export")
+async def export_skill(
+    skill_id: UUID,
+    request: Request,
+    fmt: ExportFormat = Query(..., alias="format"),
+) -> Response:
+    report = _backend(request).export(skill_id, fmt)
+    return Response(
+        content=report.content,
+        media_type=report.media_type,
+        headers={"Content-Disposition": f'attachment; filename="{report.filename}"'},
+    )
+
+
+@router.get("/cache/stats", response_model=CacheStatsResponse)
+async def cache_stats(request: Request) -> CacheStatsResponse:
+    return await _backend(request).cache_stats()
+
+
+@router.delete("/cache", response_model=DeleteCacheResponse)
+async def clear_cache(
+    request: Request,
+    older_than: str | None = Query(default=None),
+) -> DeleteCacheResponse:
+    return await _backend(request).clear_cache(older_than)
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health(request: Request) -> HealthResponse:
+    return await _backend(request).health()
+
+
+@router.get("/meta", response_model=MetaResponse)
+async def meta(request: Request) -> MetaResponse:
+    return await _backend(request).meta()
+
+
+@router.websocket("/scan/{scan_id}/stream")
+async def scan_stream(websocket: WebSocket, scan_id: UUID) -> None:
+    await websocket.accept()
+    backend: ScanBackend = websocket.app.state.backend
+    cancel = asyncio.Event()
+
+    async def client_reader() -> None:
+        try:
+            while True:
+                message = await websocket.receive_json()
+                if isinstance(message, dict) and message.get("op") == "cancel":
+                    cancel.set()
+                    return
+        except (WebSocketDisconnect, RuntimeError, ValueError):
+            return
+
+    reader = asyncio.create_task(client_reader())
+    events = backend.stream(scan_id)
+    queue: asyncio.Queue[WSMessage | None] = asyncio.Queue(maxsize=64)
+
+    def error_message(exc: ApiError) -> WSMessage:
+        error: ErrorResponse = exc.to_response()
+        return WSMessage(
+            stage=exc.stage or Stage.VERDICT,
+            skill="",
+            event=WSEventType.ERROR,
+            ts=utc_now(),
+            detail=error.model_dump(by_alias=True, mode="json")["error"],
+        )
+
+    async def pump() -> None:
+        """Move backend events into a queue without cancelling the generator.
+
+        ``asyncio.wait_for(agen.__anext__(), ...)`` closes async generators
+        when it times out, which truncates slow stages.  The queue lets the
+        route poll for client cancellation while the producer runs freely.
+        """
+        try:
+            async for message in events:
+                await queue.put(message)
+        except ApiError as exc:
+            await queue.put(error_message(exc))
+        except Exception as exc:
+            await queue.put(
+                error_message(
+                    ApiError(
+                        500,
+                        "internal_error",
+                        f"stream failed: {exc}",
+                        degraded=True,
+                    )
+                )
+            )
+        finally:
+            await queue.put(None)
+
+    producer = asyncio.create_task(pump())
+    try:
+        while not cancel.is_set():
+            try:
+                message = await asyncio.wait_for(queue.get(), timeout=0.25)
+            except TimeoutError:
+                continue
+            if message is None:
+                break
+            await websocket.send_json(message.model_dump(by_alias=True, mode="json"))
+        if cancel.is_set():
+            with suppress(ApiError):
+                await backend.cancel(scan_id)
+    except WebSocketDisconnect:
+        pass
+    finally:
+        reader.cancel()
+        with suppress(asyncio.CancelledError):
+            await reader
+        producer.cancel()
+        with suppress(asyncio.CancelledError):
+            await producer
+        with suppress(Exception):
+            await events.aclose()
+        with suppress(RuntimeError):
+            await websocket.close()
+
+
+__all__ = ["router"]

skill_sentry_cli/skill/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: skillsentry-audit
+description: >-
+  Audit AI Agent Skills for malware before installation with SkillSentry, a
+  fully-local open-source scanner powered by Gemma 4. Use when the user asks to
+  audit a skill, scan a skill, check if a skill is safe, detect malicious
+  skills, review a SKILL.md package, or verify a skill from a registry such as
+  ClawHub before installing it. Runs an 8-stage inspection: SHA-256 incremental
+  cache, spec validation with typosquat detection, AST anchors fused with Gemma
+  semantic analysis, vision scanning for image-hidden prompt injection,
+  sandboxed execution with context-aware honeypots, Poisoned Well active
+  defense (fake credentials, exfil tracked to C2), sandbox-evasion detection,
+  weighted verdict fusion. Returns a SAFE, SUSPICIOUS, or MALICIOUS verdict
+  with a 0-100 risk score, line-accurate citations, and SARIF/STIX reports.
+  Trigger keywords: audit skill, scan skill, skill security, malicious skill,
+  pre-install check, SKILL.md review, supply-chain audit, typosquat check.
+---
+
+# SkillSentry Audit
+
+Pre-install security gate for Agent Skills. Everything runs **locally** (Ollama + Docker + SQLite) — audited skill content never leaves the machine unless the user explicitly enabled the Gemini API fallback.
+
+## When to use
+
+- Before installing any skill from a registry (ClawHub, marketplaces) or a third-party repo.
+- When re-auditing installed skills after upstream updates (supply-chain poisoning check).
+- When the user asks: *"is this skill safe?"*, *"scan this skill"*, *"audit SKILL.md"*, *"check for typosquats"*.
+
+## How to run
+
+Use the bundled script (preferred):
+
+```bash
+scripts/audit.sh <path-to-skill-directory> [extra skill-sentry-cli flags]
+```
+
+Equivalent direct CLI:
+
+```bash
+skill-sentry-cli scan <path-to-skill-directory> --fail-on malicious
+```
+
+Useful flags: `--demo-mode` (offline canned demo), `--no-cache` (force full re-scan), `--sarif-out report.sarif`, `--format json`, `--backend local|cloud`.
+
+## Interpreting results
+
+| Verdict | Risk score | Recommended action |
+|:---|:---|:---|
+| ✅ `SAFE` | < 30 | Install normally |
+| ⚠️ `SUSPICIOUS` | 30–70 | Review the cited `file:line` findings with the user before deciding |
+| 🚫 `MALICIOUS` | > 70, or hard-evidence override (confidence 1.0) | **Do not install.** Report the SARIF/STIX exports; note any C2 indicators |
+
+Always surface to the user: the verdict, risk score, top findings with `file:line` citations, whether the result was ⚡ cached (< 2 s), and — if triggered — the Poisoned Well summary (targeted assets, exfil channel, C2 indicators). Never suppress a `MALICIOUS` verdict, and never present a degraded scan (e.g., `sandbox-unavailable`) as a clean pass.
+
+## Requirements
+
+- `skill-sentry-cli` CLI installed (`pip install skill-sentry-cli`)
+- Ollama running with Gemma 4 E4B (Q4) pulled — or `--backend cloud` with `GEMINI_API_KEY`, or `--demo-mode`
+- Docker daemon available for sandbox stages (Stage 4/4.5/5); without it the scan degrades to static-only analysis and says so explicitly
+
+## Safety notes
+
+- SkillSentry never connects to attacker infrastructure; C2 indicators are harvested passively from the sinkhole.
+- All canary credentials served during analysis are fake by construction (marker `SKS-<8hex>`).
+- Audited packages are executed **only** inside the hardened sandbox (60 s, 512 MB, 1 CPU, sinkhole-only egress).
+
+*Powered by Gemma 4 · open weights.*

skill_sentry_cli/skill/scripts/audit.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# audit.sh — bundled entrypoint for the SkillSentry Agent Skill (skill_sentry_cli/skill/)
+#
+# Usage:
+#   scripts/audit.sh <path-to-skill-directory> [extra skill-sentry-cli flags]
+#
+# Examples:
+#   scripts/audit.sh ./some-downloaded-skill
+#   scripts/audit.sh ./some-downloaded-skill --sarif-out report.sarif
+#   scripts/audit.sh ./some-downloaded-skill --demo-mode
+#
+# Exit codes (CI contract, docs/07-cli-reference.md §7.5):
+#   0  all skills within --fail-on threshold (default: no MALICIOUS)
+#   1  verdict above threshold found  -> DO NOT INSTALL
+#   2  usage error
+#   3  operational error (Docker down, DB locked) — not a verdict
+#   4  model unavailable and no fallback enabled
+set -euo pipefail
+
+SKILL_DIR="${1:-}"
+[ $# -gt 0 ] && shift || true
+
+if [ -z "${SKILL_DIR}" ]; then
+  echo "usage: audit.sh <skill-directory> [extra skill-sentry-cli flags]" >&2
+  exit 2
+fi
+
+if [ ! -d "${SKILL_DIR}" ]; then
+  echo "error: '${SKILL_DIR}' is not a directory" >&2
+  exit 2
+fi
+
+if [ ! -f "${SKILL_DIR}/SKILL.md" ] && [ -z "$(find "${SKILL_DIR}" -maxdepth 2 -name SKILL.md -print -quit 2>/dev/null)" ]; then
+  echo "warning: no SKILL.md found under '${SKILL_DIR}' — scanning anyway (spec validation will flag it)" >&2
+fi
+
+if ! command -v skill-sentry-cli >/dev/null 2>&1; then
+  echo "error: skill-sentry-cli CLI not found — install with: pip install skill-sentry-cli" >&2
+  exit 3
+fi
+
+# Warn (don't fail) when sandbox dependencies are missing: the engine degrades
+# to static-only analysis and marks the verdict accordingly (fail-safe rule).
+command -v docker >/dev/null 2>&1 || echo "warning: Docker not found — sandbox stages will be skipped (verdict flagged 'sandbox-unavailable')" >&2
+curl -sf --max-time 2 "${OLLAMA_HOST:-http://localhost:11434}/api/tags" >/dev/null 2>&1 \
+  || echo "warning: Ollama not reachable — set --backend cloud or --demo-mode, otherwise semantic/vision stages degrade" >&2
+
+exec skill-sentry-cli scan "${SKILL_DIR}" --fail-on malicious "$@"

skill_sentry_cli/ui/dist/assets/index-Bf0h24IX.css

@@ -0,0 +1 @@
+:root{--lightningcss-light:initial;--lightningcss-dark: ;color-scheme:light dark;--bg:#f5f6f8;--surface:#fff;--fg:#161b26;--muted:#5b6475;--rule:#d9dee6;--accent:#1f5fa8;--ok:#1a7f4b;--ok-soft:#e2f3ea;--warn:#8a5a00;--warn-soft:#fbf0d9;--bad:#b42318;--bad-soft:#fbe6e4;--code-bg:#eef1f5;--radius:8px;font-family:system-ui,-apple-system,Segoe UI,Roboto,sans-serif;font-size:15px;line-height:1.5}@media (prefers-color-scheme:dark){:root{--lightningcss-light: ;--lightningcss-dark:initial}:root:not([data-theme=light]){--bg:#0e131b;--surface:#141b26;--fg:#e6eaf1;--muted:#9aa4b5;--rule:#26303f;--accent:#7eb3f0;--ok:#5fd39a;--ok-soft:#13291e;--warn:#f0c26b;--warn-soft:#2d2412;--bad:#ff8b82;--bad-soft:#3a1a18;--code-bg:#1b2330}}*{box-sizing:border-box}body{background:var(--bg);color:var(--fg);padding-left:max(16px, env(safe-area-inset-left,0px));padding-right:max(16px, env(safe-area-inset-right,0px));margin:0}a{color:var(--accent)}h1{margin:0;font-size:1.6rem}h2{margin:0;font-size:1.05rem}h3{margin:1.2rem 0 .4rem;font-size:.95rem}.app{max-width:1120px;margin:0 auto}.topbar{border-bottom:1px solid var(--rule);flex-wrap:wrap;align-items:center;gap:12px 20px;padding:14px 0;display:flex}.brand{color:var(--fg);font-weight:700;text-decoration:none}nav{gap:14px;display:flex}nav a{color:var(--muted);text-decoration:none}nav a[aria-current=page]{color:var(--fg);font-weight:600}.status{flex-wrap:wrap;align-items:center;gap:8px;margin-left:auto;display:flex}main{padding:20px 0 48px}.page-head{flex-wrap:wrap;justify-content:space-between;align-items:center;gap:12px;margin-bottom:14px;display:flex}.head-meta{align-items:center;gap:12px;display:flex}.pill{background:var(--code-bg);color:var(--muted);white-space:nowrap;border-radius:999px;padding:2px 9px;font-size:.75rem;font-weight:600;display:inline-block}.pill.ok{background:var(--ok-soft);color:var(--ok)}.pill.warn{background:var(--warn-soft);color:var(--warn)}.pill.bad{background:var(--bad-soft);color:var(--bad)}.pill.cached{margin-left:6px}.dot{color:var(--muted);font-size:.8rem}.dot:before{content:"";background:var(--bad);border-radius:50%;width:8px;height:8px;margin-right:5px;display:inline-block}.dot.ok:before{background:var(--ok)}.toolbar{flex-wrap:wrap;align-items:center;gap:10px 14px;margin-bottom:12px;display:flex}.chips{gap:6px;display:flex}.chip{border:1px solid var(--rule);background:var(--surface);color:var(--fg);cursor:pointer;font:inherit;border-radius:999px;padding:4px 12px;font-size:.85rem}.chip.active{border-color:var(--accent);color:var(--accent);font-weight:600}input[type=search],input[type=text],input[type=number],select{font:inherit;border:1px solid var(--rule);background:var(--surface);color:var(--fg);border-radius:6px;padding:6px 10px}input[type=text]{width:100%}button,.button{font:inherit;border:1px solid var(--accent);background:var(--accent);color:#fff;cursor:pointer;border-radius:6px;padding:7px 14px;font-weight:600;text-decoration:none;display:inline-block}button:disabled{opacity:.6;cursor:default}button.ghost{color:var(--accent);background:0 0}button.danger{background:var(--bad);border-color:var(--bad)}.table-wrap{border:1px solid var(--rule);border-radius:var(--radius);background:var(--surface);overflow-x:auto}table{border-collapse:collapse;width:100%;font-size:.92rem}th,td{text-align:left;border-bottom:1px solid var(--rule);vertical-align:top;padding:10px 12px}th{letter-spacing:.08em;text-transform:uppercase;color:var(--muted);font-size:.72rem}tr:last-child td{border-bottom:0}.finding-cell{max-width:360px}.risk{background:var(--code-bg);border-radius:999px;width:120px;height:18px;position:relative;overflow:hidden}.risk-fill{background:var(--accent);height:100%}.risk-value{place-items:center;font-size:.75rem;font-weight:700;display:grid;position:absolute;inset:0}.card{background:var(--surface);border:1px solid var(--rule);border-radius:var(--radius);min-width:0;margin-bottom:16px;padding:16px 18px}.card-head{justify-content:space-between;align-items:center;gap:12px;margin-bottom:10px;display:flex}.facts{grid-template-columns:max-content 1fr;gap:6px 16px;margin:0;display:grid}.facts dt{color:var(--muted)}.facts dd{overflow-wrap:anywhere;margin:0}.plain{gap:8px;margin:0;padding:0;list-style:none;display:grid}.findings li{overflow-wrap:anywhere}.code{background:var(--code-bg);white-space:pre;border-radius:6px;margin:6px 0;padding:8px 10px;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:.85rem;overflow-x:auto}.mono{overflow-wrap:anywhere;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:.86em}.code-findings{gap:12px;margin:0;padding:0;list-style:none;display:grid}.code-findings li{border-left:3px solid var(--rule);padding-left:12px}.code-findings li.highlight{border-left-color:var(--bad)}.code-head{flex-wrap:wrap;align-items:center;gap:8px;display:flex}.tabs{border-bottom:1px solid var(--rule);flex-wrap:wrap;gap:4px;margin-bottom:14px;display:flex}.tab{color:var(--muted);background:0 0;border:0;border-bottom:2px solid #0000;border-radius:0;padding:8px 12px}.tab.active{color:var(--fg);border-bottom-color:var(--accent)}.console{gap:4px;margin:0;padding-left:20px;font-family:ui-monospace,Menlo,Consolas,monospace;font-size:.85rem;display:grid}.scan-form{gap:16px;max-width:680px;display:grid}.field{gap:4px;display:grid}.field.inline{align-items:center;gap:10px;display:flex}.options{border:1px solid var(--rule);border-radius:var(--radius);gap:8px;padding:12px 16px;display:grid}.options label{align-items:center;gap:8px;display:flex}.actions{flex-wrap:wrap;align-items:center;gap:10px;display:flex}.error{background:var(--bad-soft);color:var(--bad);border-radius:6px;margin:10px 0;padding:10px 14px}.empty,.muted{color:var(--muted)}.nowrap{white-space:nowrap}.back{color:var(--muted);margin-bottom:8px;text-decoration:none;display:inline-block}.timeline{gap:4px;margin:0;padding-left:20px;display:grid}.vision{border-top:1px solid var(--rule);margin-top:10px;padding-top:10px}@media (width<=640px){.status{margin-left:0}.facts{grid-template-columns:1fr}.toolbar input[type=search]{flex:100%}}@media (prefers-reduced-motion:reduce){*{transition:none!important;animation:none!important}}