cyvest 3.0.0__tar.gz → 3.1.0__tar.gz

{cyvest-3.0.0 → cyvest-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: cyvest
-Version: 3.0.0
+Version: 3.1.0
 Summary: Cybersecurity investigation model
 Keywords: cybersecurity,investigation,threat-intel,security-analysis
 Author: PakitoSec
@@ -300,7 +300,8 @@ SAFE checks:
 
 **Root Observable Barrier:**
 
-The root observable (the investigation's entry point with `value="input-data"`) acts as a special barrier to prevent cross-contamination:
+The root observable (the investigation's entry point with `value="root"`) acts as a special barrier to prevent cross-contamination:
+Its key is derived from type + value (e.g. `obs:file:root` or `obs:artifact:root`).
 
 **Barrier as Child** - When root appears as a child of other observables, it is **skipped** in their score calculations.
 

{cyvest-3.0.0 → cyvest-3.1.0}/README.md

@@ -271,7 +271,8 @@ SAFE checks:
 
 **Root Observable Barrier:**
 
-The root observable (the investigation's entry point with `value="input-data"`) acts as a special barrier to prevent cross-contamination:
+The root observable (the investigation's entry point with `value="root"`) acts as a special barrier to prevent cross-contamination:
+Its key is derived from type + value (e.g. `obs:file:root` or `obs:artifact:root`).
 
 **Barrier as Child** - When root appears as a child of other observables, it is **skipped** in their score calculations.
 

{cyvest-3.0.0 → cyvest-3.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cyvest"
-version = "3.0.0"
+version = "3.1.0"
 description = "Cybersecurity investigation model"
 readme = {file = "README.md", content-type = "text/markdown"}
 requires-python = ">=3.10"

{cyvest-3.0.0 → cyvest-3.1.0}/src/cyvest/__init__.py

@@ -9,16 +9,11 @@ from logurich import logger
 
 from cyvest.cyvest import Cyvest
 from cyvest.levels import Level
-from cyvest.model import (
-    CheckScorePolicy,
-    InvestigationWhitelist,
-    ObservableType,
-    RelationshipDirection,
-    RelationshipType,
-)
+from cyvest.model import InvestigationWhitelist
+from cyvest.model_enums import CheckScorePolicy, ObservableType, RelationshipDirection, RelationshipType
 from cyvest.proxies import CheckProxy, ContainerProxy, EnrichmentProxy, ObservableProxy, ThreatIntelProxy
 
-__version__ = "3.0.0"
+__version__ = "3.1.0"
 
 logger.disable("cyvest")
 

{cyvest-3.0.0 → cyvest-3.1.0}/src/cyvest/cyvest.py

@@ -215,16 +215,19 @@ class Cyvest:
         Returns:
             The created or existing observable
         """
-        obs = Observable(
-            obs_type=obs_type,
-            value=value,
-            internal=internal,
-            whitelisted=whitelisted,
-            comment=comment,
-            extra=extra or {},
-            score=Decimal(str(score)) if score is not None else Decimal("0"),
-            level=level if level is not None else Level.INFO,
-        )
+        obs_kwargs: dict[str, Any] = {
+            "obs_type": obs_type,
+            "value": value,
+            "internal": internal,
+            "whitelisted": whitelisted,
+            "comment": comment,
+            "extra": extra or {},
+        }
+        if score is not None:
+            obs_kwargs["score"] = Decimal(str(score))
+        if level is not None:
+            obs_kwargs["level"] = level
+        obs = Observable(**obs_kwargs)
         # Unwrap tuple - facade returns only Observable, discards deferred relationships
         obs_result, _ = self._investigation.add_observable(obs)
         return self._observable_proxy(obs_result)
@@ -303,15 +306,17 @@ class Cyvest:
         if not observable:
             return None
 
-        ti = ThreatIntel(
-            source=source,
-            observable_key=observable_key,
-            comment=comment,
-            extra=extra or {},
-            score=Decimal(str(score)),
-            level=level if level is not None else Level.INFO,
-            taxonomies=taxonomies or [],
-        )
+        ti_kwargs: dict[str, Any] = {
+            "source": source,
+            "observable_key": observable_key,
+            "comment": comment,
+            "extra": extra or {},
+            "score": Decimal(str(score)),
+            "taxonomies": taxonomies or [],
+        }
+        if level is not None:
+            ti_kwargs["level"] = level
+        ti = ThreatIntel(**ti_kwargs)
         result = self._investigation.add_threat_intel(ti, observable)
         return self._threat_intel_proxy(result)
 
@@ -369,16 +374,20 @@ class Cyvest:
         Returns:
             The created check
         """
-        check = Check(
-            check_id=check_id,
-            scope=scope,
-            description=description,
-            comment=comment,
-            extra=extra or {},
-            score=Decimal(str(score)) if score is not None else Decimal("0"),
-            level=level if level is not None else Level.NONE,
-            score_policy=score_policy if score_policy is not None else CheckScorePolicy.AUTO,
-        )
+        check_kwargs: dict[str, Any] = {
+            "check_id": check_id,
+            "scope": scope,
+            "description": description,
+            "comment": comment,
+            "extra": extra or {},
+        }
+        if score is not None:
+            check_kwargs["score"] = Decimal(str(score))
+        if level is not None:
+            check_kwargs["level"] = level
+        if score_policy is not None:
+            check_kwargs["score_policy"] = score_policy
+        check = Check(**check_kwargs)
         return self._check_proxy(self._investigation.add_check(check))
 
     def check_get(self, key: str) -> CheckProxy | None:
@@ -685,13 +694,17 @@ class Cyvest:
         }
 
     def display_summary(
-        self, show_graph: bool = True, exclude_levels: Level | str | Iterable[Level | str] = Level.NONE
+        self,
+        show_graph: bool = True,
+        exclude_levels: Level | str | Iterable[Level | str] = Level.NONE,
+        show_score_history: bool = False,
     ) -> None:
         display_summary(
             self,
             lambda renderables: logger.rich("INFO", renderables),
             show_graph=show_graph,
             exclude_levels=exclude_levels,
+            show_score_history=show_score_history,
         )
 
     def display_statistics(self) -> None:

{cyvest-3.0.0 → cyvest-3.1.0}/src/cyvest/investigation.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import threading
 from copy import deepcopy
+from datetime import datetime, timezone
 from decimal import Decimal
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Literal, overload
@@ -16,7 +17,8 @@ from typing import TYPE_CHECKING, Any, Literal, overload
 from logurich import logger
 
 from cyvest import keys
-from cyvest.levels import Level, get_level_from_score, normalize_level
+from cyvest.level_score_rules import recalculate_level_for_score
+from cyvest.levels import Level, normalize_level
 from cyvest.model import (
     Check,
     CheckScorePolicy,
@@ -753,6 +755,8 @@ class Investigation:
             root_type: Type of root observable ("file" or "artifact")
             score_mode: Score calculation mode (MAX or SUM)
         """
+        self._started_at = datetime.now(timezone.utc)
+
         # Object collections
         self._observables: dict[str, Observable] = {}
         self._checks: dict[str, Check] = {}
@@ -775,7 +779,7 @@ class Investigation:
 
         self._root_observable = Observable(
             obs_type=obj_type,
-            value="input-data",
+            value="root",
             internal=False,
             whitelisted=False,
             comment="Root observable for investigation",
@@ -962,11 +966,8 @@ class Investigation:
         # Take the higher score
         if incoming.score > existing.score:
             existing.score = incoming.score
-            # Recalculate level
-            if not existing._explicit_level:
-                calculated_level = get_level_from_score(existing.score)
-                if calculated_level > existing.level:
-                    existing.level = calculated_level
+            # Recalculate level from new score (SAFE remains sticky against downgrades)
+            existing.level = recalculate_level_for_score(existing.level, existing.score)
 
         # Take the higher level
         if incoming.level > existing.level:

{cyvest-3.0.0 → cyvest-3.1.0}/src/cyvest/io_rich.py

@@ -7,10 +7,12 @@ Provides formatted display of investigation results using the Rich library.
 from __future__ import annotations
 
 from collections.abc import Callable, Iterable
+from datetime import datetime, timezone
 from decimal import Decimal, InvalidOperation
 from typing import TYPE_CHECKING, Any
 
 from rich.align import Align
+from rich.markup import escape
 from rich.rule import Rule
 from rich.table import Table
 from rich.tree import Tree
@@ -22,11 +24,216 @@ if TYPE_CHECKING:
     from cyvest.cyvest import Cyvest
 
 
+def _normalize_exclude_levels(levels: Level | str | Iterable[Level | str]) -> set[Level]:
+    base_excluded: set[Level] = {Level.NONE}
+    if levels is None:
+        return base_excluded
+    if isinstance(levels, (Level, str)):
+        normalized_level = normalize_level(levels) if isinstance(levels, str) else levels
+        return base_excluded | {normalized_level}
+
+    collected = list(levels)
+    if not collected:
+        return set()
+
+    normalized: set[Level] = set()
+    for level in collected:
+        normalized.add(normalize_level(level) if isinstance(level, str) else level)
+    return base_excluded | normalized
+
+
+def _sort_key_by_score(item: Any) -> tuple[Decimal, str]:
+    score = getattr(item, "score", 0)
+    try:
+        decimal_score = Decimal(score)
+    except (TypeError, ValueError, InvalidOperation):
+        decimal_score = Decimal(0)
+
+    item_id = getattr(item, "check_id", "")
+    return (-decimal_score, item_id)
+
+
+def _get_direction_symbol(rel: Relationship, reversed_edge: bool) -> str:
+    """Return an arrow indicating direction relative to traversal."""
+    direction = rel.direction
+    if isinstance(direction, str):
+        try:
+            direction = RelationshipDirection(direction)
+        except ValueError:
+            direction = RelationshipDirection.OUTBOUND
+
+    symbol_map = {
+        RelationshipDirection.OUTBOUND: "→",
+        RelationshipDirection.INBOUND: "←",
+        RelationshipDirection.BIDIRECTIONAL: "↔",
+    }
+    symbol = symbol_map.get(direction, "→")
+    if reversed_edge and direction != RelationshipDirection.BIDIRECTIONAL:
+        symbol = "←" if direction == RelationshipDirection.OUTBOUND else "→"
+    return symbol
+
+
+def _build_observable_tree(
+    parent_tree: Tree,
+    obs: Any,
+    *,
+    all_observables: dict[str, Any],
+    reverse_relationships: dict[str, list[tuple[Any, Relationship]]],
+    visited: set[str],
+    rel_info: str = "",
+) -> None:
+    if obs.key in visited:
+        return
+    visited.add(obs.key)
+
+    color_level = get_color_level(obs.level)
+    color_score = get_color_score(obs.score)
+
+    generated_by = ""
+    if obs.generated_by_checks:
+        checks_str = "[cyan], [/cyan]".join(escape(check_id) for check_id in obs.generated_by_checks)
+        generated_by = f"[cyan][[/cyan]{checks_str}[cyan]][/cyan] "
+
+    whitelisted_str = " [green]WHITELISTED[/green]" if obs.whitelisted else ""
+
+    obs_info = (
+        f"{rel_info}{generated_by}[bold]{obs.key}[/bold] "
+        f"[{color_score}]{obs.score}[/{color_score}] "
+        f"[{color_level}]{obs.level.name}[/{color_level}]"
+        f"{whitelisted_str}"
+    )
+
+    child_tree = parent_tree.add(obs_info)
+
+    # Add outbound children
+    for rel in obs.relationships:
+        child_obs = all_observables.get(rel.target_key)
+        if child_obs:
+            direction_symbol = _get_direction_symbol(rel, reversed_edge=False)
+            rel_label = f"[dim]{rel.relationship_type_name}[/dim] {direction_symbol} "
+            _build_observable_tree(
+                child_tree,
+                child_obs,
+                all_observables=all_observables,
+                reverse_relationships=reverse_relationships,
+                visited=visited,
+                rel_info=rel_label,
+            )
+
+    # Add inbound children (observables pointing to this one)
+    for source_obs, rel in reverse_relationships.get(obs.key, []):
+        if source_obs.key == obs.key:
+            continue
+        direction_symbol = _get_direction_symbol(rel, reversed_edge=True)
+        rel_label = f"[dim]{rel.relationship_type_name}[/dim] {direction_symbol} "
+        _build_observable_tree(
+            child_tree,
+            source_obs,
+            all_observables=all_observables,
+            reverse_relationships=reverse_relationships,
+            visited=visited,
+            rel_info=rel_label,
+        )
+
+
+def _render_score_history_table(
+    *,
+    rich_print: Callable[[Any], None],
+    title: str,
+    groups: Iterable[tuple[str, Iterable[Any]]],
+    started_at: datetime | None,
+) -> None:
+    materialized_groups: list[tuple[str, list[Any]]] = [(name, list(items)) for name, items in groups]
+
+    def _coerce_utc(value: datetime) -> datetime:
+        if value.tzinfo is None:
+            return value.replace(tzinfo=timezone.utc)
+        return value.astimezone(timezone.utc)
+
+    def _format_elapsed(total_seconds: float) -> str:
+        total_ms = int(round(total_seconds * 1000))
+        if total_ms < 0:
+            total_ms = 0
+        hours, rem_ms = divmod(total_ms, 3_600_000)
+        minutes, rem_ms = divmod(rem_ms, 60_000)
+        seconds, ms = divmod(rem_ms, 1000)
+        return f"{hours:02d}:{minutes:02d}:{seconds:02d}.{ms:03d}"
+
+    table = Table(title=title, show_lines=False)
+    table.add_column("Item")
+    table.add_column("#", justify="right")
+    table.add_column("Elapsed", style="dim")
+    table.add_column("Score", justify="center")
+    table.add_column("Level", justify="center")
+    table.add_column("Reason")
+
+    effective_start = _coerce_utc(started_at) if started_at is not None else None
+    if effective_start is None:
+        earliest: datetime | None = None
+        for _group_name, items in materialized_groups:
+            for item in items:
+                for change in item.get_score_history():
+                    ts = _coerce_utc(change.timestamp)
+                    if earliest is None or ts < earliest:
+                        earliest = ts
+        effective_start = earliest
+
+    has_history = False
+    for group_name, items in materialized_groups:
+        item_color = "cyan" if group_name.lower() == "observable" else "magenta"
+        for item in items:
+            score_history = sorted(item.get_score_history(), key=lambda change: change.timestamp)
+            if not score_history:
+                continue
+
+            if has_history:
+                table.add_section()
+
+            for idx, change in enumerate(score_history, start=1):
+                has_history = True
+
+                change_timestamp = _coerce_utc(change.timestamp)
+                old_score_color = get_color_score(change.old_score)
+                new_score_color = get_color_score(change.new_score)
+                score_str = (
+                    f"[{old_score_color}]{change.old_score}[/{old_score_color}] "
+                    f"→ "
+                    f"[{new_score_color}]{change.new_score}[/{new_score_color}]"
+                )
+
+                old_level_color = get_color_level(change.old_level)
+                new_level_color = get_color_level(change.new_level)
+                level_str = (
+                    f"[{old_level_color}]{change.old_level.name}[/{old_level_color}] "
+                    f"→ "
+                    f"[{new_level_color}]{change.new_level.name}[/{new_level_color}]"
+                )
+
+                reason = escape(change.reason) if change.reason else "[dim]-[/dim]"
+                elapsed = ""
+                if effective_start is not None:
+                    elapsed = _format_elapsed((change_timestamp - effective_start).total_seconds())
+
+                item_cell = f"[{item_color}]{escape(item.key)}[/{item_color}]"
+                table.add_row(
+                    item_cell,
+                    str(idx),
+                    elapsed,
+                    score_str,
+                    level_str,
+                    reason,
+                )
+
+    table.caption = "No score changes recorded." if not has_history else ""
+    rich_print(table)
+
+
 def display_summary(
     cv: Cyvest,
     rich_print: Callable[[Any], None],
     show_graph: bool = True,
     exclude_levels: Level | str | Iterable[Level | str] = Level.NONE,
+    show_score_history: bool = False,
 ) -> None:
     """
     Display a comprehensive summary of the investigation using Rich.
@@ -36,26 +243,10 @@ def display_summary(
         rich_print: A rich renderable handler that is called with renderables for output
         show_graph: Whether to display the observable graph
         exclude_levels: Level(s) to omit from the report (default: Level.NONE)
+        show_score_history: Whether to display score change history for observables and checks (default: False)
     """
 
-    def _normalize_exclude(levels: Level | str | Iterable[Level | str]) -> set[Level]:
-        base_excluded: set[Level] = {Level.NONE}
-        if levels is None:
-            return base_excluded
-        if isinstance(levels, (Level, str)):
-            normalized_level = normalize_level(levels) if isinstance(levels, str) else levels
-            return base_excluded | {normalized_level}
-
-        collected = list(levels)
-        if not collected:
-            return set()
-
-        normalized: set[Level] = set()
-        for level in collected:
-            normalized.add(normalize_level(level) if isinstance(level, str) else level)
-        return base_excluded | normalized
-
-    resolved_excluded_levels = _normalize_exclude(exclude_levels)
+    resolved_excluded_levels = _normalize_exclude_levels(exclude_levels)
 
     all_checks = cv.get_all_checks().values()
     filtered_checks = [c for c in all_checks if c.level not in resolved_excluded_levels]
@@ -72,17 +263,6 @@ def display_summary(
         f"Applied: {applied_checks}",
     ]
 
-    def sort_key_by_score(check: Any) -> tuple[Decimal, str]:
-        score = getattr(check, "score", 0)
-        try:
-            decimal_score = Decimal(score)
-        except (TypeError, ValueError, InvalidOperation):
-            decimal_score = Decimal(0)
-
-        # Return tuple: (-score for descending, check_id for ascending alphabetically)
-        check_id = getattr(check, "check_id", "")
-        return (-decimal_score, check_id)
-
     table = Table(
         title="Investigation Report",
         caption=" | ".join(caption_parts),
@@ -107,7 +287,7 @@ def display_summary(
     for scope_name, checks in checks_by_scope.items():
         scope_rule = Align(f"[bold magenta]{scope_name}[/bold magenta]", align="left")
         table.add_row(scope_rule, "-", "-")
-        checks = sorted(checks, key=sort_key_by_score)
+        checks = sorted(checks, key=_sort_key_by_score)
         for check in checks:
             color_level = get_color_level(check.level)
             color_score = get_color_score(check.score)
@@ -144,7 +324,7 @@ def display_summary(
         checks = [
             c for c in cv.get_all_checks().values() if c.level == level_enum and c.level not in resolved_excluded_levels
         ]
-        checks = sorted(checks, key=sort_key_by_score)
+        checks = sorted(checks, key=_sort_key_by_score)
         if checks:
             color_level = get_color_level(level_enum)
             level_rule = Align(
@@ -214,73 +394,34 @@ def display_summary(
             for rel in source_obs.relationships:
                 reverse_relationships.setdefault(rel.target_key, []).append((source_obs, rel))
 
-        def get_direction_symbol(rel: Relationship, reversed_edge: bool) -> str:
-            """Return an arrow indicating direction relative to traversal."""
-            direction = rel.direction
-            if isinstance(direction, str):
-                try:
-                    direction = RelationshipDirection(direction)
-                except ValueError:
-                    direction = RelationshipDirection.OUTBOUND
-
-            symbol_map = {
-                RelationshipDirection.OUTBOUND: "→",
-                RelationshipDirection.INBOUND: "←",
-                RelationshipDirection.BIDIRECTIONAL: "↔",
-            }
-            symbol = symbol_map.get(direction, "→")
-            if reversed_edge and direction != RelationshipDirection.BIDIRECTIONAL:
-                symbol = "←" if direction == RelationshipDirection.OUTBOUND else "→"
-            return symbol
-
-        def build_tree(parent_tree: Tree, obs: Observable, visited: set[str], rel_info: str = "") -> None:
-            if obs.key in visited:
-                return
-            visited.add(obs.key)
-
-            # Format observable info
-            color_level = get_color_level(obs.level)
-            color_score = get_color_score(obs.score)
-
-            generated_by = ""
-            if obs._generated_by_checks:
-                checks_str = "][cyan], [/cyan][cyan]".join(obs._generated_by_checks)
-                generated_by = f"[cyan][[/cyan]{checks_str}[cyan]][/cyan] "
-
-            whitelisted_str = " [green]WHITELISTED[/green]" if obs.whitelisted else ""
-
-            obs_info = (
-                f"{rel_info}{generated_by}[bold]{obs.key}[/bold] "
-                f"[{color_score}]{obs.score}[/{color_score}] "
-                f"[{color_level}]{obs.level.name}[/{color_level}]"
-                f"{whitelisted_str}"
-            )
-
-            child_tree = parent_tree.add(obs_info)
-
-            # Add outbound children
-            for rel in obs.relationships:
-                child_obs = all_observables.get(rel.target_key)
-                if child_obs:
-                    direction_symbol = get_direction_symbol(rel, reversed_edge=False)
-                    rel_label = f"[dim]{rel.relationship_type_name}[/dim] {direction_symbol} "
-                    build_tree(child_tree, child_obs, visited, rel_label)
-
-            # Add inbound children (observables pointing to this one)
-            for source_obs, rel in reverse_relationships.get(obs.key, []):
-                if source_obs.key == obs.key:
-                    continue
-                direction_symbol = get_direction_symbol(rel, reversed_edge=True)
-                rel_label = f"[dim]{rel.relationship_type_name}[/dim] {direction_symbol} "
-                build_tree(child_tree, source_obs, visited, rel_label)
-
         # Start from root
         root = cv.observable_get_root()
         if root:
-            build_tree(tree, root, set())
+            _build_observable_tree(
+                tree,
+                root,
+                all_observables=all_observables,
+                reverse_relationships=reverse_relationships,
+                visited=set(),
+            )
 
         rich_print(tree)
 
+    if show_score_history:
+        all_observables = cv.get_all_observables()
+        all_checks = cv.get_all_checks()
+        if all_observables or all_checks:
+            started_at = getattr(getattr(cv, "_investigation", None), "_started_at", None)
+            _render_score_history_table(
+                rich_print=rich_print,
+                title="Score History",
+                groups=[
+                    ("Observable", [obs for _key, obs in sorted(all_observables.items())]),
+                    ("Check", [check for _key, check in sorted(all_checks.items())]),
+                ],
+                started_at=started_at,
+            )
+
 
 def display_statistics(cv: Cyvest, rich_print: Callable[[Any], None]) -> None:
     """