voidaccess 1.7.2__tar.gz → 1.8.1__tar.gz

voidaccess-1.8.1/PKG-INFO

@@ -0,0 +1,228 @@
+Metadata-Version: 2.4
+Name: voidaccess
+Version: 1.8.1
+Summary: Dark web OSINT CLI — automated threat intelligence from query to report
+Author: VoidAccess
+License-Expression: MIT
+Keywords: osint,darkweb,threat-intelligence,tor,cli
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer==0.24.1
+Requires-Dist: rich==15.0.0
+Requires-Dist: textual==8.2.7
+Requires-Dist: click==8.3.2
+Requires-Dist: fastapi==0.136.0
+Requires-Dist: aiohttp==3.13.5
+Requires-Dist: aiohttp-socks==0.11.0
+Requires-Dist: alembic==1.18.4
+Requires-Dist: apscheduler==3.11.2
+Requires-Dist: pillow==12.2.0
+Requires-Dist: sqlalchemy[asyncio]==2.0.49
+Requires-Dist: aiosqlite==0.22.1
+Requires-Dist: filelock==3.29.0
+Requires-Dist: numpy==2.2.6
+Requires-Dist: langchain==0.3.25
+Requires-Dist: langchain-openai==0.3.19
+Requires-Dist: langchain-anthropic==0.3.22
+Requires-Dist: langchain-google-genai==2.1.12
+Requires-Dist: langchain-groq==0.3.8
+Requires-Dist: langchain-ollama==0.3.10
+Requires-Dist: python-dotenv==1.2.2
+Requires-Dist: httpx==0.28.1
+Requires-Dist: spacy==3.8.14
+Requires-Dist: beautifulsoup4==4.14.3
+Requires-Dist: feedparser==6.0.11
+Requires-Dist: networkx==3.4.2
+Requires-Dist: pydantic==2.13.3
+Requires-Dist: python-jose[cryptography]==3.5.0
+Requires-Dist: passlib[bcrypt]==1.7.4
+Requires-Dist: slowapi==0.1.9
+Requires-Dist: redis==7.4.0
+Requires-Dist: pyyaml==6.0.3
+Requires-Dist: openai==1.109.1
+Requires-Dist: cryptography==46.0.7
+Requires-Dist: python-dateutil==2.9.0.post0
+Requires-Dist: langdetect==1.0.9
+Requires-Dist: pyvis==0.3.2
+Requires-Dist: urllib3==2.6.3
+Requires-Dist: trafilatura==2.0.0
+Requires-Dist: requests==2.33.1
+Requires-Dist: python-socks[asyncio]==2.8.1
+Requires-Dist: tldextract==5.3.1
+Requires-Dist: stix2==3.0.2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Provides-Extra: nlp
+Requires-Dist: sentence-transformers>=3.0; extra == "nlp"
+Requires-Dist: torch>=2.3; extra == "nlp"
+Requires-Dist: transformers>=4.42; extra == "nlp"
+Provides-Extra: vector
+Requires-Dist: chromadb>=0.5; extra == "vector"
+Requires-Dist: sentence-transformers>=3.0; extra == "vector"
+Requires-Dist: torch>=2.3; extra == "vector"
+Provides-Extra: telegram
+Requires-Dist: telethon>=1.36; extra == "telegram"
+Provides-Extra: js
+Requires-Dist: playwright>=1.45; extra == "js"
+Provides-Extra: all
+Requires-Dist: chromadb>=0.5; extra == "all"
+Requires-Dist: playwright>=1.45; extra == "all"
+Requires-Dist: sentence-transformers>=3.0; extra == "all"
+Requires-Dist: telethon>=1.36; extra == "all"
+Requires-Dist: torch>=2.3; extra == "all"
+Requires-Dist: transformers>=4.42; extra == "all"
+Dynamic: license-file
+
+<p align="center">
+  <img src="public/logo_circle.png" width="160" alt="VoidAccess logo">
+</p>
+
+<h1 align="center">VoidAccess</h1>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
+  <a href="docker-compose.yml"><img src="https://img.shields.io/badge/Docker-Compose-blue.svg" alt="Docker Compose"></a>
+  <a href="https://pypi.org/project/voidaccess/"><img src="https://img.shields.io/pypi/v/voidaccess?logo=pypi&logoColor=white" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/voidaccess/"><img src="https://img.shields.io/pypi/dm/voidaccess" alt="PyPI downloads"></a>
+</p>
+
+Self-hostable OSINT for turning dark-web research queries into structured threat intelligence. Built for security researchers, threat-intelligence teams, and authorized investigators who need collection, enrichment, relationship mapping, and export in one workflow.
+
+## Terminal Output
+
+![VoidAccess](public/terminal-hero.png)
+
+## Quick Start
+
+```bash
+pip install voidaccess
+voidaccess investigate "LockBit ransomware" --no-llm --no-tor --depth shallow
+voidaccess list
+voidaccess actors
+voidaccess status
+```
+
+![VoidAccess investigation demo](public/cli_investigation_gif.gif)
+
+## What It Does
+
+- **Parallel collection** - searches Tor indexes, paste sites, code forges, security feeds, and curated `.onion` seeds.
+- **Entity extraction** - finds IOCs, wallets, credentials, handles, vulnerabilities, actors, malware, people, and organizations.
+- **Multi-source enrichment** - adds reputation, breach, passive DNS, sandbox, blockchain, and threat-feed context.
+- **Actor intelligence** - persists aliases, infrastructure, notes, timelines, and cross-investigation relationships.
+- **Relationship graphs** - builds co-occurrence graphs, communities, paths, and infrastructure clusters.
+- **Content safety** - filters prohibited queries, URLs, content, and extracted entities at mandatory pipeline gates.
+- **Structured exports** - produces STIX 2.1, MISP, Sigma, YARA, Snort, Suricata, CSV, Markdown, JSON, and IOC packages.
+- **CLI and web UI** - runs locally with SQLite or as a Docker Compose stack with PostgreSQL and a browser interface.
+
+## Pipeline
+
+| Stage | Action |
+|---|---|
+| 1 | Refine the investigation query with the selected LLM |
+| 2 | Collect from Tor search, paste sites, code forges, RSS feeds, and curated seeds in parallel |
+| 3 | Filter noisy or irrelevant pages |
+| 4 | Enrich the query and early indicators from threat-intelligence sources |
+| 5 | Discover additional `.onion` links recursively |
+| 6 | Reuse recently processed pages from the vector cache |
+| 7 | Fetch selected pages through Tor with response-size limits |
+| 8 | Persist newly collected content |
+| 9 | Merge collected and enriched intelligence |
+| 10 | Extract entities with regex, NER, and optional LLM analysis |
+| 11 | Cross-reference entities against historical and seed datasets |
+| 12 | Build relationships, communities, and infrastructure clusters |
+| 13 | Generate the final intelligence summary and export-ready result |
+
+Full pipeline behavior, timeouts, recovery, and data flow are documented in [Architecture](docs/architecture.md).
+
+## Entity Types
+
+| Category | Examples |
+|---|---|
+| Cryptocurrency | Bitcoin, Ethereum, Monero, Litecoin, Zcash, Solana, Tron, ENS |
+| Network indicators | IPv4, IPv6, domains, URLs, `.onion` addresses, MAC addresses, PGP keys |
+| File indicators | MD5, SHA-1, SHA-256, malware families |
+| Credentials | Cloud keys, tokens, JWTs, API keys, stealer logs, combo-list entries |
+| Messaging | Telegram, Discord, XMPP, Tox, Session, Matrix, Wire, ICQ, Wickr |
+| Vulnerabilities | CVEs, MITRE ATT&CK techniques and tactics, Exploit-DB IDs |
+| Detection content | YARA rules, Nuclei templates, Snort and Suricata indicators |
+| Threat intelligence | Actor handles, ransomware groups, paste links, people, organizations, locations |
+
+## Collection and Enrichment
+
+| Layer | Sources |
+|---|---|
+| Dark-web search | 16+ Tor search engines and curated `.onion` seeds |
+| Open-web collection | Pastebin, dpaste, paste.ee, Rentry, GitHub, GitLab, and curated RSS feeds |
+| Threat feeds | AlienVault OTX, abuse.ch, MalwareBazaar, ThreatFox, URLhaus, ransomware.live, CISA KEV |
+| IP and domain context | Shodan InternetDB, GreyNoise, AbuseIPDB, Feodo Tracker, C2IntelFeeds, crt.sh, URLScan.io, Wayback Machine, CIRCL PDNS, RDAP |
+| File and identity context | VirusTotal, Hybrid Analysis, Have I Been Pwned, EmailRep |
+| Blockchain | BlockCypher and Etherscan |
+
+Sources that need API keys skip cleanly when their keys are absent. The complete key and configuration reference is in [Architecture](docs/architecture.md#13-configuration-reference).
+
+## LLM Providers
+
+| Provider | Typical models | Notes |
+|---|---|---|
+| OpenRouter | DeepSeek, Llama, Claude | Default route; free models are available |
+| Groq | Llama | Fast hosted inference with a free tier |
+| OpenAI | GPT models | API key required |
+| Anthropic | Claude | Claude Haiku is the tested default |
+| Google Gemini | Gemini Flash and Pro | Google AI Studio key required |
+| Ollama | Any installed local model | Local and suitable for air-gapped deployments |
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `voidaccess investigate "QUERY"` | Run an investigation |
+| `voidaccess show` | Open the interactive entity browser |
+| `voidaccess export INVESTIGATION_ID --format FORMAT` | Export as STIX, MISP, Sigma, YARA, Snort, Suricata, package, CSV, Markdown, or JSON |
+| `voidaccess package INVESTIGATION_ID` | Build an IOC package ZIP |
+| `voidaccess enrich INVESTIGATION_ID` | Re-enrich a saved investigation |
+| `voidaccess list` | List saved investigations |
+| `voidaccess status` | Show configuration, Tor, cache, engine, and seed status |
+| `voidaccess actors` | List persistent actor profiles |
+| `voidaccess actor HANDLE` | Show an actor profile |
+| `voidaccess actor HANDLE --timeline` | Show an actor activity timeline |
+| `voidaccess actor HANDLE --note "TEXT"` | Add an analyst note to an actor profile |
+| `voidaccess timeline HANDLE` | Open an actor timeline directly |
+| `voidaccess configure` | Run the setup wizard |
+| `voidaccess configure llm` | Configure the LLM provider, model, and key |
+| `voidaccess configure keys` | Configure enrichment API keys |
+| `voidaccess configure tor` | Override the Tor proxy host and port |
+| `voidaccess version` | Print the installed version |
+
+Optional clearnet requests can use [ScrapingAnt](https://scrapingant.com/?ref=mzliyzh) with `--use-scraping-api` or `--use-proxies`; Tor, `.onion`, GitHub, and GitLab traffic are unaffected.
+
+## Self-Hosting
+
+Run the full PostgreSQL, Tor, FastAPI, and Next.js stack with Docker Compose. The [self-hosting guide](docs/self-hosting.md) covers guided setup, environment configuration, operations, and troubleshooting.
+
+## Links
+
+| | |
+|-|-|
+| [Self-hosting guide](docs/self-hosting.md) | Docker Compose, environment setup, operations, and troubleshooting |
+| [Architecture](docs/architecture.md) | Pipeline internals, modules, schema, API, enrichment, graph, and configuration reference |
+| [Contributing](CONTRIBUTING.md) | Development setup, standards, and pull requests |
+| [Security](SECURITY.md) | Supported versions and private vulnerability reporting |
+| [Usage policy](docs/USAGE_POLICY.md) | Authorized-use requirements and prohibited activity |
+| [PyPI](https://pypi.org/project/voidaccess/) | Published package and release files |
+| [GitHub](https://github.com/KatrielMoses/VoidAccess) | Source, issues, and releases |
+
+## License
+
+MIT. Use VoidAccess only for authorized security research and threat-intelligence work; see the [Usage Policy](docs/USAGE_POLICY.md).

voidaccess-1.8.1/README.md

@@ -0,0 +1,143 @@
+<p align="center">
+  <img src="public/logo_circle.png" width="160" alt="VoidAccess logo">
+</p>
+
+<h1 align="center">VoidAccess</h1>
+
+<p align="center">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
+  <a href="docker-compose.yml"><img src="https://img.shields.io/badge/Docker-Compose-blue.svg" alt="Docker Compose"></a>
+  <a href="https://pypi.org/project/voidaccess/"><img src="https://img.shields.io/pypi/v/voidaccess?logo=pypi&logoColor=white" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/voidaccess/"><img src="https://img.shields.io/pypi/dm/voidaccess" alt="PyPI downloads"></a>
+</p>
+
+Self-hostable OSINT for turning dark-web research queries into structured threat intelligence. Built for security researchers, threat-intelligence teams, and authorized investigators who need collection, enrichment, relationship mapping, and export in one workflow.
+
+## Terminal Output
+
+![VoidAccess](public/terminal-hero.png)
+
+## Quick Start
+
+```bash
+pip install voidaccess
+voidaccess investigate "LockBit ransomware" --no-llm --no-tor --depth shallow
+voidaccess list
+voidaccess actors
+voidaccess status
+```
+
+![VoidAccess investigation demo](public/cli_investigation_gif.gif)
+
+## What It Does
+
+- **Parallel collection** - searches Tor indexes, paste sites, code forges, security feeds, and curated `.onion` seeds.
+- **Entity extraction** - finds IOCs, wallets, credentials, handles, vulnerabilities, actors, malware, people, and organizations.
+- **Multi-source enrichment** - adds reputation, breach, passive DNS, sandbox, blockchain, and threat-feed context.
+- **Actor intelligence** - persists aliases, infrastructure, notes, timelines, and cross-investigation relationships.
+- **Relationship graphs** - builds co-occurrence graphs, communities, paths, and infrastructure clusters.
+- **Content safety** - filters prohibited queries, URLs, content, and extracted entities at mandatory pipeline gates.
+- **Structured exports** - produces STIX 2.1, MISP, Sigma, YARA, Snort, Suricata, CSV, Markdown, JSON, and IOC packages.
+- **CLI and web UI** - runs locally with SQLite or as a Docker Compose stack with PostgreSQL and a browser interface.
+
+## Pipeline
+
+| Stage | Action |
+|---|---|
+| 1 | Refine the investigation query with the selected LLM |
+| 2 | Collect from Tor search, paste sites, code forges, RSS feeds, and curated seeds in parallel |
+| 3 | Filter noisy or irrelevant pages |
+| 4 | Enrich the query and early indicators from threat-intelligence sources |
+| 5 | Discover additional `.onion` links recursively |
+| 6 | Reuse recently processed pages from the vector cache |
+| 7 | Fetch selected pages through Tor with response-size limits |
+| 8 | Persist newly collected content |
+| 9 | Merge collected and enriched intelligence |
+| 10 | Extract entities with regex, NER, and optional LLM analysis |
+| 11 | Cross-reference entities against historical and seed datasets |
+| 12 | Build relationships, communities, and infrastructure clusters |
+| 13 | Generate the final intelligence summary and export-ready result |
+
+Full pipeline behavior, timeouts, recovery, and data flow are documented in [Architecture](docs/architecture.md).
+
+## Entity Types
+
+| Category | Examples |
+|---|---|
+| Cryptocurrency | Bitcoin, Ethereum, Monero, Litecoin, Zcash, Solana, Tron, ENS |
+| Network indicators | IPv4, IPv6, domains, URLs, `.onion` addresses, MAC addresses, PGP keys |
+| File indicators | MD5, SHA-1, SHA-256, malware families |
+| Credentials | Cloud keys, tokens, JWTs, API keys, stealer logs, combo-list entries |
+| Messaging | Telegram, Discord, XMPP, Tox, Session, Matrix, Wire, ICQ, Wickr |
+| Vulnerabilities | CVEs, MITRE ATT&CK techniques and tactics, Exploit-DB IDs |
+| Detection content | YARA rules, Nuclei templates, Snort and Suricata indicators |
+| Threat intelligence | Actor handles, ransomware groups, paste links, people, organizations, locations |
+
+## Collection and Enrichment
+
+| Layer | Sources |
+|---|---|
+| Dark-web search | 16+ Tor search engines and curated `.onion` seeds |
+| Open-web collection | Pastebin, dpaste, paste.ee, Rentry, GitHub, GitLab, and curated RSS feeds |
+| Threat feeds | AlienVault OTX, abuse.ch, MalwareBazaar, ThreatFox, URLhaus, ransomware.live, CISA KEV |
+| IP and domain context | Shodan InternetDB, GreyNoise, AbuseIPDB, Feodo Tracker, C2IntelFeeds, crt.sh, URLScan.io, Wayback Machine, CIRCL PDNS, RDAP |
+| File and identity context | VirusTotal, Hybrid Analysis, Have I Been Pwned, EmailRep |
+| Blockchain | BlockCypher and Etherscan |
+
+Sources that need API keys skip cleanly when their keys are absent. The complete key and configuration reference is in [Architecture](docs/architecture.md#13-configuration-reference).
+
+## LLM Providers
+
+| Provider | Typical models | Notes |
+|---|---|---|
+| OpenRouter | DeepSeek, Llama, Claude | Default route; free models are available |
+| Groq | Llama | Fast hosted inference with a free tier |
+| OpenAI | GPT models | API key required |
+| Anthropic | Claude | Claude Haiku is the tested default |
+| Google Gemini | Gemini Flash and Pro | Google AI Studio key required |
+| Ollama | Any installed local model | Local and suitable for air-gapped deployments |
+
+## CLI Reference
+
+| Command | Description |
+|---------|-------------|
+| `voidaccess investigate "QUERY"` | Run an investigation |
+| `voidaccess show` | Open the interactive entity browser |
+| `voidaccess export INVESTIGATION_ID --format FORMAT` | Export as STIX, MISP, Sigma, YARA, Snort, Suricata, package, CSV, Markdown, or JSON |
+| `voidaccess package INVESTIGATION_ID` | Build an IOC package ZIP |
+| `voidaccess enrich INVESTIGATION_ID` | Re-enrich a saved investigation |
+| `voidaccess list` | List saved investigations |
+| `voidaccess status` | Show configuration, Tor, cache, engine, and seed status |
+| `voidaccess actors` | List persistent actor profiles |
+| `voidaccess actor HANDLE` | Show an actor profile |
+| `voidaccess actor HANDLE --timeline` | Show an actor activity timeline |
+| `voidaccess actor HANDLE --note "TEXT"` | Add an analyst note to an actor profile |
+| `voidaccess timeline HANDLE` | Open an actor timeline directly |
+| `voidaccess configure` | Run the setup wizard |
+| `voidaccess configure llm` | Configure the LLM provider, model, and key |
+| `voidaccess configure keys` | Configure enrichment API keys |
+| `voidaccess configure tor` | Override the Tor proxy host and port |
+| `voidaccess version` | Print the installed version |
+
+Optional clearnet requests can use [ScrapingAnt](https://scrapingant.com/?ref=mzliyzh) with `--use-scraping-api` or `--use-proxies`; Tor, `.onion`, GitHub, and GitLab traffic are unaffected.
+
+## Self-Hosting
+
+Run the full PostgreSQL, Tor, FastAPI, and Next.js stack with Docker Compose. The [self-hosting guide](docs/self-hosting.md) covers guided setup, environment configuration, operations, and troubleshooting.
+
+## Links
+
+| | |
+|-|-|
+| [Self-hosting guide](docs/self-hosting.md) | Docker Compose, environment setup, operations, and troubleshooting |
+| [Architecture](docs/architecture.md) | Pipeline internals, modules, schema, API, enrichment, graph, and configuration reference |
+| [Contributing](CONTRIBUTING.md) | Development setup, standards, and pull requests |
+| [Security](SECURITY.md) | Supported versions and private vulnerability reporting |
+| [Usage policy](docs/USAGE_POLICY.md) | Authorized-use requirements and prohibited activity |
+| [PyPI](https://pypi.org/project/voidaccess/) | Published package and release files |
+| [GitHub](https://github.com/KatrielMoses/VoidAccess) | Source, issues, and releases |
+
+## License
+
+MIT. Use VoidAccess only for authorized security research and threat-intelligence work; see the [Usage Policy](docs/USAGE_POLICY.md).

{voidaccess-1.7.2 → voidaccess-1.8.1}/analysis/opsec.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 import logging
 import re
 from collections import Counter
+from datetime import timezone
 from typing import Optional
 
 logger = logging.getLogger(__name__)
@@ -65,11 +66,16 @@ def detect_timezone_leak(texts_with_timestamps: list[dict]) -> dict:
         if ts is None:
             continue
         if hasattr(ts, "utcoffset") and ts.utcoffset() is not None:
-            # Convert to UTC
-            utc_ts = ts.astimezone(tz=None).replace(tzinfo=None)
+            # Convert to an explicit, host-independent reference frame.  Using
+            # tz=None here made results depend on the analyst server's zone.
+            utc_ts = ts.astimezone(timezone.utc)
             posting_hours.append(utc_ts.hour)
         else:
-            posting_hours.append(ts.hour)
+            # Naive timestamps have no information with which to convert.  The
+            # ingestion contract treats them as UTC; make that assumption
+            # explicit instead of allowing the host timezone to leak in.
+            utc_ts = ts.replace(tzinfo=timezone.utc) if hasattr(ts, "replace") else ts
+            posting_hours.append(utc_ts.hour)
 
     if not posting_hours:
         return {

{voidaccess-1.7.2 → voidaccess-1.8.1}/analysis/patterns.py

@@ -9,7 +9,6 @@ from __future__ import annotations
 
 import logging
 from datetime import date, timedelta
-from typing import Any
 
 from analysis.temporal import (  # noqa: E402 — imported at module level for patchability
     build_activity_timeline,

{voidaccess-1.7.2 → voidaccess-1.8.1}/analysis/temporal.py

@@ -10,8 +10,9 @@ from __future__ import annotations
 import logging
 import math
 from collections import defaultdict
-from datetime import date, datetime, timedelta, timezone
-from typing import Any, Optional
+from datetime import date, datetime
+from statistics import median
+from typing import Optional
 
 logger = logging.getLogger(__name__)
 
@@ -124,44 +125,78 @@ def compute_activity_stats(timeline: list[dict]) -> dict:
     }
 
 
-Z_SCORE_THRESHOLD = 2.5
+POISSON_ALPHA = 0.01
 MIN_DATA_POINTS = 10
-MIN_ABSOLUTE_SPIKE = 5
+
+
+def _poisson_lower_tail(count: int, rate: float) -> float:
+    """Return P(X <= count) for X ~ Poisson(rate), without scipy."""
+    if rate <= 0:
+        return 1.0 if count >= 0 else 0.0
+    term = math.exp(-rate)
+    total = term
+    for k in range(1, count + 1):
+        term *= rate / k
+        total += term
+    return min(1.0, max(0.0, total))
+
+
+def _poisson_upper_tail(count: int, rate: float) -> float:
+    """Return P(X >= count) for X ~ Poisson(rate)."""
+    if count <= 0:
+        return 1.0
+    if rate <= 0:
+        return 0.0
+    return min(1.0, max(0.0, 1.0 - _poisson_lower_tail(count - 1, rate)))
 
 
 def detect_anomalies(
     timeline: list[dict],
-    z_threshold: float = Z_SCORE_THRESHOLD,
+    alpha: float = POISSON_ALPHA,
+    z_threshold: float | None = None,
 ) -> list[dict]:
     """
-    Flag days where activity deviates > z_threshold standard deviations.
+    Flag unusually rare daily counts under a Poisson event-count model.
 
-    Returns list of {"date": date, "count": int, "z_score": float, "type": str}.
-    Returns [] for timelines with fewer than 10 data points OR fewer than 5 posts.
+    The baseline rate is the median daily count, which is robust to the very
+    spikes this function is intended to detect.  ``z_threshold`` remains an
+    ignored compatibility parameter for callers of the old API; decisions are
+    now made from Poisson tail probabilities and ``alpha``.
+
+    Returns dictionaries containing ``poisson_p_value`` and ``expected_rate``.
+    Returns [] for timelines with fewer than 10 data points.
     """
     if len(timeline) < MIN_DATA_POINTS:
         return []
-
-    stats = compute_activity_stats(timeline)
-    mean = stats["mean_daily"]
-    std = stats["std_daily"]
-
-    if std == 0.0:
+    if z_threshold is not None:
+        logger.debug("detect_anomalies: z_threshold is deprecated; using Poisson alpha=%s", alpha)
+    if not 0.0 < alpha < 1.0:
+        raise ValueError("alpha must be between 0 and 1")
+
+    counts = [max(0, int(entry.get("count", 0))) for entry in timeline]
+    rate = float(median(counts))
+    if rate == 0.0 and not any(counts):
         return []
 
     anomalies: list[dict] = []
-    for entry in timeline:
-        count = entry["count"]
-        z = (count - mean) / std
-        if abs(z) > z_threshold:
-            if z > 0 and count < MIN_ABSOLUTE_SPIKE:
-                continue
+    for entry, count in zip(timeline, counts):
+        if count > rate:
+            p_value = _poisson_upper_tail(count, rate)
+            anomaly_type = "spike"
+        elif count < rate:
+            p_value = _poisson_lower_tail(count, rate)
+            anomaly_type = "drop"
+        else:
+            p_value = 1.0
+            anomaly_type = "variation"
+        if p_value <= alpha:
             anomalies.append(
                 {
                     "date": entry["date"],
                     "count": count,
-                    "z_score": float(z),
-                    "type": "spike" if z > 0 else "drop",
+                    "poisson_p_value": float(p_value),
+                    "expected_rate": rate,
+                    "type": anomaly_type,
                 }
             )
 

{voidaccess-1.7.2 → voidaccess-1.8.1}/api/auth.py

@@ -8,6 +8,7 @@ Flow:
 4. POST /auth/reset-password → sets new password, clears must_reset flag
 """
 
+import logging
 import secrets
 from datetime import datetime, timedelta, timezone
 from typing import Optional
@@ -22,7 +23,9 @@ from sqlalchemy.orm import Session
 from config import JWT_SECRET
 from db.models import User
 from db.session import get_session, get_db
-from auth.token_blacklist import is_token_revoked
+from auth.token_blacklist import is_token_revoked, BlacklistUnavailableError
+
+logger = logging.getLogger(__name__)
 
 # Config — single canonical source from config.py
 SECRET = JWT_SECRET
@@ -130,7 +133,28 @@ async def get_current_user(
         raise credentials_exception
 
     if token_payload.jti:
-        if await is_token_revoked(token_payload.jti):
+        # Fail closed when revocation was opted in (REDIS_URL set) but the
+        # blacklist store is unreachable: we cannot confirm the token has not
+        # been revoked, so we refuse rather than silently honour it. Enforcement
+        # resumes automatically once Redis is reachable again. When REDIS_URL is
+        # unset, is_token_revoked() simply returns False (disabled by design).
+        try:
+            token_revoked = await is_token_revoked(token_payload.jti)
+        except BlacklistUnavailableError:
+            logger.warning(
+                "Token revocation store unavailable — failing closed (rejecting "
+                "authentication). Restore Redis, or unset REDIS_URL to disable "
+                "blacklist enforcement (fail-open by design)."
+            )
+            raise HTTPException(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                detail=(
+                    "Authentication temporarily unavailable: the token revocation "
+                    "store is unreachable."
+                ),
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        if token_revoked:
             raise revoked_exception
 
     user = db.query(User).filter(

voidaccess-1.8.1/api/errors.py

@@ -0,0 +1,99 @@
+"""
+api/errors.py — Safe error responses: public generic message, private detailed log.
+
+All internal/unhandled errors surfaced to API clients must go through these
+helpers so that:
+
+  * the client only ever sees a generic message plus a correlation ID, and
+  * the full exception (message + traceback) is logged server-side, tagged
+    with the same correlation ID, for the operator to correlate.
+
+This is the standard "public error, private log" split. Never place a raw
+exception object or its string representation into a response body — a raw
+message can leak database connection fragments, internal file paths, the
+reason an enrichment provider call failed (which may include partial
+credential material for a malformed key), or other implementation details
+that make the system easier to probe. Use these helpers instead.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Optional
+
+from fastapi import HTTPException, Request
+
+logger = logging.getLogger("voidaccess.api.errors")
+
+# Generic, safe message shown to clients for any unhandled/internal error.
+GENERIC_ERROR_MESSAGE = (
+    "An internal error occurred. Reference the correlation ID when contacting support."
+)
+
+
+def new_correlation_id() -> str:
+    """Return a fresh correlation ID for a single failed request."""
+    return uuid.uuid4().hex
+
+
+def log_exception(
+    exc: BaseException,
+    *,
+    context: str = "",
+    request: Optional[Request] = None,
+    correlation_id: Optional[str] = None,
+    level: int = logging.ERROR,
+) -> str:
+    """Log the full exception detail server-side, tagged with a correlation ID.
+
+    Returns the correlation ID so the caller can echo it (and only it) back to
+    the client. The full message and traceback stay in the server log only.
+    """
+    correlation_id = correlation_id or new_correlation_id()
+
+    where = context
+    if request is not None:
+        try:
+            where = f"{request.method} {request.url.path}"
+            if context:
+                where = f"{where} ({context})"
+        except Exception:  # never let logging path-extraction raise
+            where = context
+
+    logger.log(
+        level,
+        "[correlation_id=%s] Internal error in %s: %s",
+        correlation_id,
+        where or "request",
+        exc,
+        exc_info=exc,
+    )
+    return correlation_id
+
+
+def safe_detail(correlation_id: str, message: str = GENERIC_ERROR_MESSAGE) -> str:
+    """A generic ``detail`` string safe to return to clients, with the ID appended."""
+    return f"{message} (correlation ID: {correlation_id})"
+
+
+def safe_error_body(correlation_id: str, message: str = GENERIC_ERROR_MESSAGE) -> dict:
+    """A generic JSON body safe to return to clients (generic message + ID)."""
+    return {"detail": message, "correlation_id": correlation_id}
+
+
+def internal_http_exception(
+    exc: BaseException,
+    *,
+    request: Optional[Request] = None,
+    context: str = "",
+    status_code: int = 500,
+) -> HTTPException:
+    """Log ``exc`` in full and build an ``HTTPException`` with a safe body.
+
+    Raise the returned exception from a route handler:
+
+        raise internal_http_exception(exc, context="create_monitor")
+    """
+    correlation_id = log_exception(exc, context=context, request=request)
+    return HTTPException(status_code=status_code, detail=safe_detail(correlation_id))