cyvest 0.1.0__py3-none-any.whl → 5.1.3__py3-none-any.whl

cyvest/visitors.py

@@ -1,332 +0,0 @@
-from __future__ import annotations
-
-import copy
-from abc import ABC, abstractmethod
-from typing import Any
-
-from logurich import logger
-
-from .check_tree import CheckTree
-from .models import (
-    Container,
-    Enrichment,
-    Level,
-    Model,
-    Observable,
-    ObsType,
-    ResultCheck,
-    Scope,
-    ThreatIntel,
-    get_level_from_score,
-)
-from .observable_registry import ObservableRegistry
-from .report_render import markdown_summary, stdout_from_json
-from .report_serialization import reduce_report_json, report_to_json
-
-
-class Visitor(ABC):
-    def __init__(self, *, graph: bool = False) -> None:
-        super().__init__()
-        self.graph = graph
-        self._stats = {}
-
-    @property
-    def stats(self):
-        return copy.deepcopy(self._stats)
-
-    def init_stat(self, key: str, value: int = 0) -> None:
-        self._stats[key] = value
-
-    def increment_stat(self, key: str, value: int = 1) -> None:
-        self._stats[key] += value
-
-    def decrement_stat(self, key: str, value: int = 1) -> None:
-        self._stats[key] -= value
-
-    def reduce_stats(self, stats: dict) -> dict:
-        for k, v in self._stats.items():
-            if not isinstance(v, int):
-                raise Exception("Reduce Stats can reduce only integers")
-            if stats.get(k):
-                stats[k] += v
-            else:
-                stats[k] = v
-        return stats
-
-    @abstractmethod
-    def visit_threat_intel(self, threat_intel: ThreatIntel) -> ThreatIntel:
-        """Method that returns models"""
-        raise NotImplementedError("missing method check")
-
-    @abstractmethod
-    def visit_observable(self, observable: Observable) -> Observable:
-        """Method that visit an observable"""
-        raise NotImplementedError("missing method visit_observable")
-
-    @abstractmethod
-    def visit_result_check(self, result_check: ResultCheck) -> ResultCheck:
-        """Method that visit a result entry"""
-        raise NotImplementedError("missing method visit_result_check")
-
-    @abstractmethod
-    def visit_container(self, container: Container) -> Container:
-        """Method that visit a result entry"""
-        raise NotImplementedError("missing method visit_container")
-
-    @abstractmethod
-    def visit_enrichment(self, enrichment: Enrichment) -> Enrichment:
-        """Method that visit an enrichment"""
-        raise NotImplementedError("missing method visit_enrichment")
-
-    @abstractmethod
-    def to_json(self):
-        """Method that convert the object to json"""
-        raise NotImplementedError("missing method to_json")
-
-    @abstractmethod
-    def get_check(self, path: str):
-        """Method that convert the object to json"""
-        raise NotImplementedError("missing method get_check")
-
-
-class Report(Visitor):
-    map_stats_suspicious = {
-        ObsType.IP.name: "ips",
-        ObsType.URL.name: "urls",
-        ObsType.DOMAIN.name: "domains",
-        ObsType.FILE.name: "files",
-        Scope.FULL.name: "full",
-        Scope.HEADER.name: "header",
-        Scope.BODY.name: "body",
-        Scope.ATTACHMENT.name: "attachment",
-        "threat_intel": "threat_intels",
-    }
-
-    def __init__(
-        self,
-        json_structure: dict[str, Any] | None = None,
-        linked_reports: dict[str, Report] | None = None,
-        *,
-        graph: bool = False,
-    ) -> None:
-        if linked_reports is None:
-            linked_reports = {}
-        super().__init__(graph=graph)
-        payload = copy.deepcopy(json_structure) if json_structure is not None else self.default_payload()
-        self.json = payload
-        self.linked_reports = linked_reports
-        self._seen_stats = {}
-        self.tree = CheckTree()
-        self.observable_registry = ObservableRegistry()
-        self.observables = self.observable_registry._observables
-        self.enrichments = []
-        self.global_score = 0.0
-        self.global_level = get_level_from_score(self.global_score) or Level.INFO
-        self.annotations: list[dict[str, str]] = []
-        # init statistics
-        for type_data, key in Report.map_stats_suspicious.items():
-            self.init_stat(key)
-            for level in Level:
-                stat_name = self._get_stat(type_data, level)
-                if stat_name is not None:
-                    self.init_stat(stat_name)
-
-    @staticmethod
-    def default_payload() -> dict[str, Any]:
-        return {"checks": {}, "stats": {}, "data": {"header": {}}, "graph": []}
-
-    def __getitem__(self, key):
-        return self.json[key]
-
-    def _get_stat(self, type_data: str, level: Level) -> str:
-        stat_name = Report.map_stats_suspicious.get(type_data)
-        if stat_name is None:
-            return None
-        suffix = ""
-        if level <= Level.NONE:
-            return None
-        if level >= Level.SUSPICIOUS:
-            suffix = f"_{level.name}"
-        return f"{stat_name}{suffix}".lower()
-
-    def get_dot_path(self, obj, path):
-        s_path = path.split(".")
-        struct = obj
-        for p in s_path[:-1]:
-            struct.setdefault(p, {})
-        return struct
-
-    def get(self, path: str, default: Any = None) -> Any:
-        return self.json.get(path, default)
-
-    def get_check(self, path: str) -> Any:
-        node = self.tree.get(path)
-        if isinstance(node, ResultCheck):
-            return node
-        return None
-
-    def get_observable_per_type(self, type: ObsType) -> list[Observable]:
-        return [obs for obs in self.observable_registry.values() if obs.obs_type == type]
-
-    def increment_stat(self, full_key: str, type_data: str, level: Level, model: Model) -> bool:
-        stat_name = self._get_stat(type_data, level)
-        default_stat_name = self._get_stat(type_data, Level.INFO)
-        if stat_name is None:
-            return False
-        if self._seen_stats.get(full_key):
-            # Update
-            old_level = self._seen_stats.get(full_key)
-            old_stat_name = self._get_stat(type_data, old_level)
-            if stat_name and old_stat_name != stat_name and level > old_level:
-                self._seen_stats[full_key] = level
-                logger.debug(
-                    "{}: update stat {} -> {} - default: {} (gen by: {})",
-                    full_key,
-                    old_stat_name,
-                    stat_name,
-                    default_stat_name,
-                    model.generated_by,
-                )
-                if old_stat_name != default_stat_name:
-                    super().decrement_stat(old_stat_name)
-                if stat_name != default_stat_name:
-                    super().increment_stat(stat_name)
-        else:
-            # New
-            logger.debug(
-                "{}: add stat {} - default: {} (gen by: {})", full_key, stat_name, default_stat_name, model.generated_by
-            )
-            if stat_name:
-                super().increment_stat(stat_name)
-            if stat_name != default_stat_name:
-                super().increment_stat(default_stat_name)
-            self._seen_stats[full_key] = level
-        return True
-
-    def get_linked_reports(self, sha256_file: str) -> Report:
-        return self.linked_reports.get(sha256_file)
-
-    def is_whitelisted(self, type: ObsType, value: str) -> bool:
-        full_key = f"{type.name}.{value}"
-        observable = self.observable_registry.get(full_key)
-        return bool(observable and observable.whitelisted)
-
-    def add_annotation(self, name: str, message: str) -> list[dict[str, str]]:
-        annotation = {"name": name, "message": message}
-        self.annotations.append(annotation)
-        return self.annotations
-
-    def has_annotations(self) -> bool:
-        return bool(self.annotations)
-
-    def visit_threat_intel(self, threat_intel: ThreatIntel) -> ThreatIntel:
-        full_key = threat_intel.full_key
-        # Statistic
-        self.increment_stat(full_key, "threat_intel", threat_intel.level, threat_intel)
-        return threat_intel
-
-    def visit_result_check(self, result_check: ResultCheck) -> ResultCheck:
-        full_key = result_check.full_key
-        self.increment_stat(full_key, result_check.scope.name, result_check.level, result_check)
-        rc = self.tree.integrate_result_check(result_check)
-        logger.debug("Integrated ResultCheck [{}] -> score {}", full_key, rc.score)
-        self.global_score = round(self.tree.total_score(), 2)
-        self.global_level = self.tree.highest_level()
-        return rc
-
-    def visit_container(self, container: Container) -> Container:
-        integrated = self.tree.integrate_container(container)
-        self.global_score = round(self.tree.total_score(), 2)
-        self.global_level = self.tree.highest_level()
-        return integrated
-
-    def visit_observable(self, observable: Observable) -> Observable:
-        full_key = f"{observable.obs_type.name}.{observable.obs_value}"
-        self.increment_stat(full_key, observable.obs_type.name, observable.level, observable)
-        ref = self.observable_registry.upsert(observable)
-        if self.is_whitelisted(ref.obs_type, ref.obs_value):
-            ref.whitelisted = True
-        return ref
-
-    def visit_enrichment(self, enrichment: Enrichment) -> Enrichment:
-        enrichment.ref_struct[enrichment.key] = enrichment.data
-        self.enrichments.append(enrichment)
-        return enrichment
-
-    def to_json(self) -> dict[str, Any]:
-        return report_to_json(self)
-
-    def to_stdout_from_json(self, json_data: dict[str, Any]) -> None:
-        stdout_from_json(self, json_data)
-
-    def reduce_json_report(self, json_report: dict[str, Any]) -> dict[str, Any]:
-        return reduce_report_json(json_report)
-
-    def to_markdown_summary(self, json_data: dict[str, Any], exclude_checks: list[str] | None = None) -> str:
-        return markdown_summary(json_data, exclude_checks=exclude_checks)
-
-
-class Action(Visitor):
-    """Minimal visitor that records remediation ideas.
-
-    Projects are encouraged to subclass this visitor and override the
-    ``visit_*`` methods to trigger concrete actions (ticketing, EDR tasks,
-    notifications, ...). The default implementation keeps things simple by
-    logging observables or threat intelligence above a configurable level.
-    """
-
-    def __init__(self, *, level_threshold: Level = Level.SUSPICIOUS, graph: bool = False) -> None:
-        super().__init__(graph=graph)
-        self.level_threshold = level_threshold
-        self.actions: list[dict[str, Any]] = []
-
-    def record_action(
-        self,
-        *,
-        name: str,
-        description: str,
-        impact: str | None = None,
-        context: dict[str, Any] | None = None,
-    ) -> dict[str, Any]:
-        action = {
-            "name": name,
-            "description": description,
-            "impact": impact,
-            "context": context or {},
-        }
-        logger.info("[ACTION] {} -> {}", name, description)
-        self.actions.append(action)
-        return action
-
-    def visit_threat_intel(self, threat_intel: ThreatIntel) -> ThreatIntel:
-        if threat_intel.level >= self.level_threshold:
-            desc = f"{threat_intel.obs_type.name} {threat_intel.obs_value} flagged as {threat_intel.level.name}"
-            self.record_action(
-                name=f"threat_intel::{threat_intel.name}",
-                description=desc,
-                impact=threat_intel.level.name,
-                context={
-                    "score": threat_intel.score,
-                    "details": threat_intel.details,
-                    "extra": threat_intel.extra,
-                },
-            )
-        return threat_intel
-
-    def visit_observable(self, observable: Observable) -> Observable:
-        return observable
-
-    def visit_result_check(self, result_check: ResultCheck) -> ResultCheck:
-        return result_check
-
-    def visit_container(self, container: Container) -> Container:
-        return container
-
-    def visit_enrichment(self, enrichment: Enrichment) -> Enrichment:
-        return enrichment
-
-    def to_json(self) -> list[dict[str, Any]]:
-        return copy.deepcopy(self.actions)
-
-    def get_check(self, path: str) -> Any:
-        return None

cyvest-0.1.0.dist-info/METADATA

@@ -1,110 +0,0 @@
-Metadata-Version: 2.4
-Name: cyvest
-Version: 0.1.0
-Summary: Cybersecurity investigation model
-Author-email: PakitoSec <jeromep83@gmail.com>
-License-Expression: MIT
-Project-URL: Homepage, https://github.com/PakitoSec/cyvest
-Project-URL: Repository, https://github.com/PakitoSec/cyvest
-Project-URL: Issues, https://github.com/PakitoSec/cyvest/issues
-Keywords: cybersecurity,incident-response,observability,threat-intelligence,reporting,graph
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Intended Audience :: Information Technology
-Classifier: Topic :: Security
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: logurich>=0.1
-Requires-Dist: rich>=13
-Dynamic: license-file
-
-# Cyvest – Cyber Investigation Model
-
-Reusable investigation domain models, visitor helpers, and reporting utilities for incident responders. Cyvest provides
-a consistent data model for threat intelligence, observables, and result checks while keeping the visitor layer
-extensible for bespoke workflows.
-
-## Features
-
-- Composition-friendly report builder that nests containers and checks.
-- Observable graph with automatic score/level propagation across relationships.
-- Visitor implementations for generating JSON/markdown reports or capturing follow-up actions.
-- Tested patterns for merging external intel feeds (VirusTotal, sandbox runs, allow-lists).
-
-## Installation
-
-Cyvest targets Python 3.10+ and is published on PyPI:
-
-```bash
-uv pip install cyvest
-```
-
-## Quick start
-
-Create a new report with nested containers and observables:
-
-```python
-from cyvest import Level, ObsType, ReportBuilder, Scope
-
-builder = ReportBuilder(graph=True)
-
-with builder.container("body", scope=Scope.BODY) as body:
-    check = body.add_check("url_scan", description="Detected suspicious URL")
-    check.add_observable_chain(
-        [
-            {
-                "obs_type": ObsType.URL,
-                "value": "http://example.test",
-                "intel": {"name": "sandbox", "score": 4, "level": Level.SUSPICIOUS},
-            }
-        ]
-    )
-
-report = builder.build()
-print(report.to_json())
-```
-
-Run the bundled example:
-
-```bash
-uv sync
-uv run python examples/basic_report.py
-```
-
-## Development workflow
-
-Set up dependencies with uv:
-
-```bash
-uv sync
-```
-
-Execute the unit suite:
-
-```bash
-uv run pytest tests
-```
-
-Lint and format using Ruff:
-
-```bash
-uv run ruff check
-uv run ruff format --check
-```
-
-## Graph & model axioms
-
-1. Cyclic graphs on observables or containables are not supported.
-2. Every root containable model must be visited. (Observables may be skipped because parent links are tracked.)
-3. Child observables do not update result checks linked only to their parents.
-4. A `ResultCheck` score cannot be changed by an observable that is mutated elsewhere.
-5. Adding an observable to a `ResultCheck` promotes the check to at least `Level.INFO` (a `Level.NONE` check becomes INFO).
-
-See `examples/` and the tests under `tests/` for more scenarios, including how to subclass the provided visitors to
-integrate your own tooling.

cyvest-0.1.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-cyvest/__init__.py,sha256=DGa89MSj15F2VmdrC4g8UadNA4A3y95QI46RmGWWmkA,818
-cyvest/builder.py,sha256=j9B-xs5eYDX213RqYxWPzBTNOVE8vMgf1XtXDHaqf4w,5811
-cyvest/check_tree.py,sha256=SzAnnC0OuEOITWS-ptb1sXb9SKGwkvQgeGGApQ5ovF4,4539
-cyvest/models.py,sha256=Dl27Xj0MNKKAqYtS5-_M0s0Rp0EQ_dtIGt41ILNAMuE,26911
-cyvest/observable_registry.py,sha256=1LPTjhw9y_N9TdTX77cnvPJEwKGB-J_roGbl7YdC3K8,2623
-cyvest/report_render.py,sha256=VWWfIvDVn_9pEYy9gGUBcHP1EhAoWvv--WVmmpCNogc,12000
-cyvest/report_serialization.py,sha256=mrDHiW_0gM4JSnYzP3pxNo1HdHVSrYtwYX5EqguX5l8,9069
-cyvest/visitors.py,sha256=LJ1szpNrg0noZxkigvS4ZcVzQPDKM8kBbt2hd02k95E,12115
-cyvest-0.1.0.dist-info/licenses/LICENSE,sha256=EikdGl2Ew1IWY48h_1Ppwfh0QoIxXHQadQDovHSZZdE,1066
-cyvest-0.1.0.dist-info/METADATA,sha256=SuprQJa9USk9YGPrco2NGOFGAJ_6Qp7SyW9IPauCY_w,3367
-cyvest-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-cyvest-0.1.0.dist-info/top_level.txt,sha256=IC_VayuEXgD7GqVsyh1h4g8P5WgXJ2ZrbNvdKhnh_Hw,7
-cyvest-0.1.0.dist-info/RECORD,,

cyvest-0.1.0.dist-info/licenses/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 PakitoSec
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

cyvest-0.1.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-cyvest