feat: add signal override evidence generation and update related components

Author: SagarBiswas-MultiHAT

README.md

@@ -7,6 +7,11 @@
 **This tool is for lawful, ethical OSINT research only.**
 Do not use it to harass, stalk, dox, or violate privacy. Always comply with applicable laws and third-party Terms of Service.
 
+
+!()[https://imgur.com/XCNwZsf.png]
+!()[https://imgur.com/uHusxTO.png]
+
+
 ## Table of Contents
 
 - What This Tool Does
@@ -163,6 +168,8 @@ Example:
 }
 ```
 
+When an override fires, a synthetic evidence item with `source: signal_override` is appended to the report so the Evidence list (CLI/GUI/CSV) records why the signal changed even if no adapter returned data.
+
 You can also set a custom path via `PHONEINT_SIGNAL_OVERRIDES_PATH`.
 
 ## Configuration

phoneint/cli.py

@@ -31,7 +31,11 @@
 from phoneint.reputation.google import GoogleCustomSearchAdapter
 from phoneint.reputation.public import PublicScamListAdapter
 from phoneint.reputation.score import infer_domain_signals, score_risk
-from phoneint.reputation.signals import apply_signal_overrides, load_signal_overrides
+from phoneint.reputation.signals import (
+    apply_signal_overrides,
+    generate_signal_override_evidence,
+    load_signal_overrides,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -134,6 +138,9 @@ async def lookup_async(
         domain_signals=domain_signals,
         overrides=signal_overrides,
     )
+    override_evidence = generate_signal_override_evidence(normalized.e164, override_hits)
+    if override_evidence:
+        evidence.extend(override_evidence)
 
     score = score_risk(
         found_in_scam_db=found_in_scam_db,

phoneint/gui.py

@@ -29,7 +29,11 @@
 from phoneint.reputation.google import GoogleCustomSearchAdapter
 from phoneint.reputation.public import PublicScamListAdapter
 from phoneint.reputation.score import infer_domain_signals, score_risk
-from phoneint.reputation.signals import apply_signal_overrides, load_signal_overrides
+from phoneint.reputation.signals import (
+    apply_signal_overrides,
+    generate_signal_override_evidence,
+    load_signal_overrides,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -450,6 +454,11 @@ async def run_one(adapter: ReputationAdapter) -> tuple[str, list[SearchResult]]:
                 domain_signals=domain_signals,
                 overrides=self._signal_overrides,
             )
+            override_evidence = generate_signal_override_evidence(normalized.e164, override_hits)
+            if override_evidence:
+                evidence.extend(override_evidence)
+                for entry in override_evidence:
+                    self.evidence_list.addItem(f"[{entry.source}] {entry.title}")
             score = score_risk(
                 found_in_scam_db=found_in_scam_db,
                 voip=voip,

phoneint/reputation/signals.py

@@ -3,6 +3,8 @@
 import json
 from pathlib import Path
 
+from phoneint.reputation.adapter import SearchResult, now_utc
+
 SIGNAL_NAMES = (
     "voip",
     "found_in_classifieds",
@@ -11,6 +13,12 @@
 
 DEFAULT_SIGNAL_OVERRIDES_PATH = Path("phoneint/data/signal_overrides.json")
 
+SIGNAL_DISPLAY_NAMES = {
+    "voip": "VoIP signal",
+    "found_in_classifieds": "classifieds mention",
+    "business_listing": "business directory mention",
+}
+
 
 def _normalize_number(value: str) -> str:
     return value.strip()
@@ -65,3 +73,25 @@ def apply_signal_overrides(
             hits[name] = True
 
     return voip_signal, merged, hits
+
+
+def generate_signal_override_evidence(
+    e164: str, hits: dict[str, bool]
+) -> list[SearchResult]:
+    """Return synthetic evidence entries for any fired signal overrides."""
+
+    entries: list[SearchResult] = []
+    for name in SIGNAL_NAMES:
+        if not hits.get(name):
+            continue
+        label = SIGNAL_DISPLAY_NAMES.get(name, name)
+        entries.append(
+            SearchResult(
+                title=f"Signal override: {label}",
+                url="",
+                snippet=f"Configured override flagged the {label} for {e164}.",
+                timestamp=now_utc(),
+                source="signal_override",
+            )
+        )
+    return entries

tests/test_signals.py

@@ -3,7 +3,12 @@
 from pathlib import Path
 import json
 
-from phoneint.reputation.signals import SIGNAL_NAMES, apply_signal_overrides, load_signal_overrides
+from phoneint.reputation.signals import (
+    SIGNAL_NAMES,
+    apply_signal_overrides,
+    generate_signal_override_evidence,
+    load_signal_overrides,
+)
 
 
 def test_load_signal_overrides_missing(tmp_path: Path) -> None:
@@ -47,3 +52,16 @@ def test_apply_signal_overrides_forces_flags() -> None:
     assert hits["voip"] is True
     assert hits["found_in_classifieds"] is True
     assert hits["business_listing"] is False
+
+
+def test_generate_signal_override_evidence_entries() -> None:
+    hits = {
+        "voip": True,
+        "found_in_classifieds": False,
+        "business_listing": True,
+    }
+    entries = generate_signal_override_evidence("+14155552671", hits)
+    assert len(entries) == 2
+    assert entries[0].source == "signal_override"
+    assert "Signal override" in entries[0].title
+    assert entries[1].source == "signal_override"