coretrace-python-analyzer 0.1.0__py3-none-any.whl

coretrace_python/ir/ssa.py

@@ -0,0 +1,277 @@
+"""SSA construction (architecture §7).
+
+``to_ssa`` derives a new immutable ``FunctionIR`` from the non-SSA PyIR of a function:
+local loads and stores disappear, merges get ``Phi`` instructions placed on the iterated
+dominance frontier of the definitions and pruned by liveness, a ``for_next`` terminator
+defines the loop variable, and a local read before any definition on some path reads
+an explicit ``Undefined`` value created once in the entry block. Only reachable blocks
+are kept, and values are renumbered densely in block order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import replace
+from typing import ClassVar
+
+from coretrace_python.analysis import AnalysisContext, AnyAnalysis, FunctionAnalysis
+from coretrace_python.cfg import BlockId
+from coretrace_python.cfg.dominance import DominanceAnalysis, DominatorTree
+from coretrace_python.hir import nodes
+from coretrace_python.ir.lowering import PyIRAnalysis
+from coretrace_python.ir.model import (
+    BasicBlock,
+    Branch,
+    ForNext,
+    FunctionIR,
+    Instruction,
+    Jump,
+    LoadLocal,
+    Phi,
+    StoreLocal,
+    Terminator,
+    Undefined,
+    Value,
+    substitute,
+    successors,
+)
+
+
+class _Renamer:
+    def __init__(self, function: FunctionIR, tree: DominatorTree) -> None:
+        self.function = function
+        self.tree = tree
+        self.blocks = {block.id: block for block in function.blocks if block.id in tree.blocks}
+        self.next_id = max((v.id for v in _all_values(function)), default=-1) + 1
+        self.stacks: dict[str, list[Value]] = {}
+        self.aliases: dict[Value, Value] = {}
+        self.undefined: dict[str, Undefined] = {}
+        self.phis: dict[BlockId, dict[str, Phi]] = {}
+        self.instructions: dict[BlockId, list[Instruction]] = {}
+        self.terminators: dict[BlockId, Terminator] = {}
+        self.predecessors: dict[BlockId, list[BlockId]] = {b: [] for b in self.blocks}
+        for block in self.blocks.values():
+            for successor in successors(block):
+                self.predecessors[successor].append(block.id)
+        self.loop_variables: dict[BlockId, tuple[str, BlockId]] = {}
+        for block in self.blocks.values():
+            if isinstance(block.terminator, ForNext):
+                self.loop_variables[block.terminator.body] = (block.terminator.target, block.id)
+
+    # ------------------------------------------------------------------ helpers
+
+    def new_value(self) -> Value:
+        value = Value(self.next_id)
+        self.next_id += 1
+        return value
+
+    def current(self, name: str) -> Value:
+        stack = self.stacks.get(name)
+        if stack:
+            return stack[-1]
+        if name not in self.undefined:
+            self.undefined[name] = Undefined(self.new_value(), self.function.location, name)
+        return self.undefined[name].result
+
+    def resolve(self, value: Value) -> Value:
+        return self.aliases.get(value, value)
+
+    # ------------------------------------------------------------------ phi placement
+
+    def place_phis(self) -> None:
+        definitions: dict[str, set[BlockId]] = {}
+        for block in self.blocks.values():
+            for instruction in block.instructions:
+                if isinstance(instruction, StoreLocal):
+                    definitions.setdefault(instruction.name, set()).add(block.id)
+            if isinstance(block.terminator, ForNext):
+                definitions.setdefault(block.terminator.target, set()).add(block.terminator.body)
+        live_in = _live_in(self.blocks, self.predecessors, self.loop_variables)
+        for name, blocks in definitions.items():
+            for block_id in sorted(self.tree.iterated_frontier(blocks), key=self.order):
+                if name in live_in[block_id]:
+                    self.phis.setdefault(block_id, {})[name] = Phi(
+                        self.new_value(), self.blocks[block_id].terminator.location, name, ()
+                    )
+
+    def order(self, block_id: BlockId) -> int:
+        return self.tree.blocks.index(block_id)
+
+    # ------------------------------------------------------------------ renaming
+
+    def rename(self, block_id: BlockId) -> None:
+        pushed: list[str] = []
+
+        def push(name: str, value: Value) -> None:
+            self.stacks.setdefault(name, []).append(value)
+            pushed.append(name)
+
+        if block_id in self.loop_variables:
+            name, header = self.loop_variables[block_id]
+            header_terminator = self.terminators[header]
+            assert isinstance(header_terminator, ForNext) and header_terminator.result is not None
+            push(name, header_terminator.result)
+        for name, phi in self.phis.get(block_id, {}).items():
+            push(name, phi.result)
+
+        kept: list[Instruction] = []
+        for instruction in self.blocks[block_id].instructions:
+            if isinstance(instruction, LoadLocal):
+                self.aliases[instruction.result] = self.current(instruction.name)
+            elif isinstance(instruction, StoreLocal):
+                push(instruction.name, self.resolve(instruction.value))
+            else:
+                kept.append(substitute(instruction, self.resolve))
+        self.instructions[block_id] = kept
+
+        terminator = substitute(self.blocks[block_id].terminator, self.resolve)
+        if isinstance(terminator, ForNext):
+            terminator = replace(terminator, result=self.new_value())
+        self.terminators[block_id] = terminator
+
+        for successor in (*_targets(terminator), *self.blocks[block_id].exception_targets):
+            for name, phi in self.phis.get(successor, {}).items():
+                incoming = (*phi.incoming, (self.current(name), block_id))
+                self.phis[successor][name] = replace(phi, incoming=incoming)
+
+        for child in self.tree.children(block_id):
+            self.rename(child)
+        for name in reversed(pushed):
+            self.stacks[name].pop()
+
+    # ------------------------------------------------------------------ assembly
+
+    def build(self) -> FunctionIR:
+        self.place_phis()
+        self.rename(self.tree.root)
+        blocks: list[BasicBlock] = []
+        for block in self.function.blocks:
+            if block.id not in self.blocks:
+                continue
+            instructions: list[Instruction] = []
+            if block.id == self.function.entry:
+                instructions.extend(self.undefined.values())
+            instructions.extend(self.ordered_phis(block.id))
+            instructions.extend(self.instructions[block.id])
+            blocks.append(
+                BasicBlock(
+                    block.id, tuple(instructions), self.terminators[block.id], block.exception_targets
+                )
+            )
+        return _renumber(replace(self.function, blocks=tuple(blocks)))
+
+    def ordered_phis(self, block_id: BlockId) -> list[Phi]:
+        phis = self.phis.get(block_id, {})
+        ordered_incoming = []
+        for phi in phis.values():
+            by_block = {b: v for v, b in phi.incoming}
+            incoming = tuple((by_block[p], p) for p in self.predecessors[block_id])
+            ordered_incoming.append(replace(phi, incoming=incoming))
+        return ordered_incoming
+
+
+def _targets(terminator: Terminator) -> tuple[BlockId, ...]:
+    if isinstance(terminator, Branch):
+        return (terminator.then_block, terminator.else_block)
+    if isinstance(terminator, Jump):
+        return (terminator.target,)
+    if isinstance(terminator, ForNext):
+        return (terminator.body, terminator.exit)
+    return ()
+
+
+def _all_values(function: FunctionIR) -> list[Value]:
+    values = list(function.parameters)
+    for block in function.blocks:
+        for instruction in block.instructions:
+            if instruction.result is not None:
+                values.append(instruction.result)
+    return values
+
+
+def _live_in(
+    blocks: Mapping[BlockId, BasicBlock],
+    predecessors: Mapping[BlockId, list[BlockId]],
+    loop_variables: Mapping[BlockId, tuple[str, BlockId]],
+) -> dict[BlockId, frozenset[str]]:
+    """Backward liveness of local names over the non-SSA blocks."""
+
+    uses: dict[BlockId, set[str]] = {}
+    defs: dict[BlockId, set[str]] = {}
+    for block_id, block in blocks.items():
+        used: set[str] = set()
+        defined: set[str] = set()
+        if block_id in loop_variables:
+            defined.add(loop_variables[block_id][0])
+        for instruction in block.instructions:
+            if isinstance(instruction, LoadLocal) and instruction.name not in defined:
+                used.add(instruction.name)
+            elif isinstance(instruction, StoreLocal):
+                defined.add(instruction.name)
+        uses[block_id], defs[block_id] = used, defined
+
+    successors: dict[BlockId, list[BlockId]] = {b: [] for b in blocks}
+    for block_id, preds in predecessors.items():
+        for predecessor in preds:
+            successors[predecessor].append(block_id)
+
+    live_in: dict[BlockId, frozenset[str]] = {b: frozenset() for b in blocks}
+    changed = True
+    while changed:
+        changed = False
+        for block_id in blocks:
+            live_out: set[str] = set()
+            for successor in successors[block_id]:
+                live_out |= live_in[successor]
+            new = frozenset(uses[block_id] | (live_out - defs[block_id]))
+            if new != live_in[block_id]:
+                live_in[block_id] = new
+                changed = True
+    return live_in
+
+
+def _renumber(function: FunctionIR) -> FunctionIR:
+    mapping: dict[Value, Value] = {}
+
+    def fresh(value: Value) -> None:
+        mapping[value] = Value(len(mapping))
+
+    for parameter in function.parameters:
+        fresh(parameter)
+    for block in function.blocks:
+        for instruction in block.instructions:
+            if instruction.result is not None:
+                fresh(instruction.result)
+        if isinstance(block.terminator, ForNext) and block.terminator.result is not None:
+            fresh(block.terminator.result)
+
+    def renamed(value: Value) -> Value:
+        return mapping[value]
+
+    blocks = tuple(
+        BasicBlock(
+            block.id,
+            tuple(substitute(i, renamed, include_result=True) for i in block.instructions),
+            substitute(block.terminator, renamed, include_result=True),
+            block.exception_targets,
+        )
+        for block in function.blocks
+    )
+    return replace(
+        function, parameters=tuple(renamed(p) for p in function.parameters), blocks=blocks
+    )
+
+
+def to_ssa(function: FunctionIR, dominance: DominatorTree) -> FunctionIR:
+    return _Renamer(function, dominance).build()
+
+
+class SSAAnalysis(FunctionAnalysis[FunctionIR]):
+    """SSA form of a function, derived from its PyIR and dominator tree."""
+
+    name: ClassVar[str] = "ir.ssa"
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({PyIRAnalysis, DominanceAnalysis})
+
+    @classmethod
+    def compute(cls, ctx: AnalysisContext, function: nodes.Function) -> FunctionIR:
+        return to_ssa(ctx.get(PyIRAnalysis, function), ctx.get(DominanceAnalysis, function))

coretrace_python/plugins/__init__.py

@@ -0,0 +1,58 @@
+"""Plugin API, manifests, loader and registry (architecture §13, §14, §32–§34)."""
+
+from coretrace_python.plugins.api import (
+    PLUGIN_API_VERSION,
+    ModelPlugin,
+    Plugin,
+    PluginContext,
+    ProjectContext,
+    ProjectPlugin,
+    run_plugins,
+)
+from coretrace_python.plugins.detectors import SymbolCallDetector, TaintDetector
+from coretrace_python.plugins.loader import (
+    IncompatiblePluginError,
+    LoadedPlugin,
+    discover_plugins,
+    load_plugin,
+)
+from coretrace_python.plugins.manifest import (
+    Entrypoint,
+    ManifestError,
+    PluginManifest,
+    VersionRange,
+    load_manifest,
+)
+from coretrace_python.plugins.registry import PluginRegistry
+from coretrace_python.plugins.secrets import (
+    SecretDetector,
+    SecretPattern,
+    literals,
+    shannon_entropy,
+)
+
+__all__ = [
+    "PLUGIN_API_VERSION",
+    "Entrypoint",
+    "IncompatiblePluginError",
+    "LoadedPlugin",
+    "ManifestError",
+    "ModelPlugin",
+    "Plugin",
+    "PluginContext",
+    "PluginManifest",
+    "PluginRegistry",
+    "ProjectContext",
+    "ProjectPlugin",
+    "SecretDetector",
+    "SecretPattern",
+    "SymbolCallDetector",
+    "TaintDetector",
+    "VersionRange",
+    "discover_plugins",
+    "literals",
+    "load_manifest",
+    "load_plugin",
+    "run_plugins",
+    "shannon_entropy",
+]

coretrace_python/plugins/api.py

@@ -0,0 +1,153 @@
+"""The typed plugin contract (architecture §13, §32, §33, §34).
+
+A plugin declares the analyses it needs and consumes them through a ``PluginContext``,
+a deliberately narrow view of the engine: the module, its functions and the declared
+analyses. Nothing else is reachable, which keeps plugins on the stable API and leaves
+room for out-of-process isolation later.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterable, Mapping, Sequence
+from pathlib import Path
+from typing import Any, ClassVar, overload
+
+from coretrace_python.analysis import (
+    Analysis,
+    AnalysisManager,
+    AnyAnalysis,
+    FunctionAnalysis,
+    UndeclaredDependencyError,
+)
+from coretrace_python.analysis.provider import R
+from coretrace_python.dependency import Advisory, DependencyGraph, Policy
+from coretrace_python.findings import Finding
+from coretrace_python.hir import nodes
+from coretrace_python.interprocedural import CallGraph, CallGraphAnalysis, ModuleGraph
+from coretrace_python.ir.lowering import analyzable_functions
+from coretrace_python.semantic.imports import ImportAnalysis, ImportTable
+from coretrace_python.taint import Model
+
+PLUGIN_API_VERSION = 1
+
+
+class Plugin(ABC):
+    """Declares the analyses it needs and the security models it contributes,
+    then turns analysis results into findings."""
+
+    name: ClassVar[str]
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset()
+    models: ClassVar[tuple[Model, ...]] = ()
+    advisories: ClassVar[tuple[Advisory, ...]] = ()
+
+    @abstractmethod
+    def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
+        raise NotImplementedError
+
+
+class ModelPlugin(Plugin):
+    """A plugin that only contributes security models or advisories (§15 providers)."""
+
+    def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
+        return ()
+
+
+class ProjectContext:
+    """What a project-scoped plugin sees: the module graph, the dependency graph, the
+    advisories every plugin and advisory file contributed, the dependency policy, and
+    each module's imports and call graph. The engine passes the call graphs of modules
+    it served from its cache."""
+
+    def __init__(
+        self,
+        graph: ModuleGraph,
+        dependencies: DependencyGraph,
+        advisories: tuple[Advisory, ...],
+        managers: Mapping[str, AnalysisManager],
+        call_graphs: Mapping[str, CallGraph] | None = None,
+        policy: Policy | None = None,
+        root: Path | None = None,
+    ) -> None:
+        self.root = root
+        self.graph = graph
+        self.dependencies = dependencies
+        self.advisories = advisories
+        self.policy = policy or Policy()
+        self._managers = managers
+        self._call_graphs = dict(call_graphs or {})
+
+    @property
+    def modules(self) -> tuple[str, ...]:
+        return tuple(self._managers)
+
+    def imports(self, module: str) -> ImportTable:
+        return self._managers[module].get(ImportAnalysis)
+
+    def call_graph(self, module: str) -> CallGraph:
+        cached = self._call_graphs.get(module)
+        return cached if cached is not None else self._managers[module].get(CallGraphAnalysis)
+
+
+class ProjectPlugin(Plugin):
+    """A plugin that runs once per project rather than once per module (§26)."""
+
+    def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
+        return ()
+
+    @abstractmethod
+    def analyze_project(self, ctx: ProjectContext) -> Sequence[Finding]:
+        raise NotImplementedError
+
+
+class PluginContext:
+    """What one plugin may see while analysing one module."""
+
+    def __init__(
+        self,
+        manager: AnalysisManager,
+        plugin: Plugin,
+        functions: tuple[nodes.Function, ...] | None = None,
+    ) -> None:
+        self._manager = manager
+        self._plugin = plugin
+        self._functions = analyzable_functions(manager.module) if functions is None else functions
+
+    @property
+    def module(self) -> nodes.Module:
+        return self._manager.module
+
+    def functions(self) -> tuple[nodes.Function, ...]:
+        """Top-level functions and methods the engine can analyse."""
+
+        return self._functions
+
+    @overload
+    def get(self, analysis: type[Analysis[R]], function: None = None) -> R: ...
+
+    @overload
+    def get(self, analysis: type[FunctionAnalysis[R]], function: nodes.Function) -> R: ...
+
+    def get(self, analysis: AnyAnalysis, function: nodes.Function | None = None) -> Any:
+        if analysis not in self._plugin.requires:
+            raise UndeclaredDependencyError(
+                f"{self._plugin.name} requests {analysis.name} without declaring it in requires"
+            )
+        if function is None:
+            assert issubclass(analysis, Analysis)
+            return self._manager.get(analysis)
+        assert issubclass(analysis, FunctionAnalysis)
+        return self._manager.get(analysis, function)
+
+
+def run_plugins(
+    manager: AnalysisManager,
+    plugins: Iterable[Plugin],
+    functions: tuple[nodes.Function, ...] | None = None,
+) -> tuple[Finding, ...]:
+    """Run every plugin against one shared manager and concatenate their findings."""
+
+    findings: list[Finding] = []
+    for plugin in plugins:
+        findings.extend(plugin.analyze(PluginContext(manager, plugin, functions)))
+    return tuple(findings)

coretrace_python/plugins/detectors.py

@@ -0,0 +1,114 @@
+"""Reusable detector bases (architecture §15).
+
+``TaintDetector`` turns the flows of one taint kind into findings; every security
+detector is a few class attributes on top of it. ``SymbolCallDetector`` reports calls
+whose callee resolves to a canonical symbol, through imports and local aliases alike,
+by reading the SSA form.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import ClassVar
+
+from coretrace_python.analysis import AnyAnalysis
+from coretrace_python.findings import Confidence, Finding, Severity
+from coretrace_python.findings.refutation import RefutationAnalysis, Status
+from coretrace_python.ir.model import Call, Symbol
+from coretrace_python.ir.ssa import SSAAnalysis
+from coretrace_python.plugins.api import Plugin, PluginContext
+from coretrace_python.semantic.symbols import SymbolId
+from coretrace_python.taint import TaintAnalysis, TaintKind
+
+
+class TaintDetector(Plugin):
+    """Report every taint flow carrying ``kind`` into a sink."""
+
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({TaintAnalysis, RefutationAnalysis})
+    rule_id: ClassVar[str]
+    kind: ClassVar[TaintKind]
+    severity: ClassVar[Severity]
+    title: ClassVar[str]
+    confidence: ClassVar[Confidence] = Confidence.HIGH
+
+    def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
+        findings: list[Finding] = []
+        for function in ctx.functions():
+            verdicts = ctx.get(RefutationAnalysis, function)
+            for flow in ctx.get(TaintAnalysis, function).flows:
+                if not flow.kinds & self.kind:
+                    continue
+                verdict = verdicts.verdict(flow)
+                if verdict.status is Status.REFUTED:
+                    continue
+                message = f"{self.title}: {flow.source.label} input reaches {flow.sink.symbol}"
+                metadata = {
+                    "source": str(flow.source.symbol),
+                    "source_label": flow.source.label,
+                    "sink": str(flow.sink.symbol),
+                    "verdict": verdict.status.value,
+                    "evidence": verdict.evidence,
+                }
+                if flow.through is not None and flow.sink_location is not None:
+                    message += f" through {flow.through}"
+                    metadata["through"] = flow.through
+                    metadata["sink_line"] = str(flow.sink_location.start_line)
+                confidence = (
+                    self.confidence if verdict.status is Status.VULNERABILITY else _lower(self.confidence)
+                )
+                findings.append(
+                    Finding(
+                        rule_id=self.rule_id,
+                        message=message,
+                        severity=self.severity,
+                        confidence=confidence,
+                        span=flow.location,
+                        function=function.name,
+                        metadata=metadata,
+                    )
+                )
+        return findings
+
+
+def _lower(confidence: Confidence) -> Confidence:
+    return {Confidence.HIGH: Confidence.MEDIUM}.get(confidence, Confidence.LOW)
+
+
+class SymbolCallDetector(Plugin):
+    """Report calls whose callee is one of ``symbols``, whatever name the file uses."""
+
+    requires: ClassVar[frozenset[AnyAnalysis]] = frozenset({SSAAnalysis})
+    rule_id: ClassVar[str]
+    symbols: ClassVar[frozenset[SymbolId]]
+    severity: ClassVar[Severity]
+    message_template: ClassVar[str]
+
+    def analyze(self, ctx: PluginContext) -> Sequence[Finding]:
+        findings: list[Finding] = []
+        for function in ctx.functions():
+            ssa = ctx.get(SSAAnalysis, function)
+            defined = {
+                i.result: i.symbol_id
+                for block in ssa.blocks
+                for i in block.instructions
+                if isinstance(i, Symbol)
+            }
+            for block in ssa.blocks:
+                for instruction in block.instructions:
+                    if not isinstance(instruction, Call):
+                        continue
+                    symbol = defined.get(instruction.callee)
+                    if symbol is None or symbol not in self.symbols:
+                        continue
+                    findings.append(
+                        Finding(
+                            rule_id=self.rule_id,
+                            message=self.message_template.format(symbol=symbol),
+                            severity=self.severity,
+                            confidence=Confidence.HIGH,
+                            span=instruction.location,
+                            function=function.name,
+                            metadata={"symbol": str(symbol)},
+                        )
+                    )
+        return findings

coretrace_python/plugins/loader.py

@@ -0,0 +1,84 @@
+"""In-process plugin loading (architecture §14, §34)."""
+
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+from dataclasses import dataclass
+from pathlib import Path
+
+from coretrace_python.analysis import AnalysisManager
+from coretrace_python.plugins.api import PLUGIN_API_VERSION, Plugin
+from coretrace_python.plugins.manifest import ManifestError, PluginManifest, load_manifest
+
+MANIFEST_FILENAME = "plugin.toml"
+
+
+class IncompatiblePluginError(Exception):
+    """The plugin targets a plugin API version this engine does not provide."""
+
+
+@dataclass(frozen=True)
+class LoadedPlugin:
+    manifest: PluginManifest
+    plugin: Plugin
+    directory: Path
+
+
+def load_plugin(directory: Path, manager: AnalysisManager) -> LoadedPlugin:
+    """Load the plugin in ``directory`` and check it against its manifest."""
+
+    manifest_path = directory / MANIFEST_FILENAME
+    manifest = load_manifest(manifest_path)
+    if not manifest.plugin_api.contains(PLUGIN_API_VERSION):
+        raise IncompatiblePluginError(
+            f"plugin {manifest.name!r} requires plugin_api {manifest.plugin_api}"
+            f" but this engine provides {PLUGIN_API_VERSION}"
+        )
+    for analysis_name in manifest.requires:
+        try:
+            manager.analysis(analysis_name)
+        except KeyError:
+            raise ManifestError(
+                f"{manifest_path}: unknown analysis {analysis_name!r} in requires"
+            ) from None
+
+    plugin_class = _import_entrypoint(directory, manifest)
+    declared = {analysis.name for analysis in plugin_class.requires}
+    if declared != set(manifest.requires):
+        raise ManifestError(
+            f"{manifest_path}: manifest requires {sorted(manifest.requires)}"
+            f" but {manifest.entrypoint.class_name} declares {sorted(declared)}"
+        )
+    return LoadedPlugin(manifest, plugin_class(), directory)
+
+
+def discover_plugins(root: Path, manager: AnalysisManager) -> tuple[LoadedPlugin, ...]:
+    """Load every plugin below ``root``, in path order."""
+
+    return tuple(
+        load_plugin(manifest_path.parent, manager)
+        for manifest_path in sorted(root.rglob(MANIFEST_FILENAME))
+    )
+
+
+def _import_entrypoint(directory: Path, manifest: PluginManifest) -> type[Plugin]:
+    module_path = directory / f"{manifest.entrypoint.module}.py"
+    if not module_path.is_file():
+        raise ManifestError(
+            f"{directory / MANIFEST_FILENAME}: entrypoint module"
+            f" {manifest.entrypoint.module!r} not found"
+        )
+    unique = hashlib.sha1(str(module_path.resolve()).encode()).hexdigest()[:12]
+    spec = importlib.util.spec_from_file_location(f"coretrace_plugin_{unique}", module_path)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    candidate = getattr(module, manifest.entrypoint.class_name, None)
+    if not (isinstance(candidate, type) and issubclass(candidate, Plugin)):
+        raise ManifestError(
+            f"{directory / MANIFEST_FILENAME}: entrypoint class"
+            f" {manifest.entrypoint.class_name!r} is not a Plugin"
+        )
+    return candidate