darkwatch 0.5.1__tar.gz

darkwatch-0.5.1/.dockerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.venv
+node_modules
+vscode-extension
+site
+docs
+tests
+data
+reports
+watchlist.yaml
+.env
+*.vsix
+__pycache__
+*.pyc
+.ruff_cache
+.pytest_cache
+dist

darkwatch-0.5.1/.env.example

@@ -0,0 +1,24 @@
+# Darkwatch secrets. Copy to `.env` next to the watchlist and fill in what you use.
+# Never commit `.env`. Every value here is optional; Darkwatch runs without any of them.
+
+# Have I Been Pwned API key: adds per-email breach and paste lookups. https://haveibeenpwned.com/API/Key
+DARKWATCH_HIBP_KEY=
+
+# ntfy phone push: a long, random topic name (anyone who knows it can read the pushes).
+# Subscribe to the same topic in the ntfy app. https://ntfy.sh
+DARKWATCH_NTFY_TOPIC=
+
+# Webhook for a Discord / Slack style channel (receives the full summary).
+DARKWATCH_WEBHOOK_URL=
+
+# Email alerts (receives the full summary). Port 465 uses implicit TLS; otherwise STARTTLS.
+DARKWATCH_SMTP_HOST=
+DARKWATCH_SMTP_PORT=587
+DARKWATCH_SMTP_STARTTLS=true
+DARKWATCH_SMTP_USER=
+DARKWATCH_SMTP_PASSWORD=
+DARKWATCH_SMTP_FROM=
+DARKWATCH_SMTP_TO=
+
+# Path to tor.exe, if it is not auto-detected (PATH, tools/tor-*/tor/tor.exe, or Tor Browser).
+DARKWATCH_TOR_EXE=

darkwatch-0.5.1/.github/workflows/docker.yml

@@ -0,0 +1,45 @@
+name: Publish Docker image
+
+# Builds the CLI image and pushes it to the GitHub Container Registry on a version tag:
+#   ghcr.io/daemon-vi/darkwatch:<version>  and  :latest
+# Uses the built-in GITHUB_TOKEN — no extra secret. Run by hand for a dry-run build (no push).
+
+on:
+  push:
+    tags:
+      - "v[0-9]*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  image:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - name: Log in to GHCR
+        if: ${{ github.event_name != 'workflow_dispatch' }}
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Tags
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/daemon-vi/darkwatch
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest,enable=${{ github.event_name != 'workflow_dispatch' }}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: ${{ github.event_name != 'workflow_dispatch' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

darkwatch-0.5.1/.github/workflows/pages.yml

@@ -0,0 +1,36 @@
+name: Deploy website
+
+# Publishes site/ to GitHub Pages (https://daemon-vi.github.io/darkwatch/).
+# Runs on a push to main that touches the site, or by hand from the Actions tab.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "site/**"
+      - ".github/workflows/pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4

darkwatch-0.5.1/.github/workflows/publish-vscode.yml

@@ -0,0 +1,46 @@
+name: Publish VS Code extension
+
+# Publishes the extension in vscode-extension/ to the VS Code Marketplace and Open VSX.
+# Trigger by pushing a tag like `vscode-v0.1.0`, or run it by hand from the Actions tab.
+#
+# Set two repository secrets first (Settings -> Secrets and variables -> Actions):
+#   VSCE_PAT  - a Marketplace personal access token for the `daemon-vi` publisher
+#   OVSX_PAT  - an Open VSX access token for the same namespace
+# Each publish step is skipped when its token is absent, so a run with no secrets just
+# packages and uploads the .vsix as a build artifact.
+
+on:
+  push:
+    tags:
+      - "vscode-v*"
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    env:
+      VSCE_PAT: ${{ secrets.VSCE_PAT }}
+      OVSX_PAT: ${{ secrets.OVSX_PAT }}
+    defaults:
+      run:
+        working-directory: vscode-extension
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - run: npm ci
+      - run: npm run compile
+      - run: npm run lint
+      - run: npx vsce package
+      - name: Upload the .vsix as a build artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: darkwatch-vsix
+          path: vscode-extension/*.vsix
+      - name: Publish to the VS Code Marketplace
+        if: ${{ env.VSCE_PAT != '' }}
+        run: npx vsce publish --pat "$VSCE_PAT"
+      - name: Publish to Open VSX
+        if: ${{ env.OVSX_PAT != '' }}
+        run: npx ovsx publish -p "$OVSX_PAT"

darkwatch-0.5.1/.github/workflows/release.yml

@@ -0,0 +1,67 @@
+name: Release
+
+# On a version tag like `v0.5.0`:
+#   - `release` builds and tests, then publishes a GitHub Release carrying the wheel, sdist, the
+#     VS Code extension .vsix and the install scripts (install.ps1 / install.sh install from it).
+#   - `pypi` publishes the wheel and sdist to PyPI via trusted publishing (no token). This needs a
+#     one-time PyPI trusted publisher for project `darkwatch` -> Daemon-VI/darkwatch, workflow
+#     `release.yml`. Until that exists the step fails safely and the GitHub Release still ships.
+# The `vscode-v*` tags are handled by publish-vscode.yml.
+
+on:
+  push:
+    tags:
+      - "v[0-9]*"
+
+jobs:
+  release:
+    runs-on: windows-latest
+    permissions:
+      contents: write
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Test the CLI
+        run: |
+          uv sync --all-extras
+          uv run ruff check src tests scripts
+          uv run pytest -q
+      - name: Check the tag matches the package version
+        run: |
+          version="$(uv run python -c 'import darkwatch; print(darkwatch.__version__)')"
+          test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != version $version"; exit 1; }
+      - name: Build the wheel and sdist
+        run: uv build
+
+      - name: Build the VS Code extension
+        working-directory: vscode-extension
+        run: |
+          npm ci
+          npm run compile
+          npm run lint
+          npx vsce package
+
+      - name: Publish the GitHub Release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* vscode-extension/*.vsix install.ps1 install.sh \
+            --title "Darkwatch $GITHUB_REF_NAME" --notes-file docs/release-notes/$GITHUB_REF_NAME.md
+
+  pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write   # trusted publishing to PyPI, no stored token
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

darkwatch-0.5.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.env
+/data/
+/reports/
+/watchlist.yaml
+.pytest_cache/
+.ruff_cache/

darkwatch-0.5.1/.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+  "// darkwatch": "Run the CLI from this checkout via uv, so the extension works when this folder is open.",
+  "darkwatch.command": ["uv", "run", "darkwatch"],
+  "darkwatch.watchlist": "watchlist.yaml"
+}

darkwatch-0.5.1/Dockerfile

@@ -0,0 +1,31 @@
+# Darkwatch as a container image: the CLI with Tor already inside, for running scans anywhere.
+#
+#   docker run --rm ghcr.io/daemon-vi/darkwatch --help
+#   docker run --rm -v "$PWD/dw:/work" ghcr.io/daemon-vi/darkwatch setup --name "Acme Inc" --company
+#   docker run --rm -v "$PWD/dw:/work" ghcr.io/daemon-vi/darkwatch run
+#
+# The image is for the read-only scan/CLI. The dashboard (`darkwatch web`) binds to loopback by
+# design and is meant to run on your own machine, not exposed from a container.
+
+FROM python:3.12-slim AS build
+WORKDIR /src
+RUN pip install --no-cache-dir build
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN python -m build --wheel --outdir /dist
+
+FROM python:3.12-slim
+LABEL org.opencontainers.image.source="https://github.com/Daemon-VI/darkwatch"
+LABEL org.opencontainers.image.description="Darkwatch — read-only dark web exposure monitor (CLI, with Tor)"
+LABEL org.opencontainers.image.licenses="MIT"
+# tor: the onion sources fetch over it; darkwatch finds `tor` on PATH and manages it per run
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends tor ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+COPY --from=build /dist/*.whl /tmp/
+RUN pip install --no-cache-dir /tmp/*.whl && rm -f /tmp/*.whl
+RUN useradd -m -u 10001 watcher
+USER watcher
+WORKDIR /work
+ENTRYPOINT ["darkwatch"]
+CMD ["--help"]

darkwatch-0.5.1/LICENSE

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

darkwatch-0.5.1/PKG-INFO

@@ -0,0 +1,351 @@
+Metadata-Version: 2.5
+Name: darkwatch
+Version: 0.5.1
+Summary: Darkwatch: watchlist-driven dark web exposure monitor. Finds a person's or company's identifiers on ransomware leak sites, onion pages (over a managed Tor), breach and paste data; scores, dedupes, reports with next actions and alerts.
+Author-email: Rithik Krishna <317035893+Daemon-VI@users.noreply.github.com>
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: fastapi>=0.115
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: requests[socks]>=2.32
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: aiosmtpd>=1.4; extra == 'dev'
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Darkwatch
+
+A dark web exposure monitor for people and companies you are authorised to protect.
+
+**Website: https://rithikkrishnat.me/darkwatch/** · [VS Code extension](https://marketplace.visualstudio.com/items?itemName=daemon-vi.darkwatch) · [Releases](https://github.com/Daemon-VI/darkwatch/releases) · [PyPI](https://pypi.org/project/darkwatch/)
+
+You list identifiers in a watchlist: names, emails, phone numbers, domains, usernames. Darkwatch
+checks them against ransomware leak sites, onion pages fetched over Tor, infostealer logs, and
+breach and paste data. It scores each hit by what surrounds it, remembers what it has already
+reported, and writes a report that says what to do about every hit. New hits trigger a Windows
+notification, and optionally a phone push, a webhook or an email. A scheduled task runs it daily.
+
+There is a local dashboard for everything that is easier to see than to read: keyword search
+across every finding, filters, charts, triage, live scans, and one-off investigations of a value
+that is not on the watchlist. `darkwatch web`, or the "Darkwatch" shortcut on the Desktop.
+
+It only reads. It never logs in, posts, buys, or downloads files, and it keeps no page bodies.
+Per finding it stores the URL, the title, the first and last time it was seen, a short snippet
+around the match, and a hash of the page so a changed page can be recognised — never the page.
+
+## What it searches
+
+Ten sources. Nine of them need no key at all.
+
+| Source | Needs | What it gives |
+|---|---|---|
+| `leaksites` | nothing | Every post that ransomware gangs have made on their leak sites, as crawled by ransomware.live (the full history since 2013, one bulk file cached for 12 hours) and RansomLook (last 30 days). Claim pages are never fetched. |
+| `recentattacks` | nothing | Recently reported cyber-attacks and breaches — gang-claimed or not — from ransomware.live's incident feed, so an incident a victim discloses or the press covers is caught before any leak-site post exists. |
+| `stealers` | nothing | Machines infected by credential-stealing malware that had a watched email, username or domain saved in the browser, via Hudson Rock's Cavalier OSINT API. This is the one source that says *your own machine*, rather than a service you used. The free tier masks the stolen values (`P********3`), which is all Darkwatch wants: enough to recognise the machine, never the credential. |
+| `leakcheck` | nothing | Which breaches hold each email **or username**, and which data classes they exposed (`ssn`, `dob`, `password`, `address`). The only source that answers for a handle, so a person whose strongest identifier is a username is not invisible. |
+| `xposedornot` | nothing | Breaches and pastes that included each email, plus breaches of the service at each watched domain, with the data classes exposed. The free tier allows 25 lookups per hour. |
+| `hibp` | nothing / `DARKWATCH_HIBP_KEY` | Whether a watched domain's own service was breached (free). With a paid key, per-email breaches and pastes too. |
+| `telegram` | nothing | Public Telegram threat-actor and infostealer channels (from the community-maintained deepdarkCTI index, ~940 channels), searched through Telegram's no-login web preview. This is where much leak and stealer-log trading now happens. |
+| `sites` | nothing | Which of 24 public sites carry each watched username — GitHub, X, YouTube, Mastodon, npm, Docker Hub, Hugging Face, Substack, Tumblr and more. A found profile is then read for the person's other identifiers, so a handle leads to the real name or email printed on that page. The checks run in parallel, since each site is a different host. |
+| `ahmia` | Tor for pages | Ahmia's onion search index. With Tor verified, the search itself goes over Tor to Ahmia's onion service, and never over the clearnet (`ahmia_route`). Every listing is checked locally for the exact term, then matching pages are fetched over Tor as text, plus the top 5 per query. |
+| `seeds` | Tor for onion URLs | Pages you choose, re-read every run, with same-host links followed one level deep. |
+
+Every site in `sites` was verified against live responses with a handle known to exist and one
+known to be free; a site that answers 200 for a free handle without a marker that proves absence
+is left out, because it would report every handle as a profile. Add your own with `person_sites`.
+
+## Deep scan
+
+```powershell
+darkwatch run --deep --open
+```
+
+The ordinary run is tuned to finish in a few minutes. `--deep` trades time for reach and can run
+an hour or more:
+
+- **every source**, whatever the watchlist enables;
+- **all ~940 Telegram channels** instead of the first 40;
+- **onion depth raised** — the blind top-N sweep goes 5 → 15 pages per query, on a 2,000-page budget
+  instead of 150;
+- **links followed one level** out of any onion page that already mentions a watched identifier,
+  so Darkwatch reads the actual dark-web site, not just the search listing.
+
+Two things `--deep` still will not do, by design:
+
+- **It never logs in, joins, pays, or solves a CAPTCHA**, so forums and markets that wall their
+  content behind an account (BreachForums successors, XSS, carding markets) are not reached —
+  there is no read-only way in, and creating an account is out of scope.
+- **It never blind-crawls.** Links are followed only *out of pages that already match a watched
+  identifier*, and onion discovery still goes through Ahmia's abuse filter. Darkwatch does not
+  wander an unfiltered index, which is what keeps illegal material off the machine.
+
+## The dashboard
+
+```powershell
+darkwatch web            # opens http://127.0.0.1:8787/?t=<token>
+```
+
+- **Search** every finding by keyword, across the term, title, URL, snippet, signals, target and
+  source. Quote a phrase. Filters for severity, source, status, target and identifier type, with
+  live counts.
+- **Charts**: severity over the last 30 days, the mix by source, and what each run found.
+- **Triage** in place — acknowledge, resolve, mark a false positive — with the recommended
+  actions for each finding.
+- **Run a scan** from the page and watch it happen: progress streams live over server-sent events.
+- **Investigate** any value without adding it to the watchlist. Nothing is stored.
+- **Export** the open findings as CSV or JSON.
+
+It is locked down rather than merely convenient, because it serves personal data over HTTP:
+it binds to loopback only, every API route requires a token minted at start-up (the link the
+command prints carries it once), a non-loopback `Host` header is refused so DNS-rebinding fails,
+no CORS header is ever sent, and changes are POST-only. Untrusted values — a leak-site title, an
+onion page's text — are inserted as text nodes, never as HTML, and evidence URLs are shown but
+never made clickable.
+
+## Install
+
+**Windows** — paste into PowerShell (no administrator rights needed):
+
+```powershell
+irm https://raw.githubusercontent.com/Daemon-VI/darkwatch/main/install.ps1 | iex
+```
+
+**macOS / Linux:**
+
+```sh
+curl -LsSf https://raw.githubusercontent.com/Daemon-VI/darkwatch/main/install.sh | sh
+```
+
+The installer sets up [uv](https://docs.astral.sh/uv/) if you don't have it (uv fetches a
+suitable Python itself), installs the latest release as the `darkwatch` command, asks who to
+watch, offers Desktop shortcuts, and installs the VS Code extension if VS Code is present. Run it
+again at any time to upgrade; your watchlist and findings are kept.
+
+Already have uv? `uv tool install <wheel URL from the latest release>` does the same install.
+
+**From PyPI:**
+
+```sh
+uv tool install darkwatch     # or: pipx install darkwatch
+```
+
+**Docker** — the CLI with Tor already inside, for running scans anywhere (the dashboard stays
+local by design):
+
+```sh
+docker run --rm -v "$PWD/dw:/work" ghcr.io/daemon-vi/darkwatch setup --name "Acme Inc" --company
+docker run --rm -v "$PWD/dw:/work" ghcr.io/daemon-vi/darkwatch run
+```
+
+**Setup.** `darkwatch setup` creates your Darkwatch folder (`~/Darkwatch`, or `DARKWATCH_HOME`)
+with a watchlist for one person or company, asking for their name, emails, domains, usernames
+and phone numbers. It can also run with no prompts:
+`darkwatch setup --name "Asha Rao" --email asha@example.com --username asharao --no-prompt`.
+Every command then finds that watchlist from any folder. A `watchlist.yaml` in the current folder,
+or `--watchlist <file>`, takes precedence. Add more targets by editing the file.
+
+`darkwatch doctor` checks the install and says what is missing.
+
+**From a source checkout** (development):
+
+```powershell
+git clone https://github.com/Daemon-VI/darkwatch.git
+cd darkwatch
+uv sync --all-extras
+uv run darkwatch setup
+uv run pytest -q
+```
+
+**Tor.** Darkwatch starts `tor.exe` for each run when nothing is already listening on the
+proxy port, and stops it afterwards. It finds `tor.exe` in these places, in order:
+
+1. The `tor_exe` setting.
+2. The `DARKWATCH_TOR_EXE` environment variable.
+3. `PATH`.
+4. `tools\tor-*\tor\tor.exe` beside the watchlist (or up to two folders above it), or in the
+   Darkwatch folder — where an unpacked [Tor Expert Bundle](https://www.torproject.org/download/tor/) goes.
+5. A Tor Browser install (Desktop, `%LOCALAPPDATA%` or Program Files), e.g. after
+   `winget install TorProject.TorBrowser`.
+
+Without Tor, every source except the onion page fetches still runs. If Tor Browser is already
+running, point `tor_proxy` at `socks5h://127.0.0.1:9150` and Darkwatch will use it without
+starting its own. Verify a downloaded Tor bundle's signature against the Tor Browser Developers
+key `EF6E 286D DA85 EA2A 4BA7 DE68 4E2C 6E87 9329 8290`.
+
+```powershell
+darkwatch check-tor     # starts Tor if needed, then asks check.torproject.org
+darkwatch sources       # what each source searches and what limits it
+```
+
+**Secrets** live in `.env` beside the watchlist and never in the YAML. See `.env.example`:
+`DARKWATCH_HIBP_KEY`, `DARKWATCH_NTFY_TOPIC`, `DARKWATCH_WEBHOOK_URL`, `DARKWATCH_SMTP_*`.
+
+## Use
+
+```powershell
+darkwatch setup                         # first run: who to watch
+darkwatch doctor                        # check the install
+darkwatch web                        # the dashboard: search, charts, triage, live scans
+darkwatch run --open                 # everything; opens the HTML report at the end
+darkwatch run --sources leaksites    # one source
+darkwatch run --no-tor               # no onion page fetches
+darkwatch search "for sale"          # keyword search over stored findings
+darkwatch hits --json                # stored hits as JSON (for tooling)
+darkwatch search acme --json         # search results + facets as JSON
+darkwatch search --severity CRITICAL,HIGH --source leaksite
+darkwatch search --facets            # counts per severity, source, status, target, type
+darkwatch investigate jane@mail.com  # one value, live sources, nothing stored
+darkwatch hits                       # open hits (new and acknowledged)
+darkwatch hits --min-severity HIGH --snippets
+darkwatch show 12                    # one hit with its recommended actions
+darkwatch ack 12 --note "rotated password"
+darkwatch resolve 12
+darkwatch false-positive 7 --note "different person"
+darkwatch reopen 7
+darkwatch report --open              # rebuild the report from stored hits
+darkwatch runs                       # history: duration, documents, hits, Tor
+darkwatch scan-text dump.txt --save  # check a file you already hold
+darkwatch notify-test                # synthetic alert through every configured channel
+darkwatch shortcut                   # put the Desktop shortcuts in place
+```
+
+From a source checkout, prefix each command with `uv run`.
+
+## Desktop shortcuts
+
+`darkwatch shortcut` puts three shortcuts on your Desktop, so you never need the command line:
+
+- **Darkwatch** starts the dashboard and opens it in your browser. This is the one to use.
+- **Darkwatch - Scan now** runs a scan in a console window and opens the report when it finishes.
+- **Darkwatch - Report** opens the latest report with no console window.
+
+Remove them with `darkwatch shortcut --remove`. They point at the project's own interpreter, so
+nothing has to be on `PATH`.
+
+Reports go to `reports/` as Markdown, HTML and JSON. `latest.*` always holds the newest set,
+and older sets beyond `keep_reports` (60) are deleted. The HTML report follows the system
+light or dark theme and can be filtered by severity.
+
+A hit is one identifier on one piece of evidence: a target, a term, a URL and a source. It is
+reported as new once. Later runs only update its last-seen time. If a later run finds stronger
+evidence at the same URL, the stored evidence is replaced and the hit keeps its triage status.
+If the severity also rises, the hit is escalated: it alerts again, and a resolved hit reopens.
+Reports show only targets that are still in the watchlist.
+
+## Daily runs
+
+```powershell
+darkwatch schedule install --at 09:00   # Task Scheduler: "Darkwatch daily scan"
+darkwatch schedule status
+darkwatch schedule run-now
+darkwatch schedule remove
+```
+
+The task runs the project's `pythonw.exe`, so no console window appears. It runs as you, only
+while you are logged on, which is what lets the notification show. It keeps running on battery
+and starts late if the laptop was off at the scheduled time. Output goes to
+`data/logs/darkwatch.log`. A lock file stops a manual run and the scheduled run from
+overlapping. It is an OS lock, so a killed run never leaves it stuck.
+
+## Alerts
+
+| Channel | Configure with | Receives |
+|---|---|---|
+| Windows notification | `notify.desktop: true` (default) | Counts and target names. Clicking it opens `latest.html`. |
+| ntfy phone push | `notify.ntfy_topic` or `DARKWATCH_NTFY_TOPIC` | Severity counts only, with no names. ntfy topics are readable by anyone who knows the name. Use a long random topic, then subscribe to it in the ntfy app. |
+| Webhook (Discord/Slack) | `DARKWATCH_WEBHOOK_URL` | The full summary, with identifiers and URLs. |
+| Email | `DARKWATCH_SMTP_HOST`, `_PORT`, `_USER`, `_PASSWORD`, `_FROM`, `_TO`, `_STARTTLS` | The full summary. Port 465 uses implicit TLS. Certificates are verified, and Darkwatch never logs in without TLS. |
+
+Only new or escalated hits at or above `notify.min_severity` (default MEDIUM) are sent.
+
+## Severity
+
+A hit's score adds up four parts:
+
+1. **The identifier's weight:** phone 3, email 2, domain 2, name 1, username 1, keyword 1.
+2. **One point per signal group.** There are six: credentials, financial, government ID, sale,
+   doxxing, and access (which covers RDP, VPN, initial access and ransomware wording).
+3. **The evidence's weight:** leak site 4, infostealer infection 4, reported attack 3, onion
+   page 2, seed page 2, breach 2, paste 2, Telegram channel 2, Ahmia listing 1, public profile 0.
+4. **Minus one point if the evidence is at least 3 years old.** The hit is then marked `dated`.
+
+Two things are scored down rather than up, because they were the false positives that mattered:
+a bare run of digits with nothing around it to say it is a phone number, and a single dictionary
+word repeated as a username with no `@handle` context. Both are marked `uncorroborated` and
+credited at most one point, so they surface without shouting.
+
+| Score | Severity |
+|---|---|
+| Under 3 | LOW |
+| 3 to 4 | MEDIUM |
+| 5 to 6 | HIGH |
+| 7 or more | CRITICAL |
+
+Where signals come from depends on the evidence:
+
+- **Onion and seed pages:** the page title plus 160 characters on either side of the match.
+- **Leak-site posts:** the tracker's whole record for that victim — the description, website, sector and country — not the sentence Darkwatch writes around it.
+- **Breaches:** the data classes the breach exposed, such as "Passwords" or "Dates of birth", rather than the prose describing it.
+- **Infostealer infections:** the fact of the infection. A stealer takes saved passwords and session cookies by definition, so that is not something to look for in prose; corporate services on the same machine add the access signal.
+- **Public profiles:** none. A profile a person put up is expected, so it scores LOW; the page's own wording never manufactures a breach signal. It rises only if another source finds the same identifier somewhere worse.
+
+A plaintext combolist is also recognised structurally: two or more `user:pass` lines count as
+credentials even when the page never uses the word.
+
+Every hit lists its signals, so each score can be explained.
+
+## VS Code extension
+
+Install **Darkwatch** (`daemon-vi.darkwatch`) from the VS Code Marketplace or Open VSX — the
+installer above does it for you. It is a thin, safe front end over this CLI, and it walks you
+through the rest: if the CLI is missing, the Darkwatch view offers **Install Darkwatch**; if there
+is no watchlist, **Set Up Darkwatch** asks who to watch; then **Run First Scan**.
+
+- a **Findings** view in the Activity Bar, grouped by severity, with a status-bar count;
+- **Run Scan**, **Deep Scan**, **Open Dashboard**, **Investigate** in a terminal that shows
+  progress live, refreshing the view when the scan ends;
+- **Search** stored findings; **triage** (acknowledge / resolve / false positive) from a
+  finding's menu or the Command Palette;
+- **Open Watchlist**, **Open Latest Report**, **Check Tor**, **Check the Install**.
+
+It finds the CLI by itself (on `PATH`, in `~/.local/bin`, or `uv run` in an open checkout); set
+`darkwatch.command` only to override that. Like the dashboard, it never opens an evidence URL —
+those point at leak sites and onion services — it shows the URL as text and copies it on request.
+Every CLI call is a direct process spawn with no shell. It reads data through
+`darkwatch doctor --json`, `darkwatch hits --json` and `darkwatch search --json`.
+
+Build, test and install it from source:
+
+```powershell
+cd vscode-extension
+npm install
+npm test                   # launches VS Code and drives every view state against the real CLI
+npm run package            # produces darkwatch-<version>.vsix
+code --install-extension darkwatch-0.2.0.vsix
+```
+
+Releases: `.github/workflows/release.yml` builds the wheel and the `.vsix` and makes a GitHub
+Release on a `v*` tag; `.github/workflows/publish-vscode.yml` publishes the extension to the
+Marketplace and Open VSX on a `vscode-v*` tag (see `vscode-extension/PUBLISHING.md`).
+
+## Responsible use
+
+- Monitor only identifiers you own or have written permission to monitor.
+- The report tells you what to do, but it does not do it for you. Actions include changing
+  passwords, turning on MFA, a SIM-swap lock, contacting the bank, reporting at
+  cybercrime.gov.in or on helpline 1930, and CERT-In's 6-hour incident reporting for
+  organisations in India.
+- Preserve evidence with a timestamped Tor Browser screenshot before a page changes. Do not
+  follow links out of a hit or download anything from an onion site. If you come across
+  illegal content, stop and report it.
+
+## Project docs
+
+`docs/PROJECT_STATE.md` records what has been verified, with numbers.
+`docs/ARCHITECTURE.md` explains how the pieces fit and why. `docs/ROADMAP.md` lists what is next.