osintkit 0.7.0__tar.gz → 0.8.0__tar.gz

{osintkit-0.7.0 → osintkit-0.8.0}/CHANGELOG.md

@@ -6,6 +6,13 @@ All notable changes are recorded here. The format follows
 
 ## Unreleased
 
+## 0.8.0 — 2026-11-02
+
+### Added
+
+- `watch`: interval re-runs that stay silent unless a diff shows change, with optional desktop
+  notification and bounded cycles
+
 ## 0.7.0 — 2026-11-02
 
 ### Added

{osintkit-0.7.0 → osintkit-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: osintkit
-Version: 0.7.0
+Version: 0.8.0
 Summary: Public-data OSINT aggregator for emails, usernames, domains, and companies
 Project-URL: Homepage, https://github.com/sjdsjadjajdjsa/osintkit
 Project-URL: Issues, https://github.com/sjdsjadjajdjsa/osintkit/issues
@@ -106,6 +106,7 @@ Everything else needs no credentials.
 | `batch` | A CSV of targets, run concurrently, reported in order |
 | `diff` | What changed between two archived runs |
 | `password` | Is a password in Pwned Passwords (free, no key, hash-prefix only) |
+| `watch` | Re-check on an interval, print only changes, optionally notify |
 | `history` | Past runs, replayable by id |
 | `doctor` | Key, endpoint, and directory checks (`--deep` verifies auth) |
 | `collectors` | Every collector and what it touches |
@@ -172,6 +173,18 @@ Passwords are checked separately with `osintkit password`: Pwned Passwords cover
 millions of leaked passwords, needs no key, and only the first five SHA-1 characters leave the
 machine.
 
+## Monitoring
+
+```bash
+osintkit watch --domain example.com --every 1d
+osintkit watch --email you@example.com --every 6h --no-notify
+```
+
+The first run prints a baseline. Later runs print nothing unless `diff` sees movement — a new
+breach, a new host, a source failing, or a risk change — and optionally raise a desktop
+notification through `notify-send`. `--cycles` bounds the loop, `ctrl-c` stops it, and every run
+is archived so you can inspect it afterwards. Pair with cron or a systemd timer for unattended use.
+
 ## Safety and legality
 
 - Public data only. No logins, no scraping behind auth, no paid brokers.

{osintkit-0.7.0 → osintkit-0.8.0}/README.md

@@ -74,6 +74,7 @@ Everything else needs no credentials.
 | `batch` | A CSV of targets, run concurrently, reported in order |
 | `diff` | What changed between two archived runs |
 | `password` | Is a password in Pwned Passwords (free, no key, hash-prefix only) |
+| `watch` | Re-check on an interval, print only changes, optionally notify |
 | `history` | Past runs, replayable by id |
 | `doctor` | Key, endpoint, and directory checks (`--deep` verifies auth) |
 | `collectors` | Every collector and what it touches |
@@ -140,6 +141,18 @@ Passwords are checked separately with `osintkit password`: Pwned Passwords cover
 millions of leaked passwords, needs no key, and only the first five SHA-1 characters leave the
 machine.
 
+## Monitoring
+
+```bash
+osintkit watch --domain example.com --every 1d
+osintkit watch --email you@example.com --every 6h --no-notify
+```
+
+The first run prints a baseline. Later runs print nothing unless `diff` sees movement — a new
+breach, a new host, a source failing, or a risk change — and optionally raise a desktop
+notification through `notify-send`. `--cycles` bounds the loop, `ctrl-c` stops it, and every run
+is archived so you can inspect it afterwards. Pair with cron or a systemd timer for unattended use.
+
 ## Safety and legality
 
 - Public data only. No logins, no scraping behind auth, no paid brokers.

{osintkit-0.7.0 → osintkit-0.8.0}/docs/REFERENCE.md

@@ -62,6 +62,13 @@ Explicit `--base-url` and `--model` beat both the provider and the prefix. Tempe
 Per-command: `--json`, `--markdown`, `-o/--out`, `--raw`, `--offline`, `--dry-run`, `--only`, `--skip`,
 `--ports`, `--fail-fast`, `-c/--concurrency`, `--limit`, `--show`, `--days`, `--clear`, `--deep`.
 
+## Watching
+
+`watch` repeats a lookup on an interval (`--every`, minimum 60s), prints a baseline, and then
+only reports diffs: added breaches or hosts, risk direction, source failure and recovery.
+`--notify` (default) calls `notify-send` when available; `--full` prints the whole report on a
+change; `--cycles N` bounds the loop. Every cycle is archived and logged like a normal run.
+
 ## Self-check
 
 After synthesis every breach name, date, subdomain, and account URL is compared with the supplied

{osintkit-0.7.0 → osintkit-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "osintkit"
-version = "0.7.0"
+version = "0.8.0"
 description = "Public-data OSINT aggregator for emails, usernames, domains, and companies"
 readme = "README.md"
 requires-python = ">=3.12"

{osintkit-0.7.0 → osintkit-0.8.0}/src/osintkit/__init__.py

@@ -1,3 +1,3 @@
 """osintkit: a public-data OSINT aggregator."""
 
-__version__ = "0.7.0"
+__version__ = "0.8.0"

{osintkit-0.7.0 → osintkit-0.8.0}/src/osintkit/cli.py

@@ -18,7 +18,7 @@ from rich.console import Console
 from rich.panel import Panel
 from rich.table import Table
 
-from . import __version__, diff, doctor, passwords, pipeline, render, retention, userconfig
+from . import __version__, diff, doctor, passwords, pipeline, render, retention, userconfig, watch
 from .collectors import REGISTRY
 from .config import (
     DEFAULT_RESOLVERS,
@@ -639,6 +639,57 @@ def init(
     out.print("[dim]try: osintkit lookup --domain example.com[/dim]")
 
 
+@app.command("watch")
+def watch_cmd(
+    target: str | None = typer.Argument(None, help="Email, username, domain, or company."),
+    email: str | None = typer.Option(None, "--email", help="Email target."),
+    username: str | None = typer.Option(None, "--username", help="Username target."),
+    domain: str | None = typer.Option(None, "--domain", help="Domain target."),
+    company: str | None = typer.Option(None, "--company", help="Company target."),
+    every: str = typer.Option("1d", "--every", help="Interval: 30m, 6h, 1d."),
+    cycles: int = typer.Option(0, "--cycles", min=0, help="Stop after N runs; 0 means forever."),
+    full: bool = typer.Option(False, "--full", help="Print the whole report on each change."),
+    notify_changes: bool = typer.Option(True, "--notify/--no-notify", help="Desktop notification."),
+    offline: bool = typer.Option(False, "--offline", help="Local report only; no model, no key."),
+    only: list[str] | None = typer.Option(None, "--only", help="Run only these collectors."),
+    skip: list[str] | None = typer.Option(None, "--skip", help="Skip these collectors."),
+) -> None:
+    """Re-check a target on a schedule and report only changes."""
+    out = _console()
+    try:
+        interval = watch.parse_duration(every)
+        raw, declared = _pick_target(target, email, username, domain, company)
+    except (ValueError, TargetParseError) as exc:
+        out.print(f"[red]{exc}[/red]")
+        raise typer.Exit(2) from exc
+
+    settings = _settings(offline=offline, output_json=False, output_markdown=False, raw=False)
+
+    async def run_once():
+        outcome = await pipeline.execute(
+            raw, settings, RunLogger(pipeline.new_run_id()), out, declared_type=declared
+        )
+        return outcome.report
+
+    def on_report(report, lines, baseline):
+        watch.render_event(report, lines, baseline, out, full=full)
+        if lines and notify_changes:
+            body = "; ".join(lines)[:180]
+            watch.notify(f"change for {report.target}", body)
+
+    out.print(
+        f"[dim]watching {render.escape(raw)} every {every}"
+        + (f", {cycles} runs" if cycles else "")
+        + " · ctrl-c stops[/dim]"
+    )
+    try:
+        changes = asyncio.run(watch.run(raw, run_once, on_report, every=interval, cycles=cycles))
+    except KeyboardInterrupt:
+        out.print("[yellow]stopped[/yellow]")
+        return
+    out.print(f"[dim]{changes} change event(s)[/dim]")
+
+
 @app.command()
 def password(
     value: str | None = typer.Argument(None, help="Password to check; prompt if omitted."),

osintkit-0.8.0/src/osintkit/watch.py

@@ -0,0 +1,97 @@
+"""Repeat a lookup on an interval and speak only when something changed."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import shutil
+import subprocess
+from collections.abc import Awaitable, Callable
+
+from . import diff, render
+from .models import Report
+
+UNITS = {"s": 1, "m": 60, "h": 3600, "d": 86400}
+DURATION_RE = re.compile(r"^(\d+)([smhd])$")
+MIN_INTERVAL = 60
+
+
+def parse_duration(text: str) -> int:
+    match = DURATION_RE.match(text.strip().lower())
+    if not match:
+        raise ValueError(f"{text!r} is not a duration like 30m, 6h, or 1d")
+    value = int(match.group(1)) * UNITS[match.group(2)]
+    if value < MIN_INTERVAL:
+        raise ValueError(f"interval must be at least {MIN_INTERVAL}s")
+    return value
+
+
+def describe(change: dict) -> list[str]:
+    lines: list[str] = []
+    if change["risk_rose"]:
+        lines.append(f"risk rose {change['risk']['old']} -> {change['risk']['new']}")
+    if change["risk_fell"]:
+        lines.append(f"risk fell {change['risk']['old']} -> {change['risk']['new']}")
+    for name in change["breaches"]["added"]:
+        lines.append(f"new breach: {name}")
+    for name in change["subdomains"]["added"]:
+        lines.append(f"new host: {name}")
+    for name in change["collectors"]["started_failing"]:
+        lines.append(f"source failing: {name}")
+    for name in change["collectors"]["started_working"]:
+        lines.append(f"source recovered: {name}")
+    return lines
+
+
+def notify(title: str, body: str) -> bool:
+    binary = shutil.which("notify-send")
+    if not binary:
+        return False
+    try:
+        subprocess.run([binary, "osintkit", title, body], check=False, timeout=10)
+        return True
+    except (OSError, subprocess.SubprocessError):
+        return False
+
+
+async def run(
+    target: str,
+    run_once: Callable[[], Awaitable[Report]],
+    on_report: Callable[[Report, list[str], bool], None],
+    *,
+    every: int,
+    cycles: int = 0,
+    sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+) -> int:
+    """Run `run_once` on an interval. Returns the number of change events."""
+    previous: Report | None = None
+    changes = 0
+    done = 0
+    while True:
+        report = await run_once()
+        done += 1
+        lines: list[str] = []
+        if previous is not None:
+            comparison = diff.compare(previous, report)
+            if not diff.is_empty(comparison):
+                changes += 1
+                lines = describe(comparison)
+        if previous is None or lines:
+            on_report(report, lines, previous is None)
+        previous = report
+        if cycles and done >= cycles:
+            return changes
+        await sleep(every)
+
+
+def render_event(report: Report, lines: list[str], baseline: bool, console, *, full: bool) -> None:
+    stamp = render.escape(report.generated_at)
+    if baseline:
+        console.print(f"[dim]{stamp} baseline for {render.escape(report.target)}[/dim]")
+        render.render_report(report, console)
+        return
+    console.print(f"[yellow]change[/yellow] {stamp} {render.escape(report.target)}")
+    for line in lines:
+        console.print(f"  - {render.escape(line)}")
+    if full:
+        render.render_report(report, console)

{osintkit-0.7.0 → osintkit-0.8.0}/tests/test_cli.py

@@ -688,3 +688,13 @@ def test_env_hibp_key_beats_stored(xdg, monkeypatch):
     monkeypatch.setattr(pipeline, "execute", spy)
     runner.invoke(app, ["lookup", "--domain", "a.com"])
     assert captured["hibp"] == "env-hibp"
+
+
+def test_watch_runs_a_single_cycle(monkeypatch):
+    monkeypatch.setattr(pipeline, "LLMClient", None)
+    result = runner.invoke(
+        app, ["watch", "--domain", "example.com", "--every", "60s", "--cycles", "1", "--offline"]
+    )
+    assert result.exit_code == 0
+    assert "baseline" in result.output
+    assert "0 change event" in result.output

osintkit-0.8.0/tests/test_watch.py

@@ -0,0 +1,81 @@
+import pytest
+
+from osintkit import watch
+from osintkit.models import Analysis, Report
+
+
+def report(risk="low", breaches=()):
+    return Report(
+        target="example.com",
+        target_type="domain",
+        analysis=Analysis(summary="s", risk_level=risk, breaches=[{"name": b} for b in breaches]),
+    )
+
+
+def test_parse_duration():
+    assert watch.parse_duration("30m") == 1800
+    assert watch.parse_duration("2h") == 7200
+    assert watch.parse_duration("1d") == 86400
+
+
+@pytest.mark.parametrize("text", ["10s", "soon", "5x", ""])
+def test_parse_duration_rejects(text):
+    with pytest.raises(ValueError):
+        watch.parse_duration(text)
+
+
+def test_describe_lists_changes():
+    change = {
+        "risk": {"old": "low", "new": "high"},
+        "risk_rose": True,
+        "risk_fell": False,
+        "breaches": {"added": ["Acme"], "removed": []},
+        "subdomains": {"added": ["x.example.com"], "removed": []},
+        "collectors": {"started_failing": ["crt_sh_subdomains"], "started_working": []},
+    }
+    lines = watch.describe(change)
+    assert "risk rose low -> high" in lines
+    assert "new breach: Acme" in lines
+    assert "new host: x.example.com" in lines
+    assert "source failing: crt_sh_subdomains" in lines
+
+
+async def test_run_reports_baseline_then_only_changes():
+    sequence = [report(), report(), report(risk="high"), report(risk="high")]
+    events = []
+    slept = []
+
+    async def run_once():
+        return sequence.pop(0)
+
+    async def sleeper(seconds):
+        slept.append(seconds)
+
+    changes = await watch.run(
+        "example.com",
+        run_once,
+        lambda rep, lines, baseline: events.append((baseline, list(lines))),
+        every=60,
+        cycles=4,
+        sleep=sleeper,
+    )
+    assert changes == 1
+    assert events[0] == (True, [])
+    assert events[1][0] is False
+    assert any("risk rose" in line for line in events[1][1])
+
+
+async def test_run_respects_cycles():
+    events = []
+
+    async def run_once():
+        return report()
+
+    async def sleeper(seconds):
+        return None
+
+    changes = await watch.run(
+        "example.com", run_once, lambda *a: events.append(a), every=60, cycles=3, sleep=sleeper
+    )
+    assert changes == 0
+    assert len(events) == 1