threatwatch 1.0.0__tar.gz

threatwatch-1.0.0/CHANGELOG.md

@@ -0,0 +1,46 @@
+# Changelog
+
+All notable changes to ThreatWatch are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-11-14
+
+Initial public release.
+
+### Added
+
+- Live collection from CISA KEV, NVD 2.0, FIRST EPSS, GitHub Security Advisories,
+  and curated RSS/Atom feeds.
+- Defensive-only scope: no exploit code, scanning, credential use, or offensive
+  capability. Extracted indicators are defanged and treated as unvalidated.
+- Explainable additive risk scoring with CVSS, EPSS, KEV, ransomware, recency,
+  AI relevance, and asset exposure. KEV floors and tier-based remediation SLAs.
+- Audience profiles for baseline, CISO, SOC, incident response, and AI platform
+  teams.
+- Markdown, single-file HTML, JSON, and CSV reports with KPI dashboards, priority
+  actions, vulnerability detail, KEV watch, AI/LLM threat mapping, campaign
+  intelligence, OPSEC controls, detection priorities, and IOC appendices.
+- AI/LLM taxonomy mapped to OWASP Top 10 for LLM Applications (2025) and MITRE
+  ATLAS.
+- "Recently Patched / Fix Available" view with NVD patch references, explicit
+  fix language, and GitHub fixed-version metadata. Includes `--patched-only`
+  filtering and patch fields in JSON/CSV exports.
+- Live weighted progress bar for interactive terminals, with plain milestone
+  output for cron/CI, `--quiet`, `--no-progress`, and `--no-color` controls.
+- Persistent HTTP cache with offline fallback, retry/backoff, and polite rate
+  limiting for unauthenticated NVD and GitHub API access.
+- Watch state and `--diff-only` reporting for new items since the previous run.
+- CI gating with `--fail-on p1|p2|p3` and strict source-health checks.
+- Optional LLM narrative polish with configurable endpoint and privacy controls.
+- `enrich` command for single-CVE deep dives, and `opsec` command for a defensive
+  control baseline.
+- Standard-library-only implementation for Python 3.11+.
+
+### Security
+
+- API keys and tokens are read from environment variables and redacted by
+  `config show`.
+- Generated reports may contain sensitive threat intelligence; the tool includes
+  classification markings and defanged indicators to support safe handling.

threatwatch-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ghoste12125
+
+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.

threatwatch-1.0.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include CHANGELOG.md
+include SECURITY.md
+include LICENSE
+include config.example.json
+recursive-include tests *.py

threatwatch-1.0.0/PKG-INFO

@@ -0,0 +1,496 @@
+Metadata-Version: 2.4
+Name: threatwatch
+Version: 1.0.0
+Summary: Live defensive cyber and AI threat intelligence reports from public sources
+Author-email: ghoste12125 <anonymosmauros@gmail.com>
+Maintainer-email: ghoste12125 <anonymosmauros@gmail.com>
+License-Expression: MIT
+Keywords: threat-intelligence,cybersecurity,ai-security,kev,epss,opsec
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ThreatWatch
+
+Live, defensive cyber and AI threat intelligence from public sources, rendered as a professional report for executives, SOC, incident response, and AI platform owners.
+
+ThreatWatch collects exploitation evidence and reporting, scores what matters, explains every score, and produces Markdown, single-file HTML, JSON, and CSV. It is designed for repeatable use in a terminal, cron job, systemd timer, or CI pipeline.
+
+> **Scope:** defensive intelligence only. ThreatWatch does not include exploit code, scanning, credential use, or offensive capability. All indicators are defanged and treated as unvalidated public reporting.
+
+---
+
+## Contents
+
+- [Quickstart](#quickstart)
+- [Commands](#commands)
+- [Live progress](#live-progress)
+- [Profiles](#profiles)
+- [Report sections](#report-sections)
+- [Recently patched / fix available](#recently-patched--fix-available)
+- [How prioritisation works](#how-prioritisation-works)
+- [AI and LLM taxonomy](#ai-and-llm-taxonomy)
+- [Sources](#sources)
+- [Configuration](#configuration)
+- [CI gating](#ci-gating)
+- [Scheduling](#scheduling)
+- [LLM polish and privacy](#llm-polish-and-privacy)
+- [Caching, state, and offline use](#caching-state-and-offline-use)
+- [Limitations and responsible use](#limitations-and-responsible-use)
+- [Security](#security)
+- [Changelog](#changelog)
+- [Development](#development)
+
+---
+
+## Quickstart
+
+Requirements: Python **3.11+** (standard library only, no third-party packages).
+
+```bash
+# Install the command from PyPI.
+python3 -m pip install threatwatch
+
+# Optional: create a local config and edit assets, thresholds, and org details.
+threatwatch config init
+
+# Collect, score, and write the default Markdown report.
+threatwatch run
+
+# Or write every format at once.
+threatwatch run --format all --outdir reports
+
+# See what was produced.
+ls reports/
+```
+
+Reports are written as `threatwatch-YYYYMMDD-HHMMSSZ.<ext>` plus `latest.<ext>` unless `report.write_latest` is disabled.
+
+From a source checkout, use `python3 -m threatwatch` instead of `threatwatch`, or install the checkout in editable mode:
+
+```bash
+cd threatwatch
+python3 -m pip install -e .
+threatwatch run
+```
+
+No network access is required for `--offline` runs after a cache has been populated.
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `run` (alias `report`) | Collect, correlate, score, and write a full report. |
+| `watch` | Report only items new since the previous run; exits non-zero on new P1/P2 by default. |
+| `feeds` | List configured feeds or check feed/API health. |
+| `opsec` | Print the defensive OPSEC control baseline in Markdown, JSON, or CSV. |
+| `enrich CVE-YYYY-NNNN` | Deep-dive one CVE with KEV, EPSS, AI mapping, and remediation context. |
+| `config init\|show\|validate` | Create, inspect, or validate configuration. |
+| `version` | Print the version. |
+
+Running `python3 -m threatwatch` with no arguments is equivalent to `run`.
+
+Common examples:
+
+```bash
+# All formats, named output directory.
+python3 -m threatwatch run --format all --outdir reports
+
+# Executive view for the last 14 days.
+python3 -m threatwatch run --profile ciso --since-days 14 --format md --format html
+
+# Only AI/LLM-relevant items.
+python3 -m threatwatch run --ai-only --profile ai-platform
+
+# Only vulnerabilities with patch or fixed-version evidence.
+python3 -m threatwatch run --patched-only --format md --format html
+
+# New items only (the watch command does this automatically).
+python3 -m threatwatch run --diff-only --format json --output -
+
+# Single CVE deep dive.
+python3 -m threatwatch enrich CVE-2024-3400
+
+# OPSEC controls for a SOC.
+python3 -m threatwatch opsec --profile soc --format md --output opsec-soc.md
+
+# Check sources before relying on a scheduled run.
+python3 -m threatwatch feeds --check-apis
+```
+
+Useful run flags:
+
+| Flag | Effect |
+|---|---|
+| `--format md,html,json,csv,all` | Output formats; repeatable. Default `md`. |
+| `--outdir DIR` | Output directory. Default `reports`. |
+| `--output FILE` / `--output -` | Single file, or stdout. |
+| `--since-days N` | CVE window. |
+| `--kev-days N` | KEV addition window. |
+| `--news-hours N` | Reporting window. |
+| `--top N` | Rows in vulnerability tables. |
+| `--min-tier P1..P4` | Show this tier or higher. |
+| `--ai-only` | Keep only AI/LLM-relevant vulnerabilities and reporting. |
+| `--patched-only` | Keep only vulnerabilities with detected patch or fixed-version evidence. |
+| `--diff-only` | Only items new since the previous run. |
+| `--all-kev` | Include the full KEV catalog, not just recent/relevant entries. |
+| `--no-feeds`, `--no-nvd`, `--no-ghsa` | Skip a collection source. |
+| `--profile baseline\|ciso\|soc\|ir\|ai-platform` | Audience and OPSEC profile. |
+| `--fail-on p1\|p2\|p3\|none` | CI gate; exits `2` when the threshold is met. |
+| `--no-state`, `--state-file PATH` | Disable or relocate watch state. |
+| `--offline`, `--refresh`, `--no-cache` | Cache behaviour. |
+| `--org`, `--classification` | Override report metadata. |
+| `--llm` / `--no-llm` | Opt in/out of configured LLM polish. |
+| `--print` | Also print the report to stdout. |
+| `--verbose` | Show fetch retries and diagnostics. |
+| `--quiet` | Suppress all progress and status output (ideal for cron/CI logs). |
+| `--no-progress` | Disable the live progress bar but keep normal status lines. |
+| `--no-color` | Disable ANSI colour. `NO_COLOR=1` is also honoured. |
+
+Exit codes: `0` success, `1` usage/runtime error, `2` CI gate or strict source-health failure.
+
+### Live progress
+
+On an interactive terminal, collection shows a single animated bar with per-stage and sub-stage updates: KEV catalog, NVD pages, GitHub advisories, news feeds, EPSS batches, and scoring. The bar is drawn on `stderr`, so report output (`--output -`) stays clean.
+
+When output is redirected (cron, CI, logs), ThreatWatch automatically falls back to plain stage and milestone lines instead of ANSI animation. Use `--quiet` to silence it entirely, or `--no-progress` to keep status messages but skip the bar.
+
+```bash
+# Interactive: animated bar.
+python3 -m threatwatch run --format all
+
+# CI: plain, timestamp-friendly lines; no ANSI codes.
+NO_COLOR=1 python3 -m threatwatch watch
+
+# Cron: no progress at all.
+python3 -m threatwatch watch --quiet
+```
+
+---
+
+## Profiles
+
+Profiles change emphasis, narrative, and which OPSEC controls are included. They do not change the underlying scoring.
+
+| Profile | Audience and emphasis |
+|---|---|
+| `baseline` | Balanced technical and management view. |
+| `ciso` | Exposure, deadlines, accountability, and decision-ready summaries. |
+| `soc` | Detection, KEV/EPSS triage, hunting leads, and operational queues. |
+| `ir` | Exposure verification, evidence preservation, and containment for confirmed exploitation. |
+| `ai-platform` | Model serving, agent permissions, retrieval boundaries, and artifact integrity. |
+
+OPSEC controls are tagged `Baseline`, `Enhanced`, or `Advanced`. Profiles select the relevant subset; `--advanced` / `--no-advanced` override inclusion.
+
+---
+
+## Report sections
+
+- Posture KPIs and bottom line
+- Executive summary and key findings
+- Priority actions with owners, tiers, and due dates
+- Vulnerability priorities with explainable risk drivers
+- Recently patched / fix available, sorted by most recent source modification
+- CISA KEV watch, including ransomware and asset matches
+- AI/LLM threat landscape mapped to OWASP and MITRE ATLAS
+- Exploit and campaign intelligence
+- OPSEC controls, quick wins, assurance questions, and metrics
+- Detection priorities
+- Defanged indicator appendix
+- SLA and metrics table
+- Methodology, confidence, and limitations
+- Source health and collection warnings
+- New-since-last-run delta when state is enabled
+
+The HTML export is a single self-contained file with inline CSS/JS, filtering, a theme toggle, and print/PDF support.
+
+### Recently patched / fix available
+
+ThreatWatch infers patch evidence conservatively from public metadata:
+
+- NVD references tagged `Patch`.
+- Explicit fix language in NVD descriptions, such as `fixed in`, `patched in`, `security update`, or `upgrade to`.
+- GitHub Security Advisory `first_patched_version` and `patched_versions` fields.
+
+The **Recently Patched / Fix Available** section shows these records sorted by the most recent source modification date (NVD `lastModified` or GHSA `updated_at`), with the fixed version, tier, risk, and KEV status. Use `--patched-only` to restrict the main vulnerability table and AI sections to the same records. CSV and JSON exports include `patch_available`, `patched_versions`, and `patch_urls`.
+
+Patch detection is a metadata heuristic, not confirmation that a safe update exists for your deployment. Verify with the vendor advisory before relying on it.
+
+---
+
+## How prioritisation works
+
+Every vulnerability gets an additive, explainable risk score (0–100):
+
+```text
+risk = clamp(3.0 × CVSS
+           + 20 × EPSS
+           + 22 × KEV
+           +  6 × ransomware
+           +  8 × recency
+           + 12 × AI relevance
+           +  8 × asset exposure)
+```
+
+- **Recency** decays with a 21-day half-life.
+- **KEV floors** ensure confirmed exploitation is never buried: `72` baseline, `82` with known ransomware, `86` with strong AI relevance, `88` when a declared asset matches.
+- **Tiers** come from configurable thresholds: P1 ≥ 80, P2 ≥ 62, P3 ≥ 42, otherwise P4.
+- **SLA hours** are P1 24h, P2 72h, P3 14 days, P4 30 days, capped by the CISA KEV due date where one exists.
+- **Explanations** are stored on each record and shown in tables, cards, JSON, and `enrich`.
+
+Asset matching is keyword-based against the `assets` list in configuration. It is intentionally simple and should be tuned to your real inventory.
+
+---
+
+## AI and LLM taxonomy
+
+AI relevance requires strong indicators, not generic words such as “AI”, “model”, or “agent”. Categories map to:
+
+- **OWASP Top 10 for LLM Applications (2025)** — e.g. LLM01 Prompt Injection, LLM03 Supply Chain, LLM06 Excessive Agency, LLM07 System Prompt Leakage.
+- **MITRE ATLAS** — verified technique IDs such as AML.T0051 (LLM Prompt Injection), AML.T0010 (AI Supply Chain Compromise), AML.T0040 (AI Model Inference API Access), and AML.T0110 (AI Agent Tool Poisoning).
+
+The classifier combines indicator phrases, context guards (for example, avoiding “RAG” false positives), and AI-stack inventory terms.
+
+---
+
+## Sources
+
+| Source | Role |
+|---|---|
+| CISA Known Exploited Vulnerabilities (KEV) | Authoritative confirmed exploitation and due dates. |
+| NIST NVD 2.0 | CVSS, CWE, CPE, descriptions, references. |
+| FIRST EPSS | 30-day exploitation probability and percentile. |
+| GitHub Security Advisories | Open-source package advisories and GHSA identifiers. |
+| Curated RSS/Atom feeds | Vendor research, incident reporting, and AI security commentary. |
+
+`python3 -m threatwatch feeds --list` shows built-in feed IDs. Add your own under `feeds.custom`. The default enabled set favours established security publishers and AI-security sources; tune it to your sector.
+
+NVD unauthenticated access is rate-limited. Set `NVD_API_KEY` to raise limits. Set `GITHUB_TOKEN` for higher GitHub API limits. Both are optional.
+
+---
+
+## Configuration
+
+Configuration is JSON, merged over built-in defaults. Discovery order:
+
+1. `--config PATH`
+2. `THREATWATCH_CONFIG` environment variable
+3. `.threatwatch/config.json`
+4. `config.json` in the current directory
+
+Start from the documented example:
+
+```bash
+python3 -m threatwatch config init          # writes .threatwatch/config.json
+python3 -m threatwatch config show          # effective config, secrets redacted
+python3 -m threatwatch config validate      # warnings and feed checks
+```
+
+`config.example.json` in this repository mirrors the default configuration and can be copied manually.
+
+Key sections:
+
+| Section | Purpose |
+|---|---|
+| `org` | Name, sector, classification marking, timezone. |
+| `assets` | Keyword-based inventory with criticality and exposure. |
+| `ai_stack` | Providers, frameworks, servers, vector DBs, and AI infrastructure terms. |
+| `feeds` | Enabled built-in feeds, custom feeds, per-feed item cap. |
+| `windows` | Default CVE, KEV, and news windows. |
+| `thresholds`, `sla_hours` | Tier boundaries and remediation SLAs. |
+| `report` | Top-N, patched-section cap, IOC/OPSEC inclusion, theme, profile, latest-file behaviour. |
+| `cache`, `state` | Cache TTLs, cache age, and watch-state location. |
+| `nvd`, `epss`, `ghsa`, `http` | Rate limits, tokens, retries, timeout, user agent. |
+| `llm` | Optional local/remote LLM endpoint and privacy controls. |
+| `opsec` | Advanced-control inclusion and default profile. |
+
+---
+
+## CI gating
+
+Use `--fail-on` to turn intelligence into a release or deployment gate. A gate failure exits `2`.
+
+```bash
+# Fail if any P1 is present.
+python3 -m threatwatch run --format json --output threatwatch.json --fail-on p1
+
+# Watch mode defaults to failing on newly seen P1 or P2 items.
+python3 -m threatwatch watch --format md --outdir reports
+```
+
+Example GitHub Actions step:
+
+```yaml
+- name: Threat intelligence gate
+  env:
+    NVD_API_KEY: ${{ secrets.NVD_API_KEY }}
+    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+  run: |
+    python -m pip install .
+    threatwatch run --format json --output threatwatch.json --fail-on p1
+```
+
+Recommended pattern: run `watch` on a schedule, archive JSON as an artifact, and keep the hard gate on P1. Avoid failing builds on P3/P4 noise unless your risk appetite justifies it.
+
+---
+
+## Scheduling
+
+Cron example (every four hours, new items only):
+
+```cron
+0 */4 * * * cd /opt/threatwatch && /usr/bin/python3 -m threatwatch watch --quiet --outdir /var/lib/threatwatch/reports >> /var/log/threatwatch.log 2>&1
+```
+
+A systemd timer is preferable for jitter, logging, and restart behaviour:
+
+```ini
+# /etc/systemd/system/threatwatch.service
+[Unit]
+Description=ThreatWatch intelligence report
+After=network-online.target
+
+[Service]
+Type=oneshot
+WorkingDirectory=/opt/threatwatch
+Environment=NVD_API_KEY=...
+ExecStart=/usr/bin/python3 -m threatwatch watch --quiet --outdir /var/lib/threatwatch/reports
+User=threatwatch
+```
+
+```ini
+# /etc/systemd/system/threatwatch.timer
+[Unit]
+Description=Run ThreatWatch every four hours
+
+[Timer]
+OnCalendar=00/4:00
+RandomizedDelaySec=10m
+Persistent=true
+
+[Install]
+WantedBy=timers.target
+```
+
+```bash
+sudo systemctl daemon-reload
+sudo systemctl enable --now threatwatch.timer
+```
+
+For a daily full report plus a frequent watch, use two units with different `--outdir` values.
+
+---
+
+## LLM polish and privacy
+
+LLM polish is **off by default**. When enabled with `--llm`, ThreatWatch sends **aggregate metrics only** — counts, tiers, category names, and short risk summaries — not raw reporting text, indicators, or asset details. Organisation name can be redacted with `llm.redact_org`.
+
+The default endpoint is local Ollama (`http://127.0.0.1:11434`). If you point it at a remote provider, review data-handling and residency requirements first. The report always has a deterministic fallback, so LLM failure does not block generation.
+
+For sensitive environments, leave LLM polish disabled and use the deterministic narrative.
+
+---
+
+## Caching, state, and offline use
+
+- HTTP responses are cached under `.threatwatch/cache` with per-source TTLs.
+- `--refresh` bypasses TTLs; `--no-cache` disables reads and writes; `--offline` uses cache only.
+- For time-windowed APIs (NVD, KEV, EPSS, GHSA), offline mode falls back to the most recent cached response for the same endpoint and query shape, and labels it stale rather than dropping the source.
+- Stale cache is labelled in Source Health rather than silently presented as current.
+- Watch state lives in `.threatwatch/state.json`. `--diff-only` / `watch` report new items; `--no-state` leaves state untouched.
+- Failed fetches are retried with rate limiting and recorded as collection warnings.
+
+The cache is not a substitute for a controlled archive. For audit purposes, retain generated JSON reports alongside their timestamps.
+
+---
+
+## Limitations and responsible use
+
+- Public reporting can be incomplete, delayed, duplicated, or wrong. Validate before emergency change.
+- KEV is authoritative for known exploitation; EPSS is probabilistic; NVD enrichment can lag.
+- Asset matching is keyword-based and may miss or over-match. Tune `assets` and review results.
+- AI tagging is a triage aid, not proof of exploitability or attribution. Attribution is not assessed.
+- Indicators are automatically extracted, defanged, and unvalidated. Do not block on a single low-confidence indicator.
+- The tool does not replace vendor advisories, EDR telemetry, vulnerability scanners, or incident response.
+- Reports may contain security-sensitive content. Apply the classification marking, restrict distribution, and defang before external sharing.
+
+ThreatWatch is intended for defensive security teams operating within their authorisation and applicable law.
+
+---
+
+## Security
+
+Report suspected vulnerabilities privately to **anonymosmauros@gmail.com** with the subject `[SECURITY] ThreatWatch — <short summary>`. Do not open a public issue before coordinated disclosure.
+
+Supported release: **1.0.x**. The full policy, scope, and reporting guidance are in `SECURITY.md`.
+
+ThreatWatch is defensive-only, reads API credentials from environment variables, sends no telemetry, and redacts configured secrets in `config show`. Generated reports may still contain sensitive threat intelligence; store and share them according to your classification policy.
+
+---
+
+## Changelog
+
+Release notes are maintained in `CHANGELOG.md`. This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## Development
+
+```bash
+cd threatwatch
+
+# Offline test suite (stdlib unittest).
+python3 -m unittest discover -s tests -v
+
+# Byte-compile all modules.
+python3 -m compileall -q threatwatch
+
+# Live smoke test without GitHub advisories.
+python3 -m threatwatch run --no-ghsa --since-days 3 --format md --format html --format json --outdir reports
+```
+
+Project layout:
+
+```text
+threatwatch/
+├── pyproject.toml
+├── MANIFEST.in
+├── config.example.json
+├── README.md
+├── CHANGELOG.md
+├── SECURITY.md
+├── LICENSE
+├── tests/
+│   └── test_core.py
+└── threatwatch/
+    ├── __main__.py
+    ├── cli.py          # commands, argument wiring, output
+    ├── config.py       # defaults, loading, validation
+    ├── models.py       # data structures and serialisation
+    ├── taxonomy.py     # OWASP LLM Top 10 + MITRE ATLAS mapping
+    ├── scoring.py      # risk model, tiers, SLAs, asset matching
+    ├── sources.py      # KEV, NVD, EPSS, GHSA, RSS/Atom collectors
+    ├── http.py         # caching, retries, rate limiting
+    ├── extract.py      # conservative IOC extraction
+    ├── state.py        # watch state and diffs
+    ├── correlate.py    # collection orchestration and KPIs
+    ├── summarize.py    # deterministic narrative + optional LLM polish
+    ├── opsec.py        # defensive control library
+    ├── report.py       # Markdown, HTML, JSON, CSV renderers
+    └── utils.py        # shared formatting helpers
+```
+
+Contributions should preserve three properties: standard library only, defensive scope only, and explainable scoring.