codex-plugin-scanner 1.0.0__py3-none-any.whl

codex_plugin_scanner/__init__.py

@@ -0,0 +1,14 @@
+"""Codex Plugin Scanner - security and best-practices scanner for Codex CLI plugins."""
+
+from .models import GRADE_LABELS, CategoryResult, CheckResult, ScanResult, get_grade
+from .scanner import scan_plugin
+
+__version__ = "1.0.0"
+__all__ = [
+    "GRADE_LABELS",
+    "CategoryResult",
+    "CheckResult",
+    "ScanResult",
+    "get_grade",
+    "scan_plugin",
+]

codex_plugin_scanner/checks/best_practices.py

@@ -0,0 +1,171 @@
+"""Best practice checks (25 points)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..models import CheckResult
+from .manifest import load_manifest
+
+ENV_FILES = {".env", ".env.local", ".env.production"}
+
+
+def check_readme(plugin_dir: Path) -> CheckResult:
+    exists = (plugin_dir / "README.md").exists()
+    return CheckResult(
+        name="README.md found",
+        passed=exists,
+        points=5 if exists else 0,
+        max_points=5,
+        message="README.md found" if exists else "README.md not found",
+    )
+
+
+def check_skills_directory(plugin_dir: Path) -> CheckResult:
+    manifest = load_manifest(plugin_dir)
+    if manifest is None:
+        return CheckResult(
+            name="Skills directory exists if declared",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="Cannot parse manifest, skipping check",
+        )
+    skills = manifest.get("skills")
+    if not skills:
+        return CheckResult(
+            name="Skills directory exists if declared",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="No skills field declared, check not applicable",
+        )
+    skills_path = plugin_dir / skills
+    if skills_path.is_dir():
+        return CheckResult(
+            name="Skills directory exists if declared",
+            passed=True,
+            points=5,
+            max_points=5,
+            message=f'Skills directory "{skills}" exists',
+        )
+    return CheckResult(
+        name="Skills directory exists if declared",
+        passed=False,
+        points=0,
+        max_points=5,
+        message=f'Skills directory "{skills}" declared but not found',
+    )
+
+
+def check_skill_frontmatter(plugin_dir: Path) -> CheckResult:
+    manifest = load_manifest(plugin_dir)
+    if manifest is None:
+        return CheckResult(
+            name="SKILL.md frontmatter",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="Cannot parse manifest, skipping check",
+        )
+    skills = manifest.get("skills")
+    if not skills:
+        return CheckResult(
+            name="SKILL.md frontmatter",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="No skills field declared, check not applicable",
+        )
+    skills_path = plugin_dir / skills
+    if not skills_path.is_dir():
+        return CheckResult(
+            name="SKILL.md frontmatter",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="Skills directory not found, skipping check",
+        )
+
+    skill_files = list(skills_path.glob("*/SKILL.md"))
+    if not skill_files:
+        return CheckResult(
+            name="SKILL.md frontmatter",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="No SKILL.md files found, nothing to check",
+        )
+
+    issues: list[str] = []
+    for sf in skill_files:
+        try:
+            content = sf.read_text(encoding="utf-8")
+        except OSError:  # pragma: no cover
+            continue
+        if "---" not in content:
+            issues.append(str(sf.relative_to(plugin_dir)))
+            continue
+        parts = content.split("---", 2)
+        if len(parts) < 3:
+            issues.append(str(sf.relative_to(plugin_dir)))
+            continue
+        fm = parts[1]
+        if "name:" not in fm or "description:" not in fm:
+            issues.append(str(sf.relative_to(plugin_dir)))
+
+    if not issues:
+        return CheckResult(
+            name="SKILL.md frontmatter",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="All SKILL.md files have valid frontmatter",
+        )
+    return CheckResult(
+        name="SKILL.md frontmatter",
+        passed=False,
+        points=0,
+        max_points=5,
+        message=f"SKILL.md missing valid frontmatter in: {', '.join(issues)}",
+    )
+
+
+def check_no_env_files(plugin_dir: Path) -> CheckResult:
+    found = [f for f in ENV_FILES if (plugin_dir / f).exists()]
+    if not found:
+        return CheckResult(
+            name="No .env files committed",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="No .env files found",
+        )
+    return CheckResult(
+        name="No .env files committed",
+        passed=False,
+        points=0,
+        max_points=5,
+        message=f".env files found: {', '.join(found)}",
+    )
+
+
+def check_codexignore(plugin_dir: Path) -> CheckResult:
+    exists = (plugin_dir / ".codexignore").exists()
+    return CheckResult(
+        name=".codexignore found",
+        passed=exists,
+        points=5 if exists else 0,
+        max_points=5,
+        message=".codexignore found" if exists else ".codexignore not found",
+    )
+
+
+def run_best_practice_checks(plugin_dir: Path) -> tuple[CheckResult, ...]:
+    return (
+        check_readme(plugin_dir),
+        check_skills_directory(plugin_dir),
+        check_skill_frontmatter(plugin_dir),
+        check_no_env_files(plugin_dir),
+        check_codexignore(plugin_dir),
+    )

codex_plugin_scanner/checks/code_quality.py

@@ -0,0 +1,91 @@
+"""Code quality checks (10 points)."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ..models import CheckResult
+
+CODE_EXTS = {".py", ".js", ".ts", ".jsx", ".tsx", ".mjs", ".cjs"}
+EXCLUDED_DIRS = {"node_modules", ".git", "dist", ".next", "coverage", "__pycache__", ".venv", "venv"}
+
+EVAL_RE = re.compile(r"\beval\s*\(")
+FUNCTION_RE = re.compile(r"new\s+Function\s*\(")
+SHELL_INJECT_RE = re.compile(
+    r"`[^`]*\$\{[^}]+\}[^`]*`"
+    r"[\s\S]{0,30}"
+    r"\b(exec|spawn|execSync|spawnSync|os\.system|subprocess)\b"
+)
+
+
+def _find_code_files(plugin_dir: Path) -> list[Path]:
+    files = []
+    for p in plugin_dir.rglob("*"):
+        if not p.is_file() or p.suffix not in CODE_EXTS:
+            continue
+        if any(part in EXCLUDED_DIRS for part in p.parts):
+            continue
+        files.append(p)
+    return files
+
+
+def check_no_eval(plugin_dir: Path) -> CheckResult:
+    findings: list[str] = []
+    for fpath in _find_code_files(plugin_dir):
+        try:
+            content = fpath.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        if EVAL_RE.search(content):
+            findings.append(f"{fpath.relative_to(plugin_dir)}: eval()")
+        if FUNCTION_RE.search(content):
+            findings.append(f"{fpath.relative_to(plugin_dir)}: new Function()")
+    if not findings:
+        return CheckResult(
+            name="No eval or Function constructor",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="No eval() or new Function() usage detected",
+        )
+    return CheckResult(
+        name="No eval or Function constructor",
+        passed=False,
+        points=0,
+        max_points=5,
+        message=f"Found: {', '.join(findings[:3])}",
+    )
+
+
+def check_no_shell_injection(plugin_dir: Path) -> CheckResult:
+    findings: list[str] = []
+    for fpath in _find_code_files(plugin_dir):
+        try:
+            content = fpath.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        if SHELL_INJECT_RE.search(content):
+            findings.append(str(fpath.relative_to(plugin_dir)))
+    if not findings:
+        return CheckResult(
+            name="No shell injection patterns",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="No shell injection patterns detected",
+        )
+    return CheckResult(
+        name="No shell injection patterns",
+        passed=False,
+        points=0,
+        max_points=5,
+        message=f"Shell injection patterns in: {', '.join(findings)}",
+    )
+
+
+def run_code_quality_checks(plugin_dir: Path) -> tuple[CheckResult, ...]:
+    return (
+        check_no_eval(plugin_dir),
+        check_no_shell_injection(plugin_dir),
+    )

codex_plugin_scanner/checks/manifest.py

@@ -0,0 +1,121 @@
+"""Manifest validation checks (25 points)."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from ..models import CheckResult
+
+SEMVER_RE = re.compile(r"^\d+\.\d+\.\d+")
+KEBAB_RE = re.compile(r"^[a-z0-9]+(-[a-z0-9]+)*$")
+
+
+def load_manifest(plugin_dir: Path) -> dict | None:
+    p = plugin_dir / ".codex-plugin" / "plugin.json"
+    if not p.exists():
+        return None
+    try:
+        return json.loads(p.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return None
+
+
+def check_plugin_json_exists(plugin_dir: Path) -> CheckResult:
+    p = plugin_dir / ".codex-plugin" / "plugin.json"
+    exists = p.exists()
+    return CheckResult(
+        name="plugin.json exists",
+        passed=exists,
+        points=5 if exists else 0,
+        max_points=5,
+        message="plugin.json found" if exists else "plugin.json not found at .codex-plugin/plugin.json",
+    )
+
+
+def check_valid_json(plugin_dir: Path) -> CheckResult:
+    p = plugin_dir / ".codex-plugin" / "plugin.json"
+    try:
+        content = p.read_text(encoding="utf-8")
+        json.loads(content)
+        return CheckResult(name="Valid JSON", passed=True, points=5, max_points=5, message="plugin.json is valid JSON")
+    except Exception:
+        return CheckResult(
+            name="Valid JSON", passed=False, points=0, max_points=5, message="plugin.json is not valid JSON"
+        )
+
+
+def check_required_fields(plugin_dir: Path) -> CheckResult:
+    manifest = load_manifest(plugin_dir)
+    if manifest is None:
+        return CheckResult(
+            name="Required fields present", passed=False, points=0, max_points=8, message="Cannot parse plugin.json"
+        )
+    required = ["name", "version", "description"]
+    missing = [f for f in required if not manifest.get(f) or not isinstance(manifest.get(f), str)]
+    if not missing:
+        return CheckResult(
+            name="Required fields present",
+            passed=True,
+            points=8,
+            max_points=8,
+            message="All required fields (name, version, description) present",
+        )
+    return CheckResult(
+        name="Required fields present",
+        passed=False,
+        points=0,
+        max_points=8,
+        message=f"Missing required fields: {', '.join(missing)}",
+    )
+
+
+def check_semver(plugin_dir: Path) -> CheckResult:
+    manifest = load_manifest(plugin_dir)
+    if manifest is None:
+        return CheckResult(
+            name="Version follows semver", passed=False, points=0, max_points=4, message="Cannot parse plugin.json"
+        )
+    version = manifest.get("version", "")
+    if version and SEMVER_RE.match(str(version)):
+        return CheckResult(
+            name="Version follows semver",
+            passed=True,
+            points=4,
+            max_points=4,
+            message=f'Version "{version}" follows semver',
+        )
+    return CheckResult(
+        name="Version follows semver",
+        passed=False,
+        points=0,
+        max_points=4,
+        message=f'Version "{version}" does not follow semver (expected X.Y.Z)',
+    )
+
+
+def check_kebab_case(plugin_dir: Path) -> CheckResult:
+    manifest = load_manifest(plugin_dir)
+    if manifest is None:
+        return CheckResult(
+            name="Name is kebab-case", passed=False, points=0, max_points=3, message="Cannot parse plugin.json"
+        )
+    name = manifest.get("name", "")
+    if name and KEBAB_RE.match(str(name)):
+        return CheckResult(
+            name="Name is kebab-case", passed=True, points=3, max_points=3, message=f'Name "{name}" is kebab-case'
+        )
+    return CheckResult(
+        name="Name is kebab-case", passed=False, points=0, max_points=3, message=f'Name "{name}" should be kebab-case'
+    )
+
+
+def run_manifest_checks(plugin_dir: Path) -> tuple[CheckResult, ...]:
+    return (
+        check_plugin_json_exists(plugin_dir),
+        check_valid_json(plugin_dir),
+        check_required_fields(plugin_dir),
+        check_semver(plugin_dir),
+        check_kebab_case(plugin_dir),
+    )

codex_plugin_scanner/checks/marketplace.py

@@ -0,0 +1,130 @@
+"""Marketplace validation checks (10 points)."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from ..models import CheckResult
+
+
+def check_marketplace_json(plugin_dir: Path) -> CheckResult:
+    mp = plugin_dir / "marketplace.json"
+    if not mp.exists():
+        return CheckResult(
+            name="marketplace.json valid",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="No marketplace.json found, check not applicable",
+        )
+    try:
+        data = json.loads(mp.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return CheckResult(
+            name="marketplace.json valid",
+            passed=False,
+            points=0,
+            max_points=5,
+            message="marketplace.json is not valid JSON",
+        )
+
+    if not data.get("name") or not isinstance(data.get("name"), str):
+        return CheckResult(
+            name="marketplace.json valid",
+            passed=False,
+            points=0,
+            max_points=5,
+            message='marketplace.json missing "name" field',
+        )
+    if not isinstance(data.get("plugins"), list):
+        return CheckResult(
+            name="marketplace.json valid",
+            passed=False,
+            points=0,
+            max_points=5,
+            message='marketplace.json missing "plugins" array',
+        )
+    for i, plugin in enumerate(data["plugins"]):
+        if not plugin.get("source") or not isinstance(plugin.get("source"), str):
+            return CheckResult(
+                name="marketplace.json valid",
+                passed=False,
+                points=0,
+                max_points=5,
+                message=f'marketplace.json plugin[{i}] missing "source" field',
+            )
+        if not plugin.get("policy") or not isinstance(plugin.get("policy"), dict):
+            return CheckResult(
+                name="marketplace.json valid",
+                passed=False,
+                points=0,
+                max_points=5,
+                message=f'marketplace.json plugin[{i}] missing "policy" field',
+            )
+    return CheckResult(
+        name="marketplace.json valid", passed=True, points=5, max_points=5, message="marketplace.json is valid"
+    )
+
+
+def check_policy_fields(plugin_dir: Path) -> CheckResult:
+    mp = plugin_dir / "marketplace.json"
+    if not mp.exists():
+        return CheckResult(
+            name="Policy fields present",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="No marketplace.json found, check not applicable",
+        )
+    try:
+        data = json.loads(mp.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return CheckResult(
+            name="Policy fields present",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="Cannot parse marketplace.json, skipping check",
+        )
+
+    plugins = data.get("plugins", [])
+    if not plugins:
+        return CheckResult(
+            name="Policy fields present",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="No plugins in marketplace.json, nothing to check",
+        )
+
+    issues: list[str] = []
+    for i, plugin in enumerate(plugins):
+        policy = plugin.get("policy") or {}
+        if not policy.get("installation"):
+            issues.append(f"plugin[{i}]: missing policy.installation")
+        if not policy.get("authentication"):
+            issues.append(f"plugin[{i}]: missing policy.authentication")
+
+    if not issues:
+        return CheckResult(
+            name="Policy fields present",
+            passed=True,
+            points=5,
+            max_points=5,
+            message="All plugins have required policy fields",
+        )
+    return CheckResult(
+        name="Policy fields present",
+        passed=False,
+        points=0,
+        max_points=5,
+        message=f"Policy issues: {', '.join(issues[:3])}",
+    )
+
+
+def run_marketplace_checks(plugin_dir: Path) -> tuple[CheckResult, ...]:
+    return (
+        check_marketplace_json(plugin_dir),
+        check_policy_fields(plugin_dir),
+    )

codex_plugin_scanner/checks/security.py

@@ -0,0 +1,185 @@
+"""Security checks (30 points)."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from ..models import CheckResult
+
+# Patterns for hardcoded secrets
+SECRET_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"AKIA[0-9A-Z]{16}"),  # AWS access key
+    re.compile(r"aws_secret_access_key\s*[=:]\s*[\"']?[A-Za-z0-9/+=]{40}", re.I),
+    re.compile(r"-----BEGIN (RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----"),
+    re.compile(r"password\s*[=:]\s*[\"'][^\s\"']{8,}", re.I),
+    re.compile(r"secret\s*[=:]\s*[\"'][^\s\"']{8,}", re.I),
+    re.compile(r"token\s*[=:]\s*[\"'][^\s\"']{8,}", re.I),
+    re.compile(r"api_?key\s*[=:]\s*[\"'][^\s\"']{8,}", re.I),
+    re.compile(r"API_KEY\s*[=:]\s*[\"'][^\s\"']{8,}"),
+    re.compile(r"PRIVATE_KEY\s*[=:]\s*[\"'][^\s\"']{8,}"),
+    re.compile(r"ghp_[A-Za-z0-9]{36}"),  # GitHub PAT
+    re.compile(r"gho_[A-Za-z0-9]{36}"),  # GitHub OAuth
+    re.compile(r"ghu_[A-Za-z0-9]{36}"),  # GitHub user token
+    re.compile(r"ghs_[A-Za-z0-9]{36}"),  # GitHub app token
+    re.compile(r"glpat-[A-Za-z0-9\-]{20}"),  # GitLab PAT
+    re.compile(r"xox[bpas]-[A-Za-z0-9\-]{10,}"),  # Slack tokens
+    re.compile(r"sk-[A-Za-z0-9]{48}"),  # OpenAI key
+]
+
+EXCLUDED_DIRS = {"node_modules", ".git", "dist", ".next", "coverage", ".turbo", "__pycache__", ".venv", "venv"}
+
+BINARY_EXTS = {
+    ".png",
+    ".jpg",
+    ".jpeg",
+    ".gif",
+    ".ico",
+    ".svg",
+    ".webp",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".eot",
+    ".otf",
+    ".zip",
+    ".tar",
+    ".gz",
+    ".7z",
+    ".rar",
+    ".lock",
+    ".wasm",
+    ".pyc",
+    ".so",
+    ".dylib",
+}
+
+DANGEROUS_MCP_PATTERNS: list[re.Pattern[str]] = [
+    re.compile(r"rm\s+-rf"),
+    re.compile(r"\bsudo\b"),
+    re.compile(r"curl\b.*\|\s*(ba)?sh"),
+    re.compile(r"wget\b.*\|\s*(ba)?sh"),
+    re.compile(r"bash\s+-c"),
+    re.compile(r"\beval\b"),
+    re.compile(r"\bexec\b"),
+    re.compile(r"powershell\s+-c", re.I),
+    re.compile(r"cmd\s*/c", re.I),
+]
+
+
+def _scan_all_files(plugin_dir: Path) -> list[Path]:
+    """Recursively find all files, skipping excluded dirs."""
+    files = []
+    for p in plugin_dir.rglob("*"):
+        if not p.is_file():
+            continue
+        if any(part in EXCLUDED_DIRS for part in p.parts):
+            continue
+        if p.suffix.lower() in BINARY_EXTS:
+            continue
+        files.append(p)
+    return files
+
+
+def check_security_md(plugin_dir: Path) -> CheckResult:
+    exists = (plugin_dir / "SECURITY.md").exists()
+    return CheckResult(
+        name="SECURITY.md found",
+        passed=exists,
+        points=5 if exists else 0,
+        max_points=5,
+        message="SECURITY.md found" if exists else "SECURITY.md not found",
+    )
+
+
+def check_license(plugin_dir: Path) -> CheckResult:
+    lp = plugin_dir / "LICENSE"
+    if not lp.exists():
+        return CheckResult(name="LICENSE found", passed=False, points=0, max_points=5, message="LICENSE file not found")
+    try:
+        content = lp.read_text(encoding="utf-8", errors="ignore")
+        if "Apache" in content and ("2.0" in content or "www.apache.org" in content):
+            return CheckResult(
+                name="LICENSE found", passed=True, points=5, max_points=5, message="LICENSE found (Apache-2.0)"
+            )
+        if "MIT" in content and "Permission is hereby granted" in content:
+            return CheckResult(name="LICENSE found", passed=True, points=5, max_points=5, message="LICENSE found (MIT)")
+        return CheckResult(
+            name="LICENSE found", passed=True, points=5, max_points=5, message="LICENSE found (not Apache-2.0 or MIT)"
+        )
+    except OSError:
+        return CheckResult(
+            name="LICENSE found", passed=False, points=0, max_points=5, message="LICENSE exists but could not be read"
+        )
+
+
+def check_no_hardcoded_secrets(plugin_dir: Path) -> CheckResult:
+    findings: list[str] = []
+    for fpath in _scan_all_files(plugin_dir):
+        try:
+            content = fpath.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        for pattern in SECRET_PATTERNS:
+            if pattern.search(content):
+                findings.append(str(fpath.relative_to(plugin_dir)))
+                break
+    if not findings:
+        return CheckResult(
+            name="No hardcoded secrets", passed=True, points=10, max_points=10, message="No hardcoded secrets detected"
+        )
+    shown = findings[:5]
+    suffix = f" and {len(findings) - 5} more" if len(findings) > 5 else ""
+    return CheckResult(
+        name="No hardcoded secrets",
+        passed=False,
+        points=0,
+        max_points=10,
+        message=f"Hardcoded secrets found in: {', '.join(shown)}{suffix}",
+    )
+
+
+def check_no_dangerous_mcp(plugin_dir: Path) -> CheckResult:
+    mcp_path = plugin_dir / ".mcp.json"
+    if not mcp_path.exists():
+        return CheckResult(
+            name="No dangerous MCP commands",
+            passed=True,
+            points=10,
+            max_points=10,
+            message="No .mcp.json found, skipping check",
+        )
+    try:
+        content = mcp_path.read_text(encoding="utf-8")
+    except OSError:
+        return CheckResult(
+            name="No dangerous MCP commands", passed=True, points=10, max_points=10, message="Could not read .mcp.json"
+        )
+    found: list[str] = []
+    for pattern in DANGEROUS_MCP_PATTERNS:
+        if pattern.search(content):
+            found.append(pattern.pattern)
+    if not found:
+        return CheckResult(
+            name="No dangerous MCP commands",
+            passed=True,
+            points=10,
+            max_points=10,
+            message="No dangerous commands found in .mcp.json",
+        )
+    return CheckResult(
+        name="No dangerous MCP commands",
+        passed=False,
+        points=0,
+        max_points=10,
+        message=f"Dangerous patterns in .mcp.json: {', '.join(found)}",
+    )
+
+
+def run_security_checks(plugin_dir: Path) -> tuple[CheckResult, ...]:
+    return (
+        check_security_md(plugin_dir),
+        check_license(plugin_dir),
+        check_no_hardcoded_secrets(plugin_dir),
+        check_no_dangerous_mcp(plugin_dir),
+    )

codex_plugin_scanner/cli.py

@@ -0,0 +1,154 @@
+"""Codex Plugin Scanner - CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .models import GRADE_LABELS
+from .scanner import scan_plugin
+
+__version__ = "1.0.0"
+
+
+def _build_plain_text(result) -> str:
+    """Build plain text output from a scan result."""
+    lines = [f"🔗 Codex Plugin Scanner v{__version__}", f"Scanning: {result.plugin_dir}", ""]
+    for category in result.categories:
+        cat_score = sum(c.points for c in category.checks)
+        cat_max = sum(c.max_points for c in category.checks)
+        lines.append(f"── {category.name} ({cat_score}/{cat_max}) ──")
+        for check in category.checks:
+            icon = "✅" if check.passed else "⚠️"
+            pts = f"+{check.points}" if check.passed else "+0"
+            lines.append(f"  {icon} {check.name:<42} {pts}")
+        lines.append("")
+    separator = "━" * 37
+    label = GRADE_LABELS.get(result.grade, "Unknown")
+    lines += [separator, f"Final Score: {result.score}/100 ({result.grade} - {label})", separator]
+    return "\n".join(lines)
+
+
+def _build_rich_text(result) -> str:
+    """Build rich markup text from a scan result."""
+    lines = [f"[bold cyan]🔗 Codex Plugin Scanner v{__version__}[/bold cyan]"]
+    lines.append(f"Scanning: {result.plugin_dir}")
+    lines.append("")
+    for category in result.categories:
+        cat_score = sum(c.points for c in category.checks)
+        cat_max = sum(c.max_points for c in category.checks)
+        lines.append(f"[bold yellow]── {category.name} ({cat_score}/{cat_max}) ──[/bold yellow]")
+        for check in category.checks:
+            icon = "✅" if check.passed else "⚠️"
+            style = "[green]" if check.passed else "[red]"
+            pts = f"[green]+{check.points}[/green]" if check.passed else "[red]+0[/red]"
+            lines.append(f"  {icon} {style}{check.name:<42}[/]{pts}")
+        lines.append("")
+    separator = "━" * 37
+    grade = result.grade
+    gc = {"A": "bold green", "B": "green", "C": "yellow", "D": "red", "F": "bold red"}.get(grade, "red")
+    label = GRADE_LABELS.get(grade, "Unknown")
+    lines += [
+        f"[bold]{separator}[/bold]",
+        f"Final Score: [bold]{result.score}[/bold]/100 ([{gc}]{grade} - {label}[/{gc}])",
+        f"[bold]{separator}[/bold]",
+    ]
+    return "\n".join(lines)
+
+
+def format_text(result) -> str:
+    """Format scan result as terminal output. Returns plain text string."""
+    plain = _build_plain_text(result)
+
+    try:
+        from rich.console import Console
+
+        console = Console()
+        console.print(_build_rich_text(result))
+    except ImportError:
+        print(plain)
+
+    return plain
+
+
+def format_json(result) -> str:
+    """Format scan result as JSON."""
+    data = {
+        "score": result.score,
+        "grade": result.grade,
+        "categories": [
+            {
+                "name": cat.name,
+                "score": sum(c.points for c in cat.checks),
+                "max": sum(c.max_points for c in cat.checks),
+                "checks": [
+                    {
+                        "name": c.name,
+                        "passed": c.passed,
+                        "points": c.points,
+                        "maxPoints": c.max_points,
+                        "message": c.message,
+                    }
+                    for c in cat.checks
+                ],
+            }
+            for cat in result.categories
+        ],
+        "timestamp": result.timestamp,
+        "pluginDir": result.plugin_dir,
+    }
+    return json.dumps(data, indent=2)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the CLI. Returns exit code."""
+    parser = argparse.ArgumentParser(
+        prog="codex-plugin-scanner",
+        description="Scan a Codex plugin directory for best practices and security",
+    )
+    parser.add_argument("plugin_dir", help="Path to the plugin directory to scan")
+    parser.add_argument("--json", action="store_true", help="Output results as JSON")
+    parser.add_argument("--output", "-o", help="Write JSON report to file")
+    parser.add_argument(
+        "--min-score",
+        type=int,
+        default=0,
+        help="Exit with code 1 if score is below this threshold (default: 0)",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    args = parser.parse_args(argv)
+
+    resolved = Path(args.plugin_dir).resolve()
+    if not resolved.is_dir():
+        print(f'Error: "{resolved}" is not a directory.', file=sys.stderr)
+        return 1
+
+    result = scan_plugin(args.plugin_dir)
+
+    if args.json or args.output:
+        output = format_json(result)
+        if args.output:
+            out_path = Path(args.output)
+            out_path.write_text(output, encoding="utf-8")
+            print(f"Report written to {out_path}")
+        else:
+            print(output)
+    else:
+        text = format_text(result)
+        if text:
+            print(text)
+
+    if result.score < args.min_score:
+        print(
+            f"Score {result.score} is below minimum threshold {args.min_score}",
+            file=sys.stderr,
+        )
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())  # pragma: no cover

codex_plugin_scanner/models.py

@@ -0,0 +1,57 @@
+"""Codex Plugin Scanner - types and data classes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class CheckResult:
+    """Result of an individual check."""
+
+    name: str
+    passed: bool
+    points: int
+    max_points: int
+    message: str
+
+
+@dataclass(frozen=True, slots=True)
+class CategoryResult:
+    """A category containing multiple checks."""
+
+    name: str
+    checks: tuple[CheckResult, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class ScanResult:
+    """Full result of scanning a plugin directory."""
+
+    score: int
+    grade: str
+    categories: tuple[CategoryResult, ...]
+    timestamp: str
+    plugin_dir: str
+
+
+def get_grade(score: int) -> str:
+    """Convert a numeric score to a letter grade."""
+    if score >= 90:
+        return "A"
+    if score >= 80:
+        return "B"
+    if score >= 70:
+        return "C"
+    if score >= 60:
+        return "D"
+    return "F"
+
+
+GRADE_LABELS: dict[str, str] = {
+    "A": "Excellent",
+    "B": "Good",
+    "C": "Acceptable",
+    "D": "Needs Improvement",
+    "F": "Failing",
+}

codex_plugin_scanner/scanner.py

@@ -0,0 +1,44 @@
+"""Codex Plugin Scanner - core scanning engine."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .checks.best_practices import run_best_practice_checks
+from .checks.code_quality import run_code_quality_checks
+from .checks.manifest import run_manifest_checks
+from .checks.marketplace import run_marketplace_checks
+from .checks.security import run_security_checks
+from .models import CategoryResult, ScanResult, get_grade
+
+
+def scan_plugin(plugin_dir: str | Path) -> ScanResult:
+    """Scan a Codex plugin directory and return a scored result.
+
+    Args:
+        plugin_dir: Path to the plugin directory to scan.
+
+    Returns:
+        ScanResult with score 0-100, grade A-F, and per-category breakdowns.
+    """
+    resolved = Path(plugin_dir).resolve()
+
+    categories: list[CategoryResult] = [
+        CategoryResult(name="Manifest Validation", checks=run_manifest_checks(resolved)),
+        CategoryResult(name="Security", checks=run_security_checks(resolved)),
+        CategoryResult(name="Best Practices", checks=run_best_practice_checks(resolved)),
+        CategoryResult(name="Marketplace", checks=run_marketplace_checks(resolved)),
+        CategoryResult(name="Code Quality", checks=run_code_quality_checks(resolved)),
+    ]
+
+    score = sum(c.points for cat in categories for c in cat.checks)
+    grade = get_grade(score)
+
+    return ScanResult(
+        score=score,
+        grade=grade,
+        categories=tuple(categories),
+        timestamp=datetime.now(timezone.utc).isoformat(),
+        plugin_dir=str(resolved),
+    )

codex_plugin_scanner-1.0.0.dist-info/METADATA

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: codex-plugin-scanner
+Version: 1.0.0
+Summary: Security and best-practices scanner for Codex CLI plugins. Scores plugins 0-100.
+Project-URL: Homepage, https://github.com/hashgraph-online/codex-plugin-scanner
+Project-URL: Repository, https://github.com/hashgraph-online/codex-plugin-scanner
+Project-URL: Issues, https://github.com/hashgraph-online/codex-plugin-scanner/issues
+Author-email: Hashgraph Online <dev@hol.org>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: cli,codex,mcp,plugin,scanner,security
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 🔗 Codex Plugin Scanner
+
+[![PyPI version](https://img.shields.io/pypi/v/codex-plugin-scanner.svg)](https://pypi.org/project/codex-plugin-scanner/)
+[![Python versions](https://img.shields.io/pypi/pyversions/codex-plugin-scanner.svg)](https://pypi.org/project/codex-plugin-scanner/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![CI](https://github.com/hashgraph-online/codex-plugin-scanner/actions/workflows/ci.yml/badge.svg)](https://github.com/hashgraph-online/codex-plugin-scanner/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hashgraph-online/codex-plugin-scanner/badge)](https://scorecard.dev/viewer/?uri=github.com/hashgraph-online/codex-plugin-scanner)
+
+A security and best-practices scanner for [Codex CLI plugins](https://developers.openai.com/codex/plugins). Scans plugin directories and outputs a score from 0-100.
+
+## Installation
+
+```bash
+pip install codex-plugin-scanner
+```
+
+Or run directly without installing:
+
+```bash
+pipx run codex-plugin-scanner ./my-plugin
+```
+
+## Usage
+
+```bash
+# Scan a plugin directory
+codex-plugin-scanner ./my-plugin
+
+# Output as JSON
+codex-plugin-scanner ./my-plugin --json
+
+# Write report to file
+codex-plugin-scanner ./my-plugin --output report.json
+```
+
+### Example Output
+
+```
+🔗 Codex Plugin Scanner v1.0.0
+Scanning: ./my-plugin
+
+── Manifest Validation (25/25) ──
+  ✅ plugin.json exists                          +5
+  ✅ Valid JSON                                   +5
+  ✅ Required fields present                      +8
+  ✅ Version follows semver                       +4
+  ✅ Name is kebab-case                           +3
+
+── Security (30/30) ──
+  ✅ SECURITY.md found                           +5
+  ✅ LICENSE found (Apache-2.0)                  +5
+  ✅ No hardcoded secrets detected               +10
+  ✅ No dangerous MCP commands                   +10
+
+── Best Practices (25/25) ──
+  ✅ README.md found                             +5
+  ✅ Skills directory exists if declared          +5
+  ✅ SKILL.md frontmatter                        +5
+  ✅ No .env files committed                     +5
+  ✅ .codexignore found                          +5
+
+── Marketplace (10/10) ──
+  ✅ marketplace.json valid                      +5
+  ✅ Policy fields present                       +5
+
+── Code Quality (10/10) ──
+  ✅ No eval or Function constructor             +5
+  ✅ No shell injection patterns                 +5
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Final Score: 100/100 (A - Excellent)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Scoring Breakdown
+
+| Category | Max Points | Checks |
+|----------|-----------|--------|
+| Manifest Validation | 25 | plugin.json exists, valid JSON, required fields, semver version, kebab-case name |
+| Security | 30 | SECURITY.md, LICENSE, no hardcoded secrets, no dangerous MCP commands |
+| Best Practices | 25 | README.md, skills directory, SKILL.md frontmatter, no .env files, .codexignore |
+| Marketplace | 10 | marketplace.json valid, policy fields present |
+| Code Quality | 10 | no eval/Function, no shell injection |
+
+### Grade Scale
+
+| Score | Grade | Meaning |
+|-------|-------|---------|
+| 90-100 | A | Excellent |
+| 80-89 | B | Good |
+| 70-79 | C | Acceptable |
+| 60-69 | D | Needs Improvement |
+| 0-59 | F | Failing |
+
+## Security Checks
+
+The scanner detects:
+
+- **Hardcoded secrets**: AWS keys, GitHub tokens, OpenAI keys, Slack tokens, GitLab tokens, generic password/secret/token patterns
+- **Dangerous MCP commands**: `rm -rf`, `sudo`, `curl|sh`, `wget|sh`, `eval`, `exec`, `powershell -c`
+- **Shell injection**: template literals with unsanitized interpolation in exec/spawn calls
+- **Unsafe code**: `eval()` and `new Function()` usage
+
+## Use as a GitHub Action
+
+Add to your plugin's CI:
+
+```yaml
+- name: Install scanner
+  run: pip install codex-plugin-scanner
+- name: Scan plugin
+  run: codex-plugin-scanner ./my-plugin
+```
+
+## Use as a pre-commit hook
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: codex-plugin-scanner
+        name: Codex Plugin Scanner
+        entry: codex-plugin-scanner
+        language: system
+        types: [directory]
+        pass_filenames: false
+        args: ["./"]
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check src/
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+[Apache-2.0](LICENSE) - Hashgraph Online

codex_plugin_scanner-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+codex_plugin_scanner/__init__.py,sha256=i2n3XpdZTRz03Q8m-XMzEiVjTa8ztagE-KNOK2xHEtg,359
+codex_plugin_scanner/cli.py,sha256=JnoliIK98ObwSCXEUQDb7N9SObTmuEzFPicpu_4T_1g,5268
+codex_plugin_scanner/models.py,sha256=f9LB9Jfozt8nLThh2_zSNk1SJ7NO4TlfOTUDIvXdOYE,1099
+codex_plugin_scanner/scanner.py,sha256=PwtA1G6MTDiKEoNB-5hXbagPY6jl1j2OVdBQMrYCsto,1593
+codex_plugin_scanner/checks/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codex_plugin_scanner/checks/best_practices.py,sha256=krGlH0LKglIkeDpAppKkWNnJ0akCwIU6RlEO4_prb_E,5095
+codex_plugin_scanner/checks/code_quality.py,sha256=HqxM5O0vF0cddZMKm-IxZc6hLe9aEr3-D9HxMZgFMoI,2790
+codex_plugin_scanner/checks/manifest.py,sha256=XamGZHndQWXEtY5pu6pHzn65GGLqU6X3UoclRweTTtc,4032
+codex_plugin_scanner/checks/marketplace.py,sha256=KM9dATcmbel_OlBaV3YTYvPJE76xZYftkQ-rOjDtX-Y,4157
+codex_plugin_scanner/checks/security.py,sha256=odWrNV-IFP_LDwZeLP_vuuKhoiLhdQh3SAlF2evXEA8,6137
+codex_plugin_scanner-1.0.0.dist-info/METADATA,sha256=ltdI7OiZsQh1UI9UCPMAcLUpKOtit-4Z6FV-rCG7a34,5931
+codex_plugin_scanner-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+codex_plugin_scanner-1.0.0.dist-info/entry_points.txt,sha256=Rk3DayqmbOKDsNT29p8sWSUM9rvGD1XGYTPtWwLoTHY,71
+codex_plugin_scanner-1.0.0.dist-info/licenses/LICENSE,sha256=h2qHK0hIjysdHOFg3u6YBgFFJE3Wh2moOSfgVUFwdtU,5651
+codex_plugin_scanner-1.0.0.dist-info/RECORD,,

codex_plugin_scanner-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

codex_plugin_scanner-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+codex-plugin-scanner = codex_plugin_scanner.cli:main

codex_plugin_scanner-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,118 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form.
+
+      "Derivative Works" shall mean any work that is based on the Work
+      and for which the editorial revisions, annotations, elaborations,
+      or other modifications represent, as a whole, an original work of
+      authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law, Contributor be liable for any
+      damages, including any direct, indirect, special, incidental, or
+      consequential damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Hashgraph Online
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0