plugin-scanner 1.4.15__py3-none-any.whl

codex_plugin_scanner/trust_mcp_scoring.py

@@ -0,0 +1,116 @@
+"""HCS-style MCP trust scoring."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .models import CategoryResult
+from .trust_helpers import (
+    build_adapter_score,
+    build_domain_score,
+    category_checks,
+    check_percent,
+    is_https_url,
+    load_mcp_payload,
+)
+from .trust_models import TrustDomainScore
+from .trust_specs import MCP_TRUST_SPEC
+
+
+def build_mcp_domain(plugin_dir: Path, categories: tuple[CategoryResult, ...]) -> TrustDomainScore | None:
+    payload_state = load_mcp_payload(plugin_dir)
+    if payload_state is None:
+        return None
+
+    payload = payload_state.payload
+    security_checks = category_checks(categories, "Security")
+    remotes = payload.get("remotes")
+    servers = payload.get("mcpServers")
+    remote_entries = remotes if isinstance(remotes, list) else []
+    local_servers = servers if isinstance(servers, dict) else {}
+    has_named_surfaces = bool(remote_entries) or bool(local_servers)
+    secure_remote_urls = (
+        all(isinstance(entry, dict) and is_https_url(str(entry.get("url", ""))) for entry in remote_entries)
+        if remote_entries
+        else True
+    )
+    local_commands_valid = (
+        all(
+            isinstance(config, dict)
+            and isinstance(config.get("command"), str)
+            and bool(config.get("command"))
+            and (
+                "args" not in config
+                or (
+                    isinstance(config.get("args"), list) and all(isinstance(value, str) for value in config.get("args"))
+                )
+            )
+            for config in local_servers.values()
+        )
+        if local_servers
+        else True
+    )
+    config_shape = payload_state.parse_valid and (
+        (remotes is None or isinstance(remotes, list)) and (servers is None or isinstance(servers, dict))
+    )
+
+    spec_by_id = {adapter.adapter_id: adapter for adapter in MCP_TRUST_SPEC.adapters}
+    adapters = (
+        build_adapter_score(
+            spec_by_id["verification.config-integrity"],
+            component_scores={"score": 100.0} if payload_state.parse_valid else None,
+            rationales={
+                "score": (
+                    "The .mcp.json file parsed successfully."
+                    if payload_state.parse_valid
+                    else "The .mcp.json file did not parse, so config-integrity remains 0."
+                )
+            },
+        ),
+        build_adapter_score(
+            spec_by_id["verification.execution-safety"],
+            component_scores={"score": check_percent(security_checks, "No dangerous MCP commands")},
+            rationales={"score": "Execution safety follows the scanner's dangerous-command check."},
+        ),
+        build_adapter_score(
+            spec_by_id["verification.transport-security"],
+            component_scores={"score": check_percent(security_checks, "MCP remote transports are hardened")},
+            rationales={"score": "Transport security follows the scanner's hardened-remote check."},
+        ),
+        build_adapter_score(
+            spec_by_id["metadata.server-naming"],
+            component_scores={"score": 100.0} if has_named_surfaces else None,
+            rationales={
+                "score": (
+                    "At least one MCP surface is explicitly named."
+                    if has_named_surfaces
+                    else "No local or remote MCP surfaces are declared."
+                )
+            },
+        ),
+        build_adapter_score(
+            spec_by_id["metadata.command-or-endpoint"],
+            component_scores=(
+                {"score": 100.0} if has_named_surfaces and secure_remote_urls and local_commands_valid else None
+            ),
+            rationales={
+                "score": (
+                    "Every MCP surface declares a concrete command or HTTPS endpoint."
+                    if has_named_surfaces and secure_remote_urls and local_commands_valid
+                    else "At least one MCP surface is missing a valid command or secure endpoint."
+                )
+            },
+        ),
+        build_adapter_score(
+            spec_by_id["metadata.config-shape"],
+            component_scores={"score": 100.0} if config_shape else None,
+            rationales={
+                "score": (
+                    "The top-level MCP config containers match the expected shape."
+                    if config_shape
+                    else "The MCP config containers do not match the expected shape."
+                )
+            },
+        ),
+    )
+    return build_domain_score(domain="mcp", spec=MCP_TRUST_SPEC, adapters=adapters)

codex_plugin_scanner/trust_models.py

@@ -0,0 +1,85 @@
+"""Trust provenance data models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+ContributionMode = Literal["conditional", "universal", "scoped"]
+
+
+@dataclass(frozen=True, slots=True)
+class TrustComponentScore:
+    """One scored trust component inside an adapter."""
+
+    key: str
+    score: float
+    rationale: str
+    evidence: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class TrustAdapterScore:
+    """Weighted adapter score inside a trust domain."""
+
+    adapter_id: str
+    label: str
+    weight: float
+    contribution_mode: ContributionMode
+    applicable: bool
+    emitted: bool
+    included_in_denominator: bool
+    score: float
+    components: tuple[TrustComponentScore, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TrustDomainScore:
+    """One trust domain such as plugin, skills, or MCP."""
+
+    domain: str
+    label: str
+    spec_id: str
+    spec_version: str
+    spec_path: str
+    derived_from: tuple[str, ...]
+    profile_id: str
+    profile_version: str
+    score: float
+    adapters: tuple[TrustAdapterScore, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class TrustReport:
+    """Overall trust report emitted alongside scan results."""
+
+    total: float
+    include_external: bool
+    computed_at: str
+    domains: tuple[TrustDomainScore, ...] = ()
+
+
+@dataclass(frozen=True, slots=True)
+class TrustAdapterSpec:
+    """Definition of a trust adapter and its components."""
+
+    adapter_id: str
+    label: str
+    weight: float
+    component_keys: tuple[str, ...]
+    contribution_mode: ContributionMode = "conditional"
+    default_component_key: str = "score"
+
+
+@dataclass(frozen=True, slots=True)
+class TrustSpecDefinition:
+    """Definition of a trust scoring specification."""
+
+    spec_id: str
+    version: str
+    label: str
+    spec_path: str
+    derived_from: tuple[str, ...]
+    profile_id: str
+    profile_version: str
+    adapters: tuple[TrustAdapterSpec, ...] = field(default_factory=tuple)

codex_plugin_scanner/trust_plugin_scoring.py

@@ -0,0 +1,180 @@
+"""HCS-style top-level plugin trust scoring."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .checks.manifest import load_manifest
+from .models import CategoryResult
+from .trust_helpers import build_adapter_score, build_domain_score, category_checks, check_percent, is_https_url
+from .trust_models import TrustDomainScore
+from .trust_specs import PLUGIN_TRUST_SPEC
+
+
+def build_plugin_domain(plugin_dir: Path, categories: tuple[CategoryResult, ...]) -> TrustDomainScore:
+    manifest = load_manifest(plugin_dir)
+    manifest_checks = category_checks(categories, "Manifest Validation")
+    security_checks = category_checks(categories, "Security")
+    operational_checks = category_checks(categories, "Operational Security")
+    best_checks = category_checks(categories, "Best Practices")
+    marketplace_checks = category_checks(categories, "Marketplace")
+    interface = (
+        manifest.get("interface") if isinstance(manifest, dict) and isinstance(manifest.get("interface"), dict) else {}
+    )
+    interface_declared = isinstance(manifest, dict) and "interface" in manifest
+    author = manifest.get("author") if isinstance(manifest, dict) and isinstance(manifest.get("author"), dict) else {}
+    has_author = isinstance(author.get("name"), str) and bool(author.get("name"))
+    has_homepage = is_https_url(manifest.get("homepage") if isinstance(manifest, dict) else None)
+    has_repository = is_https_url(manifest.get("repository") if isinstance(manifest, dict) else None)
+    keywords = manifest.get("keywords") if isinstance(manifest, dict) else None
+    keyword_count = len(keywords) if isinstance(keywords, list) else 0
+    has_interface_category = isinstance(interface.get("category"), str) and bool(interface.get("category"))
+    discoverability = (
+        100.0
+        if has_interface_category and keyword_count >= 3
+        else 75.0
+        if has_interface_category or keyword_count >= 1
+        else 0.0
+    )
+    provenance = (
+        100.0
+        if has_author and has_homepage and has_repository
+        else 70.0
+        if has_author and (has_homepage or has_repository)
+        else 40.0
+        if has_author or has_repository or has_homepage
+        else 0.0
+    )
+    has_marketplace_surface = (plugin_dir / "marketplace.json").exists()
+    has_mcp_surface = (plugin_dir / ".mcp.json").exists()
+
+    spec_by_id = {adapter.adapter_id: adapter for adapter in PLUGIN_TRUST_SPEC.adapters}
+    adapters = (
+        build_adapter_score(
+            spec_by_id["verification.manifest-integrity"],
+            component_scores={
+                "score": (
+                    check_percent(manifest_checks, "plugin.json exists") * 0.20
+                    + check_percent(manifest_checks, "Valid JSON") * 0.20
+                    + check_percent(manifest_checks, "Required fields present") * 0.35
+                    + check_percent(manifest_checks, "Version follows semver") * 0.25
+                )
+            },
+            rationales={
+                "score": "Manifest integrity blends existence, JSON validity, required fields, and semver checks."
+            },
+        ),
+        build_adapter_score(
+            spec_by_id["verification.interface-integrity"],
+            component_scores={
+                "score": (
+                    check_percent(manifest_checks, "Interface metadata complete if declared") * 0.60
+                    + check_percent(manifest_checks, "Interface links and assets valid if declared") * 0.40
+                )
+            }
+            if interface_declared
+            else None,
+            rationales={"score": "Interface integrity applies when the plugin declares an install surface."},
+            applicable=interface_declared,
+        ),
+        build_adapter_score(
+            spec_by_id["verification.path-safety"],
+            component_scores={"score": check_percent(manifest_checks, "Declared paths are safe")},
+            rationales={"score": "Path safety uses the scanner's declared-path safety check."},
+        ),
+        build_adapter_score(
+            spec_by_id["verification.marketplace-alignment"],
+            component_scores={
+                "score": (
+                    check_percent(marketplace_checks, "marketplace.json valid") * 0.35
+                    + check_percent(marketplace_checks, "Policy fields present") * 0.35
+                    + check_percent(marketplace_checks, "Marketplace sources are safe") * 0.30
+                )
+            }
+            if has_marketplace_surface
+            else None,
+            rationales={
+                "score": "Marketplace alignment applies when repository-scoped marketplace metadata is present."
+            },
+            applicable=has_marketplace_surface,
+        ),
+        build_adapter_score(
+            spec_by_id["security.disclosure"],
+            component_scores={"score": check_percent(security_checks, "SECURITY.md found")},
+            rationales={"score": "Disclosure is one explicit signal, not a proxy for the entire security posture."},
+        ),
+        build_adapter_score(
+            spec_by_id["security.license"],
+            component_scores={"score": check_percent(security_checks, "LICENSE found")},
+            rationales={"score": "License clarity remains a separate scored signal."},
+        ),
+        build_adapter_score(
+            spec_by_id["security.secret-hygiene"],
+            component_scores={"score": check_percent(security_checks, "No hardcoded secrets")},
+            rationales={"score": "Secret hygiene uses the scanner's hardcoded-secret detection."},
+        ),
+        build_adapter_score(
+            spec_by_id["security.mcp-safety"],
+            component_scores={
+                "score": (
+                    check_percent(security_checks, "No dangerous MCP commands") * 0.50
+                    + check_percent(security_checks, "MCP remote transports are hardened") * 0.50
+                )
+            }
+            if has_mcp_surface
+            else None,
+            rationales={"score": "MCP safety applies only when the plugin declares an MCP surface."},
+            applicable=has_mcp_surface,
+        ),
+        build_adapter_score(
+            spec_by_id["security.approval-hygiene"],
+            component_scores={"score": check_percent(security_checks, "No approval bypass defaults")},
+            rationales={"score": "Approval hygiene checks for bypass-style defaults."},
+        ),
+        build_adapter_score(
+            spec_by_id["metadata.documentation"],
+            component_scores={"score": check_percent(best_checks, "README.md found")},
+            rationales={"score": "Documentation reflects README coverage for operators and maintainers."},
+        ),
+        build_adapter_score(
+            spec_by_id["metadata.manifest-metadata"],
+            component_scores={"score": check_percent(manifest_checks, "Recommended metadata present")},
+            rationales={"score": "Manifest metadata tracks the scanner's recommended-metadata check."},
+        ),
+        build_adapter_score(
+            spec_by_id["metadata.discoverability"],
+            component_scores={"score": discoverability},
+            rationales={"score": "Discoverability uses category plus keyword coverage."},
+        ),
+        build_adapter_score(
+            spec_by_id["metadata.provenance"],
+            component_scores={"score": provenance},
+            rationales={"score": "Provenance reflects author, homepage, and repository metadata coverage."},
+        ),
+        build_adapter_score(
+            spec_by_id["operations.action-pinning"],
+            component_scores={"score": check_percent(operational_checks, "Third-party GitHub Actions pinned to SHAs")},
+            rationales={"score": "Action pinning uses the scanner's immutable-action check."},
+        ),
+        build_adapter_score(
+            spec_by_id["operations.permission-scope"],
+            component_scores={"score": check_percent(operational_checks, "No write-all GitHub Actions permissions")},
+            rationales={"score": "Permission scope uses the least-privilege workflow check."},
+        ),
+        build_adapter_score(
+            spec_by_id["operations.untrusted-checkout"],
+            component_scores={"score": check_percent(operational_checks, "No privileged untrusted checkout patterns")},
+            rationales={"score": "Untrusted-checkout protection uses the scanner's privileged-workflow check."},
+        ),
+        build_adapter_score(
+            spec_by_id["operations.update-automation"],
+            component_scores={
+                "score": (
+                    check_percent(operational_checks, "Dependabot configured for automation surfaces") * 0.50
+                    + check_percent(operational_checks, "Dependency manifests have lockfiles") * 0.50
+                )
+            },
+            rationales={"score": "Update automation combines Dependabot coverage and lockfile hygiene."},
+        ),
+    )
+    return build_domain_score(domain="plugin", spec=PLUGIN_TRUST_SPEC, adapters=adapters)

codex_plugin_scanner/trust_scoring.py

@@ -0,0 +1,52 @@
+"""Trust scoring and provenance formatting for scan results."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .checks.skill_security import SkillSecurityContext
+from .models import CategoryResult
+from .trust_domain_scoring import build_mcp_domain, build_plugin_domain, build_skill_domain
+from .trust_helpers import normalize_report_total, round_trust_score
+from .trust_models import TrustReport
+
+
+def build_plugin_trust_report(
+    plugin_dir: Path,
+    categories: tuple[CategoryResult, ...],
+    skill_security_context: SkillSecurityContext,
+) -> TrustReport:
+    computed_at = datetime.now(timezone.utc).isoformat()
+    domains = [
+        domain
+        for domain in (
+            build_plugin_domain(plugin_dir, categories),
+            build_skill_domain(plugin_dir, skill_security_context),
+            build_mcp_domain(plugin_dir, categories),
+        )
+        if domain is not None
+    ]
+    scores = tuple(domain.score for domain in domains)
+    return TrustReport(
+        total=normalize_report_total(scores),
+        include_external=False,
+        computed_at=computed_at,
+        domains=tuple(domains),
+    )
+
+
+def build_repository_trust_report(plugin_reports: tuple[TrustReport, ...]) -> TrustReport:
+    if not plugin_reports:
+        return TrustReport(
+            total=0.0,
+            include_external=False,
+            computed_at=datetime.now(timezone.utc).isoformat(),
+            domains=(),
+        )
+    return TrustReport(
+        total=round_trust_score(min(report.total for report in plugin_reports)),
+        include_external=False,
+        computed_at=max(report.computed_at for report in plugin_reports),
+        domains=(),
+    )