orithos-cli 0.1.0__py3-none-any.whl

orithos_cli/skill.py

@@ -0,0 +1,64 @@
+"""Skill / plugin scanner commands."""
+
+from __future__ import annotations
+
+import click
+
+from orithos_cli.skillscan import (
+    render_json,
+    render_sarif,
+    render_text,
+    scan_artifact,
+    severity_at_least,
+)
+
+
+@click.group(name="skill")
+def skill_group() -> None:
+    """Scan AI agent skills and plugins for risky behavior."""
+    pass
+
+
+@skill_group.command("scan")
+@click.argument("artifact")
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json", "sarif"]),
+    default="text",
+    help="Output format. sarif is for CI/code-scanning ingestion.",
+)
+@click.option(
+    "--fail-on",
+    type=click.Choice(["critical", "high", "medium", "low"]),
+    default="high",
+    help="Exit 1 when any finding is at or above this severity (default: high).",
+)
+def skill_scan(artifact: str, output_format: str, fail_on: str) -> None:
+    """Scan a skill/plugin artifact (local path or URL).
+
+    \b
+    Examples:
+      orithos skill scan ./my-claude-skill
+      orithos skill scan https://example.com/plugin.zip --format sarif
+      orithos skill scan ./plugin --fail-on medium
+
+    Exit codes: 0 = no findings at/above --fail-on · 1 = findings · 2 = error.
+    """
+    try:
+        result = scan_artifact(artifact)
+    except Exception as exc:  # noqa: BLE001 — CLI boundary: report any failure as exit 2
+        click.echo(f"Error: {exc}", err=True)
+        raise SystemExit(2)
+
+    renderers = {"text": render_text, "json": render_json, "sarif": render_sarif}
+    click.echo(renderers[output_format](result))
+
+    blocking = [f for f in result.findings if severity_at_least(f.severity, fail_on)]
+    if blocking:
+        if output_format == "text":
+            click.echo(
+                f"FAIL — {len(blocking)} finding(s) at or above '{fail_on}'.", err=True
+            )
+        raise SystemExit(1)
+    raise SystemExit(0)

orithos_cli/skillscan/__init__.py

@@ -0,0 +1,37 @@
+"""Orithos skill scanner — static analysis for agent skills and plugins.
+
+Public API used by the CLI and tests:
+
+    from orithos_cli.skillscan import scan_artifact
+    result = scan_artifact("./my-skill")
+"""
+
+from __future__ import annotations
+
+from orithos_cli.skillscan.checks import ALL_CHECKS
+from orithos_cli.skillscan.collect import load_artifact, resolve_source
+from orithos_cli.skillscan.model import Finding, ScanResult, severity_at_least
+from orithos_cli.skillscan.report import render_json, render_sarif, render_text
+
+__all__ = [
+    "Finding",
+    "ScanResult",
+    "render_json",
+    "render_sarif",
+    "render_text",
+    "scan_artifact",
+    "severity_at_least",
+]
+
+
+def scan_artifact(source: str) -> ScanResult:
+    """Scan a local path or URL and return the aggregated result."""
+    path = resolve_source(source)
+    files, skipped, errors = load_artifact(path)
+
+    result = ScanResult(
+        source=source, files_scanned=len(files), skipped=skipped, errors=errors
+    )
+    for _name, check in ALL_CHECKS:
+        result.findings.extend(check(files))
+    return result

orithos_cli/skillscan/checks/__init__.py

@@ -0,0 +1,28 @@
+"""Check registry for the skill scanner."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from orithos_cli.skillscan.checks import (
+    credentials,
+    iocs,
+    manifest,
+    network,
+    obfuscation,
+    permissions,
+    shell,
+)
+from orithos_cli.skillscan.model import ArtifactFile, Finding
+
+CheckFn = Callable[[list[ArtifactFile]], list[Finding]]
+
+ALL_CHECKS: list[tuple[str, CheckFn]] = [
+    ("manifest", manifest.run),
+    ("permissions", permissions.run),
+    ("network", network.run),
+    ("shell", shell.run),
+    ("credentials", credentials.run),
+    ("obfuscation", obfuscation.run),
+    ("iocs", iocs.run),
+]

orithos_cli/skillscan/checks/credentials.py

@@ -0,0 +1,112 @@
+"""Check 5 — credential and sensitive-data access.
+
+Flags code paths that read credential material (SSH/AWS/registry configs,
+.env files, wallets, browser profiles, keychains) or dump the environment.
+"""
+
+from __future__ import annotations
+
+import re
+
+from orithos_cli.skillscan.model import ArtifactFile, Finding, line_of, snippet
+
+# needle -> (severity, label)
+SENSITIVE_PATHS: list[tuple[str, str, str]] = [
+    (".ssh/", "high", "SSH directory"),
+    ("id_rsa", "high", "SSH private key"),
+    ("id_ed25519", "high", "SSH private key"),
+    (".aws/credentials", "high", "AWS credentials file"),
+    (".aws/config", "medium", "AWS config"),
+    (".env", "high", "environment file"),
+    (".netrc", "high", "netrc credentials"),
+    (".git-credentials", "high", "git credential store"),
+    (".npmrc", "high", "npm registry token store"),
+    (".pypirc", "high", "PyPI token store"),
+    (".docker/config.json", "high", "Docker registry credentials"),
+    ("credentials.json", "medium", "service-account credentials file"),
+    ("wallet.dat", "high", "crypto wallet"),
+    ("keystore", "medium", "keystore"),
+    ("Login Data", "medium", "browser password store"),
+    ("Cookies", "low", "browser cookie store"),
+    ("login.keychain", "high", "macOS keychain"),
+    (".kube/config", "high", "Kubernetes credentials"),
+]
+
+_ENV_DUMP_RES: list[re.Pattern[str]] = [
+    re.compile(r"os\.environ\b(?![\.\[]?\.get\()"),
+    re.compile(r"JSON\.stringify\(\s*process\.env"),
+    re.compile(r"Object\.keys\(\s*process\.env\s*\)"),
+    re.compile(r"\bprintenv\b"),
+    re.compile(r"\benv\s*\|\s*curl\b"),
+]
+
+_CLIPBOARD_RES: list[re.Pattern[str]] = [
+    re.compile(r"pyperclip|pbcopy|pbpaste|navigator\.clipboard\.readText|xclip|xsel"),
+]
+
+
+def run(files: list[ArtifactFile]) -> list[Finding]:
+    out: list[Finding] = []
+    for f in files:
+        if f.kind != "code":
+            continue
+
+        for needle, sev, label in SENSITIVE_PATHS:
+            idx = f.text.find(needle)
+            if idx < 0:
+                continue
+            # "Cookies"/"keystore" style names only matter in string literals.
+            if needle in ("Cookies", "keystore", "Login Data") and not re.search(
+                rf"['\"][^'\"]*{re.escape(needle)}[^'\"]*['\"]", f.text
+            ):
+                continue
+            out.append(
+                Finding(
+                    check="credentials",
+                    severity=sev,
+                    title=f"References {label}",
+                    detail=(
+                        f"`{f.path}` references `{needle}` ({label}). Skills have no "
+                        "legitimate reason to read host credential stores."
+                    ),
+                    file=f.path,
+                    line=line_of(f.text, needle),
+                    evidence=snippet(f.text, idx),
+                )
+            )
+
+        for pattern in _ENV_DUMP_RES:
+            m = pattern.search(f.text)
+            if m:
+                out.append(
+                    Finding(
+                        check="credentials",
+                        severity="high",
+                        title="Environment variable enumeration",
+                        detail=(
+                            f"`{f.path}` reads or dumps the full process environment — "
+                            "a common credential-harvesting primitive."
+                        ),
+                        file=f.path,
+                        line=line_of(f.text, m.group(0)),
+                        evidence=snippet(f.text, m.start()),
+                    )
+                )
+                break
+
+        for pattern in _CLIPBOARD_RES:
+            m = pattern.search(f.text)
+            if m:
+                out.append(
+                    Finding(
+                        check="credentials",
+                        severity="medium",
+                        title="Clipboard access",
+                        detail=f"`{f.path}` reads the system clipboard, which frequently holds secrets.",
+                        file=f.path,
+                        line=line_of(f.text, m.group(0)),
+                        evidence=snippet(f.text, m.start()),
+                    )
+                )
+                break
+    return out

orithos_cli/skillscan/checks/iocs.py

@@ -0,0 +1,95 @@
+"""Check 7 — known-bad artifact indicators.
+
+Static signatures that are hostile regardless of campaign attribution:
+reverse shells, SSH-key injection, persistence via cron, shell-history
+tampering. `IOCS_VERSION` tracks this ruleset; campaign-specific indicators
+(domains, hashes) get added here as research lands.
+"""
+
+from __future__ import annotations
+
+import re
+
+from orithos_cli.skillscan.model import ArtifactFile, Finding, line_of, snippet
+
+IOCS_VERSION = "2026.09.1"
+
+# (pattern, severity, title, description)
+_SIGNATURES: list[tuple[re.Pattern[str], str, str, str]] = [
+    (
+        re.compile(r"bash\s+-i\s+>&?\s*/dev/tcp/"),
+        "critical",
+        "Reverse shell: /dev/tcp",
+        "opens an interactive shell back to a remote host",
+    ),
+    (
+        re.compile(r"\bnc\b[^\n]{0,30}\s-e\s+(?:/bin/)?(?:sh|bash)"),
+        "critical",
+        "Reverse shell: netcat -e",
+        "wires a shell to a network socket via netcat",
+    ),
+    (
+        re.compile(r"\bsocat\b[^\n]*\bexec:"),
+        "critical",
+        "Reverse shell: socat exec",
+        "bridges a socket to a process via socat",
+    ),
+    (
+        re.compile(r">>?\s*[~\/\w.\-]*\.ssh/authorized_keys"),
+        "critical",
+        "SSH authorized_keys injection",
+        "appends an attacker key to the SSH authorized_keys file",
+    ),
+    (
+        re.compile(r"\bcrontab\s+-"),
+        "high",
+        "Cron persistence",
+        "installs a scheduled job — a standard persistence mechanism",
+    ),
+    (
+        re.compile(r"\bunset\s+HISTFILE\b|\bset\s+\+o\s+history\b"),
+        "high",
+        "Shell history tampering",
+        "disables command logging to cover tracks",
+    ),
+    (
+        re.compile(r"\b(?:history\s+-c|shred\s+[^\n]*\.bash_history)\b"),
+        "high",
+        "Shell history destruction",
+        "erases shell history",
+    ),
+    (
+        re.compile(r"chmod\s+(?:777|a\+x)\s+[^\n]*(?:/tmp|\$TMPDIR)"),
+        "medium",
+        "World-executable drop in temp directory",
+        "marks a temp payload executable",
+    ),
+    (
+        re.compile(r"\bmkfifo\b[^\n]*\b(?:nc|socat|sh|bash)\b"),
+        "high",
+        "FIFO-back shell relay",
+        "relays command output through a named pipe — reverse-shell variant",
+    ),
+]
+
+
+def run(files: list[ArtifactFile]) -> list[Finding]:
+    out: list[Finding] = []
+    for f in files:
+        if f.kind not in ("code", "text", "skill-md", "npm-manifest", "mcp-manifest"):
+            continue
+        for pattern, sev, title, description in _SIGNATURES:
+            m = pattern.search(f.text)
+            if m:
+                out.append(
+                    Finding(
+                        check="iocs",
+                        severity=sev,
+                        title=title,
+                        detail=f"`{f.path}` {description} (signature: {pattern.pattern[:60]}).",
+                        file=f.path,
+                        line=line_of(f.text, m.group(0)),
+                        evidence=snippet(f.text, m.start()),
+                    )
+                )
+    return out

orithos_cli/skillscan/checks/manifest.py

@@ -0,0 +1,156 @@
+"""Check 1 — manifest hygiene.
+
+Signals about what a skill/plugin *declares*: missing descriptions, wildcard
+tool grants, unpinned runtime installs. Code-level behavior is the job of the
+other checks; this module only judges declarations.
+"""
+
+from __future__ import annotations
+
+import json
+
+from orithos_cli.skillscan.model import ArtifactFile, Finding, line_of
+
+
+def _check_skill_md(f: ArtifactFile, out: list[Finding]) -> None:
+    fm = f.frontmatter or {}
+    raw_tools = fm.get("allowed-tools") or fm.get("allowed_tools") or fm.get("tools")
+    tools: list[str] = []
+    if isinstance(raw_tools, str):
+        tools = [t.strip() for t in raw_tools.split(",") if t.strip()]
+    elif isinstance(raw_tools, list):
+        tools = [str(t) for t in raw_tools]
+
+    for tool in tools:
+        if tool in ("*", "all", "any") or tool.endswith(":*"):
+            out.append(
+                Finding(
+                    check="manifest",
+                    severity="high",
+                    title="Wildcard tool grant in skill manifest",
+                    detail=(
+                        f"`{f.path}` grants `{tool}`, which lets the skill invoke any tool "
+                        "without an explicit, reviewable scope. Grant the minimal tool set."
+                    ),
+                    file=f.path,
+                    line=line_of(f.text, tool),
+                    evidence=f"allowed-tools: {tool}",
+                )
+            )
+
+    if not fm.get("name"):
+        out.append(
+            Finding(
+                check="manifest",
+                severity="medium",
+                title="Skill manifest missing `name`",
+                detail=f"`{f.path}` frontmatter has no `name` field; unnamed skills are hard to attribute or audit.",
+                file=f.path,
+                line=1,
+                evidence="--- frontmatter without name ---",
+            )
+        )
+    if not fm.get("description"):
+        out.append(
+            Finding(
+                check="manifest",
+                severity="low",
+                title="Skill manifest missing `description`",
+                detail=f"`{f.path}` frontmatter has no `description`; consumers cannot judge intent.",
+                file=f.path,
+                line=1,
+                evidence="--- frontmatter without description ---",
+            )
+        )
+
+
+def _check_npm(f: ArtifactFile, out: list[Finding]) -> None:
+    try:
+        data = json.loads(f.text)
+    except json.JSONDecodeError:
+        out.append(
+            Finding(
+                check="manifest",
+                severity="medium",
+                title="Unparseable package.json",
+                detail=f"`{f.path}` is not valid JSON; dependency and script analysis was skipped.",
+                file=f.path,
+                line=1,
+            )
+        )
+        return
+    if not isinstance(data, dict):
+        return
+    for field in ("name", "version"):
+        if not data.get(field):
+            out.append(
+                Finding(
+                    check="manifest",
+                    severity="low",
+                    title=f"package.json missing `{field}`",
+                    detail=f"`{f.path}` has no `{field}`; provenance is unclear.",
+                    file=f.path,
+                    line=1,
+                )
+            )
+
+
+def _check_mcp(f: ArtifactFile, out: list[Finding]) -> None:
+    try:
+        data = json.loads(f.text)
+    except json.JSONDecodeError:
+        return
+    servers = {}
+    if isinstance(data, dict):
+        for key in ("mcpServers", "mcp_servers", "mcp-servers"):
+            if isinstance(data.get(key), dict):
+                servers = data[key]
+                break
+    for name, cfg in servers.items():
+        if not isinstance(cfg, dict):
+            continue
+        args = cfg.get("args") or []
+        command = str(cfg.get("command", ""))
+        joined = " ".join(str(a) for a in args) if isinstance(args, list) else str(args)
+        if (
+            command in ("npx", "npx.cmd", "uvx")
+            and "-y" in joined
+            and "@latest" not in joined
+        ):
+            out.append(
+                Finding(
+                    check="manifest",
+                    severity="medium",
+                    title="MCP server runs an unpinned package",
+                    detail=(
+                        f"Server `{name}` in `{f.path}` runs `{command} {joined}` without a "
+                        "version pin — the executed code can change after review."
+                    ),
+                    file=f.path,
+                    line=line_of(f.text, name),
+                    evidence=f"{command} {joined}".strip() or command,
+                )
+            )
+        elif not command and "url" not in cfg:
+            out.append(
+                Finding(
+                    check="manifest",
+                    severity="low",
+                    title="MCP server entry with no command or URL",
+                    detail=f"Server `{name}` in `{f.path}` declares neither `command` nor `url`.",
+                    file=f.path,
+                    line=line_of(f.text, name),
+                )
+            )
+
+
+def run(files: list[ArtifactFile]) -> list[Finding]:
+    out: list[Finding] = []
+    for f in files:
+        if f.kind == "skill-md":
+            _check_skill_md(f, out)
+        elif f.kind == "npm-manifest":
+            _check_npm(f, out)
+        elif f.kind == "mcp-manifest":
+            _check_mcp(f, out)
+    return out

orithos_cli/skillscan/checks/network.py

@@ -0,0 +1,117 @@
+"""Check 3 — outbound network destinations.
+
+Flags exfiltration-friendly endpoints (paste sites, request bins, tunnels)
+and public IP literals in code and manifests. Documentation URLs are only
+reported when they match an exfiltration endpoint class.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+
+from orithos_cli.skillscan.model import ArtifactFile, Finding, line_of, snippet
+
+# Host pattern -> (severity, reason). These are endpoint *classes* commonly
+# abused for payload staging and exfiltration in agent-skill attacks; the list
+# is intentionally short and versioned here so it can grow with research.
+EXFIL_HOSTS: list[tuple[str, str, str]] = [
+    ("webhook.site", "critical", "webhook catch-all service"),
+    ("pipedream.net", "critical", "webhook catch-all service"),
+    ("requestbin", "critical", "request bin service"),
+    ("requestcatcher", "critical", "request bin service"),
+    ("transfer.sh", "high", "anonymous file drop"),
+    ("file.io", "high", "anonymous file drop"),
+    ("0x0.st", "high", "anonymous file drop"),
+    ("tmpfiles.org", "high", "anonymous file drop"),
+    ("pastebin.com", "high", "paste site"),
+    ("hastebin", "high", "paste site"),
+    ("ngrok", "high", "tunnel service"),
+    ("trycloudflare.com", "high", "tunnel service"),
+    ("localtunnel", "high", "tunnel service"),
+    ("interact.sh", "critical", "OOB interaction service"),
+    ("oast.fun", "critical", "OOB interaction service"),
+    ("oastify", "critical", "OOB interaction service"),
+    ("burpcollaborator", "critical", "OOB interaction service"),
+    ("canarytokens", "high", "token callback service"),
+]
+
+_URL_RE = re.compile(r"https?://([A-Za-z0-9._~-]+)(?::\d+)?(?:[/?#]|\b)")
+_IPV4_RE = re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b")
+
+
+def _severity_for(kind: str, base: str) -> str:
+    # Documentation may legitimately reference a service; demote in prose.
+    if kind in ("skill-md", "text") and base in ("critical", "high"):
+        return "medium"
+    return base
+
+
+def run(files: list[ArtifactFile]) -> list[Finding]:
+    out: list[Finding] = []
+    for f in files:
+        if f.kind not in (
+            "code",
+            "skill-md",
+            "text",
+            "npm-manifest",
+            "mcp-manifest",
+            "python-project",
+        ):
+            continue
+        text_lower = f.text.lower()
+        for pattern, base_sev, reason in EXFIL_HOSTS:
+            idx = text_lower.find(pattern)
+            if idx < 0:
+                continue
+            out.append(
+                Finding(
+                    check="network",
+                    severity=_severity_for(f.kind, base_sev),
+                    title="Reference to exfiltration-prone endpoint",
+                    detail=(
+                        f"`{f.path}` references `{pattern}` ({reason}). Agent skills posting "
+                        "data to catch-all endpoints is a common exfiltration pattern."
+                    ),
+                    file=f.path,
+                    line=line_of(f.text.lower(), pattern),
+                    evidence=snippet(f.text, idx),
+                )
+            )
+        for m in _URL_RE.finditer(f.text):
+            host = m.group(1)
+            host_l = host.lower()
+            if any(p in host_l for p in [p for p, _, _ in EXFIL_HOSTS]):
+                continue  # already reported above
+            if host_l in ("localhost", "127.0.0.1", "0.0.0.0"):
+                continue
+            try:
+                ip = ipaddress.ip_address(host)
+            except ValueError:
+                ip = None
+            if ip is not None:
+                continue  # IP literals handled below (URL already implies network use)
+            if f.kind in ("skill-md", "text"):
+                continue  # docs may link anywhere; only endpoint classes matter there
+        for m in _IPV4_RE.finditer(f.text):
+            try:
+                ip = ipaddress.ip_address(m.group(0))
+            except ValueError:
+                continue
+            if ip.is_private or ip.is_loopback or ip.is_multicast or ip.is_reserved:
+                continue
+            out.append(
+                Finding(
+                    check="network",
+                    severity="medium",
+                    title="Public IP literal instead of a hostname",
+                    detail=(
+                        f"`{f.path}` references the public IP `{m.group(0)}` directly. IPs "
+                        "dodge domain-based review and blocklists."
+                    ),
+                    file=f.path,
+                    line=line_of(f.text, m.group(0)),
+                    evidence=snippet(f.text, m.start()),
+                )
+            )
+    return out