pkgwhy 1.0.0__py3-none-any.whl

pkgwhy/reports/audit.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import html
+from typing import Any, TypedDict
+
+from pkgwhy.core.models import PackageJudgement
+
+AUDIT_SCHEMA_VERSION = "pkgwhy.audit.v2"
+
+
+class AuditReport(TypedDict):
+    schema_version: str
+    package_count: int
+    vulnerability_match_count: int
+    vulnerability_sources: list[str]
+    provenance_sources: list[str]
+    warnings: list[str]
+    packages: list[dict[str, Any]]
+
+
+def build_audit_report(judgements: list[PackageJudgement], warnings: list[str] | None = None) -> AuditReport:
+    return {
+        "schema_version": AUDIT_SCHEMA_VERSION,
+        "package_count": len(judgements),
+        "vulnerability_match_count": sum(len(judgement.known_vulnerabilities) for judgement in judgements),
+        "vulnerability_sources": sorted(
+            {
+                vulnerability.source
+                for judgement in judgements
+                for vulnerability in judgement.known_vulnerabilities
+                if vulnerability.source
+            }
+        ),
+        "provenance_sources": sorted(
+            {
+                judgement.provenance.metadata_source
+                for judgement in judgements
+                if judgement.provenance is not None and judgement.provenance.metadata_source
+            }
+        ),
+        "warnings": warnings or [],
+        "packages": [judgement.model_dump(mode="json") for judgement in judgements],
+    }
+
+
+def render_audit_markdown(judgements: list[PackageJudgement], warnings: list[str] | None = None) -> str:
+    lines = [
+        "# pkgwhy Audit Report",
+        "",
+        "Runtime capability exposure:",
+        "",
+        "> Python packages run with the same permissions as the Python process. Static signals are not proof of runtime behavior or intent.",
+        "",
+        "| Package | Version | Risk | Decision | Vulnerabilities | Warnings |",
+        "| --- | --- | --- | --- | --- | --- |",
+    ]
+    for judgement in judgements:
+        warning_count = len(judgement.warnings)
+        lines.append(
+            "| "
+            f"{_escape_markdown_table_cell(judgement.package)} | "
+            f"{_escape_markdown_table_cell(judgement.version or 'unknown')} | "
+            f"{_escape_markdown_table_cell(judgement.risk_level.value)} | "
+            f"{_escape_markdown_table_cell(judgement.decision.value)} | "
+            f"{len(judgement.known_vulnerabilities)} | "
+            f"{warning_count} |"
+        )
+    if warnings:
+        lines.extend(["", "## Warnings", ""])
+        for warning in warnings:
+            lines.append(f"- {_escape_markdown_list_item(warning)}")
+    return "\n".join(lines) + "\n"
+
+
+def _escape_markdown_table_cell(value: str) -> str:
+    escaped = html.escape(value, quote=False)
+    return escaped.replace("\\", r"\\").replace("\r", " ").replace("\n", " ").replace("|", r"\|")
+
+
+def _escape_markdown_list_item(value: str) -> str:
+    return html.escape(value, quote=False).replace("\\", r"\\").replace("\r", " ").replace("\n", " ")

pkgwhy/risk/__init__.py

@@ -0,0 +1,5 @@
+"""Conservative risk scoring."""
+
+from pkgwhy.risk.scoring import judge_inspection
+
+__all__ = ["judge_inspection"]

pkgwhy/risk/rules.py

@@ -0,0 +1,372 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pkgwhy.core.models import Confidence, RiskRuleEvidence, RuleCategory, RuleSeverity
+
+RULE_CATALOG_SCHEMA_VERSION = "pkgwhy.static_rule_catalog.v1"
+
+
+@dataclass(frozen=True)
+class RuleDefinition:
+    """Stable metadata for one pre-alpha risk rule."""
+
+    rule_id: str
+    name: str
+    category: RuleCategory
+    severity: RuleSeverity
+    confidence: Confidence
+    default_message: str
+    false_positive_note: str | None = None
+
+
+RULES: dict[str, RuleDefinition] = {
+    "PKGWHY-VULN-001": RuleDefinition(
+        rule_id="PKGWHY-VULN-001",
+        name="known_vulnerability_match",
+        category=RuleCategory.VULNERABILITY,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.MEDIUM,
+        default_message="Known vulnerability advisory matched this package version.",
+        false_positive_note="Advisory databases can be incomplete or imprecise; verify the source advisory and version range.",
+    ),
+    "PKGWHY-RISK-001": RuleDefinition(
+        rule_id="PKGWHY-RISK-001",
+        name="possible_typosquat_similarity",
+        category=RuleCategory.IDENTITY,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.MEDIUM,
+        default_message="Package name is similar to a popular package name.",
+        false_positive_note="Legitimate ecosystem packages can share prefixes or naming families.",
+    ),
+    "PKGWHY-RISK-002": RuleDefinition(
+        rule_id="PKGWHY-RISK-002",
+        name="source_availability_unknown",
+        category=RuleCategory.SOURCE,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.MEDIUM,
+        default_message="Source availability is unknown from installed files.",
+        false_positive_note="Some legitimate packages ship metadata-only wheels or generated artifacts.",
+    ),
+    "PKGWHY-RISK-003": RuleDefinition(
+        rule_id="PKGWHY-RISK-003",
+        name="missing_license_metadata",
+        category=RuleCategory.METADATA,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.MEDIUM,
+        default_message="Installed metadata does not include a clear license value.",
+        false_positive_note="License metadata can be omitted even when licensing is documented elsewhere.",
+    ),
+    "PKGWHY-RISK-004": RuleDefinition(
+        rule_id="PKGWHY-RISK-004",
+        name="native_compiled_code_present",
+        category=RuleCategory.BINARY,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.MEDIUM,
+        default_message="Native compiled files are present.",
+        false_positive_note="Native extensions are common in legitimate numerical, cryptographic, and performance packages.",
+    ),
+    "PKGWHY-RISK-005": RuleDefinition(
+        rule_id="PKGWHY-RISK-005",
+        name="static_capability_signal",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.MEDIUM,
+        default_message="Static capability signal detected.",
+        false_positive_note="Static references are not proof of runtime behavior, intent, or unsafe use.",
+    ),
+    "PKGWHY-RISK-006": RuleDefinition(
+        rule_id="PKGWHY-RISK-006",
+        name="no_installed_files_found",
+        category=RuleCategory.METADATA,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.LOW,
+        default_message="No installed package files were found through distribution metadata.",
+        false_positive_note="Editable installs or unusual packaging layouts can hide files from distribution metadata.",
+    ),
+    "PKGWHY-PY-001": RuleDefinition(
+        rule_id="PKGWHY-PY-001",
+        name="python_dynamic_code_execution",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.HIGH,
+        default_message="Python dynamic code execution construct referenced.",
+        false_positive_note="Dynamic execution can be legitimate in frameworks, plugins, and compatibility layers.",
+    ),
+    "PKGWHY-PY-002": RuleDefinition(
+        rule_id="PKGWHY-PY-002",
+        name="python_dynamic_import",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.HIGH,
+        default_message="Python dynamic import construct referenced.",
+        false_positive_note="Dynamic imports are common in plugin systems and optional dependency loading.",
+    ),
+    "PKGWHY-PY-003": RuleDefinition(
+        rule_id="PKGWHY-PY-003",
+        name="python_deserialisation_risk",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.HIGH,
+        default_message="Python deserialisation-risk construct referenced.",
+        false_positive_note="Deserialisation APIs can be safe when inputs are trusted and validated.",
+    ),
+    "PKGWHY-PY-004": RuleDefinition(
+        rule_id="PKGWHY-PY-004",
+        name="python_encoded_payload_handling",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.HIGH,
+        default_message="Python encoded-payload handling construct referenced.",
+        false_positive_note="Encoding and compression APIs are common in legitimate data processing code.",
+    ),
+    "PKGWHY-PY-005": RuleDefinition(
+        rule_id="PKGWHY-PY-005",
+        name="python_subprocess_or_shell_execution",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.HIGH,
+        default_message="Python subprocess or shell execution construct referenced.",
+        false_positive_note="Subprocess APIs can be legitimate for CLI wrappers, build tools, and integrations.",
+    ),
+    "PKGWHY-PY-006": RuleDefinition(
+        rule_id="PKGWHY-PY-006",
+        name="python_environment_or_secret_access",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.MEDIUM,
+        default_message="Python environment or secret-like access pattern referenced.",
+        false_positive_note="Environment variable and credential-like names can appear in legitimate configuration code.",
+    ),
+    "PKGWHY-PY-007": RuleDefinition(
+        rule_id="PKGWHY-PY-007",
+        name="python_package_manager_manipulation",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.MEDIUM,
+        default_message="Python package-manager manipulation pattern referenced.",
+        false_positive_note="Installer wrappers and build tooling may legitimately invoke package managers.",
+    ),
+    "PKGWHY-PY-008": RuleDefinition(
+        rule_id="PKGWHY-PY-008",
+        name="python_unsafe_yaml_load",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.HIGH,
+        default_message="Python unsafe YAML load construct referenced.",
+        false_positive_note="YAML loading can be safe when using safe loaders or trusted inputs; review call arguments.",
+    ),
+    "PKGWHY-PY-009": RuleDefinition(
+        rule_id="PKGWHY-PY-009",
+        name="python_obfuscation_bootstrap_signal",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.MEDIUM,
+        default_message="Python obfuscation-bootstrap pattern referenced.",
+        false_positive_note="Obfuscation-bootstrap names can appear in comments, fixtures, or vendored compatibility code.",
+    ),
+    "PKGWHY-BUILD-001": RuleDefinition(
+        rule_id="PKGWHY-BUILD-001",
+        name="executable_setup_py_present",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.HIGH,
+        default_message="Executable setup.py file is present.",
+        false_positive_note="Many legacy packages include setup.py; presence alone is not proof of unsafe install behavior.",
+    ),
+    "PKGWHY-BUILD-002": RuleDefinition(
+        rule_id="PKGWHY-BUILD-002",
+        name="setup_time_subprocess_signal",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.MEDIUM,
+        default_message="setup.py contains subprocess or shell execution references.",
+        false_positive_note="Build scripts can legitimately invoke compilers or local build tools.",
+    ),
+    "PKGWHY-BUILD-003": RuleDefinition(
+        rule_id="PKGWHY-BUILD-003",
+        name="setup_time_network_signal",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.MEDIUM,
+        default_message="setup.py contains network access references.",
+        false_positive_note="Build scripts can reference network libraries without using them during installation.",
+    ),
+    "PKGWHY-BUILD-004": RuleDefinition(
+        rule_id="PKGWHY-BUILD-004",
+        name="setup_time_dynamic_execution_signal",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.MEDIUM,
+        default_message="setup.py contains dynamic execution references.",
+        false_positive_note="Dynamic execution references can appear in compatibility logic; inspect context manually.",
+    ),
+    "PKGWHY-BUILD-005": RuleDefinition(
+        rule_id="PKGWHY-BUILD-005",
+        name="build_backend_declared",
+        category=RuleCategory.METADATA,
+        severity=RuleSeverity.INFO,
+        confidence=Confidence.HIGH,
+        default_message="Build backend metadata is declared.",
+        false_positive_note="Declarative build metadata is informational unless paired with other suspicious signals.",
+    ),
+    "PKGWHY-BUILD-006": RuleDefinition(
+        rule_id="PKGWHY-BUILD-006",
+        name="setup_cfg_present",
+        category=RuleCategory.METADATA,
+        severity=RuleSeverity.INFO,
+        confidence=Confidence.HIGH,
+        default_message="setup.cfg metadata file is present.",
+        false_positive_note="setup.cfg is usually declarative metadata and is not executable Python code.",
+    ),
+    "PKGWHY-NET-001": RuleDefinition(
+        rule_id="PKGWHY-NET-001",
+        name="source_url_or_domain_reference",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.LOW,
+        confidence=Confidence.MEDIUM,
+        default_message="Source text references a URL or domain.",
+        false_positive_note="URL references can be documentation, examples, tests, or metadata and are not proof of network behavior.",
+    ),
+    "PKGWHY-CRED-001": RuleDefinition(
+        rule_id="PKGWHY-CRED-001",
+        name="credential_like_assignment",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.MEDIUM,
+        default_message="Source text contains a credential-like assignment pattern.",
+        false_positive_note="Credential-like names can appear in placeholders, tests, documentation, and configuration examples.",
+    ),
+    "PKGWHY-JS-001": RuleDefinition(
+        rule_id="PKGWHY-JS-001",
+        name="javascript_minification_signal",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.LOW,
+        confidence=Confidence.MEDIUM,
+        default_message="JavaScript minification or density signal detected.",
+        false_positive_note="Minified JavaScript is common in legitimate distributions and is not automatically suspicious.",
+    ),
+    "PKGWHY-JS-002": RuleDefinition(
+        rule_id="PKGWHY-JS-002",
+        name="javascript_dynamic_execution_signal",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.HIGH,
+        default_message="JavaScript dynamic execution construct referenced.",
+        false_positive_note="Dynamic JavaScript execution can be legitimate in loaders and compatibility code; inspect context manually.",
+    ),
+    "PKGWHY-JS-003": RuleDefinition(
+        rule_id="PKGWHY-JS-003",
+        name="javascript_encoded_payload_signal",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.MEDIUM,
+        default_message="JavaScript encoded-payload handling signal detected.",
+        false_positive_note="Encoding APIs and encoded strings can be legitimate in bundled assets and data fixtures.",
+    ),
+    "PKGWHY-JS-004": RuleDefinition(
+        rule_id="PKGWHY-JS-004",
+        name="javascript_obfuscation_signal",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.MEDIUM,
+        default_message="JavaScript obfuscation-like pattern detected.",
+        false_positive_note="Obfuscation-like patterns can appear in generated or bundled code; they require context-sensitive review.",
+    ),
+    "PKGWHY-JS-005": RuleDefinition(
+        rule_id="PKGWHY-JS-005",
+        name="javascript_source_map_reference",
+        category=RuleCategory.STATIC_ANALYSIS,
+        severity=RuleSeverity.INFO,
+        confidence=Confidence.HIGH,
+        default_message="JavaScript source-map reference detected.",
+        false_positive_note="Source maps are often helpful debug metadata and are not a security issue by themselves.",
+    ),
+    "PKGWHY-BIN-001": RuleDefinition(
+        rule_id="PKGWHY-BIN-001",
+        name="native_extension_present",
+        category=RuleCategory.BINARY,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.HIGH,
+        default_message="Native compiled extension or library file is present.",
+        false_positive_note="Native extensions are common in legitimate numerical, cryptographic, and performance packages.",
+    ),
+    "PKGWHY-BIN-002": RuleDefinition(
+        rule_id="PKGWHY-BIN-002",
+        name="wasm_binary_present",
+        category=RuleCategory.BINARY,
+        severity=RuleSeverity.MEDIUM,
+        confidence=Confidence.HIGH,
+        default_message="WebAssembly binary file is present.",
+        false_positive_note="WASM can be legitimate for portable performance-sensitive code and is not automatically malicious.",
+    ),
+    "PKGWHY-BIN-003": RuleDefinition(
+        rule_id="PKGWHY-BIN-003",
+        name="native_executable_present",
+        category=RuleCategory.BINARY,
+        severity=RuleSeverity.HIGH,
+        confidence=Confidence.HIGH,
+        default_message="Native executable file is present.",
+        false_positive_note="Executable files can be legitimate helper tools, but should be reviewed before agent or production use.",
+    ),
+}
+
+
+def rule_ids() -> tuple[str, ...]:
+    """Return rule IDs in the public catalog order."""
+    return tuple(RULES)
+
+
+def rules_by_category() -> dict[RuleCategory, tuple[RuleDefinition, ...]]:
+    """Group rule definitions by category while preserving catalog order."""
+    grouped: dict[RuleCategory, list[RuleDefinition]] = {}
+    for rule in RULES.values():
+        grouped.setdefault(rule.category, []).append(rule)
+    return {category: tuple(definitions) for category, definitions in grouped.items()}
+
+
+def rule_catalog_snapshot() -> dict[str, object]:
+    """Return a stable, JSON-friendly snapshot of the current rule catalog."""
+    return {
+        "schema_version": RULE_CATALOG_SCHEMA_VERSION,
+        "rule_count": len(RULES),
+        "rules": [
+            {
+                "rule_id": rule.rule_id,
+                "name": rule.name,
+                "default_message": rule.default_message,
+                "category": rule.category.value,
+                "severity": rule.severity.value,
+                "confidence": rule.confidence.value,
+                "false_positive_note": rule.false_positive_note,
+            }
+            for rule in RULES.values()
+        ],
+    }
+
+
+def make_rule_evidence(
+    rule_id: str,
+    *,
+    message: str | None = None,
+    evidence: list[str] | None = None,
+    severity: RuleSeverity | None = None,
+    confidence: Confidence | None = None,
+    file_path: str | None = None,
+    line_number: int | None = None,
+    symbol: str | None = None,
+) -> RiskRuleEvidence:
+    definition = RULES[rule_id]
+    return RiskRuleEvidence(
+        rule_id=definition.rule_id,
+        name=definition.name,
+        category=definition.category,
+        severity=severity or definition.severity,
+        confidence=confidence or definition.confidence,
+        message=message or definition.default_message,
+        evidence=evidence or [],
+        file_path=file_path,
+        line_number=line_number,
+        symbol=symbol,
+        false_positive_note=definition.false_positive_note,
+    )

pkgwhy/risk/scoring.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+from pkgwhy.core.models import (
+    AgentDecision,
+    Confidence,
+    PackageInspection,
+    PackageJudgement,
+    PackageProvenance,
+    RiskRuleEvidence,
+    RiskLevel,
+    RuleSeverity,
+    SourceAvailability,
+    VulnerabilityMatch,
+)
+from pkgwhy.provenance.installed import assess_installed_provenance
+from pkgwhy.risk.rules import make_rule_evidence
+from pkgwhy.typosquat.detector import detect_typosquat
+
+
+def judge_inspection(
+    inspection: PackageInspection,
+    known_vulnerabilities: list[VulnerabilityMatch] | None = None,
+    provenance: PackageProvenance | None = None,
+) -> PackageJudgement:
+    metadata = inspection.metadata
+    warnings = list(inspection.warnings)
+    evidence = list(inspection.evidence)
+    risk_rules: list[RiskRuleEvidence] = []
+    known_vulnerabilities = known_vulnerabilities or []
+    risk = RiskLevel.LOW
+    confidence = Confidence.MEDIUM
+    provenance = provenance or assess_installed_provenance(metadata)
+
+    for rule in inspection.rule_evidence:
+        risk_rules.append(rule)
+        risk = _raise_risk(risk, _risk_for_rule(rule))
+
+    for vulnerability in known_vulnerabilities:
+        fixed = f" Fixed versions: {', '.join(vulnerability.fixed_versions)}." if vulnerability.fixed_versions else ""
+        message = (
+            f"Known vulnerability match: {vulnerability.vulnerability_id} from {vulnerability.source}. "
+            "This result depends on the supplied vulnerability source and may be incomplete."
+            f"{fixed}"
+        )
+        warnings.append(message)
+        evidence.extend(vulnerability.evidence)
+        risk_rules.append(
+            make_rule_evidence(
+                "PKGWHY-VULN-001",
+                message=message,
+                evidence=vulnerability.evidence,
+                severity=_severity_for_vulnerability(vulnerability),
+                confidence=vulnerability.confidence,
+            )
+        )
+        risk = _raise_risk(risk, _risk_for_vulnerability(vulnerability))
+
+    typosquat_candidate = detect_typosquat(metadata.identity.name)
+    if typosquat_candidate is not None:
+        message = (
+            "Possible typosquatting risk: "
+            f"'{metadata.identity.name}' is similar to popular package '{typosquat_candidate.possible_target}'. "
+            "This is a signal, not proof of unsafe behavior."
+        )
+        warnings.append(message)
+        evidence.extend(typosquat_candidate.evidence)
+        risk_rules.append(make_rule_evidence("PKGWHY-RISK-001", message=message, evidence=typosquat_candidate.evidence))
+        risk = _raise_risk(risk, RiskLevel.MEDIUM)
+
+    if inspection.source_availability in {
+        SourceAvailability.SOURCE_AVAILABILITY_UNKNOWN,
+        SourceAvailability.INSTALLED_METADATA_ONLY,
+    }:
+        message = "Source availability is unknown from installed files."
+        warnings.append(message)
+        risk_rules.append(
+            make_rule_evidence(
+                "PKGWHY-RISK-002",
+                message=message,
+                evidence=["Installed file metadata did not provide readable source paths."],
+            )
+        )
+        risk = _raise_risk(risk, RiskLevel.MEDIUM)
+
+    if not metadata.license:
+        message = "Installed metadata does not include a clear license value."
+        warnings.append(message)
+        risk_rules.append(
+            make_rule_evidence("PKGWHY-RISK-003", message=message, evidence=["License metadata field was empty."])
+        )
+        risk = _raise_risk(risk, RiskLevel.MEDIUM)
+
+    if "Native compiled code present" in inspection.detected_capabilities:
+        message = "Native compiled files are present. This can be legitimate, but static review is more limited."
+        warnings.append(message)
+        risk_rules.append(
+            make_rule_evidence(
+                "PKGWHY-RISK-004",
+                message=message,
+                evidence=["Installed file scan detected native binary file extensions."],
+            )
+        )
+        risk = _raise_risk(risk, RiskLevel.MEDIUM)
+
+    for capability in _warning_capability_signals(inspection.detected_capabilities):
+        message = f"Static capability signal detected: {capability}. This is not proof of unsafe behavior."
+        warnings.append(message)
+        risk_rules.append(
+            make_rule_evidence(
+                "PKGWHY-RISK-005",
+                message=message,
+                evidence=[f"Detected capability signal: {capability}."],
+            )
+        )
+        risk = _raise_risk(risk, RiskLevel.MEDIUM)
+
+    if inspection.size.file_count == 0:
+        message = "No installed package files were found through distribution metadata."
+        warnings.append(message)
+        risk_rules.append(
+            make_rule_evidence(
+                "PKGWHY-RISK-006",
+                message=message,
+                evidence=["Distribution metadata did not expose files for static inspection."],
+            )
+        )
+        if risk not in {RiskLevel.HIGH, RiskLevel.CRITICAL}:
+            risk = RiskLevel.UNKNOWN
+            confidence = Confidence.LOW
+
+    decision = _decision_for_risk(risk)
+    recommendation = _recommendation_for_risk(risk)
+    summary = metadata.summary or "No installed summary is available for this package."
+
+    return PackageJudgement(
+        package=metadata.identity.name,
+        version=metadata.identity.version,
+        decision=decision,
+        risk_level=risk,
+        confidence=confidence,
+        summary=summary,
+        source_availability=inspection.source_availability,
+        installed_size_bytes=inspection.size.total_bytes,
+        detected_capabilities=inspection.detected_capabilities,
+        warnings=sorted(set(warnings)),
+        recommendation=recommendation,
+        evidence=evidence,
+        risk_rules=risk_rules,
+        known_vulnerabilities=known_vulnerabilities,
+        provenance=provenance,
+    )
+
+
+def _warning_capability_signals(capabilities: list[str]) -> list[str]:
+    warning_signals = {
+        "Subprocess or shell execution signals",
+        "Dynamic code execution signals",
+        "JavaScript dynamic code execution signals",
+        "JavaScript obfuscation signals",
+        "Encoded payload handling signals",
+        "Deserialisation risk signals",
+        "Credential or token access patterns",
+        "Package manager manipulation signals",
+        "Shell script files present",
+        "Install-time setup files present",
+        "WASM binary code present",
+    }
+    return sorted(set(capabilities) & warning_signals)
+
+
+def _decision_for_risk(risk: RiskLevel) -> AgentDecision:
+    if risk == RiskLevel.LOW:
+        return AgentDecision.ALLOW
+    if risk == RiskLevel.MEDIUM:
+        return AgentDecision.ALLOW_WITH_CAUTION
+    if risk == RiskLevel.HIGH:
+        return AgentDecision.REVIEW_MANUALLY
+    if risk == RiskLevel.CRITICAL:
+        return AgentDecision.BLOCK
+    if risk == RiskLevel.UNKNOWN:
+        return AgentDecision.REVIEW_MANUALLY
+    return AgentDecision.REVIEW_MANUALLY
+
+
+def _recommendation_for_risk(risk: RiskLevel) -> str:
+    if risk == RiskLevel.LOW:
+        return "Allow for normal use in trusted projects, while keeping normal dependency review practices."
+    if risk == RiskLevel.MEDIUM:
+        return "Allow with caution. Review the listed signals before agent or production use."
+    if risk == RiskLevel.HIGH:
+        return "Manual review recommended before installation, import, or execution."
+    if risk == RiskLevel.CRITICAL:
+        return "Block for AI-agent usage until a human reviews the evidence."
+    if risk == RiskLevel.UNKNOWN:
+        return "Risk is unknown. Manual review recommended."
+    return "Risk is unknown. Manual review recommended."
+
+
+def _raise_risk(current: RiskLevel, candidate: RiskLevel) -> RiskLevel:
+    order = {
+        RiskLevel.LOW: 0,
+        RiskLevel.MEDIUM: 1,
+        RiskLevel.HIGH: 2,
+        RiskLevel.CRITICAL: 3,
+        RiskLevel.UNKNOWN: 1,
+    }
+    return candidate if order[candidate] > order[current] else current
+
+
+def _risk_for_vulnerability(vulnerability: VulnerabilityMatch) -> RiskLevel:
+    severity = " ".join(vulnerability.severity).lower()
+    if "critical" in severity:
+        return RiskLevel.CRITICAL
+    return RiskLevel.HIGH
+
+
+def _risk_for_rule(rule: RiskRuleEvidence) -> RiskLevel:
+    if rule.severity == RuleSeverity.CRITICAL:
+        return RiskLevel.CRITICAL
+    if rule.severity == RuleSeverity.HIGH:
+        return RiskLevel.HIGH
+    if rule.severity == RuleSeverity.MEDIUM:
+        return RiskLevel.MEDIUM
+    return RiskLevel.LOW
+
+
+def _severity_for_vulnerability(vulnerability: VulnerabilityMatch) -> RuleSeverity:
+    severity = " ".join(vulnerability.severity).lower()
+    if "critical" in severity:
+        return RuleSeverity.CRITICAL
+    return RuleSeverity.HIGH