plugin-scanner 1.4.15__py3-none-any.whl

codex_plugin_scanner/reporting.py

@@ -0,0 +1,376 @@
+"""Structured report formatters for scan results."""
+
+from __future__ import annotations
+
+import json
+
+from .models import GRADE_LABELS, SEVERITY_ORDER, Finding, ScanResult, Severity, severity_from_value
+from .version import __version__
+
+
+def _sorted_findings(findings: tuple[Finding, ...]) -> list[Finding]:
+    return sorted(findings, key=lambda finding: SEVERITY_ORDER[finding.severity], reverse=True)
+
+
+def _serialize_trust(result: ScanResult) -> dict[str, object]:
+    report = result.trust_report
+    if report is None:
+        return {
+            "total": 0.0,
+            "execution": {"includeExternal": False, "computedAt": result.timestamp},
+            "domains": [],
+        }
+    return {
+        "total": report.total,
+        "execution": {
+            "includeExternal": report.include_external,
+            "computedAt": report.computed_at,
+        },
+        "domains": [
+            {
+                "domain": domain.domain,
+                "label": domain.label,
+                "score": domain.score,
+                "spec": {
+                    "id": domain.spec_id,
+                    "version": domain.spec_version,
+                    "path": domain.spec_path,
+                    "derivedFrom": list(domain.derived_from),
+                },
+                "profile": {
+                    "id": domain.profile_id,
+                    "version": domain.profile_version,
+                },
+                "adapters": [
+                    {
+                        "id": adapter.adapter_id,
+                        "label": adapter.label,
+                        "weight": adapter.weight,
+                        "contributionMode": adapter.contribution_mode,
+                        "applicable": adapter.applicable,
+                        "emitted": adapter.emitted,
+                        "includedInDenominator": adapter.included_in_denominator,
+                        "score": adapter.score,
+                        "components": [
+                            {
+                                "key": component.key,
+                                "score": component.score,
+                                "rationale": component.rationale,
+                                "evidence": list(component.evidence),
+                            }
+                            for component in adapter.components
+                        ],
+                    }
+                    for adapter in domain.adapters
+                ],
+            }
+            for domain in report.domains
+        ],
+    }
+
+
+def build_json_payload(
+    result: ScanResult,
+    *,
+    profile: str = "default",
+    policy_pass: bool = True,
+    verify_pass: bool = True,
+    raw_score: int | None = None,
+    effective_score: int | None = None,
+) -> dict[str, object]:
+    """Convert a scan result into a JSON-serializable payload."""
+
+    payload = {
+        "schema_version": "scan-result.v1",
+        "tool_version": __version__,
+        "profile": profile,
+        "policy_pass": policy_pass,
+        "verify_pass": verify_pass,
+        "scope": result.scope,
+        "score": result.score,
+        "raw_score": result.score if raw_score is None else raw_score,
+        "effective_score": result.score if effective_score is None else effective_score,
+        "grade": result.grade,
+        "ecosystems": list(result.ecosystems),
+        "packages": [
+            {
+                "ecosystem": package.ecosystem,
+                "packageKind": package.package_kind,
+                "rootPath": package.root_path,
+                "manifestPath": package.manifest_path,
+                "name": package.name,
+                "version": package.version,
+            }
+            for package in result.packages
+        ],
+        "summary": {
+            "gradeLabel": GRADE_LABELS.get(result.grade, "Unknown"),
+            "findings": result.severity_counts,
+            "integrations": [
+                {
+                    "name": integration.name,
+                    "status": integration.status,
+                    "message": integration.message,
+                    "findingsCount": integration.findings_count,
+                    "metadata": integration.metadata,
+                }
+                for integration in result.integrations
+            ],
+        },
+        "trust": _serialize_trust(result),
+        "categories": [
+            {
+                "name": category.name,
+                "score": sum(check.points for check in category.checks),
+                "max": sum(check.max_points for check in category.checks),
+                "checks": [
+                    {
+                        "name": check.name,
+                        "passed": check.passed,
+                        "points": check.points,
+                        "maxPoints": check.max_points,
+                        "message": check.message,
+                        "findings": [
+                            {
+                                "ruleId": finding.rule_id,
+                                "severity": finding.severity.value,
+                                "title": finding.title,
+                                "description": finding.description,
+                                "remediation": finding.remediation,
+                                "filePath": finding.file_path,
+                                "lineNumber": finding.line_number,
+                                "source": finding.source,
+                            }
+                            for finding in check.findings
+                        ],
+                    }
+                    for check in category.checks
+                ],
+            }
+            for category in result.categories
+        ],
+        "findings": [
+            {
+                "ruleId": finding.rule_id,
+                "severity": finding.severity.value,
+                "category": finding.category,
+                "title": finding.title,
+                "description": finding.description,
+                "remediation": finding.remediation,
+                "filePath": finding.file_path,
+                "lineNumber": finding.line_number,
+                "source": finding.source,
+            }
+            for finding in _sorted_findings(result.findings)
+        ],
+        "timestamp": result.timestamp,
+        "pluginDir": result.plugin_dir,
+    }
+    if result.scope == "repository":
+        payload["repository"] = {
+            "marketplaceFile": result.marketplace_file,
+            "localPluginCount": len(result.plugin_results),
+        }
+        payload["plugins"] = [
+            {
+                "name": plugin.plugin_name or plugin.plugin_dir.rsplit("/", 1)[-1],
+                "pluginDir": plugin.plugin_dir,
+                "score": plugin.score,
+                "grade": plugin.grade,
+                "trust": _serialize_trust(plugin),
+                "summary": {
+                    "findings": plugin.severity_counts,
+                    "integrations": [
+                        {
+                            "name": integration.name,
+                            "status": integration.status,
+                            "message": integration.message,
+                            "findingsCount": integration.findings_count,
+                            "metadata": integration.metadata,
+                        }
+                        for integration in plugin.integrations
+                    ],
+                },
+            }
+            for plugin in result.plugin_results
+        ]
+        payload["skippedTargets"] = [
+            {
+                "name": skipped.name,
+                "reason": skipped.reason,
+                "sourcePath": skipped.source_path,
+            }
+            for skipped in result.skipped_targets
+        ]
+    return payload
+
+
+def format_json(
+    result: ScanResult,
+    *,
+    profile: str = "default",
+    policy_pass: bool = True,
+    verify_pass: bool = True,
+    raw_score: int | None = None,
+    effective_score: int | None = None,
+) -> str:
+    """Render a scan result as indented JSON."""
+
+    return json.dumps(
+        build_json_payload(
+            result,
+            profile=profile,
+            policy_pass=policy_pass,
+            verify_pass=verify_pass,
+            raw_score=raw_score,
+            effective_score=effective_score,
+        ),
+        indent=2,
+    )
+
+
+def format_markdown(result: ScanResult) -> str:
+    """Render a scan result as a markdown report."""
+
+    lines = [
+        "# Codex Plugin Scanner Report",
+        "",
+        f"- {'Repository' if result.scope == 'repository' else 'Plugin'}: `{result.plugin_dir}`",
+        f"- Score: **{result.score}/100**",
+        f"- Grade: **{result.grade} - {GRADE_LABELS.get(result.grade, 'Unknown')}**",
+        f"- Trust: **{result.trust_report.total if result.trust_report else 0.0}/100**",
+        f"- Ecosystems: **{', '.join(result.ecosystems) if result.ecosystems else 'unknown'}**",
+        "",
+        "## Findings Summary",
+        "",
+    ]
+    for severity in Severity:
+        lines.append(f"- {severity.value.title()}: {result.severity_counts.get(severity.value, 0)}")
+
+    if result.scope == "repository":
+        lines += ["", "## Local Plugins", ""]
+        for plugin in result.plugin_results:
+            trust_total = plugin.trust_report.total if plugin.trust_report else 0.0
+            lines.append(
+                f"- **{plugin.plugin_name or plugin.plugin_dir}**: "
+                f"{plugin.score}/100 ({plugin.grade}), trust {trust_total}/100"
+            )
+        if result.skipped_targets:
+            lines += ["", "## Skipped Marketplace Entries", ""]
+            for skipped in result.skipped_targets:
+                source_path = f" (`{skipped.source_path}`)" if skipped.source_path else ""
+                lines.append(f"- **{skipped.name}**{source_path}: {skipped.reason}")
+
+    lines += ["", "## Categories", ""]
+    for category in result.categories:
+        category_score = sum(check.points for check in category.checks)
+        category_max = sum(check.max_points for check in category.checks)
+        lines.append(f"- **{category.name}**: {category_score}/{category_max}")
+
+    top_findings = _sorted_findings(result.findings)[:10]
+    lines += ["", "## Top Findings", ""]
+    if not top_findings:
+        lines.append("- No findings detected.")
+    else:
+        for finding in top_findings:
+            path = f" (`{finding.file_path}`)" if finding.file_path else ""
+            lines.append(f"- **{finding.severity.value.upper()}** {finding.title}{path}")
+            lines.append(f"  - {finding.description}")
+            if finding.remediation:
+                lines.append(f"  - Remediation: {finding.remediation}")
+
+    if result.trust_report and result.trust_report.domains:
+        lines += ["", "## Trust Provenance", ""]
+        for domain in result.trust_report.domains:
+            lines.append(f"- **{domain.label}** ({domain.spec_id}): {domain.score}/100")
+            for adapter in domain.adapters:
+                lines.append(f"  - {adapter.label}: {adapter.score}/100 (weight {adapter.weight})")
+
+    lines += ["", "## Integration Status", ""]
+    for integration in result.integrations:
+        lines.append(f"- **{integration.name}**: `{integration.status}` - {integration.message}")
+
+    return "\n".join(lines)
+
+
+def format_sarif(result: ScanResult) -> str:
+    """Render a scan result as SARIF 2.1.0 JSON."""
+
+    sorted_findings = _sorted_findings(result.findings)
+    rules = []
+    seen_rules: set[str] = set()
+    for finding in sorted_findings:
+        if finding.rule_id in seen_rules:
+            continue
+        rules.append(
+            {
+                "id": finding.rule_id,
+                "name": finding.title,
+                "shortDescription": {"text": finding.title},
+                "fullDescription": {"text": finding.description},
+                "help": {"text": finding.remediation or "Review and remediate this finding."},
+                "properties": {
+                    "tags": [finding.category, finding.source],
+                    "precision": "high",
+                    "problem.severity": finding.severity.value,
+                },
+            }
+        )
+        seen_rules.add(finding.rule_id)
+
+    results = []
+    for finding in sorted_findings:
+        level = "note"
+        if SEVERITY_ORDER[finding.severity] >= SEVERITY_ORDER[Severity.HIGH]:
+            level = "error"
+        elif SEVERITY_ORDER[finding.severity] >= SEVERITY_ORDER[Severity.MEDIUM]:
+            level = "warning"
+
+        result_entry: dict[str, object] = {
+            "ruleId": finding.rule_id,
+            "level": level,
+            "message": {"text": finding.description},
+            "properties": {
+                "severity": finding.severity.value,
+                "category": finding.category,
+                "source": finding.source,
+            },
+        }
+        if finding.file_path:
+            location = {
+                "physicalLocation": {
+                    "artifactLocation": {"uri": finding.file_path},
+                }
+            }
+            if finding.line_number:
+                location["physicalLocation"]["region"] = {"startLine": finding.line_number}
+            result_entry["locations"] = [location]
+        results.append(result_entry)
+
+    payload = {
+        "version": "2.1.0",
+        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+        "runs": [
+            {
+                "tool": {
+                    "driver": {
+                        "name": "codex-plugin-scanner",
+                        "informationUri": "https://github.com/hashgraph-online/codex-plugin-scanner",
+                        "version": __version__,
+                        "rules": rules,
+                    }
+                },
+                "results": results,
+            }
+        ],
+    }
+    return json.dumps(payload, indent=2)
+
+
+def should_fail_for_severity(result: ScanResult, threshold: str | None) -> bool:
+    """Return True when the result contains a finding at or above the threshold."""
+
+    if not threshold or threshold.lower() == "none":
+        return False
+    threshold_severity = severity_from_value(threshold)
+    return any(SEVERITY_ORDER[finding.severity] >= SEVERITY_ORDER[threshold_severity] for finding in result.findings)

codex_plugin_scanner/rules/__init__.py

@@ -0,0 +1,6 @@
+"""Rule registry exports."""
+
+from codex_plugin_scanner.rules.registry import CATEGORY_WEIGHTS, get_rule_spec, has_rule_spec, list_rule_specs
+from codex_plugin_scanner.rules.specs import RuleSpec
+
+__all__ = ["CATEGORY_WEIGHTS", "RuleSpec", "get_rule_spec", "has_rule_spec", "list_rule_specs"]

codex_plugin_scanner/rules/registry.py

@@ -0,0 +1,101 @@
+"""Built-in rule registry for stable rule IDs and metadata."""
+
+from __future__ import annotations
+
+from codex_plugin_scanner.models import Severity
+from codex_plugin_scanner.rules.specs import RuleSpec
+
+CATEGORY_WEIGHTS: dict[str, int] = {
+    "manifest": 31,
+    "security": 16,
+    "operational-security": 18,
+    "best-practices": 15,
+    "marketplace": 11,
+    "skill-security": 9,
+    "code-quality": 10,
+}
+
+_DOC_ROOT = "https://github.com/hashgraph-online/codex-plugin-scanner/blob/main/docs/rules"
+
+
+def _rule(
+    rule_id: str,
+    category: str,
+    severity: Severity,
+    weight: int,
+    docs_slug: str,
+    *,
+    fixable: bool = False,
+) -> RuleSpec:
+    title = rule_id.replace("_", " ").replace("-", " ").title()
+    return RuleSpec(
+        rule_id=rule_id,
+        category=category,
+        default_severity=severity,
+        weight=weight,
+        docs_slug=docs_slug,
+        description=f"{title} was detected.",
+        remediation=f"Review and remediate {title.lower()}.",
+        docs_url=f"{_DOC_ROOT}/{docs_slug}.md",
+        fixable=fixable,
+    )
+
+
+RULE_SPECS: tuple[RuleSpec, ...] = (
+    _rule("PLUGIN_JSON_MISSING", "manifest", Severity.HIGH, 5, "plugin-json-missing"),
+    _rule("PLUGIN_JSON_INVALID", "manifest", Severity.HIGH, 5, "plugin-json-invalid"),
+    _rule("README_MISSING", "best-practices", Severity.LOW, 3, "readme-missing", fixable=True),
+    _rule("SKILLS_DIR_MISSING", "best-practices", Severity.MEDIUM, 4, "skills-dir-missing"),
+    _rule("SKILL_FRONTMATTER_INVALID", "best-practices", Severity.MEDIUM, 4, "skill-frontmatter-invalid"),
+    _rule("ENV_FILE_COMMITTED", "best-practices", Severity.HIGH, 5, "env-file-committed"),
+    _rule("CODEXIGNORE_MISSING", "best-practices", Severity.LOW, 3, "codexignore-missing", fixable=True),
+    _rule("SECURITY_MD_MISSING", "security", Severity.MEDIUM, 3, "security-md-missing", fixable=True),
+    _rule("LICENSE_MISSING", "security", Severity.MEDIUM, 3, "license-missing", fixable=True),
+    _rule("HARDCODED_SECRET", "security", Severity.CRITICAL, 7, "hardcoded-secret"),
+    _rule("DANGEROUS_MCP_COMMAND", "security", Severity.HIGH, 4, "dangerous-mcp-command"),
+    _rule("MCP_CONFIG_INVALID_JSON", "security", Severity.HIGH, 4, "mcp-config-invalid-json"),
+    _rule("MCP_REMOTE_URL_INSECURE", "security", Severity.HIGH, 4, "mcp-remote-url-insecure"),
+    _rule("RISKY_APPROVAL_DEFAULT", "security", Severity.MEDIUM, 2, "risky-approval-default"),
+    _rule("MARKETPLACE_JSON_INVALID", "marketplace", Severity.HIGH, 5, "marketplace-json-invalid"),
+    _rule("MARKETPLACE_NAME_MISSING", "marketplace", Severity.MEDIUM, 5, "marketplace-name-missing"),
+    _rule("MARKETPLACE_PLUGINS_MISSING", "marketplace", Severity.HIGH, 5, "marketplace-plugins-missing"),
+    _rule("MARKETPLACE_SOURCE_MISSING", "marketplace", Severity.MEDIUM, 5, "marketplace-source-missing"),
+    _rule("MARKETPLACE_POLICY_MISSING", "marketplace", Severity.MEDIUM, 5, "marketplace-policy-missing"),
+    _rule("MARKETPLACE_POLICY_FIELDS_MISSING", "marketplace", Severity.MEDIUM, 4, "marketplace-policy-fields-missing"),
+    _rule("MARKETPLACE_UNSAFE_SOURCE", "marketplace", Severity.HIGH, 3, "marketplace-unsafe-source"),
+    _rule("DANGEROUS_DYNAMIC_EXECUTION", "code-quality", Severity.HIGH, 5, "dangerous-dynamic-execution"),
+    _rule("SHELL_INJECTION_PATTERN", "code-quality", Severity.HIGH, 5, "shell-injection-pattern"),
+    _rule("GITHUB_ACTION_UNPINNED", "operational-security", Severity.HIGH, 5, "github-action-unpinned"),
+    _rule("GITHUB_ACTIONS_WRITE_ALL", "operational-security", Severity.HIGH, 5, "github-actions-write-all"),
+    _rule(
+        "GITHUB_ACTIONS_UNTRUSTED_CHECKOUT",
+        "operational-security",
+        Severity.HIGH,
+        4,
+        "github-actions-untrusted-checkout",
+    ),
+    _rule("DEPENDABOT_MISSING", "operational-security", Severity.LOW, 2, "dependabot-missing"),
+    _rule(
+        "DEPENDABOT_GITHUB_ACTIONS_MISSING",
+        "operational-security",
+        Severity.LOW,
+        2,
+        "dependabot-github-actions-missing",
+    ),
+    _rule("DEPENDENCY_LOCKFILE_MISSING", "operational-security", Severity.MEDIUM, 2, "dependency-lockfile-missing"),
+    _rule("CISCO-SCANNER-UNAVAILABLE", "skill-security", Severity.LOW, 3, "cisco-scanner-unavailable"),
+)
+
+_RULES_BY_ID: dict[str, RuleSpec] = {rule.rule_id: rule for rule in RULE_SPECS}
+
+
+def list_rule_specs() -> tuple[RuleSpec, ...]:
+    return RULE_SPECS
+
+
+def get_rule_spec(rule_id: str) -> RuleSpec | None:
+    return _RULES_BY_ID.get(rule_id)
+
+
+def has_rule_spec(rule_id: str) -> bool:
+    return rule_id in _RULES_BY_ID

codex_plugin_scanner/rules/specs.py

@@ -0,0 +1,26 @@
+"""Rule specification models used by lint and scan policy layers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from codex_plugin_scanner.models import Severity
+
+
+@dataclass(frozen=True, slots=True)
+class RuleSpec:
+    """Static metadata for a scanner rule."""
+
+    rule_id: str
+    category: str
+    default_severity: Severity
+    weight: int
+    docs_slug: str
+    description: str
+    remediation: str
+    docs_url: str
+    fixable: bool = False
+    profiles: tuple[str, ...] = ("default", "public-marketplace", "strict-security")
+
+
+ALL_PROFILES: tuple[str, ...] = ("default", "public-marketplace", "strict-security")