cyvest 4.4.0__py3-none-any.whl → 5.1.0__py3-none-any.whl

{cyvest-4.4.0.dist-info → cyvest-5.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: cyvest
-Version: 4.4.0
+Version: 5.1.0
 Summary: Cybersecurity investigation model
 Keywords: cybersecurity,investigation,threat-intel,security-analysis
 Author: PakitoSec
@@ -47,6 +47,7 @@ Description-Content-Type: text/markdown
 - 💾 **Multiple Export Formats**: JSON and Markdown output for reporting and LLM consumption
 - 🎨 **Rich Console Output**: Beautiful terminal displays with the Rich library
 - 🧩 **Fluent helpers**: Convenient API with method chaining for rapid development
+- 🔬 **Investigation Comparison**: Compare investigations with tolerance rules and visual diff output
 
 ## Installation
 
@@ -111,14 +112,14 @@ cv.io_save_json("investigation.json")
 ### Model Proxies
 
 Cyvest only exposes immutable model proxies. Helpers like `observable_create`, `check_create`, and the
-fluent `cv.observable()`/`cv.check()` convenience methods return `ObservableProxy`, `CheckProxy`, `ContainerProxy`, etc.
+fluent `cv.observable()`/`cv.check()` convenience methods return `ObservableProxy`, `CheckProxy`, `TagProxy`, etc.
 These proxies reflect the live investigation state but raise `AttributeError` if you try to assign to their attributes.
 All mutations are routed through the Investigation layer, so use the facade helpers (`cv.observable_set_level`,
 `cv.check_update_score`, `cv.observable_add_threat_intel`) or the built-in fluent methods on the proxies themselves
 (`with_ti`, `relate_to`, `link_observable`, `with_score`, …) so the score engine and audit log stay consistent.
 
 Mutation helpers that reference existing objects (for example, `cv.observable_add_relationship`,
-`cv.check_link_observable`, `cv.container_add_check`) raise `KeyError` when a key is missing.
+`cv.check_link_observable`, `cv.tag_add_check`) raise `KeyError` when a key is missing.
 
 Safe metadata fields like `comment`, `extra`, or `internal` can be updated through the proxies without breaking score
 consistency:
@@ -208,15 +209,22 @@ ti.add_taxonomy(level=cv.LVL.SUSPICIOUS, name="confidence", value="medium")
 ti.remove_taxonomy("confidence")
 ```
 
-### Containers
+### Tags
 
-Containers organize checks hierarchically:
+Tags organize checks with automatic hierarchy based on `:` delimiter:
 
 ```python
-with cv.container("network_analysis") as network:
-    with network.sub_container("c2_detection") as c2:
-        check = cv.check("beacon_detection", "network", "Detect C2 beacons")
-        c2.add_check(check)
+# Simple: pass tag names directly (auto-creates tags)
+check = cv.check("beacon_detection", "Detect C2 beacons")
+check.tagged("network", "c2:detection", "suspicious")
+
+# With description: create tag first, then reference it
+tag = cv.tag("network:c2:detection", "C2 Detection Checks")
+check.tagged(tag)
+
+# Query hierarchy
+children = cv.tag_get_children("network")  # ["network:c2"]
+descendants = cv.tag_get_descendants("network")  # ["network:c2", "network:c2:detection"]
 ```
 
 ### Lookup Helpers
@@ -232,9 +240,9 @@ check = cv.check_create("malware_detection", "endpoint", "Verify file hash")
 same_check = cv.check_get("malware_detection", "endpoint")
 same_check_by_key = cv.check_get(check.key)
 
-container = cv.container_create("network_analysis")
-same_container = cv.container_get("network_analysis")
-same_container_by_key = cv.container_get(container.key)
+tag = cv.tag_create("network:analysis")
+same_tag = cv.tag_get("network:analysis")
+same_tag_by_key = cv.tag_get(tag.key)
 
 enrichment = cv.enrichment_create("whois", {"registrar": "Example Inc"})
 same_enrichment = cv.enrichment_get("whois")
@@ -383,6 +391,88 @@ Its key is derived from type + value (e.g. `obs:file:root` or `obs:artifact:root
 
 This design enables flexible investigation structures while preventing unintended score contamination.
 
+### Comparing Investigations
+
+Compare two investigations to identify differences in checks, observables, and threat intelligence:
+
+```python
+from decimal import Decimal
+from cyvest import Cyvest, ExpectedResult, Level, compare_investigations
+from cyvest.io_rich import display_diff
+
+# Create expected and actual investigations
+expected = Cyvest(investigation_name="expected")
+expected.check_create("domain-check", "Verify domain", score=Decimal("1.0"))
+
+actual = Cyvest(investigation_name="actual")
+actual.check_create("domain-check", "Verify domain", score=Decimal("2.0"))
+actual.check_create("new-check", "New detection", score=Decimal("1.5"))
+
+# Compare investigations
+diffs = compare_investigations(actual, expected)
+# diffs contains:
+#   - MISMATCH for domain-check (score changed 1.0 -> 2.0)
+#   - ADDED for new-check
+```
+
+**Tolerance Rules**
+
+Use `result_expected` rules to define acceptable score variations:
+
+```python
+# Define tolerance rules
+rules = [
+    # Accept any score >= 1.0 for this check
+    ExpectedResult(check_name="domain-check", score=">= 1.0"),
+    # Accept any score < 3.0 for roger-ai
+    ExpectedResult(key="chk:roger-ai", level=Level.SUSPICIOUS, score="< 3.0"),
+]
+
+# Compare with tolerance - checks satisfying rules are not flagged as diffs
+diffs = compare_investigations(actual, expected, result_expected=rules)
+```
+
+Supported operators: `>=`, `<=`, `>`, `<`, `==`, `!=`
+
+**Visual Diff Display**
+
+Display differences in a rich table format:
+
+```python
+from cyvest.io_rich import display_diff
+from logurich import logger
+
+# Display diff table with tree structure showing observables and threat intel
+display_diff(diffs, lambda r: logger.rich("INFO", r), title="Investigation Diff")
+```
+
+Output:
+```
+╭────────────────────────────────────────────────┬────────────────────┬─────────────────┬────────╮
+│ Key                                            │      Expected      │     Actual      │ Status │
+├────────────────────────────────────────────────┼────────────────────┼─────────────────┼────────┤
+│ chk:new-check                                  │         -          │  NOTABLE 1.50   │   +    │
+│ └── domain: example.com                        │         -          │   INFO 0.00     │        │
+│     └── VirusTotal                             │         -          │   INFO 0.00     │        │
+├────────────────────────────────────────────────┼────────────────────┼─────────────────┼────────┤
+│ chk:domain-check                               │   NOTABLE 1.00     │  NOTABLE 2.00   │   ✗    │
+╰────────────────────────────────────────────────┴────────────────────┴─────────────────┴────────╯
+```
+
+Status symbols: `+` (added), `-` (removed), `✗` (mismatch)
+
+**Convenience Methods**
+
+Use methods directly on Cyvest objects:
+
+```python
+# Compare and get diff items
+diffs = actual.compare(expected=expected, result_expected=rules)
+
+# Compare and display in one call
+actual.display_diff(expected=expected, title="My Investigation Diff")
+```
+
 ## Examples
 
 See the `examples/` directory for complete examples:
@@ -392,6 +482,7 @@ See the `examples/` directory for complete examples:
 - **03_merge_demo.py**: Multi-process investigation merging
 - **04_email.py**: Multi-threaded investigation with SharedInvestigationContext
 - **05_visualization.py**: Interactive HTML visualization showcasing scores, levels, and relationship flows
+- **06_compare_investigations.py**: Compare investigations with tolerance rules and visual diff output
 
 Run an example:
 
@@ -522,6 +613,7 @@ Cyvest is designed for:
 - **Malware Analysis**: Track relationships between artifacts
 - **Phishing Analysis**: Analyze emails and linked resources
 - **Integration**: Combine results from multiple security tools
+- **Regression Testing**: Compare investigation outputs across rule or detection updates
 
 ## Architecture Highlights
 
@@ -531,6 +623,7 @@ Cyvest is designed for:
 - **Score Propagation**: Automatic hierarchical score calculation
 - **Flexible Export**: JSON for storage, Markdown for LLM analysis
 - **Audit Trail**: Score change history for debugging
+- **Investigation Comparison**: Compare investigations with tolerance rules for regression testing
 
 ## Future Enhancements
 

cyvest-5.1.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+cyvest/__init__.py,sha256=cqJ-Sbwopy3acHEn1UO4C7wkqde8rE_iuD3SByy5cmU,1383
+cyvest/cli.py,sha256=K_BgHhBEt_lw7CehM3wpDb03BOA2uzPRD2XNRGld0Pc,14321
+cyvest/compare.py,sha256=CcBGP6pF1fp4tYl3mdTJke8dgzr8C4YTJDA9eOvpVKQ,10119
+cyvest/cyvest.py,sha256=vAeh7q9_HQ87vMmJmpSkAwi4zTlRR55-KhjKP7MwJok,47459
+cyvest/investigation.py,sha256=dt4jzx5TjdWCXXvKUdX0eiri10mCS87EKuPPB1dt-Bw,61447
+cyvest/io_rich.py,sha256=fLg-1-SiHbUTMk7rhic425WBdqg06191O9Tu05LEHOg,24813
+cyvest/io_schema.py,sha256=Z-vlhrbWnGJcIm8k-XVSmzv1vbSvl7I6Z2GV55iU1fc,1296
+cyvest/io_serialization.py,sha256=ZNrjY29SvJoeGZHOTajRbdKUqmsayNw1cP-5HeOTvik,17755
+cyvest/io_visualization.py,sha256=kPT8cAqZJ3liSA2BzwvQXMaejnk496m0Ck11QXJCQLc,11010
+cyvest/keys.py,sha256=xNpSZW5VDzeqc5F0-66-jHM7_v00wt2A70kvbqRSxwA,5678
+cyvest/level_score_rules.py,sha256=MoCCYCLsTDCM-OqLV4Ln_GEH7H_tjNpK4tte89IEQeU,2391
+cyvest/levels.py,sha256=1d3YHCbP2aptSGyIwVzLF4rJjAYdpSzmOnzjs7ZLsdg,4556
+cyvest/model.py,sha256=Em3D5kXS5HCUrehjEEOPWXbX1-UVaEf4ebOs5Z1DBAw,18600
+cyvest/model_enums.py,sha256=t7uFDnGcLXLMZdwgHMxk3HU5KHQgqUvBNZ5i_H2_Jvc,2050
+cyvest/model_schema.py,sha256=Xrd10_dRPcXyiotAF6LJHi7iioGqPBvQlCE87vUVvaM,6037
+cyvest/proxies.py,sha256=74FQvC3gDRpCjv7_-G6x90eJnQmcSVom_3jwS_3EGTY,19525
+cyvest/score.py,sha256=CiD-dcjEVr2oLHPJ4MlcQWv5338Tq-Zn4Q7lXIEq9fY,19807
+cyvest/shared.py,sha256=PidiXY3bfB1ph5B0Ah_etyZKkiUa5S7FoNk5eRjnOLw,19375
+cyvest/stats.py,sha256=X2e9BHqJrfaOHNUt6jShQqy2Pdw4DMdGheRD9WGPmS0,9035
+cyvest/ulid.py,sha256=NA3k6hlgMZyfzLEMJEIMqt73CY2V07Bupqk7gemshDM,1069
+cyvest-5.1.0.dist-info/WHEEL,sha256=eycQt0QpYmJMLKpE3X9iDk8R04v2ZF0x82ogq-zP6bQ,79
+cyvest-5.1.0.dist-info/entry_points.txt,sha256=bwtGzs4Eh9i3WEhW4dhxHaYP8qf8qUN4sDnt4xXywUk,44
+cyvest-5.1.0.dist-info/METADATA,sha256=efWG28fBJ9CRGtXOyLF2l34Q9-wF0Z-juNhW9OgNwUw,23156
+cyvest-5.1.0.dist-info/RECORD,,

{cyvest-4.4.0.dist-info → cyvest-5.1.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.21
+Generator: uv 0.9.24
 Root-Is-Purelib: true
 Tag: py3-none-any

cyvest-4.4.0.dist-info/RECORD

@@ -1,23 +0,0 @@
-cyvest/__init__.py,sha256=ISyIqEKzFg5WvCKWyAa1k6B3-bSdC8mxhWXkIhuiIYA,1046
-cyvest/cli.py,sha256=Zj8RVCG4BXFTNQt0Oo2GgwviF1aY5by_69eZE2XOgkg,12271
-cyvest/cyvest.py,sha256=82DSGeog6YjEyZagkD5E2e5Vmxk7hSERfhOA_5YCF0I,45041
-cyvest/investigation.py,sha256=LKiP3p74m5UnC1QnCZ5WEX6xtxIyrzI-chdd9nE8YLE,61074
-cyvest/io_rich.py,sha256=46mPidDNzqo1hgcWxVrEFRNMdto_nEe8vaaxaOwGqFk,21932
-cyvest/io_schema.py,sha256=vhreQyKQbVrXFVj1ddIoAuEXc6zGhTVndHZZdDxTd0c,1302
-cyvest/io_serialization.py,sha256=V0KAxGZu11t7LA413L7QlJyh5o2lwytQCLllDflH6I4,18478
-cyvest/io_visualization.py,sha256=kPT8cAqZJ3liSA2BzwvQXMaejnk496m0Ck11QXJCQLc,11010
-cyvest/keys.py,sha256=9S7ELhloRzKrLPlpfRnwYtL7WXbKIsyhteh62mn3j2E,4614
-cyvest/level_score_rules.py,sha256=MoCCYCLsTDCM-OqLV4Ln_GEH7H_tjNpK4tte89IEQeU,2391
-cyvest/levels.py,sha256=1d3YHCbP2aptSGyIwVzLF4rJjAYdpSzmOnzjs7ZLsdg,4556
-cyvest/model.py,sha256=Bi1IRXM2Ca47t5KpJ1vtSnPyeJhHZ1ZnezE4-JkSwv0,18184
-cyvest/model_enums.py,sha256=t7uFDnGcLXLMZdwgHMxk3HU5KHQgqUvBNZ5i_H2_Jvc,2050
-cyvest/model_schema.py,sha256=LVJ99i-_T6cSJ3N7OJO2F0k1LjpA23S-PKSk6RYzwks,6119
-cyvest/proxies.py,sha256=s_vc4KPWvta7saNNR92WHgzn73V-BdOYhZoRJ_0evHw,19581
-cyvest/score.py,sha256=CiD-dcjEVr2oLHPJ4MlcQWv5338Tq-Zn4Q7lXIEq9fY,19807
-cyvest/shared.py,sha256=217ufZ-sBAMr0CMflBEpfeTSXs2eRlgNIul1fm0l_Qw,19505
-cyvest/stats.py,sha256=mBHgLaRPs1R9l775_K3zQKN6ujup5sGzD5o5CQCPSK8,9926
-cyvest/ulid.py,sha256=NA3k6hlgMZyfzLEMJEIMqt73CY2V07Bupqk7gemshDM,1069
-cyvest-4.4.0.dist-info/WHEEL,sha256=RRVLqVugUmFOqBedBFAmA4bsgFcROUBiSUKlERi0Hcg,79
-cyvest-4.4.0.dist-info/entry_points.txt,sha256=bwtGzs4Eh9i3WEhW4dhxHaYP8qf8qUN4sDnt4xXywUk,44
-cyvest-4.4.0.dist-info/METADATA,sha256=8PLZvgm-LAEV_fxfDLupzWHcPa-_mqqCT2rcG0gzDps,18718
-cyvest-4.4.0.dist-info/RECORD,,