provide-uterm-annotation 0.5.1__tar.gz

provide_uterm_annotation-0.5.1/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: provide-uterm-annotation
+Version: 0.5.1
+Summary: Session-annotation models, pattern detector, and built-in rules for provide-uterm
+License-Expression: AGPL-3.0-or-later
+Requires-Python: >=3.11
+Requires-Dist: provide-uterm>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
+Requires-Dist: mypy>=1.19; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Requires-Dist: bandit>=1.9; extra == "dev"
+Requires-Dist: provide-uterm>=0.5.0; extra == "dev"

provide_uterm_annotation-0.5.1/VERSION

@@ -0,0 +1 @@
+0.5.1

provide_uterm_annotation-0.5.1/pyproject.toml

@@ -0,0 +1,96 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "provide-uterm-annotation"
+dynamic = ["version"]
+description = "Session-annotation models, pattern detector, and built-in rules for provide-uterm"
+requires-python = ">=3.11"
+license = "AGPL-3.0-or-later"
+dependencies = ["provide-uterm>=0.5.0"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9.0",
+    "pytest-asyncio>=1.3",
+    "pytest-cov>=7.0",
+    "pytest-timeout>=2.4.0",
+    "mypy>=1.19",
+    "ruff>=0.15",
+    "bandit>=1.9",
+    "provide-uterm>=0.5.0",
+]
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"provide.uterm" = ["py.typed"]
+"provide.uterm.annotation" = ["py.typed"]
+
+[tool.pytest.ini_options]
+consider_namespace_packages = true
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+addopts = [
+    "--import-mode=importlib",
+    "-v",
+    "--strict-markers",
+    "--strict-config",
+    "--tb=short",
+    "-ra",
+    "--cov=provide.uterm.annotation",
+    "--cov-branch",
+    "--cov-report=term-missing",
+    "--cov-fail-under=100",
+]
+
+[tool.coverage.run]
+source = ["provide.uterm.annotation"]
+omit = ["tests/*"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_covered = false
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = [
+    "E", "W", "F", "I", "N", "UP", "B", "C4", "SIM", "TCH", "PTH",
+    "DTZ", "ICN", "ISC", "PERF", "PIE", "RET", "RSE", "TID", "S", "ARG", "RUF",
+]
+# Aligned with the workspace-root ruff config in ../../pyproject.toml.
+ignore = [
+    "E501", "S101", "S104", "S108", "S110", "S112", "S311", "S603", "S607",
+    "S604", "F811", "N806", "N814", "B017", "SIM105", "SIM117", "ARG001",
+    "ARG002", "PTH108", "SIM108", "PERF401",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"__init__.py" = ["F401", "RUF022"]
+"tests/**/*.py" = ["E402", "B905", "S101", "S105", "S106", "S110", "ARG", "TCH", "RUF003", "RUF012", "RUF015", "RUF043", "RUF059"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src"]
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.uv.sources]
+provide-uterm = { workspace = true }

provide_uterm_annotation-0.5.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

provide_uterm_annotation-0.5.1/src/provide/uterm/annotation/__init__.py

@@ -0,0 +1,22 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+
+"""Annotation feature: mark and detect interesting moments in terminal session recordings."""
+
+from __future__ import annotations
+
+from provide.uterm.annotation._detector import PatternDetector
+from provide.uterm.annotation._models import Annotation, AnnotationSpan, DetectionRule
+from provide.uterm.annotation._rules import BUILTIN_RULES
+from provide.uterm.annotation._streaming import StreamingDetector
+
+__all__ = [
+    "Annotation",
+    "AnnotationSpan",
+    "BUILTIN_RULES",
+    "DetectionRule",
+    "PatternDetector",
+    "StreamingDetector",
+]

provide_uterm_annotation-0.5.1/src/provide/uterm/annotation/_detector.py

@@ -0,0 +1,86 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""PatternDetector — hot-path scanner that matches terminal event text against DetectionRules."""
+
+from __future__ import annotations
+
+from provide.uterm.annotation._models import Annotation, AnnotationSpan, DetectionRule
+from provide.uterm.annotation._rules import BUILTIN_RULES
+
+_DESCRIPTION_TRUNCATE = 80
+# Placeholder used in the fallback description so the raw match (a potential
+# secret) is never embedded when a description_template fails to format.
+_FALLBACK_PLACEHOLDER = "<unavailable>"
+
+
+class PatternDetector:
+    """Scan terminal event text against a set of :class:`DetectionRule` objects.
+
+    Designed for the hot path: returns an empty list immediately when *text* is
+    empty and performs no allocations beyond the returned list when no rules
+    match.
+    """
+
+    def __init__(self, rules: list[DetectionRule] | None = None) -> None:
+        """Initialise with *rules*.
+
+        If *rules* is ``None`` the built-in rule set is used.
+        """
+        self._rules: list[DetectionRule] = BUILTIN_RULES if rules is None else rules
+
+    def detect(self, event_type: str, text: str, seq: int) -> list[Annotation]:
+        """Scan *text* against all rules that apply to *event_type*.
+
+        Returns a (possibly empty) list of :class:`Annotation` objects.  At
+        most one annotation is returned per *category* — the first rule whose
+        pattern matches wins and later rules in that category are skipped.
+        """
+        return self.scan(event_type, text, seq)[0]
+
+    def scan(self, event_type: str, text: str, seq: int) -> tuple[list[Annotation], int]:
+        """Like :meth:`detect`, but also return the end offset of the furthest
+        match in *text* (0 when nothing matches).
+
+        :class:`StreamingDetector` uses the offset to carry only the window tail
+        *after* the matched region — bridging a second secret that straddles the
+        boundary without re-reporting a match that already completed.
+        """
+        if not text:
+            return [], 0
+
+        results: list[Annotation] = []
+        seen_categories: set[str] = set()
+        max_end = 0
+
+        for rule in self._rules:
+            if rule.category in seen_categories:
+                continue
+            if event_type not in rule.event_types:
+                continue
+            m = rule.pattern.search(text)
+            if m is None:
+                continue
+
+            seen_categories.add(rule.category)
+            max_end = max(max_end, m.end())
+            match_text = m.group(0)[:_DESCRIPTION_TRUNCATE]
+            try:
+                description = rule.description_template.format(match=match_text, event_type=event_type)
+            except (KeyError, IndexError):
+                # A malformed template must not leak the raw match (a potential
+                # secret) into the description, which flows to telemetry/logs.
+                description = f"{rule.label}: {_FALLBACK_PLACEHOLDER}"
+            results.append(
+                Annotation(
+                    label=rule.label,
+                    description=description,
+                    severity=rule.severity,
+                    source="detector",
+                    principal="system",
+                    span=AnnotationSpan(from_seq=seq, to_seq=seq),
+                )
+            )
+
+        return results, max_end

provide_uterm_annotation-0.5.1/src/provide/uterm/annotation/_models.py

@@ -0,0 +1,60 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""Data models for session annotation — marking interesting moments in terminal recordings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import re
+
+
+@dataclass(slots=True)
+class AnnotationSpan:
+    """A contiguous range of recording event sequence numbers."""
+
+    from_seq: int
+    to_seq: int
+
+
+@dataclass(slots=True)
+class Annotation:
+    """A single annotation marking an interesting moment (or range) in a session recording."""
+
+    label: str
+    description: str
+    severity: str
+    source: str
+    principal: str
+    span: AnnotationSpan | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serialise to a plain :class:`dict`, with ``span`` as a nested dict if present."""
+        result: dict[str, Any] = {
+            "label": self.label,
+            "description": self.description,
+            "severity": self.severity,
+            "source": self.source,
+            "principal": self.principal,
+            "span": None,
+        }
+        if self.span is not None:
+            result["span"] = {"from_seq": self.span.from_seq, "to_seq": self.span.to_seq}
+        return result
+
+
+@dataclass(slots=True)
+class DetectionRule:
+    """A compiled regex rule used to detect annotation-worthy events in terminal output."""
+
+    rule_id: str
+    label: str
+    pattern: re.Pattern[str]
+    severity: str
+    description_template: str
+    event_types: frozenset[str]
+    category: str

provide_uterm_annotation-0.5.1/src/provide/uterm/annotation/_rules.py

@@ -0,0 +1,216 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""Built-in detection rules for session annotation."""
+
+from __future__ import annotations
+
+import re
+
+from provide.uterm.annotation._models import DetectionRule
+
+# All built-in rules apply to both inbound and outbound event streams.
+_BOTH: frozenset[str] = frozenset({"read", "send"})
+
+# ---------------------------------------------------------------------------
+# Built-in rules — ordered most-specific first within each category.
+# ---------------------------------------------------------------------------
+
+BUILTIN_RULES: list[DetectionRule] = [
+    # -------------------------------------------------------------------------
+    # Credentials — high severity
+    # -------------------------------------------------------------------------
+    DetectionRule(
+        rule_id="cred.aws_access_key",
+        label="credential_exposure",
+        pattern=re.compile(r"AKIA[0-9A-Z]{12}"),
+        severity="high",
+        description_template="AWS access key detected in {event_type}",
+        event_types=_BOTH,
+        category="credentials",
+    ),
+    DetectionRule(
+        rule_id="cred.github_token",
+        label="credential_exposure",
+        pattern=re.compile(r"gh[psourx]_[A-Za-z0-9_]{8}"),
+        severity="high",
+        description_template="GitHub token detected in {event_type}",
+        event_types=_BOTH,
+        category="credentials",
+    ),
+    DetectionRule(
+        rule_id="cred.generic_secret",
+        label="credential_exposure",
+        pattern=re.compile(r"(?i)(password|secret|token|api_key)\s*[=:]"),
+        severity="high",
+        description_template="Secret assignment detected in {event_type}",
+        event_types=_BOTH,
+        category="credentials",
+    ),
+    DetectionRule(
+        rule_id="cred.bearer_token",
+        label="credential_exposure",
+        pattern=re.compile(r"Bearer\s+\S{8}"),
+        severity="high",
+        description_template="Bearer token detected in {event_type}",
+        event_types=_BOTH,
+        category="credentials",
+    ),
+    DetectionRule(
+        rule_id="cred.private_key_header",
+        label="credential_exposure",
+        pattern=re.compile(r"-----BEGIN\s+(RSA|EC|OPENSSH)\s+PRIVATE KEY-----"),
+        severity="high",
+        description_template="Private key header detected: {match}",
+        event_types=_BOTH,
+        category="credentials",
+    ),
+    # -------------------------------------------------------------------------
+    # Privilege escalation — high severity
+    # -------------------------------------------------------------------------
+    DetectionRule(
+        rule_id="esc.sudo",
+        label="privilege_escalation",
+        pattern=re.compile(r"\bsudo\b"),
+        severity="high",
+        description_template="sudo command detected: {match}",
+        event_types=_BOTH,
+        category="escalation",
+    ),
+    DetectionRule(
+        rule_id="esc.su_dash",
+        label="privilege_escalation",
+        pattern=re.compile(r"\bsu\s+-"),
+        severity="high",
+        description_template="su - (switch to root) detected: {match}",
+        event_types=_BOTH,
+        category="escalation",
+    ),
+    DetectionRule(
+        rule_id="esc.pkexec",
+        label="privilege_escalation",
+        pattern=re.compile(r"\bpkexec\b"),
+        severity="high",
+        description_template="pkexec privilege escalation detected: {match}",
+        event_types=_BOTH,
+        category="escalation",
+    ),
+    # -------------------------------------------------------------------------
+    # Destructive commands — critical severity
+    # -------------------------------------------------------------------------
+    DetectionRule(
+        rule_id="dest.rm_rf",
+        label="destructive_command",
+        pattern=re.compile(r"\brm\s+(-[rRf]{2,}|-[rR]\s+-f|-f\s+-[rR])"),
+        severity="critical",
+        description_template="Recursive force-remove detected: {match}",
+        event_types=_BOTH,
+        category="destructive",
+    ),
+    DetectionRule(
+        rule_id="dest.drop_table",
+        label="destructive_command",
+        pattern=re.compile(r"(?i)\bDROP\s+(TABLE|DATABASE)\b"),
+        severity="critical",
+        description_template="SQL DROP statement detected: {match}",
+        event_types=_BOTH,
+        category="destructive",
+    ),
+    DetectionRule(
+        rule_id="dest.kubectl_delete",
+        label="destructive_command",
+        pattern=re.compile(r"\bkubectl\s+delete\b"),
+        severity="critical",
+        description_template="kubectl delete command detected: {match}",
+        event_types=_BOTH,
+        category="destructive",
+    ),
+    DetectionRule(
+        rule_id="dest.dd_if",
+        label="destructive_command",
+        pattern=re.compile(r"\bdd\s+if="),
+        severity="critical",
+        description_template="dd disk-copy command detected: {match}",
+        event_types=_BOTH,
+        category="destructive",
+    ),
+    DetectionRule(
+        rule_id="dest.mkfs",
+        label="destructive_command",
+        pattern=re.compile(r"\bmkfs\."),
+        severity="critical",
+        description_template="mkfs (format filesystem) detected: {match}",
+        event_types=_BOTH,
+        category="destructive",
+    ),
+    # -------------------------------------------------------------------------
+    # Outbound connections — info severity
+    # -------------------------------------------------------------------------
+    DetectionRule(
+        rule_id="conn.ssh",
+        label="outbound_connection",
+        pattern=re.compile(r"\bssh\s+[\w.\-]+@"),
+        severity="info",
+        description_template="SSH connection detected: {match}",
+        event_types=_BOTH,
+        category="connections",
+    ),
+    DetectionRule(
+        rule_id="conn.curl",
+        label="outbound_connection",
+        pattern=re.compile(r"\bcurl\b.*https?://"),
+        severity="info",
+        description_template="curl HTTP request detected: {match}",
+        event_types=_BOTH,
+        category="connections",
+    ),
+    DetectionRule(
+        rule_id="conn.wget",
+        label="outbound_connection",
+        pattern=re.compile(r"\bwget\b.*https?://"),
+        severity="info",
+        description_template="wget HTTP request detected: {match}",
+        event_types=_BOTH,
+        category="connections",
+    ),
+    DetectionRule(
+        rule_id="conn.scp",
+        label="outbound_connection",
+        pattern=re.compile(r"\bscp\b"),
+        severity="info",
+        description_template="scp file transfer detected: {match}",
+        event_types=_BOTH,
+        category="connections",
+    ),
+    # -------------------------------------------------------------------------
+    # Session lifecycle — info severity
+    # -------------------------------------------------------------------------
+    DetectionRule(
+        rule_id="life.exit",
+        label="session_lifecycle",
+        pattern=re.compile(r"\bexit\b"),
+        severity="info",
+        description_template="exit command detected: {match}",
+        event_types=_BOTH,
+        category="lifecycle",
+    ),
+    DetectionRule(
+        rule_id="life.shutdown",
+        label="session_lifecycle",
+        pattern=re.compile(r"\bshutdown\b"),
+        severity="info",
+        description_template="shutdown command detected: {match}",
+        event_types=_BOTH,
+        category="lifecycle",
+    ),
+    DetectionRule(
+        rule_id="life.reboot",
+        label="session_lifecycle",
+        pattern=re.compile(r"\breboot\b"),
+        severity="info",
+        description_template="reboot command detected: {match}",
+        event_types=_BOTH,
+        category="lifecycle",
+    ),
+]

provide_uterm_annotation-0.5.1/src/provide/uterm/annotation/_streaming.py

@@ -0,0 +1,63 @@
+#
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 provide.io llc. All rights reserved.
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+"""StreamingDetector — catch patterns split across consecutive detect() calls.
+
+:class:`PatternDetector` is stateless: it scans one chunk at a time, so a
+multi-character pattern (an AWS key, a URL) that happens to straddle two
+``detect()`` chunks is silently missed. This wrapper carries a small bounded
+tail of the previous chunk and prepends it to the next one, so a boundary-split
+match is still found.
+
+It is **stateful** — use one instance per logical stream (one per session, and
+not shared across event types whose text must not be concatenated). The wrapped
+``PatternDetector`` stays stateless and may be shared.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from provide.uterm.annotation._detector import PatternDetector
+    from provide.uterm.annotation._models import Annotation
+
+# Longest fixed-shape secret we expect to bridge a boundary. Bounds how much of
+# the previous chunk is retained (and re-scanned), capping memory and CPU.
+_DEFAULT_MAX_CARRY = 512
+
+
+class StreamingDetector:
+    """Stateful per-stream wrapper that bridges chunk boundaries for a detector."""
+
+    __slots__ = ("_carry", "_detector", "_max_carry")
+
+    def __init__(self, detector: PatternDetector, *, max_carry: int = _DEFAULT_MAX_CARRY) -> None:
+        self._detector = detector
+        self._max_carry = max_carry
+        self._carry = ""
+
+    def detect(self, event_type: str, text: str, seq: int) -> list[Annotation]:
+        """Scan *text* (joined with the carried tail) and return any matches.
+
+        A match is owned by the chunk in which it *completes* — the returned
+        annotation's span carries the *seq* passed for that chunk. The carried
+        tail is the bounded window suffix *after* the furthest match: it bridges
+        a secret straddling the next boundary (including a second one that begins
+        right after a completed match) without re-reporting a match that already
+        finished.
+        """
+        if not text:
+            return []
+        window = self._carry + text if self._carry else text
+        annotations, match_end = self._detector.scan(event_type, window, seq)
+        self._carry = window[match_end:][-self._max_carry :]
+        return annotations
+
+    def reset(self) -> None:
+        """Forget the carried tail (e.g. on screen clear / session resync)."""
+        self._carry = ""
+
+
+__all__ = ["StreamingDetector"]

provide_uterm_annotation-0.5.1/src/provide_uterm_annotation.egg-info/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: provide-uterm-annotation
+Version: 0.5.1
+Summary: Session-annotation models, pattern detector, and built-in rules for provide-uterm
+License-Expression: AGPL-3.0-or-later
+Requires-Python: >=3.11
+Requires-Dist: provide-uterm>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=9.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.3; extra == "dev"
+Requires-Dist: pytest-cov>=7.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.4.0; extra == "dev"
+Requires-Dist: mypy>=1.19; extra == "dev"
+Requires-Dist: ruff>=0.15; extra == "dev"
+Requires-Dist: bandit>=1.9; extra == "dev"
+Requires-Dist: provide-uterm>=0.5.0; extra == "dev"

provide_uterm_annotation-0.5.1/src/provide_uterm_annotation.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+VERSION
+pyproject.toml
+src/provide/uterm/annotation/__init__.py
+src/provide/uterm/annotation/_detector.py
+src/provide/uterm/annotation/_models.py
+src/provide/uterm/annotation/_rules.py
+src/provide/uterm/annotation/_streaming.py
+src/provide/uterm/annotation/py.typed
+src/provide_uterm_annotation.egg-info/PKG-INFO
+src/provide_uterm_annotation.egg-info/SOURCES.txt
+src/provide_uterm_annotation.egg-info/dependency_links.txt
+src/provide_uterm_annotation.egg-info/requires.txt
+src/provide_uterm_annotation.egg-info/top_level.txt
+tests/test_annotation_detector.py
+tests/test_annotation_models.py
+tests/test_annotation_rules.py
+tests/test_detector_exception_path.py
+tests/test_streaming_detector.py

provide_uterm_annotation-0.5.1/src/provide_uterm_annotation.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

provide_uterm_annotation-0.5.1/src/provide_uterm_annotation.egg-info/requires.txt

@@ -0,0 +1,11 @@
+provide-uterm>=0.5.0
+
+[dev]
+pytest>=9.0
+pytest-asyncio>=1.3
+pytest-cov>=7.0
+pytest-timeout>=2.4.0
+mypy>=1.19
+ruff>=0.15
+bandit>=1.9
+provide-uterm>=0.5.0

provide_uterm_annotation-0.5.1/src/provide_uterm_annotation.egg-info/top_level.txt

@@ -0,0 +1 @@
+provide