plugin-scanner 2.0.112__tar.gz → 2.0.113__tar.gz

{plugin_scanner-2.0.112 → plugin_scanner-2.0.113}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 2.0.112
+Version: 2.0.113
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://github.com/hashgraph-online/ai-plugin-scanner
 Project-URL: Repository, https://github.com/hashgraph-online/ai-plugin-scanner

{plugin_scanner-2.0.112 → plugin_scanner-2.0.113}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "2.0.112"
+version = "2.0.113"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.112 → plugin_scanner-2.0.113}/pyproject.toml.bak

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hol-guard"
-version = "2.0.112"
+version = "2.0.113"
 description = "Protect local AI harnesses with HOL Guard and run scanner checks for Codex, Claude, Cursor, Gemini, and OpenCode."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-2.0.112 → plugin_scanner-2.0.113}/src/codex_plugin_scanner/guard/runtime/data_flow.py

@@ -207,6 +207,12 @@ def extract_pipes(command: str) -> tuple[ShellPipe, ...]:
     return tuple(pipes)
 
 
+def extract_command_segments(command: str) -> tuple[str, ...]:
+    """Return top-level shell command segments split on command separators."""
+
+    return _split_top_level_commands(command)
+
+
 def extract_http_methods(command: str) -> tuple[str, ...]:
     """Return explicit or strongly implied HTTP methods referenced by shell text."""
 
@@ -226,6 +232,15 @@ def extract_urls(command: str) -> tuple[str, ...]:
     return _dedupe(url for url in urls if url)
 
 
+def extract_url_ranges(command: str) -> tuple[tuple[int, int], ...]:
+    """Return HTTP(S) URL character ranges in shell text."""
+
+    return tuple(
+        (match.start(), match.start() + len(_strip_url_suffix(match.group(0))))
+        for match in _URL_PATTERN.finditer(command)
+    )
+
+
 def _append_http_method(methods: list[str], method: str) -> None:
     normalized = method.upper()
     if normalized in _HTTP_METHODS:
@@ -264,18 +279,27 @@ def _split_top_level_commands(command: str) -> tuple[str, ...]:
         if next_index != index + 1:
             index = next_index
             continue
-        if state.is_top_level and command[index] == ";":
+        if state.is_top_level and command[index] in {";", "\n"}:
             _append_segment(parts, command[start:index])
             start = index + 1
         elif state.is_top_level and (command.startswith("&&", index) or command.startswith("||", index)):
             _append_segment(parts, command[start:index])
             start = index + 2
             index += 1
+        elif state.is_top_level and command[index] == "&" and _is_background_separator(command, index):
+            _append_segment(parts, command[start:index])
+            start = index + 1
         index += 1
     _append_segment(parts, command[start:])
     return tuple(parts)
 
 
+def _is_background_separator(command: str, index: int) -> bool:
+    previous_char = command[index - 1] if index > 0 else ""
+    next_char = command[index + 1] if index + 1 < len(command) else ""
+    return previous_char not in {">", "<", "|"} and next_char not in {"&", ">"}
+
+
 def _split_top_level_pipes(command: str) -> tuple[str, ...]:
     parts: list[str] = []
     start = 0
@@ -291,7 +315,7 @@ def _split_top_level_pipes(command: str) -> tuple[str, ...]:
             next_is_pipe = index + 1 < len(command) and command[index + 1] == "|"
             if not previous_is_pipe and not next_is_pipe:
                 _append_segment(parts, command[start:index])
-                start = index + 1
+                start = index + 2 if index + 1 < len(command) and command[index + 1] == "&" else index + 1
         index += 1
     _append_segment(parts, command[start:])
     return tuple(parts)

plugin_scanner-2.0.113/src/codex_plugin_scanner/guard/runtime/data_flow_rules.py

@@ -0,0 +1,472 @@
+"""Data-flow exfiltration rules for Guard runtime shell actions."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from pathlib import Path
+from urllib.parse import urlparse
+
+from codex_plugin_scanner.guard.runtime.actions import GuardActionEnvelope
+from codex_plugin_scanner.guard.runtime.data_flow import (
+    ShellPipe,
+    extract_command_segments,
+    extract_command_substitutions,
+    extract_pipes,
+    extract_urls,
+)
+from codex_plugin_scanner.guard.runtime.secret_sensitivity import SecretPathMatch, classify_secret_path
+from codex_plugin_scanner.guard.runtime.secret_sources import secret_path_matches_in_command, strip_shell_token
+from codex_plugin_scanner.guard.runtime.shell_commands import (
+    command_execution_segments,
+    command_tokens_after_env_assignments,
+    git_remote_add_url_tokens,
+    is_scp_remote_target,
+    npm_publish_index,
+    npm_publish_is_dry_run,
+    scp_operands,
+    segment_executes_command,
+)
+from codex_plugin_scanner.guard.runtime.signals import RiskSignalCategory, RiskSignalV2
+from codex_plugin_scanner.guard.runtime.temp_files import chmod_temp_targets, temp_write_targets
+
+_CURL_DATA_FILE_PATTERN = re.compile(
+    r"(?s)(?:^|[\s;&|])(?i:curl|curl\.exe)\b.*?"
+    r"(?:(?:--data(?:-binary|-raw|-urlencode)?|-d)\s*@|--upload-file(?:=|\s+)|-T\s*)"
+    r"(?P<path>\"[^\"]+\"|'[^']+'|[^\s;&|]+)"
+)
+_CURL_DATA_STDIN_PATTERN = re.compile(
+    r"(?s)(?:^|[\s;&|])(?i:curl|curl\.exe)\b[^\r\n;&|]*?"
+    r"(?:(?:--data(?:-binary|-raw|-urlencode)?|-d)\s*@-|(?:--form|-F)(?:=|\s*)[^\s;&|]*@[.-](?=$|[\s;&|])|"
+    r"--upload-file(?:=|\s+)[.-](?=$|[\s;&|])|-T\s*[.-](?=$|[\s;&|]))"
+)
+_CURL_DATA_VALUE_PATTERN = re.compile(
+    r"(?s)(?:^|[\s;&|])(?i:curl|curl\.exe)\b[^\r\n;&|]*?"
+    r"(?:--data(?:-binary|-raw|-urlencode)?|-d)(?:=|\s*)"
+    r"(?P<value>\"[^\"]+\"|'[^']+'|[^\s;&|]+)"
+)
+_PYTHON_SECRET_POST_PATTERN = re.compile(
+    r"(?is)\bpython(?:3)?\b.*?-c\s+.*?"
+    r"(?:requests\.post|urllib\.request|http\.client).*?open\(['\"](?P<path>[^'\"]+)['\"]"
+)
+_NODE_SECRET_FETCH_PATTERN = re.compile(
+    r"(?is)\bnode\b.*?-e\s+.*?(?:fetch|axios\.post|https\.request|http\.request).*?"
+    r"readFileSync\(['\"](?P<path>[^'\"]+)['\"]"
+)
+_DNS_LONG_LABEL_PATTERN = re.compile(
+    r"(?i)(?:^|[\s;&|])(?:dig|nslookup|host)\s+"
+    r"(?P<host>(?:[A-Za-z0-9_-]+\.)*[A-Za-z0-9_-]{48,}(?:\.[A-Za-z0-9_-]+)*)"
+)
+_SCP_PATTERN = re.compile(r"(?is)(?:^|[\s;&|])scp\b(?P<body>[^\r\n;&|]+)")
+_TOKEN_SOURCE_PATTERN = re.compile(r"(?i)\b(?:NPM_TOKEN|NODE_AUTH_TOKEN|_authToken|npm[_-]?token)\b")
+_CLIPBOARD_COMMANDS = frozenset({"pbcopy", "xclip", "xsel", "wl-copy", "clip", "clip.exe"})
+_WEBHOOK_HOST_PATTERN = re.compile(
+    r"webhook\.site|hooks\.slack\.com|discord\.com|pastebin\.com|gist\.github\.com|transfer\.sh|requestbin"
+)
+
+
+def detect_data_flow_exfiltration(
+    action: GuardActionEnvelope,
+    *,
+    workspace: Path | None,
+) -> tuple[RiskSignalV2, ...]:
+    if action.action_type != "shell_command" or action.command is None:
+        return ()
+    command = action.command
+    findings: list[RiskSignalV2] = []
+    secret_matches = _secret_path_matches_in_command(command, workspace=workspace)
+    pipes = extract_pipes(command)
+    if _has_secret_pipe_to_http_upload(pipes, command, workspace=workspace):
+        findings.append(
+            _data_flow_signal(
+                "secret-pipe-http",
+                "Shell pipeline sends a local secret to a network host",
+                "This command pipes a local secret into an HTTP upload.",
+                "secret path and HTTP upload appear in the same pipe chain",
+                category="network",
+            )
+        )
+    if _curl_uploads_secret_file(command, workspace=workspace):
+        findings.append(
+            _data_flow_signal(
+                "curl-data-file",
+                "Curl uploads a local secret file",
+                "This command sends a local secret file as curl request data.",
+                "curl data flag references a sensitive local path",
+                category="network",
+            )
+        )
+    if _python_posts_secret(command, workspace=workspace):
+        findings.append(
+            _data_flow_signal(
+                "python-secret-post",
+                "Python posts a local secret",
+                "This Python snippet reads a local secret and posts it to a network host.",
+                "python -c combines a sensitive file read with an HTTP post",
+                category="network",
+            )
+        )
+    if _node_fetches_secret(command, workspace=workspace):
+        findings.append(
+            _data_flow_signal(
+                "node-secret-fetch",
+                "Node sends a local secret",
+                "This Node snippet reads a local secret and sends it to a network host.",
+                "node -e combines fs.readFileSync on a sensitive path with fetch/request",
+                category="network",
+            )
+        )
+    if _encoded_secret_send(command, secret_matches, workspace=workspace):
+        findings.append(
+            _data_flow_signal(
+                "encoded-secret-send",
+                "Encoded local secret is sent to a network host",
+                "This command encodes a local secret before sending it to a network host.",
+                "base64 appears between a sensitive path and HTTP upload",
+                category="network",
+            )
+        )
+    if _has_dns_exfil_hostname(command):
+        findings.append(
+            _data_flow_signal(
+                "dns-exfil",
+                "DNS query looks like encoded exfiltration",
+                "This command sends an unusually long encoded-looking DNS label.",
+                "DNS tool is called with a long encoded-looking label",
+                category="network",
+            )
+        )
+    if _has_webhook_exfil(command, workspace=workspace):
+        findings.append(
+            _data_flow_signal(
+                "webhook-sink",
+                "Local secret is sent to a public collection endpoint",
+                "This command targets a paste, gist, transfer, or webhook endpoint with local secret data.",
+                "known collection host appears with local secret source",
+                category="network",
+            )
+        )
+    if _scp_sends_secret(command, workspace=workspace):
+        findings.append(
+            _data_flow_signal(
+                "scp-secret",
+                "SCP sends a local secret file",
+                "This command copies a local secret file to a remote host.",
+                "scp command references a sensitive local source",
+                category="network",
+            )
+        )
+    if _git_remote_adds_token_url(command):
+        findings.append(
+            _data_flow_signal(
+                "git-remote-token",
+                "Git remote URL contains an access token",
+                "This command stores a token-bearing URL in git remote configuration.",
+                "git remote add URL includes credentials before host",
+                category="secret",
+            )
+        )
+    if _npm_publish_with_token_source(command, workspace=workspace):
+        findings.append(
+            _data_flow_signal(
+                "npm-publish-token-source",
+                "NPM publish uses local token material",
+                "This command publishes a package while local npm token material is in scope.",
+                "npm publish appears with npm token source evidence",
+                category="network",
+            )
+        )
+    if _clipboard_receives_secret(pipes, command, workspace=workspace):
+        findings.append(
+            _data_flow_signal(
+                "clipboard-secret",
+                "Clipboard receives a local secret",
+                "This command copies local secret contents into the clipboard.",
+                "clipboard command receives sensitive source through a pipe",
+                category="secret",
+            )
+        )
+    if _world_readable_temp_secret(command, workspace=workspace):
+        findings.append(
+            _data_flow_signal(
+                "world-readable-temp-secret",
+                "Local secret is written to a world-readable temp file",
+                "This command writes local secret contents to a world-readable temp file.",
+                "sensitive source is redirected to /tmp and chmod makes it world-readable",
+                category="secret",
+            )
+        )
+    return tuple(_dedupe_signals(findings))
+
+
+def _secret_path_matches_in_command(command: str, *, workspace: Path | None) -> tuple[SecretPathMatch, ...]:
+    return secret_path_matches_in_command(command, workspace=workspace, extra_paths=_curl_data_file_paths(command))
+
+
+def _curl_data_file_paths(command: str) -> tuple[str, ...]:
+    paths: list[str] = []
+    for segment in command_execution_segments(command):
+        if not segment_executes_command(segment, {"curl", "curl.exe"}):
+            continue
+        for match in _CURL_DATA_FILE_PATTERN.finditer(segment):
+            paths.append(strip_shell_token(match.group("path")))
+    return tuple(paths)
+
+
+def _has_secret_pipe_to_http_upload(pipes: Sequence[ShellPipe], command: str, *, workspace: Path | None) -> bool:
+    if not pipes or not _has_http_upload(command):
+        return False
+    return any(
+        extract_pipes(segment)
+        and _secret_path_matches_in_command(segment, workspace=workspace)
+        and _contains_http_upload_sink(segment)
+        for segment in extract_command_segments(command)
+    )
+
+
+def _has_http_upload(command: str) -> bool:
+    return any(
+        segment_executes_command(segment, {"curl", "curl.exe"}) and _CURL_DATA_STDIN_PATTERN.search(segment)
+        for segment in command_execution_segments(command)
+    )
+
+
+def _contains_http_upload_sink(command: str) -> bool:
+    return bool(extract_urls(command)) and _has_http_upload(command)
+
+
+def _curl_uploads_secret_file(command: str, *, workspace: Path | None) -> bool:
+    return any(
+        extract_urls(segment)
+        and any(classify_secret_path(path, cwd=workspace) is not None for path in _curl_data_file_paths(segment))
+        for segment in extract_command_segments(command)
+    ) or _curl_data_substitution_reads_secret(command, workspace=workspace)
+
+
+def _curl_data_substitution_reads_secret(command: str, *, workspace: Path | None) -> bool:
+    for segment in command_execution_segments(command):
+        if not segment_executes_command(segment, {"curl", "curl.exe"}):
+            continue
+        if not extract_urls(segment):
+            continue
+        for match in _CURL_DATA_VALUE_PATTERN.finditer(segment):
+            value = match.group("value")
+            if not any(
+                _secret_path_matches_in_command(substitution, workspace=workspace)
+                for substitution in extract_command_substitutions(value)
+            ):
+                continue
+            return True
+    return False
+
+
+def _python_posts_secret(command: str, *, workspace: Path | None) -> bool:
+    for segment in extract_command_segments(command):
+        if (
+            segment_executes_command(segment, {"python", "python3"})
+            and extract_urls(segment)
+            and any(
+                classify_secret_path(match.group("path"), cwd=workspace) is not None
+                for match in _PYTHON_SECRET_POST_PATTERN.finditer(segment)
+            )
+        ):
+            return True
+    return False
+
+
+def _node_fetches_secret(command: str, *, workspace: Path | None) -> bool:
+    for segment in extract_command_segments(command):
+        if (
+            segment_executes_command(segment, {"node"})
+            and extract_urls(segment)
+            and any(
+                classify_secret_path(match.group("path"), cwd=workspace) is not None
+                for match in _NODE_SECRET_FETCH_PATTERN.finditer(segment)
+            )
+        ):
+            return True
+    return False
+
+
+def _encoded_secret_send(command: str, secret_matches: Sequence[SecretPathMatch], *, workspace: Path | None) -> bool:
+    if not secret_matches:
+        return False
+    return any(
+        _secret_path_matches_in_command(segment, workspace=workspace)
+        and "base64" in segment.lower()
+        and _has_http_upload(segment)
+        and bool(extract_urls(segment))
+        for segment in extract_command_segments(command)
+    )
+
+
+def _has_dns_exfil_hostname(command: str) -> bool:
+    return any(
+        segment_executes_command(segment, {"dig", "nslookup", "host"})
+        and any(_has_long_encoded_label(token) for token in _dns_query_tokens(segment))
+        for segment in extract_command_segments(command)
+    )
+
+
+def _dns_query_tokens(segment: str) -> tuple[str, ...]:
+    tokens = command_tokens_after_env_assignments(segment)
+    return tuple(token.strip("'\"") for token in tokens[1:] if "." in token and not token.startswith(("-", "+", "@")))
+
+
+def _has_long_encoded_label(host: str) -> bool:
+    return any(len(label) >= 48 for label in host.split("."))
+
+
+def _has_webhook_sink(urls: Sequence[str]) -> bool:
+    for url in urls:
+        host = (urlparse(url).hostname or "").lower()
+        if _WEBHOOK_HOST_PATTERN.search(host):
+            return True
+    return False
+
+
+def _has_webhook_exfil(command: str, *, workspace: Path | None) -> bool:
+    for segment in extract_command_segments(command):
+        if not _has_webhook_sink(extract_urls(segment)):
+            continue
+        if _secret_path_matches_in_command(segment, workspace=workspace):
+            return True
+        if _curl_uploads_secret_file(segment, workspace=workspace):
+            return True
+        if _has_secret_pipe_to_http_upload(extract_pipes(segment), segment, workspace=workspace):
+            return True
+    return False
+
+
+def _scp_sends_secret(command: str, *, workspace: Path | None) -> bool:
+    for segment in extract_command_segments(command):
+        if not segment_executes_command(segment, {"scp"}):
+            continue
+        match = _SCP_PATTERN.search(segment)
+        if match is None:
+            continue
+        operands = scp_operands(match.group("body"))
+        if len(operands) < 2:
+            continue
+        target = operands[-1]
+        sources = operands[:-1]
+        if not is_scp_remote_target(target):
+            continue
+        if any(not is_scp_remote_target(source) and classify_secret_path(source, cwd=workspace) for source in sources):
+            return True
+    return False
+
+
+def _git_remote_adds_token_url(command: str) -> bool:
+    for segment in extract_command_segments(command):
+        tokens = command_tokens_after_env_assignments(segment)
+        url_tokens = git_remote_add_url_tokens(tokens)
+        if not url_tokens:
+            continue
+        for url in extract_urls(" ".join(url_tokens)):
+            parsed = urlparse(url)
+            if parsed.username and _looks_like_token(parsed.username):
+                return True
+            if parsed.password and _looks_like_token(parsed.password):
+                return True
+    return False
+
+
+def _looks_like_token(value: str) -> bool:
+    lowered = value.lower()
+    return lowered.startswith(("ghp_", "github_pat_", "glpat-", "x-access-token")) or len(value) >= 24
+
+
+def _npm_publish_with_token_source(command: str, *, workspace: Path | None) -> bool:
+    for segment in extract_command_segments(command):
+        tokens = command_tokens_after_env_assignments(segment)
+        publish_index = npm_publish_index(tokens)
+        if publish_index is None:
+            continue
+        if npm_publish_is_dry_run(tokens, publish_index):
+            continue
+        if _TOKEN_SOURCE_PATTERN.search(segment):
+            return True
+        if _has_npm_secret_match(_secret_path_matches_in_command(segment, workspace=workspace)):
+            return True
+    return False
+
+
+def _has_npm_secret_match(secret_matches: Sequence[SecretPathMatch]) -> bool:
+    return any("npm" in match.family.lower() or ".npmrc" in match.requested_path.lower() for match in secret_matches)
+
+
+def _clipboard_receives_secret(pipes: Sequence[ShellPipe], command: str, *, workspace: Path | None) -> bool:
+    if not pipes:
+        return False
+    return any(
+        (segment_pipes := extract_pipes(segment))
+        and _secret_path_matches_in_command(segment, workspace=workspace)
+        and any(segment_executes_command(pipe.right, _CLIPBOARD_COMMANDS) for pipe in segment_pipes)
+        for segment in extract_command_segments(command)
+    )
+
+
+def _world_readable_temp_secret(command: str, *, workspace: Path | None) -> bool:
+    write_targets = {
+        target
+        for segment in extract_command_segments(command)
+        if _secret_path_matches_in_command(segment, workspace=workspace)
+        for target in temp_write_targets(segment)
+    }
+    if not write_targets:
+        return False
+    return any(
+        target in write_targets and _mode_makes_world_readable(mode) for target, mode in chmod_temp_targets(command)
+    )
+
+
+def _mode_makes_world_readable(mode: str) -> bool:
+    normalized = mode.lower()
+    if normalized.isdigit():
+        return normalized[-1] in {"4", "5", "6", "7"}
+    for clause in normalized.split(","):
+        if "+r" in clause:
+            who = clause.split("+", 1)[0]
+            if not who or "a" in who or "o" in who:
+                return True
+        if "=" in clause:
+            who, permissions = clause.split("=", 1)
+            if "r" in permissions and (not who or "a" in who or "o" in who):
+                return True
+    return False
+
+
+def _data_flow_signal(
+    signal_key: str,
+    title: str,
+    plain_reason: str,
+    technical_detail: str,
+    *,
+    category: RiskSignalCategory,
+) -> RiskSignalV2:
+    return RiskSignalV2(
+        signal_id=f"data-flow:{signal_key}",
+        category=category,
+        severity="critical",
+        confidence="strong",
+        detector="data_flow.exfiltration",
+        title=title,
+        plain_reason=plain_reason,
+        technical_detail=technical_detail,
+        evidence_ref="command",
+        redaction_level="summary",
+        false_positive_hint="Allow only if this exact command intentionally moves non-sensitive local data.",
+        advisory_id=None,
+    )
+
+
+def _dedupe_signals(signals: Sequence[RiskSignalV2]) -> tuple[RiskSignalV2, ...]:
+    seen: set[str] = set()
+    result: list[RiskSignalV2] = []
+    for signal in signals:
+        if signal.signal_id in seen:
+            continue
+        seen.add(signal.signal_id)
+        result.append(signal)
+    return tuple(result)

{plugin_scanner-2.0.112 → plugin_scanner-2.0.113}/src/codex_plugin_scanner/guard/runtime/detectors.py

@@ -10,6 +10,7 @@ from typing import Literal, Protocol
 
 from codex_plugin_scanner.guard.config import GuardConfig
 from codex_plugin_scanner.guard.runtime.actions import GuardActionEnvelope
+from codex_plugin_scanner.guard.runtime.data_flow_rules import detect_data_flow_exfiltration
 from codex_plugin_scanner.guard.runtime.secret_sensitivity import SecretPathMatch, classify_secret_path
 from codex_plugin_scanner.guard.runtime.signals import RiskSignalCategory, RiskSignalV2
 
@@ -120,7 +121,7 @@ class DetectorRegistry:
             if elapsed_ms > timeout_ms:
                 telemetry.append(_telemetry(detector, "timeout", elapsed_ms=elapsed_ms))
                 continue
-            signals.extend(detector_signals)
+            signals.extend(_filter_signals(detector_signals, category_filter))
             telemetry.append(_telemetry(detector, "ok", elapsed_ms=elapsed_ms))
         return DetectorRunResult(signals=tuple(signals), telemetry=tuple(telemetry))
 
@@ -136,8 +137,16 @@ class SecretPathDetector:
         return tuple(_secret_path_signal(match, index=index) for index, match in enumerate(matches))
 
 
+class DataFlowExfiltrationDetector:
+    detector_id = "data_flow.exfiltration"
+    categories: tuple[RiskSignalCategory, ...] = ("secret", "network")
+
+    def detect(self, action: GuardActionEnvelope, context: DetectorContext) -> tuple[RiskSignalV2, ...]:
+        return detect_data_flow_exfiltration(action, workspace=context.workspace)
+
+
 def register_default_detectors() -> tuple[GuardDetector, ...]:
-    return (SecretPathDetector(),)
+    return (DataFlowExfiltrationDetector(), SecretPathDetector())
 
 
 def _secret_path_signal(match: SecretPathMatch, *, index: int) -> RiskSignalV2:
@@ -170,6 +179,15 @@ def _elapsed_ms(started_at: float, finished_at: float) -> int:
     return max(0, round((finished_at - started_at) * 1000))
 
 
+def _filter_signals(
+    signals: Sequence[RiskSignalV2],
+    category_filter: frozenset[RiskSignalCategory] | None,
+) -> tuple[RiskSignalV2, ...]:
+    if category_filter is None:
+        return tuple(signals)
+    return tuple(signal for signal in signals if signal.category in category_filter)
+
+
 def _slug(value: str) -> str:
     return "-".join(part for part in value.lower().replace(".", " ").replace("/", " ").split() if part)