orithos-cli 0.1.0__py3-none-any.whl

orithos_cli/skillscan/checks/obfuscation.py

@@ -0,0 +1,130 @@
+"""Check 6 — obfuscation and encoded payloads.
+
+Flags base64/hex-encoded blobs that decode to executable content, `eval(atob(`
+style chains, long char-code chains, and dense hex-escape runs.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import re
+
+from orithos_cli.skillscan.model import ArtifactFile, Finding, line_of, snippet
+
+_B64_BLOB_RE = re.compile(r"[A-Za-z0-9+/]{120,}={0,2}")
+_EVAL_ATOB_RE = re.compile(r"eval\s*\(\s*(?:atob|Buffer\.from)\s*\(")
+_EVAL_B64_RE = re.compile(
+    r"\b(?:eval|exec)\s*\(\s*(?:base64\.b64decode|b64decode)\s*\("
+)
+_CHARCODE_RE = re.compile(r"String\.fromCharCode\((?:\s*\d+\s*,){6,}")
+_HEX_RUN_RE = re.compile(r"(?:\\x[0-9a-fA-F]{2}){8,}")
+
+# Decoded payload content that indicates executable/offensive intent.
+_SUSPICIOUS_DECODED = (
+    "http://",
+    "https://",
+    "/bin/sh",
+    "/bin/bash",
+    "subprocess",
+    "child_process",
+    "eval(",
+    "exec(",
+    "curl ",
+    "wget ",
+    "import os",
+    "require(",
+    "powershell",
+    "cmd.exe",
+)
+
+
+def _try_b64(token: str) -> bytes | None:
+    padded = token + "=" * (-len(token) % 4)
+    try:
+        return base64.b64decode(padded, validate=False)
+    except (binascii.Error, ValueError):
+        return None
+
+
+def run(files: list[ArtifactFile]) -> list[Finding]:
+    out: list[Finding] = []
+    for f in files:
+        if f.kind != "code":
+            continue
+
+        m = _EVAL_ATOB_RE.search(f.text)
+        if m is None:
+            m = _EVAL_B64_RE.search(f.text)
+        if m:
+            out.append(
+                Finding(
+                    check="obfuscation",
+                    severity="critical",
+                    title="eval() over decoded base64",
+                    detail=(
+                        f"`{f.path}` decodes base64 and evaluates it in one step — the "
+                        "executed payload is unreadable to review."
+                    ),
+                    file=f.path,
+                    line=line_of(f.text, m.group(0)),
+                    evidence=snippet(f.text, m.start()),
+                )
+            )
+
+        m = _CHARCODE_RE.search(f.text)
+        if m:
+            out.append(
+                Finding(
+                    check="obfuscation",
+                    severity="high",
+                    title="Long String.fromCharCode chain",
+                    detail=f"`{f.path}` builds a string character-by-character, typical of hidden payloads.",
+                    file=f.path,
+                    line=line_of(f.text, m.group(0)),
+                    evidence=snippet(f.text, m.start()),
+                )
+            )
+
+        m = _HEX_RUN_RE.search(f.text)
+        if m:
+            out.append(
+                Finding(
+                    check="obfuscation",
+                    severity="high",
+                    title="Dense hex-escape sequence",
+                    detail=f"`{f.path}` contains a run of hex-escaped bytes — likely an embedded payload.",
+                    file=f.path,
+                    line=line_of(f.text, m.group(0)),
+                    evidence=snippet(f.text, m.start(), 80),
+                )
+            )
+
+        for m in _B64_BLOB_RE.finditer(f.text):
+            token = m.group(0)
+            decoded = _try_b64(token)
+            if decoded is None:
+                continue
+            try:
+                text = decoded.decode("utf-8", errors="strict")
+            except UnicodeDecodeError:
+                continue
+            lowered = text.lower()
+            hits = [s for s in _SUSPICIOUS_DECODED if s in lowered]
+            if hits:
+                out.append(
+                    Finding(
+                        check="obfuscation",
+                        severity="high",
+                        title="Base64 blob decodes to executable content",
+                        detail=(
+                            f"`{f.path}` embeds a base64 blob whose plaintext contains: "
+                            f"{', '.join(hits[:3])}."
+                        ),
+                        file=f.path,
+                        line=line_of(f.text, token[:40]),
+                        evidence=snippet(f.text, m.start(), 80),
+                    )
+                )
+            break  # one blob finding per file is enough signal
+    return out

orithos_cli/skillscan/checks/permissions.py

@@ -0,0 +1,108 @@
+"""Check 2 — permission scope (declared vs implied).
+
+Judges mismatches between what a manifest *declares* and what the artifact
+would *need* to run: code that shells out or reaches the network while the
+skill manifest declares no such capability.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from orithos_cli.skillscan.model import ArtifactFile, Finding, line_of, snippet
+
+_NETWORK_RE = re.compile(
+    r"\b(?:https?://|fetch\(|axios\.|requests\.get|requests\.post|urllib\.request)\b"
+)
+_SHELL_RE = re.compile(
+    r"\b(?:subprocess\.|child_process|os\.system|os\.popen|execSync|spawnSync)\b"
+)
+_FILE_WRITE_RE = re.compile(
+    r"\b(?:writeFile|write_text|open\([^)]*['\"]w|fs\.write|shutil\.)\b"
+)
+
+_CAPABILITY_PATTERNS: list[tuple[str, re.Pattern[str], str]] = [
+    ("network", _NETWORK_RE, "makes network calls"),
+    ("shell", _SHELL_RE, "executes shell commands"),
+    ("filesystem-write", _FILE_WRITE_RE, "writes files"),
+]
+
+_TEXT_TOOLS = ("read", "glob", "grep", "ls")
+
+
+def _declared_tools(fm: dict[str, object]) -> list[str]:
+    raw = fm.get("allowed-tools") or fm.get("allowed_tools") or fm.get("tools")
+    if isinstance(raw, str):
+        return [t.strip().lower() for t in raw.split(",") if t.strip()]
+    if isinstance(raw, list):
+        return [str(t).lower() for t in raw]
+    return []
+
+
+def _code_files(files: Iterable[ArtifactFile]) -> list[ArtifactFile]:
+    return [f for f in files if f.kind == "code"]
+
+
+def run(files: list[ArtifactFile]) -> list[Finding]:
+    out: list[Finding] = []
+    code_files = _code_files(files)
+
+    for f in files:
+        if f.kind != "skill-md":
+            continue
+        fm = f.frontmatter or {}
+        tools = _declared_tools(fm)
+        if not tools:
+            out.append(
+                Finding(
+                    check="permissions",
+                    severity="medium",
+                    title="Skill declares no tool permissions",
+                    detail=(
+                        f"`{f.path}` has no `allowed-tools` declaration — the skill's "
+                        "capability scope is undefined. Declare the minimal tool set."
+                    ),
+                    file=f.path,
+                    line=1,
+                )
+            )
+            continue
+        tool_blob = " ".join(tools)
+        allows_shell = any(
+            t in tool_blob for t in ("bash", "shell", "exec", "terminal", "*", "all")
+        )
+        allows_net = any(
+            t in tool_blob
+            for t in ("webfetch", "web", "browser", "curl", "http", "*", "all")
+        )
+        declared_write = any(
+            t in tool_blob for t in ("write", "edit", "create", "*", "all")
+        ) or any(t in _TEXT_TOOLS for t in tools)
+
+        for cap, pattern, verb in _CAPABILITY_PATTERNS:
+            if cap == "network" and (allows_net or "*" in tool_blob):
+                continue
+            if cap == "shell" and (allows_shell or "*" in tool_blob):
+                continue
+            if cap == "filesystem-write" and declared_write:
+                continue
+            for cf in code_files:
+                m = pattern.search(cf.text)
+                if m and "*" not in tool_blob:
+                    out.append(
+                        Finding(
+                            check="permissions",
+                            severity="high" if cap == "shell" else "medium",
+                            title=f"Undeclared capability: code {verb}",
+                            detail=(
+                                f"`{cf.path}` {verb}, but `{f.path}` declares only: "
+                                f"{', '.join(tools)}. Declared scope is narrower than behavior."
+                            ),
+                            file=cf.path,
+                            line=line_of(cf.text, m.group(0)),
+                            evidence=snippet(cf.text, m.start()),
+                        )
+                    )
+                    break
+    return out

orithos_cli/skillscan/checks/shell.py

@@ -0,0 +1,140 @@
+"""Check 4 — shell execution and install hooks.
+
+Flags command execution primitives, `curl | sh` download-execute chains, and
+npm lifecycle scripts that run at install time.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+from orithos_cli.skillscan.model import ArtifactFile, Finding, line_of, snippet
+
+_PIPE_TO_SHELL_RE = re.compile(
+    r"\b(?:curl|wget)\b[^\n|;&]*\|[^\n]*\b(?:sh|bash|zsh|python3?|node)\b",
+    re.IGNORECASE,
+)
+_B64_PIPE_SHELL_RE = re.compile(
+    r"base64\s+(?:-d|--decode)[^\n]*\|[^\n]*\b(?:sh|bash|zsh)\b"
+)
+_PY_EXEC_RE = re.compile(
+    r"\b(?:subprocess\.(?:run|Popen|call|check_output)|os\.system|os\.popen|pty\.spawn)\b"
+)
+_PY_SHELL_TRUE_RE = re.compile(r"shell\s*=\s*True")
+_JS_EXEC_RE = re.compile(r"\b(?:child_process|execSync|spawnSync|exec\(|spawn\()")
+_NPM_RUN_HOOKS = ("preinstall", "install", "postinstall", "prepare")
+
+
+def run(files: list[ArtifactFile]) -> list[Finding]:
+    out: list[Finding] = []
+    for f in files:
+        if f.kind in ("code", "npm-manifest", "mcp-manifest", "python-project"):
+            m = _PIPE_TO_SHELL_RE.search(f.text)
+            if m:
+                out.append(
+                    Finding(
+                        check="shell",
+                        severity="critical",
+                        title="Download-and-execute chain",
+                        detail=(
+                            f"`{f.path}` pipes a download straight into a shell — the fetched "
+                            "payload is executed without review."
+                        ),
+                        file=f.path,
+                        line=line_of(f.text, m.group(0)),
+                        evidence=snippet(f.text, m.start()),
+                    )
+                )
+            m = _B64_PIPE_SHELL_RE.search(f.text)
+            if m:
+                out.append(
+                    Finding(
+                        check="shell",
+                        severity="critical",
+                        title="Base64 payload piped into a shell",
+                        detail=f"`{f.path}` decodes base64 and executes it — payload content is hidden from review.",
+                        file=f.path,
+                        line=line_of(f.text, m.group(0)),
+                        evidence=snippet(f.text, m.start()),
+                    )
+                )
+
+        if f.kind == "code":
+            m = _PY_SHELL_TRUE_RE.search(f.text)
+            if m and _PY_EXEC_RE.search(f.text):
+                out.append(
+                    Finding(
+                        check="shell",
+                        severity="high",
+                        title="subprocess with shell=True",
+                        detail=f"`{f.path}` runs subprocesses through a shell, enabling injection via interpolated input.",
+                        file=f.path,
+                        line=line_of(f.text, m.group(0)),
+                        evidence=snippet(f.text, m.start()),
+                    )
+                )
+            for pattern, label in (
+                (_PY_EXEC_RE, "python"),
+                (_JS_EXEC_RE, "javascript"),
+            ):
+                m = pattern.search(f.text)
+                if m:
+                    out.append(
+                        Finding(
+                            check="shell",
+                            severity="medium",
+                            title="Shell command execution primitive",
+                            detail=(
+                                f"`{f.path}` ({label}) invokes shell/process execution. "
+                                "Legitimate for some skills — verify what it runs and with which inputs."
+                            ),
+                            file=f.path,
+                            line=line_of(f.text, m.group(0)),
+                            evidence=snippet(f.text, m.start()),
+                        )
+                    )
+        elif f.kind == "npm-manifest":
+            try:
+                data = json.loads(f.text)
+            except json.JSONDecodeError:
+                continue
+            scripts = data.get("scripts") if isinstance(data, dict) else None
+            if not isinstance(scripts, dict):
+                continue
+            for hook in _NPM_RUN_HOOKS:
+                cmd = scripts.get(hook)
+                if not cmd:
+                    continue
+                out.append(
+                    Finding(
+                        check="shell",
+                        severity="high",
+                        title=f"npm install-time hook: {hook}",
+                        detail=(
+                            f"`{f.path}` runs `{hook}` on install. Lifecycle hooks execute "
+                            "arbitrary commands before the package is ever imported."
+                        ),
+                        file=f.path,
+                        line=line_of(f.text, hook),
+                        evidence=f"{hook}: {str(cmd)[:100]}",
+                    )
+                )
+        elif f.kind == "python-project":
+            if "cmdclass" in f.text or "build_ext" in f.text:
+                out.append(
+                    Finding(
+                        check="shell",
+                        severity="medium",
+                        title="Python build-time hook",
+                        detail=(
+                            f"`{f.path}` defines a custom build hook (cmdclass/build_ext), "
+                            "which can execute code at install time."
+                        ),
+                        file=f.path,
+                        line=line_of(f.text, "cmdclass")
+                        if "cmdclass" in f.text
+                        else line_of(f.text, "build_ext"),
+                    )
+                )
+    return out

orithos_cli/skillscan/collect.py

@@ -0,0 +1,205 @@
+"""Artifact collection: discovery, loading, and safe unpacking.
+
+The scanner accepts a local path or a URL. URLs are downloaded to a temp
+directory; archives (zip / tar.gz) are extracted with traversal protection
+(zip-slip and symlink members are rejected before extraction).
+"""
+
+from __future__ import annotations
+
+import io
+import tarfile
+import tempfile
+import zipfile
+from pathlib import Path
+from typing import Any
+
+import httpx
+import yaml
+
+from orithos_cli.skillscan.model import ArtifactFile
+
+SKIP_DIRS = {
+    ".git",
+    "node_modules",
+    ".venv",
+    "venv",
+    "__pycache__",
+    "dist",
+    "build",
+    ".next",
+    ".mypy_cache",
+    ".ruff_cache",
+}
+CODE_EXTENSIONS = {
+    ".py": "code",
+    ".js": "code",
+    ".mjs": "code",
+    ".cjs": "code",
+    ".ts": "code",
+    ".sh": "code",
+    ".bash": "code",
+    ".zsh": "code",
+}
+MAX_FILE_BYTES = 512 * 1024
+MAX_FILES = 2000
+SKILL_MANIFEST_NAMES = {"skill.md", "agent.md"}
+MCP_MANIFEST_HINTS = ("mcpservers", "mcp_servers", "mcp-servers")
+
+
+def _decode(raw: bytes) -> str:
+    return raw.decode("utf-8", errors="replace")
+
+
+def parse_frontmatter(text: str) -> dict[str, Any] | None:
+    """Parse YAML frontmatter delimited by leading `---` lines."""
+    if not text.startswith("---"):
+        return None
+    end = text.find("\n---", 3)
+    if end < 0:
+        return None
+    body = text[3:end]
+    try:
+        loaded = yaml.safe_load(body)
+    except yaml.YAMLError:
+        return None
+    return loaded if isinstance(loaded, dict) else None
+
+
+def classify(path: Path, text: str) -> tuple[str, dict[str, Any] | None]:
+    """Return (kind, frontmatter) for a loaded file."""
+    name = path.name.lower()
+    suffix = path.suffix.lower()
+    if suffix == ".md":
+        if name in SKILL_MANIFEST_NAMES:
+            return "skill-md", parse_frontmatter(text)
+        return "text", None
+    if name == "package.json":
+        return "npm-manifest", None
+    if name in ("pyproject.toml", "setup.py", "setup.cfg"):
+        return "python-project", None
+    if suffix == ".json" and any(h in text.lower() for h in MCP_MANIFEST_HINTS):
+        return "mcp-manifest", None
+    if suffix in CODE_EXTENSIONS:
+        return CODE_EXTENSIONS[suffix], None
+    if name.endswith(".md"):
+        return "text", None
+    return "text", None
+
+
+def load_local(root: Path) -> tuple[list[ArtifactFile], list[str], list[str]]:
+    """Walk a local artifact directory. Returns (files, skipped, errors)."""
+    files: list[ArtifactFile] = []
+    skipped: list[str] = []
+    errors: list[str] = []
+
+    if root.is_file():
+        candidates = [root]
+        base = root.parent
+    else:
+        candidates = sorted(p for p in root.rglob("*") if p.is_file())
+        base = root
+
+    count = 0
+    for p in candidates:
+        if any(part in SKIP_DIRS for part in p.parts):
+            continue
+        if count >= MAX_FILES:
+            skipped.append(f"{p.relative_to(base)} (file cap {MAX_FILES} reached)")
+            continue
+        rel = str(p.relative_to(base))
+        try:
+            size = p.stat().st_size
+        except OSError as exc:
+            errors.append(f"{rel}: {exc}")
+            continue
+        if size > MAX_FILE_BYTES:
+            skipped.append(f"{rel} ({size} bytes > {MAX_FILE_BYTES} cap)")
+            continue
+        try:
+            text = _decode(p.read_bytes())
+        except OSError as exc:
+            errors.append(f"{rel}: {exc}")
+            continue
+        if "\x00" in text:
+            skipped.append(f"{rel} (binary)")
+            continue
+        kind, fm = classify(p, text)
+        files.append(ArtifactFile(path=rel, kind=kind, text=text, frontmatter=fm))
+        count += 1
+
+    return files, skipped, errors
+
+
+def _safe_zip_members(zf: zipfile.ZipFile, dest: Path) -> list[zipfile.ZipInfo]:
+    members: list[zipfile.ZipInfo] = []
+    dest_resolved = dest.resolve()
+    for info in zf.infolist():
+        name = info.filename
+        if name.startswith("/") or ".." in Path(name).parts:
+            raise ValueError(f"unsafe archive member: {name}")
+        target = (dest / name).resolve()
+        if not str(target).startswith(str(dest_resolved)):
+            raise ValueError(f"archive member escapes extraction dir: {name}")
+        members.append(info)
+    return members
+
+
+def _safe_extract_tar(tf: tarfile.TarFile, dest: Path) -> None:
+    dest_resolved = dest.resolve()
+    for member in tf.getmembers():
+        if member.issym() or member.islnk():
+            raise ValueError(f"unsafe archive member (link): {member.name}")
+        if member.name.startswith("/") or ".." in Path(member.name).parts:
+            raise ValueError(f"unsafe archive member: {member.name}")
+        target = (dest / member.name).resolve()
+        if not str(target).startswith(str(dest_resolved)):
+            raise ValueError(f"archive member escapes extraction dir: {member.name}")
+    # Python 3.12: data filter re-validates and strips dangerous metadata.
+    tf.extractall(dest, filter="data")
+
+
+def fetch_url(url: str) -> Path:
+    """Download a URL into a temp dir; unpack archives safely.
+
+    Returns a path suitable for `load_local`.
+    """
+    with httpx.Client(follow_redirects=True, timeout=30.0) as client:
+        resp = client.get(url)
+        resp.raise_for_status()
+        payload = resp.content
+        name = url.rsplit("/", 1)[-1].split("?")[0] or "artifact"
+
+    tmp_root = Path(tempfile.mkdtemp(prefix="orithos-skillscan-"))
+    lower = name.lower()
+    if lower.endswith(".zip"):
+        dest = tmp_root / "artifact"
+        dest.mkdir()
+        with zipfile.ZipFile(io.BytesIO(payload)) as zf:
+            zf.extractall(dest, members=_safe_zip_members(zf, dest))
+        return dest
+    if lower.endswith((".tar.gz", ".tgz")):
+        dest = tmp_root / "artifact"
+        dest.mkdir()
+        with tarfile.open(fileobj=io.BytesIO(payload), mode="r:gz") as tf:
+            _safe_extract_tar(tf, dest)
+        return dest
+
+    target = tmp_root / (name or "artifact.txt")
+    target.write_bytes(payload)
+    return target
+
+
+def resolve_source(source: str) -> Path:
+    """Turn a CLI argument (path or URL) into a local path to scan."""
+    if source.startswith(("http://", "https://")):
+        return fetch_url(source)
+    path = Path(source).expanduser()
+    if not path.exists():
+        raise FileNotFoundError(f"path does not exist: {source}")
+    return path
+
+
+def load_artifact(root: Path) -> tuple[list[ArtifactFile], list[str], list[str]]:
+    """Load every scannable file under `root`."""
+    return load_local(root)

orithos_cli/skillscan/model.py

@@ -0,0 +1,99 @@
+"""Core data model for the skill scanner."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+SEVERITY_ORDER: dict[str, int] = {
+    "critical": 0,
+    "high": 1,
+    "medium": 2,
+    "low": 3,
+    "info": 4,
+}
+
+
+def severity_at_least(severity: str, floor: str) -> bool:
+    """True when `severity` is at or above the `floor` severity."""
+    return SEVERITY_ORDER.get(severity, 99) <= SEVERITY_ORDER.get(floor, 99)
+
+
+@dataclass
+class Finding:
+    """One scanner finding. `file` is relative to the scanned artifact root."""
+
+    check: str
+    severity: str
+    title: str
+    detail: str
+    file: str
+    line: int | None = None
+    evidence: str = ""
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "check": self.check,
+            "severity": self.severity,
+            "title": self.title,
+            "detail": self.detail,
+            "file": self.file,
+        }
+        if self.line is not None:
+            out["line"] = self.line
+        if self.evidence:
+            out["evidence"] = self.evidence
+        return out
+
+
+@dataclass
+class ArtifactFile:
+    """A text file loaded from the scanned artifact."""
+
+    path: str
+    kind: str  # skill-md | npm-manifest | python-project | mcp-manifest | code | text
+    text: str
+    frontmatter: dict[str, Any] | None = None
+
+
+@dataclass
+class ScanResult:
+    """Aggregated scanner result for one artifact."""
+
+    source: str
+    files_scanned: int
+    findings: list[Finding] = field(default_factory=list)
+    skipped: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+    def counts(self) -> dict[str, int]:
+        counts: dict[str, int] = {}
+        for f in self.findings:
+            counts[f.severity] = counts.get(f.severity, 0) + 1
+        return counts
+
+    def sorted_findings(self) -> list[Finding]:
+        return sorted(
+            self.findings,
+            key=lambda f: (SEVERITY_ORDER.get(f.severity, 99), f.file, f.line or 0),
+        )
+
+
+def line_of(text: str, needle: str) -> int | None:
+    """1-based line number of the first occurrence of `needle`, or None."""
+    idx = text.find(needle)
+    if idx < 0:
+        return None
+    return text[:idx].count("\n") + 1
+
+
+def snippet(text: str, idx: int, length: int = 120) -> str:
+    """Short single-line evidence snippet around `idx`."""
+    start = text.rfind("\n", 0, idx) + 1
+    end = text.find("\n", idx)
+    if end < 0:
+        end = len(text)
+    raw = text[start:end].strip()
+    if len(raw) > length:
+        raw = raw[: length - 1] + "…"
+    return raw