ardvane 0.2.0__py3-none-any.whl

ardvane/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+Each version's section becomes its GitHub release notes automatically. To release, raise `VERSION` in
+`app/backend/config.py`, add a section here, and merge the pull request.
+
+## 0.2.0
+
+**Install Ardvane with one command.** No cloning needed.
+
+```bash
+brew install abdul-moiz31/ardvane/ardvane     # macOS (Homebrew)
+pipx install ardvane                          # macOS, Linux and Windows
+```
+
+Then run `ardvane` to open the dashboard.
+
+- New terminal commands: `ardvane scan`, `ardvane check <folder>`, `ardvane protect`, `ardvane unprotect`,
+  `ardvane fixes`, `ardvane launcher`. Run `ardvane --help` for all of them.
+- Published to PyPI automatically with every release (trusted publishing, no stored passwords or tokens), and to
+  Homebrew through the `abdul-moiz31/ardvane` tap, which follows releases by itself.
+- The app icon now opens the installed `ardvane` command, so it keeps working after upgrades.
+
+## 0.1.0
+
+The first release of **Ardvane**: free, open-source protection for developers against malware that spreads through code
+(fake job interviews, malicious packages and the PolinRider worm). Everything runs on your own computer.
+
+**Get started**
+
+```bash
+git clone https://github.com/Abdul-Moiz31/ardvane.git
+cd ardvane
+python3 app/dashboard.py
+```
+
+**What's in 0.1.0**
+
+- **Ardvane dashboard** — status at a glance, scans with live progress, 30-day history, protection switches, reports
+  and offline guides. Runs on `127.0.0.1` only.
+- **Scans your computer** — malware locations, running malware, startup items, attacker connections, editor settings,
+  every git project and installed package.
+- **Blocks infected code** — safe `git clone`, scans on pull / checkout, blocks infected pushes.
+- **Hardening** — editors can't auto-run code from a folder; npm packages can't run install scripts.
+- **Fixes with undo** — ask first (default) or automatic. Malware is quarantined, never deleted.
+- **To-do list** — every finding becomes practical steps; a later scan checks your fix worked; weekly GitHub-account checks.
+- **Daily check** at the time you choose, with a notification.
+- **GitHub account check** (optional) — uses the GitHub CLI when you're logged in; your token stays there.
+
+Platforms: macOS and Linux; Windows is beta. Requires Python 3.8+ and git, nothing else.
+Found a false alarm or tested on Windows? Please open an issue.

ardvane/LICENSE

@@ -0,0 +1,29 @@
+MIT License
+
+Copyright (c) 2026 Abdul Moiz
+
+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.
+
+---
+
+Indicator lists in scanner/lists/ and parts of the detection indicators in
+scanner/checkrepo.py are derived from:
+  - polinrider-cleaner (https://github.com/meSingh/polinrider-cleaner), MIT License
+  - Bedri-B/polinrider (https://github.com/Bedri-B/polinrider), MIT License
+Copyright of those works remains with their respective authors.

ardvane/README.md

@@ -0,0 +1,202 @@
+<div align="center">
+
+<img src="app/ui/icon.png" alt="" width="96" height="96">
+
+# Ardvane
+
+**Free, open-source protection for developers against malware that spreads through code:
+fake job interviews, malicious packages and the PolinRider worm.**
+
+Find it · block it · fix it · and stay on top of it every day. Everything runs on your own computer.
+
+[![Tests](https://github.com/Abdul-Moiz31/ardvane/actions/workflows/tests.yml/badge.svg)](https://github.com/Abdul-Moiz31/ardvane/actions/workflows/tests.yml)
+[![Version](https://img.shields.io/badge/version-0.1.0-blue)](https://github.com/Abdul-Moiz31/ardvane/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+![Platforms](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows%20(beta)-blue)
+![Dependencies](https://img.shields.io/badge/dependencies-none-brightgreen)
+
+[Get started](#get-started) ·
+[What it does](#what-it-does) ·
+[How it protects you](#how-it-protects-you) ·
+[Accuracy](#accuracy) ·
+[I think I'm infected](docs/after-a-scan/if-danger-found.md) ·
+[Contributing](CONTRIBUTING.md)
+
+</div>
+
+---
+
+## Why Ardvane exists
+
+Developers are being targeted by state-sponsored malware (North Korea's *Contagious Interview* campaign) that spreads
+**through code**: fake recruiters with "take-home tests", fake npm packages and malicious editor extensions. Once inside,
+a worm uses your stolen GitHub access to **force-push itself into every repository you can reach**, including your
+teammates' and your company's.
+
+I was hit **three times in five weeks**. A clean reinstall lasted three days. Deleting files, rewriting history and
+revoking tokens didn't stop it, because it kept coming back through infected repositories and collaborators. Ardvane is
+everything that finally worked, packaged so you don't lose the weeks I did. → [Read the story](docs/story)
+
+> 🛑 **Think you're infected right now?** Go to [`docs/after-a-scan/if-danger-found.md`](docs/after-a-scan/if-danger-found.md). The order of the steps matters.
+
+<a id="get-started"></a>
+
+## 🚀 Get started
+
+**1. Install** with one command:
+
+| | |
+|---|---|
+| **macOS** (Homebrew) | `brew install abdul-moiz31/ardvane/ardvane` |
+| **macOS, Linux, Windows** (Python 3.8+) | `pipx install ardvane` |
+
+No pipx yet? `brew install pipx` on a Mac, `py -m pip install --user pipx` on Windows, or use
+`python3 -m pip install --user ardvane` instead.
+
+**2. Open Ardvane:**
+
+```bash
+ardvane
+```
+
+The dashboard opens in your browser and runs **only on your computer**. Press **Scan now**, then:
+
+- **Protection → Turn on protection**: you see every change before it's made
+- **Overview → Daily check**: choose your time (9:00 by default)
+- **Protection → Add app icon**: open Ardvane from Launchpad / the Start menu from now on, no terminal needed
+
+→ [Dashboard guide](docs/dashboard.md)
+
+**Prefer the terminal?**
+
+| Command | What it does |
+|---|---|
+| `ardvane scan` | Read-only scan of this computer and your projects (`--quick` for machine checks only) |
+| `ardvane check <folder>` | Scan one folder before you open it: a download, a coding test, a colleague's repo |
+| `ardvane protect` | Turn on protection (`--dry-run` shows every change first) |
+| `ardvane unprotect` | Remove protection and restore your previous settings |
+| `ardvane fixes` | What Ardvane can fix for you, with undo |
+| `ardvane --help` | Everything else |
+
+The scan ends with ✅ **CLEAN**, ⚠️ **worth a look** or 🛑 **INFECTED**, says exactly what to do next, and saves a report.
+Update with `brew upgrade ardvane` or `pipx upgrade ardvane`.
+
+<details>
+<summary>Run from source instead (contributors, or no Homebrew / pipx)</summary>
+
+```bash
+git clone https://github.com/Abdul-Moiz31/ardvane.git
+cd ardvane
+python3 app/dashboard.py            # = `ardvane`; add a command, e.g. python3 app/dashboard.py scan
+```
+
+The scripts also work on their own: `bash scan-my-machine.sh`, `bash mac/install.sh`, `bash mac/install-routine.sh 9:00`,
+and on Windows (beta) the matching `.ps1` files in `windows/`.
+
+</details>
+
+<a id="what-it-does"></a>
+
+## ✨ What Ardvane does
+
+| | |
+|---|---|
+| 🔍 **Scans your computer** | Malware locations, running malware, startup items, attacker connections, editor settings, every git project and every installed package |
+| 🧱 **Blocks infected code** | `git clone` checks a repository *before* its files are written; `git pull` / `checkout` warn you; `git push` is blocked if a repository contains malware |
+| ⚙️ **Hardens your tools** | VS Code / Cursor can't auto-run code when you open a folder; npm packages can't run install scripts |
+| 🔧 **Fixes, with undo** | Fixes what's safe to fix (editor and npm settings, switched-off protection, malware in known locations), **ask first** by default or **automatic** if you choose. Malware is quarantined, never deleted |
+| ✅ **To-do list** | Every finding becomes a short checklist; a real infection opens the recovery checklist; a later scan checks that your fix worked |
+| ☀️ **Daily check** | Runs at the time you choose, notices if malware switched your protection off, and shows a notification |
+| 🐙 **GitHub account check** *(optional)* | Warns about many repos pushed at once and scans recently pushed branches. Your token stays in the GitHub CLI |
+| 📚 **Guides** | Every attack explained, and step-by-step recovery: cut off access, clean repositories, rotate secrets, harden |
+
+<a id="how-it-protects-you"></a>
+
+## 🛡️ How it protects you
+
+| You do | Ardvane does |
+|---|---|
+| `git clone …` in a terminal | Downloads without writing project files → scans → **blocks** the clone if infected |
+| `git pull`, `git checkout` | Scans and warns you before you open anything |
+| `git push` | **Blocks** the push if the repository contains malware |
+| Open a folder in VS Code / Cursor | Nothing runs on its own (automatic tasks off, Workspace Trust on) |
+| `npm install` | Packages can't run install scripts |
+| Every day at your time | Checks your machine, projects, protections and (optionally) GitHub, then adds anything it finds to your to-do list |
+| `checkrepo <folder>` | Scan anything before you open it: a download, a coding test, a colleague's repo |
+
+A scan takes about **0.1–0.7 seconds per repository**. When everything is clean you won't notice it.
+
+## 🔒 Safe by design
+
+- **Local only.** No account, no telemetry, no cloud. The dashboard listens on `127.0.0.1`, needs a per-session key,
+  and refuses requests from other websites.
+- **Reads, doesn't run.** The scanner only reads files and runs git with hooks and `core.fsmonitor` disabled, so even a
+  booby-trapped repository can't make it execute anything.
+- **Nothing deleted, everything reversible.** You see every change before it's made, fixes can be undone, and malware is
+  quarantined as evidence.
+- **No dependencies.** Python's standard library and plain JavaScript. No npm, no build step, no CDN: what you read
+  here is exactly what runs.
+- **No real malware in this repository.** Tests build synthetic samples at runtime.
+
+<a id="accuracy"></a>
+
+## 📊 Accuracy
+
+The scanner was built from **real malware files** taken from an actual infection, then tuned against clean code:
+
+| Test | Result |
+|---|---|
+| Real malware files (both payload variants, fake fonts, auto-run tasks, droppers) | **71 / 71 detected** |
+| Same files with every known marker switched off (behaviour rules only) | **71 / 71 detected** |
+| 18 popular open-source projects, 106,225 files (Font-Awesome, Babel, Webpack, Prettier, javascript-obfuscator…) | **0 false alarms** |
+| A developer's 14 real projects + all installed packages, ~240,000 files | **0 false alarms** · 1 real infection leftover found |
+| Automated tests: scanner, fixer (incl. attempts to trick it), dashboard security, GitHub check | **97 tests**, run on macOS, Linux and Windows on every change, plus a build-and-install test of the package |
+
+**Honest limits:** Ardvane targets this family of attacks, so a completely new technique may not be detected. That's
+why it also hardens your editor, npm, git and GitHub and checks every day. The Windows scripts are beta. A scan can't
+prove a machine is clean after a backdoor has run; see the [recovery guide](docs/after-a-scan/if-danger-found.md).
+
+## 📁 What's in the repository
+
+```
+ardvane/
+├── app/                        the Ardvane dashboard and `ardvane` command (Python standard library + plain JavaScript)
+├── packaging/                  builds the PyPI package (standard library only)
+├── scan-my-machine.sh / .ps1   one-command, read-only machine scan
+├── scanner/                    detection and fixes: checkrepo, autofix, GitHub check, package lists, git hooks, safe clone, tests
+├── mac/                        install / uninstall / daily check for macOS and Linux
+├── windows/                    the same for Windows (beta)
+└── docs/                       guides: the attacks, recovery, hardening, the story
+```
+
+## 📚 Learn more
+
+- [The attacks](docs/attacks): PolinRider worm, fake job interviews, BeaverTail / InvisibleFerret stealers, the
+  MicrosoftSystem64 backdoor, VS Code auto-run tasks, GlassWorm extensions, malicious npm packages, AI coding-agent
+  attacks, ClickFix, EtherHiding
+- [If you're infected](docs/after-a-scan/if-danger-found.md) · [Cleaning GitHub repositories](docs/after-a-scan/clean-github-repos.md) ·
+  [Secrets rotation](docs/after-a-scan/secrets-rotation-checklist.md) · [Hardening checklist](docs/after-a-scan/hardening-checklist.md)
+- Reference: [Dashboard](docs/dashboard.md) · [checkrepo](docs/checkrepo.md) · [Daily check](docs/daily-routine.md) · [Infected packages](docs/infected-packages.md)
+
+## 🤝 Contributing
+
+Contributions are very welcome, especially **Windows test reports**, **new malicious packages or indicators** (with a
+link to the public report) and **false-alarm reports**. Read [CONTRIBUTING.md](CONTRIBUTING.md), fork, branch, and open a
+pull request; every change needs a test.
+
+Found a security problem in Ardvane itself? Please report it privately; see [SECURITY.md](SECURITY.md).
+
+## 🙏 Credits
+
+Ardvane stands on the work of researchers and other victims who published their findings:
+[OpenSourceMalware](https://github.com/OpenSourceMalware/PolinRider) ·
+[polinrider-cleaner](https://github.com/meSingh/polinrider-cleaner) (MIT, indicator lists) ·
+[Bedri-B/polinrider](https://github.com/Bedri-B/polinrider) (MIT) ·
+[pushwarden](https://github.com/FaheemRafiq/pushwarden) · [gitshield](https://github.com/mirzasaikatahmmed/gitshield) ·
+Palo Alto Networks Unit 42 · Google Threat Intelligence Group · JFrog Security Research · Socket · Elastic Security Labs ·
+Checkmarx · Cloud Security Alliance. Full source lists are at the end of every page in [`docs/attacks`](docs/attacks).
+
+## ⚖️ License and disclaimer
+
+[MIT](LICENSE): use it, share it, adapt it.
+Ardvane reduces risk; it cannot guarantee that a machine is clean or will stay clean. It is provided as-is, without warranty.

ardvane/__init__.py

@@ -0,0 +1 @@
+"""Ardvane: protection against malware that spreads through code. Run `ardvane --help`."""

ardvane/__main__.py

@@ -0,0 +1,21 @@
+"""The `ardvane` command (and `python -m ardvane`) for the installed package (pipx / pip).
+
+The package carries the whole kit (app, scanner, scripts, guides) next to this file, so every feature works exactly
+as it does from a clone of the repository.
+"""
+import os
+import sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+def main():
+    os.environ["ARDVANE_KIT"] = HERE              # where the kit's files are
+    os.environ["ARDVANE_INSTALLED"] = "1"         # tells the app it runs as the installed `ardvane` command
+    sys.path.insert(0, os.path.join(HERE, "app"))
+    from backend.cli import main as cli_main      # noqa: E402 (needs the path above)
+    return cli_main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    sys.exit(main())

ardvane/app/backend/__init__.py

@@ -0,0 +1 @@
+"""Backend of the Ardvane dashboard (Python 3.8+, standard library only)."""

ardvane/app/backend/actions.py

@@ -0,0 +1,90 @@
+"""Changes the user asked for: turn protection on/off, schedule the daily check, show a file, pick a folder.
+
+Each one runs the kit's own, reviewed scripts — the dashboard never edits system settings itself.
+"""
+import os
+import shutil
+import threading
+
+from .config import HOME, IS_MAC, IS_WIN, KIT
+from .system import powershell, powershell_command, run
+
+_picker_lock = threading.Lock()
+PICKER_PROMPT = "Choose a folder with your projects"
+
+
+def scan_command(quick=False, folders=()):
+    """The one-command machine scan for this system (used by the dashboard and by `ardvane scan`)."""
+    if IS_WIN:
+        return powershell_command(os.path.join(KIT, "scan-my-machine.ps1"), *(["-Quick"] if quick else []), *folders)
+    return ["bash", os.path.join(KIT, "scan-my-machine.sh"), *(["--quick"] if quick else []), *folders]
+
+
+def installer_command(action, dry_run=False):
+    """action: 'install' or 'uninstall'; dry_run previews an install without changing anything."""
+    if action not in ("install", "uninstall"):
+        raise ValueError("bad action")
+    preview = dry_run and action == "install"
+    if IS_WIN:
+        return powershell_command(os.path.join(KIT, "windows", action + ".ps1"), *(["-DryRun"] if preview else []))
+    return ["bash", os.path.join(KIT, "mac", action + ".sh"), *(["--dry-run"] if preview else [])]
+
+
+def installer(action, dry_run=False):
+    """Run the installer and capture its output (for the dashboard). Returns (exit code, output)."""
+    return run(installer_command(action, dry_run), timeout=600)
+
+
+def set_routine(on, at="09:00"):
+    if IS_WIN:
+        return powershell(os.path.join(KIT, "windows", "install-routine.ps1"), *(["-At", at] if on else ["-Remove"]), timeout=120)
+    if IS_MAC:
+        return run(["bash", os.path.join(KIT, "mac", "install-routine.sh")] + ([at] if on else ["--remove"]), timeout=120)
+    return 1, ("The scheduled daily check is available on macOS and Windows. On Linux, add this line with `crontab -e`:\n"
+               f"0 9 * * * bash {os.path.join(KIT, 'scan-my-machine.sh')} --quick")
+
+
+def _picker_command():
+    """The system's own folder picker, or None when there isn't one (some Linux setups)."""
+    if IS_MAC:
+        return ["osascript", "-e", "activate", "-e", f'POSIX path of (choose folder with prompt "{PICKER_PROMPT}")']
+    if IS_WIN:
+        script = ("Add-Type -AssemblyName System.Windows.Forms; $d = New-Object System.Windows.Forms.FolderBrowserDialog; "
+                  f"$d.Description = '{PICKER_PROMPT}'; $d.ShowNewFolderButton = $false; "
+                  "$top = New-Object System.Windows.Forms.Form -Property @{TopMost = $true}; "
+                  "if ($d.ShowDialog($top) -eq 'OK') { $d.SelectedPath }")
+        return ["powershell", "-NoProfile", "-STA", "-Command", script]
+    if shutil.which("zenity"):
+        return ["zenity", "--file-selection", "--directory", f"--title={PICKER_PROMPT}"]
+    if shutil.which("kdialog"):
+        return ["kdialog", "--getexistingdirectory", HOME, "--title", PICKER_PROMPT]
+    return None
+
+
+def pick_folder(runner=run):
+    """Open the native folder picker. Returns {"path": "~/..."} | {"cancelled": True} | {"unavailable": True} | {"busy": True}."""
+    cmd = _picker_command()
+    if cmd is None:
+        return {"unavailable": True}
+    if not _picker_lock.acquire(blocking=False):            # one picker at a time
+        return {"busy": True}
+    try:
+        code, out = runner(cmd, timeout=600)
+    finally:
+        _picker_lock.release()
+    path = (out.strip().splitlines() or [""])[-1].strip()
+    if code != 0 or not path or not os.path.isabs(path) or not os.path.isdir(path):
+        return {"cancelled": True}
+    path = os.path.normpath(path)
+    if path == HOME or path.startswith(HOME + os.sep):
+        path = "~" + path[len(HOME):]                       # shorter to read, and the scripts understand ~
+    return {"path": path}
+
+
+def reveal(path):
+    """Show a file or folder in Finder / Explorer / the file manager."""
+    if IS_MAC:
+        return run(["open", "-R", path], timeout=15)
+    if IS_WIN:
+        return run(["explorer", "/select," + os.path.normpath(path)], timeout=15)
+    return run(["xdg-open", path if os.path.isdir(path) else os.path.dirname(path)], timeout=15)

ardvane/app/backend/cli.py

@@ -0,0 +1,146 @@
+"""Start / reuse the dashboard, and the `launcher` sub-command."""
+import http.server
+import json
+import os
+import secrets
+import signal
+import sys
+import threading
+import time
+import urllib.request
+import webbrowser
+
+import subprocess
+
+from . import actions, launcher
+from .config import APP_NAME, IDLE_LIMIT, INSTALLED, INSTANCE, KIT, VERSION
+from .server import App, Handler
+from .system import python_exe, read_json, write_private
+
+PROG = "ardvane" if INSTALLED else "python3 app/dashboard.py"
+USAGE = f"""{APP_NAME} {VERSION}: protection against malware that spreads through code. Runs only on this computer.
+
+  {PROG}                             open the dashboard (add --no-browser to print its address instead)
+  {PROG} scan [--quick] [FOLDER ...]  read-only scan of this computer and your projects
+  {PROG} check [FOLDER]               scan one folder before you open it: a download, a coding test, a colleague's repo
+  {PROG} protect [--dry-run]          turn on protection: git hooks, safe clone, npm and editor hardening
+  {PROG} unprotect                    remove protection and restore your previous settings
+  {PROG} fixes [list | history | fix ID | undo ID]
+                                       fixes Ardvane can make for you, with undo
+  {PROG} launcher [--remove]          add (or remove) the app icon
+  {PROG} --version
+
+The dashboard runs on 127.0.0.1 and stops by itself a few minutes after you close its tab.
+"""
+
+
+def running_instance():
+    """Address of a dashboard that is already running (so a second click reuses it), or None."""
+    info = read_json(INSTANCE, {})
+    port, token = info.get("port"), info.get("token")
+    if not isinstance(port, int) or not isinstance(token, str):
+        return None
+    try:
+        req = urllib.request.Request(f"http://127.0.0.1:{port}/api/ping", headers={"X-Guard-Key": token})
+        with urllib.request.urlopen(req, timeout=2) as r:
+            return f"http://127.0.0.1:{port}/#k={token}" if r.status == 200 else None
+    except Exception:
+        return None
+
+
+def _watchdog():
+    while True:
+        time.sleep(15)
+        scanning = App.job is not None and App.job.finished is None
+        if not scanning and not App.busy and time.time() - App.last_seen > IDLE_LIMIT:
+            App.httpd.shutdown()
+            return
+
+
+def _stop_on_sigterm(signum, frame):
+    """Stopped by the system or `kill`: shut down cleanly, exactly like Ctrl+C."""
+    raise KeyboardInterrupt
+
+
+def serve(open_browser=True, port=0):
+    url = running_instance()
+    if url:
+        print(f"{APP_NAME} is already open.", flush=True)
+        if open_browser:
+            webbrowser.open(url)
+        return 0
+    App.token = secrets.token_urlsafe(32)
+    App.httpd = http.server.ThreadingHTTPServer(("127.0.0.1", port), Handler)
+    App.httpd.daemon_threads = True
+    App.port = App.httpd.server_address[1]
+    App.last_seen = time.time()
+    write_private(INSTANCE, json.dumps({"port": App.port, "token": App.token, "pid": os.getpid()}))
+    url = f"http://127.0.0.1:{App.port}/#k={App.token}"
+    threading.Thread(target=_watchdog, daemon=True).start()
+    signal.signal(signal.SIGTERM, _stop_on_sigterm)
+    print(f"{APP_NAME} is running on this computer only (port {App.port}).", flush=True)
+    print("It stops by itself a few minutes after you close the browser tab, or press Ctrl+C.", flush=True)
+    if open_browser:
+        webbrowser.open(url)
+    else:
+        print("Open this address — it contains your private key, don't share it:", url, flush=True)
+    try:
+        App.httpd.serve_forever(poll_interval=0.5)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        if App.job:
+            App.job.cancel()
+        if read_json(INSTANCE, {}).get("pid") == os.getpid():
+            try:
+                os.remove(INSTANCE)
+            except OSError:
+                pass
+    return 0
+
+
+def _call(cmd):
+    """Run one of the kit's own scripts in this terminal and return its exit code."""
+    try:
+        return subprocess.call(cmd)
+    except KeyboardInterrupt:
+        return 130
+    except OSError as e:
+        print(f"{APP_NAME}: could not start {cmd[0]}: {e}", file=sys.stderr)
+        return 3
+
+
+def _scanner(name, args):
+    return _call([python_exe(), os.path.join(KIT, "scanner", name), *args])
+
+
+# `ardvane <command> ...`: each command runs the same reviewed script the dashboard uses
+COMMANDS = {
+    "scan": lambda a: _call(actions.scan_command("--quick" in a, [x for x in a if x != "--quick"])),
+    "check": lambda a: _scanner("checkrepo.py", a),
+    "protect": lambda a: _call(actions.installer_command("install", "--dry-run" in a)),
+    "unprotect": lambda a: _call(actions.installer_command("uninstall")),
+    "fixes": lambda a: _scanner("autofix.py", a or ["list"]),
+    "launcher": lambda a: print((launcher.remove() if "--remove" in a else launcher.install())[1]) or 0,
+}
+
+
+def main(argv):
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors="replace")
+        except (AttributeError, ValueError):
+            pass
+    if argv[:1] in (["-h"], ["--help"], ["help"]):
+        print(USAGE)
+        return 0
+    if argv[:1] in (["--version"], ["version"]):
+        print(APP_NAME, VERSION)
+        return 0
+    if argv and argv[0] in COMMANDS:
+        return COMMANDS[argv[0]](argv[1:])
+    unknown = [a for a in argv if a != "--no-browser"]
+    if unknown:
+        print(f"unknown command: {unknown[0]}\n\n{USAGE}", file=sys.stderr)
+        return 3
+    return serve(open_browser="--no-browser" not in argv)

ardvane/app/backend/config.py

@@ -0,0 +1,33 @@
+"""Names, paths and constants shared by the whole backend."""
+import os
+import sys
+
+APP_NAME = "Ardvane"                      # the product name lives here and in ui/index.html
+APP_ID = "ardvane"
+VERSION = "0.2.0"
+
+APP_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+KIT = os.environ.get("ARDVANE_KIT") or os.environ.get("POLINRIDER_KIT") or os.path.dirname(APP_DIR)
+INSTALLED = bool(os.environ.get("ARDVANE_INSTALLED"))   # started by the installed `ardvane` command (pipx / Homebrew)
+UI = os.path.join(APP_DIR, "ui")
+
+HOME = os.path.expanduser("~")
+DEST = os.path.join(HOME, ".checkrepo")                 # where the installer puts the scanner, hooks and reports
+REPORTS = os.path.join(DEST, "reports")
+SCANS = os.path.join(REPORTS, "scans")
+SETTINGS = os.path.join(DEST, "settings.json")
+PROJECTS = os.path.join(DEST, "projects.txt")
+INSTANCE = os.path.join(DEST, "dashboard.json")
+TASKS = os.path.join(DEST, "tasks.json")
+
+IS_WIN = os.name == "nt"
+IS_MAC = sys.platform == "darwin"
+OS_NAME = "windows" if IS_WIN else "mac" if IS_MAC else "linux"
+
+# These three keep the project's original name on purpose: installs already on people's computers use them.
+ROUTINE_LABEL = "com.polinrider-survival-kit.daily-check"      # macOS launchd job (mac/install-routine.sh)
+ROUTINE_TASK = "polinrider-survival-kit daily check"           # Windows scheduled task (windows/install-routine.ps1)
+RC_MARKER = "# >>> polinrider-survival-kit >>>"                # block the installer adds to shell profiles
+
+IDLE_LIMIT = 300            # seconds without a request from the tab before the dashboard stops itself
+DEFAULT_FOLDERS = ["~/Documents", "~/Desktop", "~/Downloads", "~/code", "~/projects"] + (["~/source/repos"] if IS_WIN else [])

ardvane/app/backend/docs.py

@@ -0,0 +1,41 @@
+"""The kit's own guides (docs/*.md), served read-only to the Learn page."""
+import os
+
+from .config import KIT
+
+GROUPS = [("If you're infected", "after-a-scan"), ("The attacks", "attacks"), ("The story", "story"), ("Reference", "")]
+ROOT = os.path.join(KIT, "docs")
+
+
+def _title(full, fallback):
+    try:
+        with open(full, encoding="utf-8") as f:
+            for line in f:
+                if line.startswith("# "):
+                    return line[2:].strip()
+    except OSError:
+        pass
+    return fallback
+
+
+def list_all():
+    out = []
+    for group, sub in GROUPS:
+        folder = os.path.join(ROOT, sub)
+        try:
+            names = sorted(n for n in os.listdir(folder) if n.endswith(".md"))
+        except OSError:
+            continue
+        names = (["README.md"] if "README.md" in names else []) + [n for n in names if n != "README.md"]
+        for name in names:
+            rel = f"{sub}/{name}" if sub else name
+            out.append({"group": group, "path": rel, "title": _title(os.path.join(folder, name), name[:-3].replace("-", " ").capitalize())})
+    return out
+
+
+def read(rel):
+    """Text of a guide, or None. Only paths from list_all() are accepted, so nothing outside docs/ can be read."""
+    if rel not in {d["path"] for d in list_all()}:
+        return None
+    with open(os.path.join(ROOT, *rel.split("/")), encoding="utf-8") as f:
+        return f.read()