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

skill_sentry_cli/core/verdict/sarif_report.py

@@ -0,0 +1,139 @@
+"""SARIF 2.1.0 report writer (docs/05-api-reference.md §5.6)."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+from urllib.parse import quote
+
+from skill_sentry_cli.core.contracts import Finding, Severity, Verdict, format_utc, utc_now
+from skill_sentry_cli.core.version import ENGINE_VERSION
+
+SARIF_SCHEMA = "https://json.schemastore.org/sarif-2.1.0.json"
+LEVEL_BY_SEVERITY: dict[Severity, str] = {
+    Severity.CRITICAL: "error",
+    Severity.HIGH: "error",
+    Severity.MEDIUM: "warning",
+    Severity.LOW: "note",
+    Severity.NOTE: "note",
+}
+
+
+def _slug(value: str, *, fallback: str = "finding", max_length: int = 64) -> str:
+    slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
+    return (slug or fallback)[:max_length].strip("-") or fallback
+
+
+def rule_id(finding: Finding) -> str:
+    """``skillsentry/<stage>/<type>`` — §5.6."""
+    kind = finding.finding_type or _slug(finding.message)
+    return f"skillsentry/{finding.stage.value}/{_slug(kind)}"
+
+
+def _artifact_uri(path: str | None) -> str | None:
+    if not path:
+        return None
+    normalised = path.replace("\\", "/").lstrip("/")
+    while normalised.startswith("./"):
+        normalised = normalised[2:]
+    return quote(normalised, safe="/-._~")
+
+
+def _result(finding: Finding, rule_index: int) -> dict[str, Any]:
+    result: dict[str, Any] = {
+        "ruleId": rule_id(finding),
+        "ruleIndex": rule_index,
+        "level": LEVEL_BY_SEVERITY[finding.severity],
+        "message": {"text": finding.message},
+        "properties": {
+            "stage": finding.stage.value,
+            "severity": finding.severity.value,
+            "evidence": finding.evidence.model_dump(by_alias=True, mode="json", exclude_none=True),
+        },
+    }
+    uri = _artifact_uri(finding.evidence.file)
+    if uri:
+        physical: dict[str, Any] = {"artifactLocation": {"uri": uri}}
+        if finding.evidence.line:
+            physical["region"] = {"startLine": finding.evidence.line}
+        result["locations"] = [{"physicalLocation": physical}]
+    return result
+
+
+def build_sarif(
+    verdict: Verdict,
+    *,
+    generated_at=None,
+    decision: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build a schema-shaped SARIF 2.1.0 document for one verdict."""
+    rules: dict[str, dict[str, Any]] = {}
+    results: list[dict[str, Any]] = []
+
+    for finding in verdict.findings:
+        rid = rule_id(finding)
+        if rid not in rules:
+            rules[rid] = {
+                "id": rid,
+                "name": _slug(rid.rsplit("/", 1)[-1], fallback="finding"),
+                "shortDescription": {"text": finding.message},
+                "helpUri": "https://github.com/skillsentry/skillsentry#readme",
+                "defaultConfiguration": {"level": LEVEL_BY_SEVERITY[finding.severity]},
+                "properties": {
+                    "stage": finding.stage.value,
+                    "severity": finding.severity.value,
+                    "tags": [finding.stage.value, finding.severity.value],
+                },
+            }
+        results.append(_result(finding, list(rules).index(rid)))
+
+    run_properties: dict[str, Any] = {
+        "verdict": verdict.verdict.value,
+        "riskScore": verdict.risk_score,
+        "confidence": verdict.confidence,
+        "cached": verdict.cached,
+        "skill": verdict.skill,
+        "skillId": str(verdict.skill_id),
+        "scanId": str(verdict.scan_id),
+        "engineVersion": ENGINE_VERSION,
+        "generatedAt": format_utc(generated_at or utc_now()),
+    }
+    if verdict.active_defense is not None:
+        run_properties["activeDefense"] = verdict.active_defense.model_dump(
+            by_alias=True, mode="json", exclude_none=False
+        )
+    if decision is not None:
+        # Report-safe summary only; see skill_sentry_cli.core.decisions.report.
+        run_properties["decisionLayer"] = decision
+
+    return {
+        "$schema": SARIF_SCHEMA,
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "SkillSentry",
+                        "informationUri": "https://github.com/skillsentry/skillsentry",
+                        "version": ENGINE_VERSION,
+                        "semanticVersion": ENGINE_VERSION,
+                        "rules": list(rules.values()),
+                    }
+                },
+                "automationDetails": {"id": f"skillsentry/{verdict.scan_id}"},
+                "invocations": [{"executionSuccessful": True}],
+                "results": results,
+                "properties": run_properties,
+                "columnKind": "utf16CodeUnits",
+            }
+        ],
+    }
+
+
+def build_sarif_text(verdict: Verdict) -> str:
+    import json
+
+    return json.dumps(build_sarif(verdict, generated_at=utc_now()), indent=2) + "\n"
+
+
+__all__ = ["LEVEL_BY_SEVERITY", "SARIF_SCHEMA", "build_sarif", "build_sarif_text", "rule_id"]

skill_sentry_cli/core/verdict/status.py

@@ -0,0 +1,35 @@
+"""What a scan's result says about completeness, shared by every renderer.
+
+A verdict is only as complete as its stages.  When a stage degraded, the scan did
+not read everything it should have, so a SAFE or SUSPICIOUS result is shown as
+``UNSCANNED`` with the reason.  A MALICIOUS verdict is conclusive evidence and is
+never downgraded to "unscanned" by another stage's failure.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+from skill_sentry_cli.core.contracts import StageResult, VerdictTier
+
+UNSCANNED = "UNSCANNED"
+
+
+def is_unscanned(verdict: VerdictTier, stage_results: Sequence[StageResult] | None) -> bool:
+    if verdict == VerdictTier.MALICIOUS:
+        return False
+    return any(result.degraded for result in stage_results or ())
+
+
+def degraded_reason(stage_results: Sequence[StageResult] | None) -> str:
+    for result in stage_results or ():
+        if result.degraded:
+            return f"{result.stage.value} degraded: {result.error or 'not fully analysed'}"
+    return "not fully analysed"
+
+
+def shown_status(verdict: VerdictTier, stage_results: Sequence[StageResult] | None) -> str:
+    return UNSCANNED if is_unscanned(verdict, stage_results) else verdict.value
+
+
+__all__ = ["UNSCANNED", "degraded_reason", "is_unscanned", "shown_status"]

skill_sentry_cli/core/verdict/stix_report.py

@@ -0,0 +1,132 @@
+"""STIX 2.1 IOC bundle writer (docs/05-api-reference.md §5.7)."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime
+from typing import Any
+from uuid import uuid4
+
+from skill_sentry_cli.core.contracts import Verdict, format_utc, utc_now
+from skill_sentry_cli.core.version import ENGINE_VERSION
+
+_IPV4_RE = re.compile(r"^(?:\d{1,3}\.){3}\d{1,3}$")
+
+
+class NoIOCsError(RuntimeError):
+    """Raised when a STIX export is requested for a scan without IOCs."""
+
+
+def _pattern_for(value: str) -> tuple[str, str]:
+    if value.startswith(("http://", "https://")):
+        return "url", f"[url:value = '{value}']"
+    if _IPV4_RE.match(value):
+        return "ipv4-addr", f"[ipv4-addr:value = '{value}']"
+    return "domain-name", f"[domain-name:value = '{value}']"
+
+
+def _sdo(object_type: str, **fields: Any) -> dict[str, Any]:
+    return {"type": object_type, "spec_version": "2.1", "id": f"{object_type}--{uuid4()}", **fields}
+
+
+def build_stix(verdict: Verdict, *, generated_at: datetime | None = None) -> dict[str, Any]:
+    """Build a STIX 2.1 bundle, or raise when active defense did not trigger."""
+    active = verdict.active_defense
+    if active is None or not active.triggered:
+        raise NoIOCsError("no_iocs")
+    indicators = [value for value in active.c2_indicators if value]
+    if not indicators:
+        raise NoIOCsError("no_iocs")
+
+    created = generated_at or utc_now()
+    stamp = format_utc(created)
+    identity_id = f"identity--{uuid4()}"
+    malware_id = f"malware--{uuid4()}"
+
+    objects: list[dict[str, Any]] = [
+        _sdo(
+            "identity",
+            created=stamp,
+            modified=stamp,
+            name="SkillSentry 2.0",
+            description="Local-first Agent Skill supply-chain auditor.",
+            identity_class="system",
+            x_skillsentry_engine_version=ENGINE_VERSION,
+        ),
+        _sdo(
+            "malware",
+            created=stamp,
+            modified=stamp,
+            created_by_ref=identity_id,
+            name=verdict.skill,
+            description=(
+                f"Agent Skill flagged {verdict.verdict.value} with risk "
+                f"{verdict.risk_score}/100. {active.actual_behavior or ''}".strip()
+            ),
+            is_family=False,
+            labels=["malicious-activity"],
+            confidence=max(0, min(100, round(verdict.confidence * 100))),
+            x_skillsentry_scan_id=str(verdict.scan_id),
+            x_skillsentry_skill_id=str(verdict.skill_id),
+            x_skillsentry_canary_marker=active.canary_marker,
+            x_skillsentry_exfil_channel=(
+                active.exfil_channel.value if active.exfil_channel else None
+            ),
+            x_skillsentry_encoding=active.encoding,
+        ),
+    ]
+
+    for value in indicators:
+        ioc_type, pattern = _pattern_for(value)
+        indicator_id = f"indicator--{uuid4()}"
+        objects.append(
+            _sdo(
+                "indicator",
+                created=stamp,
+                modified=stamp,
+                created_by_ref=identity_id,
+                name=f"C2 {ioc_type} {value}",
+                description=(
+                    f"Observed in sandboxed {active.exfil_channel.value if active.exfil_channel else 'egress'} "
+                    f"traffic while serving canary {active.canary_marker or 'material'}."
+                ),
+                indicator_types=["malicious-activity"],
+                pattern=pattern,
+                pattern_type="stix",
+                valid_from=stamp,
+                labels=["malicious-activity"],
+                confidence=100 if active.triggered else 50,
+                x_skillsentry_channel=(
+                    active.exfil_channel.value if active.exfil_channel else None
+                ),
+            )
+        )
+        objects.append(
+            _sdo(
+                "relationship",
+                created=stamp,
+                modified=stamp,
+                created_by_ref=identity_id,
+                relationship_type="indicates",
+                source_ref=malware_id,
+                target_ref=indicator_id,
+                description=f"{verdict.skill} exfiltrates to {value}",
+            )
+        )
+
+    return {
+        "type": "bundle",
+        "id": f"bundle--{uuid4()}",
+        "spec_version": "2.1",
+        "objects": objects,
+        "x_skillsentry_verdict": verdict.verdict.value,
+        "x_skillsentry_risk_score": verdict.risk_score,
+    }
+
+
+def build_stix_text(verdict: Verdict, *, generated_at: datetime | None = None) -> str:
+    return json.dumps(build_stix(verdict, generated_at=generated_at), indent=2) + "\n"
+
+
+__all__ = ["NoIOCsError", "build_stix", "build_stix_text"]

skill_sentry_cli/core/version.py

@@ -0,0 +1,38 @@
+"""Package metadata and engine version helpers.
+
+The engine version participates in the Stage-0 cache key.  Any change to the
+fusion weights is folded into the version string so cached verdicts produced
+under different scoring rules are never reused (docs/03-database.md §3.5).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+
+__version__ = "2.0.0"
+ENGINE_VERSION = __version__
+CONTRACT_VERSION = "1"
+GEMMA_BADGE = "Fully local analysis · open weights"
+
+DEFAULT_WEIGHTS: dict[str, float] = {
+    "anchors": 0.15,
+    "semantic": 0.20,
+    "vision": 0.20,
+    "sandbox": 0.25,
+}
+
+
+def weights_fingerprint(weights: Mapping[str, float] | None = None) -> str:
+    """Return a stable short fingerprint for a fusion-weight configuration."""
+    payload = json.dumps(dict(weights or DEFAULT_WEIGHTS), sort_keys=True, separators=(",", ":"))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()[:8]
+
+
+def engine_version(weights: Mapping[str, float] | None = None) -> str:
+    """Engine version including the scoring-weight fingerprint.
+
+    Example: ``2.0.0+a1b2c3d4``.
+    """
+    return f"{ENGINE_VERSION}+{weights_fingerprint(weights)}"

skill_sentry_cli/core/vision/__init__.py

@@ -0,0 +1,8 @@
+"""Bundled image extraction and vision analysis."""
+
+from __future__ import annotations
+
+from skill_sentry_cli.core.vision.image_extractor import ImageAsset, extract_images
+from skill_sentry_cli.core.vision.vision_scanner import scan_vision
+
+__all__ = ["ImageAsset", "extract_images", "scan_vision"]

skill_sentry_cli/core/vision/image_extractor.py

@@ -0,0 +1,91 @@
+"""Bounded image discovery and safe preview construction for vision analysis."""
+
+from __future__ import annotations
+
+import base64
+import mimetypes
+from dataclasses import dataclass
+from pathlib import Path
+
+from skill_sentry_cli.core.parser import SkillPackage
+
+IMAGE_SUFFIXES = frozenset(
+    {".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tif", ".tiff", ".svg"}
+)
+MAX_IMAGES = 20
+MAX_IMAGE_BYTES = 20 * 1024 * 1024
+MAX_PREVIEW_BYTES = 2 * 1024 * 1024
+
+
+@dataclass(frozen=True)
+class ImageAsset:
+    path: Path
+    relative: str
+    suffix: str
+    size: int
+    data: bytes
+    mime: str
+
+    @property
+    def is_svg(self) -> bool:
+        return self.suffix == ".svg"
+
+    def preview_uri(self) -> str:
+        payload = self.data
+        if len(payload) > MAX_PREVIEW_BYTES:
+            # The API schema needs a displayable string.  Do not inline
+            # arbitrarily large blobs into a verdict; give the UI a stable
+            # relative reference instead.
+            return f"skill-file:{self.relative}"
+        encoded = base64.b64encode(payload).decode("ascii")
+        return f"data:{self.mime};base64,{encoded}"
+
+
+def extract_images(package: SkillPackage) -> tuple[list[ImageAsset], list[str]]:
+    """Return image assets (bounded) and human-readable skip notes."""
+
+    assets: list[ImageAsset] = []
+    notes: list[str] = []
+    for path in package.files:
+        if len(assets) >= MAX_IMAGES:
+            notes.append(f"image limit reached ({MAX_IMAGES}); remaining images not scanned")
+            break
+        suffix = path.suffix.lower()
+        if suffix not in IMAGE_SUFFIXES:
+            continue
+        try:
+            size = path.stat().st_size
+        except OSError as exc:
+            notes.append(f"could not stat {path.name}: {exc}")
+            continue
+        if size > MAX_IMAGE_BYTES:
+            notes.append(f"{path.name} exceeds 20 MiB and was not scanned")
+            continue
+        try:
+            data = path.read_bytes()
+        except OSError as exc:
+            notes.append(f"could not read {path.name}: {exc}")
+            continue
+        mime = mimetypes.guess_type(path.name)[0] or (
+            "image/svg+xml" if suffix == ".svg" else "application/octet-stream"
+        )
+        assets.append(
+            ImageAsset(
+                path=path,
+                relative=path.relative_to(package.root).as_posix(),
+                suffix=suffix,
+                size=size,
+                data=data,
+                mime=mime,
+            )
+        )
+    return assets, notes
+
+
+__all__ = [
+    "IMAGE_SUFFIXES",
+    "MAX_IMAGES",
+    "MAX_IMAGE_BYTES",
+    "ImageAsset",
+    "extract_images",
+]