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

skill_sentry_cli/core/parser/skill_parser.py

@@ -0,0 +1,520 @@
+"""SKILL.md / package parsing and manifest validation."""
+
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from skill_sentry_cli.core.cache.hash_utils import HashError, hash_skill_dir
+
+MAX_SKILL_MD_BYTES = 1024 * 1024
+MAX_TEXT_FILE_BYTES = 1024 * 1024
+MAX_TEXT_TOTAL_BYTES = 4 * 1024 * 1024
+FRONTMATTER_MAX_BYTES = 256 * 1024
+
+_TEXT_SUFFIXES = frozenset(
+    {
+        ".md",
+        ".markdown",
+        ".txt",
+        ".py",
+        ".sh",
+        ".bash",
+        ".zsh",
+        ".fish",
+        ".js",
+        ".mjs",
+        ".cjs",
+        ".ts",
+        ".tsx",
+        ".jsx",
+        ".json",
+        ".yaml",
+        ".yml",
+        ".toml",
+        ".ini",
+        ".cfg",
+        ".ps1",
+        ".rb",
+        ".go",
+        ".rs",
+        ".java",
+        ".kt",
+        ".php",
+        ".pl",
+        ".lua",
+    }
+)
+
+_NAME_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$")
+_INTERPRETERS = frozenset({"python", "python3", "bash", "sh", "node", "deno", "ruby", "php"})
+_ENTRYPOINT_KEYS = (
+    "entrypoint",
+    "entry_point",
+    "entry",
+    "command",
+    "run",
+)
+
+
+class SkillParseError(RuntimeError):
+    """The directory is not a usable Agent Skill package."""
+
+
+@dataclass(frozen=True)
+class PackageIssue:
+    severity: str  # low | medium | high | critical
+    message: str
+    file: str = "SKILL.md"
+    line: int = 1
+    code: str | None = None
+
+
+@dataclass(frozen=True)
+class TextFile:
+    path: Path
+    relative: str
+    text: str
+    line_count: int
+    truncated: bool = False
+
+    def line(self, number: int) -> str | None:
+        if number < 1 or number > self.line_count:
+            return None
+        return self.text.splitlines()[number - 1]
+
+
+@dataclass
+class SkillPackage:
+    root: Path
+    name: str
+    description: str
+    declared_intent: str
+    manifest: dict[str, Any]
+    frontmatter: dict[str, Any]
+    body: str
+    skill_md: str
+    files: list[Path]
+    text_files: list[TextFile]
+    entrypoint: list[str] | None
+    entrypoint_declared: bool
+    content_hash: str
+    issues: list[PackageIssue] = field(default_factory=list)
+
+    @property
+    def metadata(self) -> dict[str, Any]:
+        return (
+            self.frontmatter.get("metadata")
+            if isinstance(self.frontmatter.get("metadata"), dict)
+            else {}
+        )
+
+    @property
+    def declared_network(self) -> list[str]:
+        permissions = self.frontmatter.get("permissions")
+        values: list[str] = []
+        if isinstance(permissions, str):
+            values.append(permissions)
+        elif isinstance(permissions, list):
+            values.extend(str(item) for item in permissions)
+        elif isinstance(permissions, dict):
+            network = permissions.get("network")
+            if isinstance(network, str):
+                values.append(network)
+            elif isinstance(network, list):
+                values.extend(str(item) for item in network)
+        for key in ("network", "networks", "allowed_domains"):
+            value = self.frontmatter.get(key)
+            if isinstance(value, str):
+                values.append(value)
+            elif isinstance(value, list):
+                values.extend(str(item) for item in value)
+        return values
+
+
+def _split_frontmatter(text: str) -> tuple[str, str, bool]:
+    """Return ``(yaml_text, body, present)`` for a leading YAML block."""
+
+    if not text.startswith("---"):
+        return "", text, False
+    first_newline = text.find("\n")
+    if first_newline == -1:
+        return "", text, False
+    if text[:first_newline].strip() != "---":
+        return "", text, False
+    # Accept CRLF as well as LF.  On Windows, checked-out SKILL.md files and
+    # Path.write_text() both commonly use CRLF; treating the trailing carriage
+    # return as content made every such manifest look like it had no
+    # frontmatter (and therefore produced a spurious high-severity issue).
+    closing = re.search(r"(?m)^---[ \t]*\r?$", text[first_newline + 1 :])
+    if closing is None:
+        return "", text, False
+    start = first_newline + 1
+    end = start + closing.start()
+    yaml_text = text[start:end]
+    body = text[start + closing.end() :]
+    return yaml_text, body.lstrip("\n"), True
+
+
+MAX_YAML_DEPTH = 10
+MAX_YAML_EVENTS = 20_000
+
+# Windows device names are reserved in every directory and with any extension.
+_RESERVED_DEVICE_NAMES = frozenset(
+    {"CON", "PRN", "AUX", "NUL"}
+    | {f"COM{index}" for index in range(1, 10)}
+    | {f"LPT{index}" for index in range(1, 10)}
+)
+
+
+def _path_name_issue(relative: str) -> str | None:
+    """Return an issue message for reserved device names or alternate data streams."""
+
+    for component in relative.split("/"):
+        base = component.split(".", 1)[0].rstrip(" ").upper()
+        if base in _RESERVED_DEVICE_NAMES:
+            return f"reserved device name in path: {relative}"
+        if ":" in component:
+            return f"alternate data stream notation in path: {relative}"
+    return None
+
+
+def _check_yaml_structure(yaml_text: str) -> None:
+    """Reject YAML that is deeply nested, uses aliases, or has too many nodes.
+
+    Aliases are refused outright: they are the vehicle for "billion laughs"
+    expansion, and skill frontmatter has no legitimate need for them.  The check
+    walks parser events, so nothing is expanded before it is judged.
+    """
+
+    depth = 0
+    events = 0
+    try:
+        for event in yaml.parse(yaml_text, Loader=yaml.SafeLoader):
+            events += 1
+            if events > MAX_YAML_EVENTS:
+                raise SkillParseError("frontmatter has too many YAML nodes")
+            if isinstance(event, yaml.AliasEvent):
+                raise SkillParseError("YAML aliases are not allowed in frontmatter")
+            if isinstance(event, (yaml.MappingStartEvent, yaml.SequenceStartEvent)):
+                depth += 1
+                if depth > MAX_YAML_DEPTH:
+                    raise SkillParseError(f"frontmatter nests deeper than {MAX_YAML_DEPTH} levels")
+            elif isinstance(event, (yaml.MappingEndEvent, yaml.SequenceEndEvent)):
+                depth -= 1
+    except yaml.YAMLError as exc:
+        raise SkillParseError(f"invalid YAML frontmatter: {exc}") from exc
+
+
+def _safe_yaml(yaml_text: str) -> dict[str, Any]:
+    if len(yaml_text.encode("utf-8", "replace")) > FRONTMATTER_MAX_BYTES:
+        raise SkillParseError("frontmatter exceeds 256 KiB")
+    _check_yaml_structure(yaml_text)
+    try:
+        loaded = yaml.safe_load(yaml_text)
+    except yaml.YAMLError as exc:
+        raise SkillParseError(f"invalid YAML frontmatter: {exc}") from exc
+    if loaded is None:
+        return {}
+    if not isinstance(loaded, dict):
+        raise SkillParseError("frontmatter must be a YAML mapping")
+    return loaded
+
+
+def _unread_reason(path: Path, remaining: int) -> str:
+    """Why a text candidate was not read, for the finding that reports it."""
+
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return "unreadable"
+    if size > MAX_TEXT_FILE_BYTES:
+        return f"larger than {MAX_TEXT_FILE_BYTES // (1024 * 1024)} MiB"
+    if remaining <= 0:
+        return "skill text budget exhausted"
+    return "binary or unreadable content"
+
+
+def _read_text(path: Path, relative: str, remaining: int) -> TextFile | None:
+    try:
+        size = path.stat().st_size
+    except OSError:
+        return None
+    if size > MAX_TEXT_FILE_BYTES or remaining <= 0:
+        return None
+    limit = min(size, remaining)
+    try:
+        with open(path, "rb") as handle:
+            data = handle.read(limit)
+    except OSError:
+        return None
+    if b"\x00" in data[:4096]:
+        return None
+    text = data.decode("utf-8", "replace")
+    return TextFile(
+        path=path,
+        relative=relative,
+        text=text,
+        line_count=len(text.splitlines()) or 1,
+        truncated=limit < size,
+    )
+
+
+def _is_text(relative: str) -> bool:
+    suffix = Path(relative).suffix.lower()
+    if suffix in _TEXT_SUFFIXES:
+        return True
+    # Extensionless scripts are common in skills (run, install, setup), at the
+    # root as well as in subdirectories.  Binary content is excluded later by
+    # the NUL-byte check in _read_text.
+    return suffix == ""
+
+
+def _resolve_entrypoint(
+    manifest: dict[str, Any], root: Path
+) -> tuple[list[str] | None, bool, PackageIssue | None]:
+    declared = False
+    raw: Any = None
+    for key in _ENTRYPOINT_KEYS:
+        if manifest.get(key) is not None:
+            raw = manifest[key]
+            declared = True
+            break
+    if not declared:
+        scripts = manifest.get("scripts")
+        if isinstance(scripts, dict) and scripts:
+            # Conventional package manifests map names to commands.  Pick
+            # ``start``/``run`` when present, otherwise the first entry, but
+            # remember that the author declared a launch surface.
+            for key in ("start", "run", "main"):
+                if key in scripts:
+                    raw = scripts[key]
+                    declared = True
+                    break
+            else:
+                raw = next(iter(scripts.values()))
+                declared = True
+        elif isinstance(scripts, str) and scripts.strip():
+            raw = scripts
+            declared = True
+    if not declared:
+        return None, False, None
+
+    if isinstance(raw, dict):
+        # e.g. {"command": "python main.py", "args": [...]}
+        command = raw.get("command") or raw.get("path")
+        args = raw.get("args") or []
+        if command is None:
+            return None, True, PackageIssue("high", "manifest entrypoint object has no command")
+        raw = [command, *args] if isinstance(args, list) else str(command)
+    if isinstance(raw, str):
+        try:
+            tokens = shlex.split(raw, posix=True)
+        except ValueError as exc:
+            return (
+                None,
+                True,
+                PackageIssue("high", f"manifest entrypoint is not shell-parseable: {exc}"),
+            )
+    elif isinstance(raw, (list, tuple)) and all(isinstance(item, (str, int)) for item in raw):
+        tokens = [str(item) for item in raw]
+    else:
+        return None, True, PackageIssue("high", "manifest entrypoint must be a string or list")
+    if not tokens:
+        return None, True, PackageIssue("high", "manifest entrypoint is empty")
+
+    candidate_index = 0
+    if Path(tokens[0]).name in _INTERPRETERS:
+        # python scripts/main.py --flag
+        if len(tokens) < 2:
+            return None, True, PackageIssue("high", "interpreter entrypoint has no script path")
+        candidate_index = 1
+    candidate = tokens[candidate_index]
+    if candidate.startswith(("/", "\\")) or re.match(r"^[A-Za-z]:[\\/]", candidate):
+        return (
+            None,
+            True,
+            PackageIssue("high", "manifest entrypoint must be relative to the skill root"),
+        )
+    rel = Path(candidate)
+    if ".." in rel.parts:
+        return None, True, PackageIssue("high", "manifest entrypoint escapes the skill root")
+    target = (root / rel).resolve()
+    try:
+        target.relative_to(root.resolve())
+    except ValueError:
+        return None, True, PackageIssue("high", "manifest entrypoint escapes the skill root")
+    if not target.is_file():
+        return (
+            None,
+            True,
+            PackageIssue(
+                "high",
+                f"declared entrypoint does not exist: {candidate}",
+                code=candidate,
+            ),
+        )
+    normalised = list(tokens)
+    normalised[candidate_index] = str(rel).replace("\\", "/")
+    if not normalised[0].startswith((".", "/")):
+        # Preserve interpreter names; the sandbox image provides python/sh/node.
+        normalised[0] = tokens[0]
+    return normalised, True, None
+
+
+def parse_skill(path: str | Path) -> SkillPackage:
+    """Parse and validate a skill package without executing any of its code."""
+
+    root = Path(path).expanduser()
+    try:
+        root = root.resolve(strict=True)
+    except OSError as exc:
+        raise SkillParseError(f"skill directory does not exist: {path}") from exc
+    if not root.is_dir():
+        raise SkillParseError(f"not a directory: {root}")
+    skill_md_path = root / "SKILL.md"
+    if not skill_md_path.is_file() or skill_md_path.is_symlink():
+        raise SkillParseError(f"no SKILL.md found in {root}")
+    try:
+        raw_skill_md = skill_md_path.read_bytes()
+    except OSError as exc:
+        raise SkillParseError(f"could not read SKILL.md: {exc}") from exc
+    if len(raw_skill_md) > MAX_SKILL_MD_BYTES:
+        raise SkillParseError("SKILL.md exceeds 1 MiB")
+    issues: list[PackageIssue] = []
+    try:
+        skill_md = raw_skill_md.decode("utf-8")
+    except UnicodeDecodeError:
+        # Analysed with replacement characters rather than refused: an invalid
+        # byte must not hide the rest of the file from the scan.
+        skill_md = raw_skill_md.decode("utf-8", "replace")
+        issues.append(PackageIssue("high", "SKILL.md is not valid UTF-8"))
+    yaml_text, body, present = _split_frontmatter(skill_md)
+    manifest: dict[str, Any] = {}
+    if not present:
+        issues.append(PackageIssue("medium", "SKILL.md has no YAML frontmatter"))
+    else:
+        try:
+            manifest = _safe_yaml(yaml_text)
+        except SkillParseError as exc:
+            issues.append(PackageIssue("high", str(exc)))
+            manifest = {}
+
+    name_raw = manifest.get("name")
+    if isinstance(name_raw, str) and _NAME_RE.match(name_raw.strip()):
+        name = name_raw.strip()
+    else:
+        name = root.name
+        if name_raw is None:
+            issues.append(PackageIssue("high", "frontmatter is missing required field: name"))
+        else:
+            issues.append(PackageIssue("high", "frontmatter name is not a valid skill identifier"))
+        if not _NAME_RE.match(name):
+            name = re.sub(r"[^A-Za-z0-9._-]+", "-", name).strip("-") or "unknown-skill"
+
+    description_raw = manifest.get("description")
+    if not isinstance(description_raw, str) or not description_raw.strip():
+        description = ""
+        issues.append(PackageIssue("high", "frontmatter is missing required field: description"))
+    else:
+        description = description_raw.strip()
+        if len(description) > 4096:
+            issues.append(PackageIssue("medium", "description exceeds 4096 characters"))
+            description = description[:4096]
+
+    entrypoint, entrypoint_declared, entry_issue = _resolve_entrypoint(manifest, root)
+    if entry_issue is not None:
+        issues.append(entry_issue)
+
+    files: list[Path] = []
+    text_files: list[TextFile] = []
+    text_budget = MAX_TEXT_TOTAL_BYTES
+    for candidate in sorted(root.rglob("*"), key=lambda p: p.relative_to(root).as_posix()):
+        if candidate.is_symlink():
+            issues.append(
+                PackageIssue(
+                    "high",
+                    f"symlink is not allowed in a skill package: {candidate.relative_to(root).as_posix()}",
+                )
+            )
+            continue
+        name_issue = _path_name_issue(candidate.relative_to(root).as_posix())
+        if name_issue is not None:
+            # Reported as high, and the file is still analysed: a reserved name
+            # must not hide content from the scan.
+            issues.append(PackageIssue("high", name_issue))
+        if candidate.is_dir():
+            continue
+        if not candidate.is_file():
+            issues.append(
+                PackageIssue(
+                    "medium",
+                    f"unsupported file type: {candidate.relative_to(root).as_posix()}",
+                )
+            )
+            continue
+        files.append(candidate)
+        relative = candidate.relative_to(root).as_posix()
+        if relative == "SKILL.md":
+            text_files.append(
+                TextFile(
+                    path=candidate,
+                    relative=relative,
+                    text=skill_md,
+                    line_count=len(skill_md.splitlines()) or 1,
+                )
+            )
+            text_budget -= len(raw_skill_md)
+            continue
+        if _is_text(relative):
+            parsed = _read_text(candidate, relative, text_budget)
+            if parsed is not None:
+                text_files.append(parsed)
+                text_budget -= len(parsed.text.encode("utf-8", "replace"))
+            else:
+                # A script the scan did not read is a gap, not a clean file.
+                # The HIGH issue degrades the spec stage, so the verdict cannot be SAFE.
+                issues.append(
+                    PackageIssue(
+                        "high",
+                        f"text file not analysed: {relative} ({_unread_reason(candidate, text_budget)})",
+                        file=relative,
+                    )
+                )
+
+    try:
+        package_hash = hash_skill_dir(root)
+    except HashError as exc:
+        raise SkillParseError(str(exc)) from exc
+
+    return SkillPackage(
+        root=root,
+        name=name,
+        description=description,
+        declared_intent=description,
+        manifest=manifest,
+        frontmatter=manifest,
+        body=body,
+        skill_md=skill_md,
+        files=files,
+        text_files=text_files,
+        entrypoint=entrypoint,
+        entrypoint_declared=entrypoint_declared,
+        content_hash=package_hash.digest,
+        issues=issues,
+    )
+
+
+__all__ = [
+    "MAX_SKILL_MD_BYTES",
+    "PackageIssue",
+    "SkillPackage",
+    "SkillParseError",
+    "TextFile",
+    "parse_skill",
+]

skill_sentry_cli/core/parser/typosquat.py

@@ -0,0 +1,167 @@
+"""Typosquat / homograph detection for skill names.
+
+The known-name list is intentionally small and local: this is a supply-chain
+warning signal, not a verdict by itself.  The matching rules are conservative
+(normalised Levenshtein distance <= 2 for names of at least four characters)
+and exact names are never flagged.
+"""
+
+from __future__ import annotations
+
+import json
+import unicodedata
+from dataclasses import dataclass
+from importlib import resources
+
+
+def _load_known_names() -> tuple[str, ...]:
+    """Load the curated list from the packaged data file (works from a wheel install)."""
+
+    raw = (
+        resources.files("skill_sentry_cli.data")
+        .joinpath("known_skills_v1.json")
+        .read_text(encoding="utf-8")
+    )
+    entries = json.loads(raw)["entries"]
+    return tuple(sorted({str(entry["name"]) for entry in entries}))
+
+
+KNOWN_SKILL_NAMES: tuple[str, ...] = _load_known_names()
+
+_TRANSLATION = str.maketrans(
+    {
+        "0": "o",
+        "1": "l",
+        "3": "e",
+        "4": "a",
+        "5": "s",
+        "7": "t",
+        "8": "b",
+        "9": "g",
+        "@": "a",
+        "$": "s",
+        "!": "i",
+        "|": "l",
+    }
+)
+
+
+@dataclass(frozen=True)
+class TyposquatMatch:
+    name: str
+    candidate: str
+    distance: int
+    normalised: str
+
+    @property
+    def message(self) -> str:
+        return (
+            f"Skill name {self.name!r} resembles known skill {self.candidate!r} "
+            f"(edit distance {self.distance})"
+        )
+
+
+# Cyrillic and Greek letters that render like Latin ones: a common homograph trick.
+_CONFUSABLES = str.maketrans(
+    {
+        "а": "a",
+        "е": "e",
+        "о": "o",
+        "р": "p",
+        "с": "c",
+        "у": "y",
+        "х": "x",
+        "і": "i",
+        "ј": "j",
+        "ѕ": "s",
+        "һ": "h",
+        "ԁ": "d",
+        "ɡ": "g",
+        "α": "a",
+        "ο": "o",
+        "ν": "v",
+        "ρ": "p",
+        "ι": "i",
+        "κ": "k",
+        "τ": "t",
+        "ε": "e",
+        "υ": "u",
+        "χ": "x",
+    }
+)
+
+
+def _fold(value: str) -> str:
+    folded = unicodedata.normalize("NFKC", value).lower().translate(_CONFUSABLES)
+    folded = folded.translate(_TRANSLATION)
+    folded = folded.replace("rn", "m").replace("vv", "w")
+    folded = folded.replace("_", "-")
+    return folded
+
+
+def levenshtein(left: str, right: str, *, max_distance: int = 3) -> int:
+    """Small bounded Levenshtein implementation (no external dependency)."""
+
+    if left == right:
+        return 0
+    if abs(len(left) - len(right)) > max_distance:
+        return max_distance + 1
+    previous = list(range(len(right) + 1))
+    for i, left_char in enumerate(left, start=1):
+        current = [i]
+        best = i
+        for j, right_char in enumerate(right, start=1):
+            value = min(
+                current[j - 1] + 1,
+                previous[j] + 1,
+                previous[j - 1] + (left_char != right_char),
+            )
+            current.append(value)
+            best = min(best, value)
+        if best > max_distance:
+            return max_distance + 1
+        previous = current
+    return previous[-1]
+
+
+def check_typosquat(
+    name: str, *, known: tuple[str, ...] = KNOWN_SKILL_NAMES
+) -> TyposquatMatch | None:
+    """Return the nearest known name when ``name`` is a likely imitation."""
+
+    stripped = unicodedata.normalize("NFKC", name.strip())
+    lowered = stripped.lower()
+    if len(lowered) < 4:
+        return None
+    folded = _fold(lowered)
+    # Only the exact spelling of a known name is the original.  A case variant or
+    # a homograph that folds onto a known name is an imitation, not the original.
+    if stripped in known:
+        return None
+    for item in known:
+        if folded == _fold(item.lower()) and stripped != item:
+            return TyposquatMatch(name=name, candidate=item, distance=0, normalised=folded)
+    best: TyposquatMatch | None = None
+    for candidate in known:
+        candidate_lower = candidate.lower()
+        candidate_folded = _fold(candidate_lower)
+        distance = min(
+            levenshtein(lowered, candidate_lower, max_distance=2),
+            levenshtein(folded, candidate_folded, max_distance=2),
+        )
+        if distance > 2:
+            continue
+        # Very short candidates produce too many false positives.
+        if min(len(lowered), len(candidate_lower)) < 5:
+            continue
+        if best is None or distance < best.distance:
+            best = TyposquatMatch(
+                name=name,
+                candidate=candidate,
+                distance=distance,
+                normalised=folded,
+            )
+    return best
+
+
+__all__ = ["KNOWN_SKILL_NAMES", "TyposquatMatch", "check_typosquat", "levenshtein"]