gotchu 0.1.0__py3-none-any.whl

gotchu/__init__.py

@@ -0,0 +1,3 @@
+"""gotchu - free, local, read-only checks for downloads and infections."""
+
+__version__ = "0.1.0"

gotchu/__main__.py

@@ -0,0 +1,219 @@
+import argparse
+import json
+import os
+import sys
+
+from . import __version__, check, exposure, harden, report, respond, scan, tripwire
+
+
+def _choose_passphrase(getpass, prompt, nothing):
+    """Ask for a new passphrase twice. None (after saying why) if it is too short or the two differ."""
+    passphrase = getpass.getpass(f"{prompt} (at least 10 characters; a few random words work well): ")
+    if len(passphrase) < 10:
+        print(f"Too short. {nothing}")
+        return None
+    if passphrase != getpass.getpass("Type it again: "):
+        print(f"The two did not match. {nothing}")
+        return None
+    return passphrase
+
+
+RECOVERY_NOTE = ("Write this on paper now and keep it away from this PC. It is shown only once.\n"
+                 "If you forget the passphrase, this key is the only other way in. Lose both and the\n"
+                 "files in the vault are gone for good.")
+
+
+def _vault(args):
+    import getpass
+    import os
+
+    from . import vault
+    try:
+        if args.action == "create":
+            if vault.exists():
+                print("There is already a vault on this PC.")
+                return 1
+            passphrase = _choose_passphrase(getpass, "Choose a passphrase", "Nothing was created.")
+            if passphrase is None:
+                return 1
+            recovery = vault.create(passphrase)
+            print(f"\nVault created in {vault.FOLDER}\n\nRECOVERY KEY:  {recovery}\n\n{RECOVERY_NOTE}")
+            return 0
+        if args.action == "restore":
+            vault.restore(args.folder)
+            print(f"Vault restored from {args.folder}. It opens with the passphrase or recovery key it had when it was backed up.")
+            return 0
+        if not vault.exists():
+            print("There is no vault yet. Make one with: gotchu vault create")
+            return 1
+        if args.action == "backup":
+            count = vault.backup(args.folder)
+            print(f"Copied the vault ({count} files, still encrypted) to {args.folder}.\n"
+                  "The copy is useless without your passphrase or recovery key, so it is safe on a USB stick or in cloud storage.")
+            return 0
+        key = vault.unlock(getpass.getpass("Vault passphrase (or recovery key): "))
+        if args.action == "list":
+            print("\n".join(sorted(vault.names(key))) or "The vault is empty.")
+        elif args.action == "add":
+            for path in args.paths:
+                name = vault.add(key, path, name=args.name if len(args.paths) == 1 else None, move=args.move)
+                print(f"{name}: in the vault" + (", original deleted." if args.move else
+                      f". The original is still at {path} - delete it, or add with --move."))
+            if args.move:
+                print("A deleted file can sometimes be recovered from the disk. If a key was ever exposed, replace it.")
+        elif args.action == "get":
+            target = args.to or args.name
+            if os.path.exists(target):
+                print(f"{target} already exists. Nothing was written.")
+                return 1
+            with open(target, "wb") as f:
+                f.write(vault.get(key, args.name))
+            print(f"Written to {target}. It is an ordinary file again - delete it when you are done.")
+        elif args.action == "use":
+            command = [part for part in args.run if part != "--"]
+            if not command:
+                print("Give the command to run, for example: gotchu vault use server.pem -- ssh -i {} user@host")
+                return 1
+            return vault.use(key, args.name, command)
+        elif args.action == "passphrase":
+            passphrase = _choose_passphrase(getpass, "Choose a new passphrase", "Nothing was changed.")
+            if passphrase is None:
+                return 1
+            vault.change_passphrase(key, passphrase)
+            print("Passphrase changed. The old one no longer opens the vault; your recovery key still does.")
+        elif args.action == "recovery":
+            recovery = vault.replace_recovery(key)
+            print(f"\nNEW RECOVERY KEY:  {recovery}\n\nThe old recovery key no longer opens the vault.\n{RECOVERY_NOTE}")
+        else:
+            vault.remove(key, args.name)
+            print(f"{args.name} removed from the vault.")
+        return 0
+    except vault.WrongSecret:
+        print("That did not open the vault. Nothing was changed.")
+    except KeyError as e:
+        print(e.args[0])
+    except (OSError, ValueError) as e:
+        print(e)
+    return 1
+
+
+def _setup(args):
+    from . import admin
+    ok, message = admin.remove() if args.remove else admin.install()
+    print(message)
+    if ok and not args.remove:
+        if admin.own_folder_writable():
+            print(f"\nNote: gotchu itself is in a folder your account can change ({admin.HERE}). A program running as\n"
+                  "you could change it, including what it asks Windows to run as administrator. For the strongest\n"
+                  "setup, install gotchu with a Python that is installed for all users, in Program Files.")
+        if tripwire.status()["on"]:
+            print("\nThe tripwire is on: run gotchu tripwire --on once more so its watcher uses the new version.")
+    return 0 if ok else 1
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="gotchu", description="Free, local, read-only PC safety checks.")
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    p = sub.add_parser("check", help="inspect a download (zip, folder or file) without running it")
+    p.add_argument("path")
+    p.add_argument("--json", action="store_true", help="print the result as JSON")
+    p = sub.add_parser("scan", help="look for signs that this PC is infected right now")
+    p.add_argument("--json", action="store_true", help="print the result as JSON")
+    p = sub.add_parser("exposure", help="show what a thief could take from this PC right now (counts only)")
+    p.add_argument("--json", action="store_true", help="print the result as JSON")
+    p = sub.add_parser("harden", help="show which Windows protections are on; turn one on or put it back")
+    p.add_argument("--json", action="store_true", help="print the result as JSON")
+    changeable = [k["key"] for k in harden.LOCKS if k["can_apply"]]
+    p.add_argument("--on", choices=changeable, metavar="LOCK", help="turn on: " + ", ".join(changeable))
+    p.add_argument("--undo", choices=changeable, metavar="LOCK", help="put a lock back the way it was")
+    p = sub.add_parser("tripwire", help="decoy files that raise an alarm when a thief reads them")
+    p.add_argument("--json", action="store_true", help="print the result as JSON")
+    p.add_argument("--on", action="store_true", help="plant the decoys and start watching (alert only)")
+    p.add_argument("--cut", action="store_true", help="with --on: also block the reading program from the internet")
+    p.add_argument("--off", action="store_true", help="remove the decoys and put Windows back as it was")
+    p.add_argument("--restore", action="store_true", help="after an alarm: lift the internet blocks and clear the alarm")
+    p = sub.add_parser("vault", help="keep key files encrypted so a stolen copy is useless")
+    act = p.add_subparsers(dest="action", required=True)
+    act.add_parser("create", help="make the vault and choose its passphrase")
+    a = act.add_parser("add", help="encrypt files into the vault")
+    a.add_argument("paths", nargs="+")
+    a.add_argument("--move", action="store_true", help="delete the original once the vault copy is verified")
+    a.add_argument("--name", help="store a single file under another name")
+    act.add_parser("list", help="show what is in the vault")
+    a = act.add_parser("get", help="take a file out as an ordinary file")
+    a.add_argument("name")
+    a.add_argument("--to", help="where to write it (default: this folder)")
+    a = act.add_parser("use", help="run a command with the file present only while it runs")
+    a.add_argument("name")
+    a.add_argument("run", nargs=argparse.REMAINDER, help="the command; {} is replaced by the file's path")
+    a = act.add_parser("remove", help="delete a file from the vault")
+    a.add_argument("name")
+    act.add_parser("passphrase", help="choose a new passphrase (opens with the old one or the recovery key)")
+    act.add_parser("recovery", help="make a new recovery key; the old one stops working")
+    a = act.add_parser("backup", help="copy the vault, still encrypted, to another folder or drive")
+    a.add_argument("folder", help="a new or empty folder")
+    a = act.add_parser("restore", help="bring a backed-up vault back onto a PC that has none")
+    a.add_argument("folder", help="the folder a backup was copied to")
+    p = sub.add_parser("respond", help="after running something bad: what to do, in what order")
+    p.add_argument("--json", action="store_true", help="print the result as JSON")
+    p.add_argument("--sites", action="store_true", help="also list the websites with a password saved on this PC (names only)")
+    p = sub.add_parser("setup", help="install or update gotchu's administrator helpers in Program Files")
+    p.add_argument("--remove", action="store_true", help="remove them, once nothing gotchu turned on still needs them")
+    p = sub.add_parser("ui", help="open the gotchu window in your browser")
+    p.add_argument("path", nargs="?", help="a download to check as soon as the window opens")
+    p.add_argument("--no-browser", action="store_true", help="start without opening a browser")
+    args = parser.parse_args(argv)
+
+    if args.command == "ui":
+        from . import ui
+        return ui.serve(open_browser=not args.no_browser, path=args.path)
+
+    if args.command == "vault":
+        return _vault(args)
+
+    if args.command == "setup":
+        return _setup(args)
+
+    try:
+        return _run(args)
+    except report.CouldNotRun as e:
+        print(e)
+        return 3
+
+
+def _run(args):
+    if args.command == "harden" and (args.on or args.undo):
+        ok, message = harden.change(args.on or args.undo, undo=bool(args.undo))
+        print(message)
+        return 0 if ok else 1
+
+    if args.command == "tripwire" and (args.on or args.off or args.restore):
+        ok, message = tripwire.change("on" if args.on else "off" if args.off else "restore", cut=args.cut)
+        print(message)
+        return 0 if ok else 1
+
+    if args.command == "check":
+        if not os.path.exists(args.path):
+            raise report.CouldNotRun(f"{args.path} does not exist. Check the path and try again.")
+        try:
+            result = check.result(args.path)
+        except OSError as e:
+            raise report.CouldNotRun(f"Windows would not let gotchu read {args.path} ({e.strerror or e}). "
+                                     "Try a copy in your Downloads folder.") from None
+    elif args.command == "tripwire":
+        result = tripwire.result()
+    elif args.command == "exposure":
+        result = exposure.result()
+    elif args.command == "respond":
+        result = respond.result(with_sites=args.sites)
+    else:
+        result = scan.result() if args.command == "scan" else harden.result()
+    print(json.dumps(result, indent=2) if args.json else report.render(result))
+    if args.command == "respond" and args.sites and not args.json:
+        print(f"\nWebsites with a password saved on this PC ({len(result['sites'])}):\n" + "\n".join(result["sites"]))
+    return {"danger": 2, "warn": 1}.get(result["level"], 0)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gotchu/admin.py

@@ -0,0 +1,156 @@
+"""Administrator helpers: the only gotchu code that runs with administrator rights.
+
+They run from C:\\Program Files\\gotchu, which only an administrator can change - never from gotchu's
+own folder, which is often one that any program running as you can change.
+
+They are copied there the first time they are needed, or by `gotchu setup` after an update. After
+that, gotchu will not ask Windows to elevate while its own copy differs from the installed one, so a
+program that edits gotchu's files cannot slip its code into a permission prompt you were expecting.
+
+Limit, stated plainly: if gotchu's own folder is one you can change, a program running as you could
+change gotchu itself. `gotchu setup` says so; installing for all users, in Program Files, closes it.
+"""
+import hashlib
+import os
+import subprocess
+import tempfile
+
+HERE = os.path.dirname(__file__)
+INSTALLED = os.path.join(os.environ.get("ProgramFiles", r"C:\Program Files"), "gotchu")
+HELPERS = ("harden_apply.ps1", "tripwire_apply.ps1", "tripwire_watch.ps1")
+CANCELLED = 1223    # Windows' code for "the user said no"
+UNANSWERED = -1     # ours: the prompt sat unanswered until gotchu stopped waiting
+DECLINED = "Nothing was changed: the Windows permission prompt was declined or closed."
+NO_ANSWER = ("Nothing was changed: the Windows permission prompt was not answered within five minutes. It may be "
+             "behind another window or flashing on the taskbar. If it is still on screen, choose No, then try again.")
+
+
+def _sha256(path):
+    with open(path, "rb") as f:
+        return hashlib.sha256(f.read()).hexdigest().upper()
+
+
+def state(source=HERE, dest=INSTALLED):
+    """'current', 'missing' (not installed yet) or 'different' (installed, but not this copy's version)."""
+    missing = False
+    for name in HELPERS:
+        try:
+            with open(os.path.join(dest, name), "rb") as f:
+                installed = f.read()
+        except FileNotFoundError:
+            missing = True
+            continue
+        with open(os.path.join(source, name), "rb") as f:
+            if f.read() != installed:
+                return "different"
+    return "missing" if missing else "current"
+
+
+def own_folder_writable(folder=HERE):
+    """Can this account change gotchu's own files? Then so can any program it runs."""
+    try:
+        with tempfile.TemporaryFile(dir=folder):
+            return True
+    except OSError:
+        return False
+
+
+def _quote(text):
+    return "'" + text.replace("'", "''") + "'"
+
+
+def launcher(args, elevate=True):
+    """PowerShell that starts powershell.exe with `args` - with administrator rights, after Windows asks -
+    waits for it, and exits with its exit code (CANCELLED if the prompt was declined)."""
+    verb = "-Verb RunAs " if elevate else ""
+    listed = ",".join(_quote(a) for a in args)
+    return (f"try {{ $p = Start-Process powershell.exe {verb}-Wait -PassThru -WindowStyle Hidden -ArgumentList {listed} }} "
+            f"catch {{ exit {CANCELLED} }}; if ($null -eq $p.ExitCode) {{ exit 1 }}; exit $p.ExitCode")
+
+
+def _elevate(args):
+    try:
+        out = subprocess.run(["powershell.exe", "-NoProfile", "-Command", launcher(args)], capture_output=True, timeout=300)
+    except subprocess.TimeoutExpired:
+        return UNANSWERED
+    return out.returncode
+
+
+def _refused(code):
+    """The message for a prompt that was declined or left unanswered; None for any other exit code."""
+    return {CANCELLED: DECLINED, UNANSWERED: NO_ANSWER}.get(code)
+
+
+def install_script(hashes, source=HERE, dest=INSTALLED):
+    """PowerShell, run elevated, that copies the helpers into dest. A copy is kept only if it is exactly the
+    file gotchu read (same SHA-256), so a file swapped in the meantime never stays in Program Files."""
+    pairs = ",".join(f"@({_quote(name)},{_quote(digest)})" for name, digest in hashes.items())
+    return (f"$ErrorActionPreference = 'Stop'; $d = {_quote(dest)}; New-Item -ItemType Directory -Force -Path $d | Out-Null; "
+            f"foreach ($f in @({pairs})) {{ $to = Join-Path $d $f[0]; "
+            f"Copy-Item -LiteralPath (Join-Path {_quote(source)} $f[0]) -Destination $to -Force; "
+            "if ((Get-FileHash -LiteralPath $to -Algorithm SHA256).Hash -ne $f[1]) "
+            "{ Remove-Item -LiteralPath $to -Force; exit 2 } }; exit 0")
+
+
+def install(source=HERE, dest=INSTALLED):
+    """Copy the helpers into Program Files: one Windows permission prompt. Returns (ok, message)."""
+    if state(source, dest) == "current":
+        return True, f"GotchU's administrator helpers in {dest} are installed and up to date."
+    hashes = {name: _sha256(os.path.join(source, name)) for name in HELPERS}
+    script = install_script(hashes, source, dest)
+    code = _elevate(["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command", f'"{script}"'])
+    if _refused(code):
+        return False, _refused(code)
+    if code == 2:
+        return False, ("A helper file changed while it was being installed, so it was removed again. "
+                       "Run gotchu scan, then try again.")
+    if code or state(source, dest) != "current":
+        return False, f"Windows could not install GotchU's administrator helpers in {dest}."
+    return True, f"Installed GotchU's administrator helpers in {dest}."
+
+
+def remove(dest=INSTALLED):
+    """Remove the helpers, but only when nothing gotchu set up still needs them. Returns (ok, message)."""
+    if os.path.exists(os.path.join(dest, "tripwire.json")):
+        return False, "The tripwire is on and uses these helpers. Turn it off first: gotchu tripwire --off"
+    journal = os.path.join(dest, "journal")
+    pending = sorted(os.path.splitext(n)[0] for n in os.listdir(journal)) if os.path.isdir(journal) else []
+    if pending:
+        return False, ("These helpers are needed to put back what GotchU turned on: " + ", ".join(pending)
+                       + ". Undo those first with gotchu harden --undo <lock>.")
+    if not os.path.isdir(dest):
+        return True, "GotchU's administrator helpers are not installed."
+    code = _elevate(["-NoProfile", "-ExecutionPolicy", "Bypass", "-Command",
+                     f'"Remove-Item -LiteralPath {_quote(dest)} -Recurse -Force"'])
+    if _refused(code):
+        return False, _refused(code)
+    if os.path.isdir(dest):
+        return False, f"Windows could not remove {dest}."
+    return True, f"Removed {dest}."
+
+
+def run(script, args):
+    """Run one helper from Program Files with administrator rights; Windows asks the user first.
+
+    The first time, the helpers are installed before that (one more prompt). Returns (ok, message).
+    """
+    current = state()
+    if current == "different":
+        return False, (f"GotchU's administrator helpers in {INSTALLED} are not the ones in this copy of GotchU, "
+                       "so nothing was changed. If you have just updated GotchU, run: gotchu setup. "
+                       "If you have not, something may have changed GotchU's files: run gotchu scan first.")
+    if current == "missing":
+        ok, message = install()
+        if not ok:
+            return False, message
+    code = _elevate(["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", f'"{os.path.join(INSTALLED, script)}"']
+                    + list(args))
+    if _refused(code):
+        return False, _refused(code)
+    if code:
+        try:
+            with open(os.path.join(INSTALLED, "last-error.txt"), encoding="utf-8-sig") as f:
+                return False, "Windows refused the change. " + f.read().strip()
+        except OSError:
+            return False, f"Windows refused the change (code {code})."
+    return True, ""

gotchu/browse.ps1

@@ -0,0 +1,15 @@
+# Shows the standard Windows "pick a file / folder" window and prints the chosen path.
+param([switch]$Folder)
+[Console]::OutputEncoding = [Text.Encoding]::UTF8
+Add-Type -AssemblyName System.Windows.Forms
+$owner = New-Object System.Windows.Forms.Form -Property @{ TopMost = $true; ShowInTaskbar = $false; Opacity = 0 }
+$owner.Show()
+if ($Folder) {
+    $d = New-Object System.Windows.Forms.FolderBrowserDialog
+    if ($d.ShowDialog($owner) -eq 'OK') { $d.SelectedPath }
+} else {
+    $d = New-Object System.Windows.Forms.OpenFileDialog
+    $d.InitialDirectory = Join-Path $env:USERPROFILE 'Downloads'
+    if ($d.ShowDialog($owner) -eq 'OK') { $d.FileName }
+}
+$owner.Close()