fiddlesticks 0.0.0__tar.gz → 0.2.0__tar.gz

fiddlesticks-0.2.0/.gitattributes

@@ -0,0 +1,3 @@
+* text eol=lf
+*.kdbx binary
+*.kdbx -text -diff

fiddlesticks-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,38 @@
+name: Tests
+
+on:
+  workflow_dispatch:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        test-case: [
+          "test_is_7zip_installed",
+          "test_alt_chars_candidates_generator",
+          "test_7z_archives_extracted_via_fiddlesticks_CLI",
+          "test_piping_candidates_to_stdout",
+          "test_aegis_checker_from_CLI",
+          "test_aegis_checker_errors_from_CLI",
+          "test_aegis_checker_against_avdu_vault",
+          "test_pykeepass_checker_against_Test_vault",
+        ]
+    steps:
+    - name: Check out repo
+      uses: actions/checkout@v7
+    
+    - name: Set up Python
+      uses: actions/setup-python@v7
+      with:
+        python-version: "3.14"
+    
+    - name: Install dependencies
+      run: |
+        pip install -e .[tests,py7zr,aegis,keepassxc]
+
+    - name: Run PyTest
+      run: |
+        pytest -k ${{ matrix.test-case }}

{fiddlesticks-0.0.0 → fiddlesticks-0.2.0}/.gitignore

@@ -6,5 +6,8 @@ dist/
 wheels/
 *.egg-info
 
+.pytest_cache
+.hypothesis
+
 # Virtual environments
 .venv

{fiddlesticks-0.0.0 → fiddlesticks-0.2.0}/PKG-INFO

@@ -1,12 +1,16 @@
 Metadata-Version: 2.5
 Name: fiddlesticks
-Version: 0.0.0
+Version: 0.2.0
 Summary: Password recovery tool for encrypted archives (currently only .7z files supported).
 Project-URL: GitHub, https://github.com/Hazardous-Area/fiddlesticks
 Author-email: James Parrott <james@jamesparrott.dev>
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.12
+Provides-Extra: aegis
+Requires-Dist: py-avdu; extra == 'aegis'
+Provides-Extra: keepassxc
+Requires-Dist: pykeepass; extra == 'keepassxc'
 Provides-Extra: py7zr
 Requires-Dist: py7zr; extra == 'py7zr'
 Provides-Extra: tests
@@ -16,20 +20,31 @@ Description-Content-Type: text/markdown
 
 # Fiddlesticks!
 *"Aaaagh!  I forgot my 7zip password"* - James (more times than he cares to remember).
+![Tests passing](https://github.com/Hazardous-Area/fiddlesticks/actions/workflows/tests.yml/badge.svg)
+
+Version 0.2.0 
 
 ## Description
 Password recovery tool, for password-encrypted files, using simple off-line brute 
 force attacks.  Password candidates are generated, using common variations 
 of a guessed password (e.g. typos and substitutions).  
 
-### Usage
+### Raison d'etre
  - Password-protected file owners recovering their own password themselves, as long as 
 they can still recall a rough guess for their password, might only need to test 
 every candidate password that's similar enough to the guess.  
  - This may be a much faster and cheaper computation
-than the one an adversary must do, without such a guess, but in posession 
+than the one an adversary must do, without such a guess, but in possession 
 of a stolen password protected file[^0].
 
+### Warning
+Strictly speaking, Fiddlesticks is a password-protected file recovery tool.  Use it to 
+get your files back.  But once you've found a password that protected those files via Fiddlesticks
+(or any third party tool) it should not be used again.  Anywhere else it is also used, the 
+password should be reset (or the files re-encrypted with a different one).  By default,
+Fiddlesticks does not print the password it finds (or any candidates) unless `-P` or `-v` is set 
+(or if using `--pipe` with no pipe).
+
 ### "Back of envelope" sketch 'calculation'
  - Attackers targetting a truly[^0] random password, must try up to `2**N` 
  candidate passwords (for each bit length `N` being considered). 
@@ -46,30 +61,45 @@ archive can also do so - the password wasn't strong enough.
  (e.g. this could indicate that the starting guess was wrong).
 
  ### Design and security notes
+ *"FAQ: Why the heck should anyone in their right mind trust this with their password?"*
  - Any similar 3rd party password cracking service based on 'best guess' passwords, requires 
  the user to share the guesses for their passwords with the service.  Even if the password
  was not used for anything else, sharing even guesses for secret credentials with 3rd parties, 
  is a critical security issue.
- - Fiddlesticks is designed to minimise the need for this.  It is designed to:
-   - a) require as few dependencies as possible,
-   - b) be as easy to install as possible.  
- The intention is firstly b) assists users to run Fiddlesticks in their own secure
- environment, without requiring them to take their password guesses outside of that.  Secondly
- a) helps them decide for themselves whether or not to trust Fiddlesticks 
- in the first place, in particular whether or not it will take their password guesses outside
- of its running environment.  When the project was concieved, the intention was also to design it to:
-  - c) require as little code as possible
- but the code has since become somewhat more complex, mainly in order to have a nice CLI.  Simplicity and brevity should be much more highly prized features of any software.  But you 
- be the judge of whether or not this c) is still the case.
+ - Fiddlesticks is designed to minimise the need for this.  It is designed to i) be as easy 
+ to install as possible, and in particular ii) require as few dependencies as possible.  
+ Firstly, the intention of i) is to assist users to run Fiddlesticks in their own secure
+ environment, locked down as much as they want (e.g. offline and disconnected from 
+ all external network access), without requiring them to take their 
+ password guesses outside of that.  For example, for recovery of password encrypted .7z archives,
+ only a normal installation of 7zip is required on Linux (plus a close enough guess of the password!).
+ Fiddlesticks can even generate a file of candidate passwords, for external programs, and other 
+ possible applications.  Secondly, ii) helps users decide for themselves whether or not to trust Fiddlesticks 
+ in the first place.  In particular whether or not it will take their password guesses outside
+ of its running environment.  When the project was concieved, the intention was also to 
+ iii) require as little code as possible.  But the code base has since become somewhat more 
+ complex, mainly to have a nice CLI.  Simplicity and brevity should both be much 
+ more highly prized features of software in general.  But you 
+ be the judge of whether or not c) is still the case.  The application code is all in a 526 line file.
+
+### Usage
+Recommended use is simply to automate attempts to open a 7z archive via the user's own 7zip.
+Fiddlesticks can also try to decrypt KeepassXC vaults and Aegis vault files (for TOTP authenticators) if 
+[pykeepass](https://pypi.org/project/pykeepass/) and [py-avdu](https://pypi.org/project/py-avdu/) respectively, are 
+also installed.
+
+There are a couple of alternative modes too, firstly: automating any other external Bash command that a candidate password can be appended to (that obeys the normal return code convention).
+
+Secondly with `--pipe` candidate passwords can be sent to stdout, from where they can be piped to a user's own external program or code (all the normal output from fiddlesticks goes to stderr).
 
- - Recommended use is simply to automate attempts to open a 7z archive via the user's own 7zip.
- - There are a couple of alternative modes too, firstly: automating any other external Bash command that a candidate password can be appended to (that obeys the normal return code convention).
- - Secondly candidate passwords can be sent to stdout, from where they can be piped to a
-  user's own external program or code (all the normal output from fiddlesticks goes to stderr).
- - Thirdly, if py7zr is also installed, fiddlesticks can use it to test passwords for 7z archived
+Thirdly, if py7zr is also installed, with `--py7zr` fiddlesticks can use it to test passwords for 7z archives,
  entirely within Python.
 
 ### Other Notes
+ - Successful attempts to extract a password-protected archive, result in the archive being
+ unencrypted (naturally) by some methods.  Currently all such plaintext unencrypted archives 
+ are not deleted from the file system afterwards.  If the options `--extract-to` or `-x` 
+ are given, archives are extracted there.
  - Fiddlesticks cannot recover passwords for online accounts.  Online password entry attempts 
  should be rate limited.  Cracking is only possible locally if the website owner shares the 
  password hash with the user, in which case they can probably provide the rest of their 

{fiddlesticks-0.0.0 → fiddlesticks-0.2.0}/README.md

@@ -1,19 +1,30 @@
 # Fiddlesticks!
 *"Aaaagh!  I forgot my 7zip password"* - James (more times than he cares to remember).
+![Tests passing](https://github.com/Hazardous-Area/fiddlesticks/actions/workflows/tests.yml/badge.svg)
+
+Version 0.2.0 
 
 ## Description
 Password recovery tool, for password-encrypted files, using simple off-line brute 
 force attacks.  Password candidates are generated, using common variations 
 of a guessed password (e.g. typos and substitutions).  
 
-### Usage
+### Raison d'etre
  - Password-protected file owners recovering their own password themselves, as long as 
 they can still recall a rough guess for their password, might only need to test 
 every candidate password that's similar enough to the guess.  
  - This may be a much faster and cheaper computation
-than the one an adversary must do, without such a guess, but in posession 
+than the one an adversary must do, without such a guess, but in possession 
 of a stolen password protected file[^0].
 
+### Warning
+Strictly speaking, Fiddlesticks is a password-protected file recovery tool.  Use it to 
+get your files back.  But once you've found a password that protected those files via Fiddlesticks
+(or any third party tool) it should not be used again.  Anywhere else it is also used, the 
+password should be reset (or the files re-encrypted with a different one).  By default,
+Fiddlesticks does not print the password it finds (or any candidates) unless `-P` or `-v` is set 
+(or if using `--pipe` with no pipe).
+
 ### "Back of envelope" sketch 'calculation'
  - Attackers targetting a truly[^0] random password, must try up to `2**N` 
  candidate passwords (for each bit length `N` being considered). 
@@ -30,30 +41,45 @@ archive can also do so - the password wasn't strong enough.
  (e.g. this could indicate that the starting guess was wrong).
 
  ### Design and security notes
+ *"FAQ: Why the heck should anyone in their right mind trust this with their password?"*
  - Any similar 3rd party password cracking service based on 'best guess' passwords, requires 
  the user to share the guesses for their passwords with the service.  Even if the password
  was not used for anything else, sharing even guesses for secret credentials with 3rd parties, 
  is a critical security issue.
- - Fiddlesticks is designed to minimise the need for this.  It is designed to:
-   - a) require as few dependencies as possible,
-   - b) be as easy to install as possible.  
- The intention is firstly b) assists users to run Fiddlesticks in their own secure
- environment, without requiring them to take their password guesses outside of that.  Secondly
- a) helps them decide for themselves whether or not to trust Fiddlesticks 
- in the first place, in particular whether or not it will take their password guesses outside
- of its running environment.  When the project was concieved, the intention was also to design it to:
-  - c) require as little code as possible
- but the code has since become somewhat more complex, mainly in order to have a nice CLI.  Simplicity and brevity should be much more highly prized features of any software.  But you 
- be the judge of whether or not this c) is still the case.
+ - Fiddlesticks is designed to minimise the need for this.  It is designed to i) be as easy 
+ to install as possible, and in particular ii) require as few dependencies as possible.  
+ Firstly, the intention of i) is to assist users to run Fiddlesticks in their own secure
+ environment, locked down as much as they want (e.g. offline and disconnected from 
+ all external network access), without requiring them to take their 
+ password guesses outside of that.  For example, for recovery of password encrypted .7z archives,
+ only a normal installation of 7zip is required on Linux (plus a close enough guess of the password!).
+ Fiddlesticks can even generate a file of candidate passwords, for external programs, and other 
+ possible applications.  Secondly, ii) helps users decide for themselves whether or not to trust Fiddlesticks 
+ in the first place.  In particular whether or not it will take their password guesses outside
+ of its running environment.  When the project was concieved, the intention was also to 
+ iii) require as little code as possible.  But the code base has since become somewhat more 
+ complex, mainly to have a nice CLI.  Simplicity and brevity should both be much 
+ more highly prized features of software in general.  But you 
+ be the judge of whether or not c) is still the case.  The application code is all in a 526 line file.
+
+### Usage
+Recommended use is simply to automate attempts to open a 7z archive via the user's own 7zip.
+Fiddlesticks can also try to decrypt KeepassXC vaults and Aegis vault files (for TOTP authenticators) if 
+[pykeepass](https://pypi.org/project/pykeepass/) and [py-avdu](https://pypi.org/project/py-avdu/) respectively, are 
+also installed.
+
+There are a couple of alternative modes too, firstly: automating any other external Bash command that a candidate password can be appended to (that obeys the normal return code convention).
+
+Secondly with `--pipe` candidate passwords can be sent to stdout, from where they can be piped to a user's own external program or code (all the normal output from fiddlesticks goes to stderr).
 
- - Recommended use is simply to automate attempts to open a 7z archive via the user's own 7zip.
- - There are a couple of alternative modes too, firstly: automating any other external Bash command that a candidate password can be appended to (that obeys the normal return code convention).
- - Secondly candidate passwords can be sent to stdout, from where they can be piped to a
-  user's own external program or code (all the normal output from fiddlesticks goes to stderr).
- - Thirdly, if py7zr is also installed, fiddlesticks can use it to test passwords for 7z archived
+Thirdly, if py7zr is also installed, with `--py7zr` fiddlesticks can use it to test passwords for 7z archives,
  entirely within Python.
 
 ### Other Notes
+ - Successful attempts to extract a password-protected archive, result in the archive being
+ unencrypted (naturally) by some methods.  Currently all such plaintext unencrypted archives 
+ are not deleted from the file system afterwards.  If the options `--extract-to` or `-x` 
+ are given, archives are extracted there.
  - Fiddlesticks cannot recover passwords for online accounts.  Online password entry attempts 
  should be rate limited.  Cracking is only possible locally if the website owner shares the 
  password hash with the user, in which case they can probably provide the rest of their 

{fiddlesticks-0.0.0 → fiddlesticks-0.2.0}/pyproject.toml

@@ -16,8 +16,11 @@ dynamic=["version"]
 dependencies = []
 
 [project.optional-dependencies]
+py7zr = ["py7zr"]
+aegis = ["py-avdu"]
+keepassxc = ["pykeepass"]
 tests = ["pytest", "hypothesis"]
-py7zr = ["py7zr",]
+
 
 [project.urls]
 GitHub = "https://github.com/Hazardous-Area/fiddlesticks"

{fiddlesticks-0.0.0 → fiddlesticks-0.2.0}/src/fiddlesticks.py

@@ -2,29 +2,30 @@
 # requires-python = ">=3.12"
 # dependencies = []
 # optional_dependencies = [
-#   py7zr = ["py7zr",],
+#   py7zr = ["py7zr"],
+#   aegis = ["py-avdu"],
+#   keepassxc = ["pykeepass"],
+#   tests = ["pytest", "hypothesis"],
 # ]
 # ///
 
-__version__ = "0.0.0"
+__version__ = "0.2.0"
 
 import argparse
 import atexit
 import collections
-import functools
 import getpass
 import io
 import itertools
-from pathlib import Path
 import string
 import subprocess
 import sys
 import tempfile
 import textwrap
 import time
-from typing import Iterator, Iterable, Collection, Hashable, Callable
 import warnings
-
+from collections.abc import Callable, Hashable, Iterable, Iterator
+from pathlib import Path
 
 TMP_DIR = Path(tempfile.gettempdir()) / "fiddlesticks"
 TMP_DIR.mkdir(exist_ok=True)
@@ -144,18 +145,24 @@ def candidate_passwords_from_alt_chars(
 
 def make_py7zr_checker(archive: str, extract_to: str | None = None, **kwargs):
     import py7zr
+    exceptions = (py7zr.exceptions.PasswordRequired, py7zr.exceptions.Bad7zFile)
+    try:
+        import _lzma
+    except ImportError:
+        pass
+    else:
+        exceptions += ( _lzma.LZMAError,)
     if extract_to is None:
         extract_to = str(_make_new_tmp_sub_dir(archive))
     stream = io.BytesIO(Path(archive).read_bytes())
-    def is_correct_password_for_7z_file(candidate: str, ) -> bool:
+    def is_correct_password_for_7z_file(candidate: str) -> bool:
         stream.seek(0)
         try:
             f = py7zr.SevenZipFile(stream, 'r', password=candidate)
             f.extractall(path=extract_to)
-        except (py7zr.exceptions.PasswordRequired, py7zr.exceptions.Bad7zFile):
+        except exceptions:
             return False
-        else:
-            f.close()
+        f.close()
         return True
     return is_correct_password_for_7z_file
 
@@ -163,7 +170,7 @@ def make_py7zr_checker(archive: str, extract_to: str | None = None, **kwargs):
 def make_subprocess_checker(*args: str, **kwargs):
     *rest, last = args
     def is_correct_password(candidate: str) -> bool:
-        result = subprocess.run([*rest, f"{last}{candidate}"], capture_output=True)
+        result = subprocess.run([*rest, f"{last}{candidate}"], capture_output=True, check=False)
         return result.returncode==0
     return is_correct_password
 
@@ -181,7 +188,7 @@ class ProgramNotFound(Exception): pass
 
 def make_7zip_checker(file: str, extract_to: str | None = None, **kwargs):
     args = ["7z", "--help"]
-    result =subprocess.run(args, capture_output=True)
+    result = subprocess.run(args, capture_output=True, check=False)
     if result.returncode != 0:
         raise ProgramNotFound(f"7zip.  Args: {args}")
 
@@ -190,19 +197,16 @@ def make_7zip_checker(file: str, extract_to: str | None = None, **kwargs):
 
     return make_subprocess_checker("7z","x", f"-o{extract_to}", file, "-p")
 
-def make_password_candidate_piper(**kwargs):
+def make_password_candidate_piper(*args, **kwargs):
     def piper(password: str):
         print(password, file=sys.stdout)
         return False
     return piper
 
-def make_persistent_7zip_checker(file: str, extract_to: str | None = None, **kwargs):
-    if extract_to is None:
-        extract_to = str(_make_new_tmp_sub_dir(file))
+PERSISTENT_7Z_CHECKER_OUTLINE = """\
+#!/usr/bin/env bash
 
-    cmd = textwrap.dedent(f"""\
-    while read -r line; do
-    
+while read -r line; do
     # Silently run command, only check exit code
     7z x -o{extract_to} {file} -p"$line" > /dev/null 2>&1
     if [ $? -eq 0 ]; then
@@ -210,8 +214,14 @@ def make_persistent_7zip_checker(file: str, extract_to: str | None = None, **kwa
         break
     fi
     echo "Nope :("
-    done
-    """)
+done
+"""
+
+def make_persistent_7zip_checker(file: str, extract_to: str | None = None, **kwargs):
+    if extract_to is None:
+        extract_to = str(_make_new_tmp_sub_dir(file))
+
+    cmd = textwrap.dedent(PERSISTENT_7Z_CHECKER_OUTLINE.format(extract_to=extract_to, file=file))
 
     # Launch a single persistent Bash process reading from stdin line-by-line
     proc = subprocess.Popen(
@@ -239,6 +249,42 @@ def make_persistent_7zip_checker(file: str, extract_to: str | None = None, **kwa
     return checker
 
 
+def make_py_avdu_aegis_checker(file: str, **kwargs):
+
+    import json
+
+    from py_avdu.encrypted_classes import VaultEncrypted
+
+    vault_dict = json.loads(Path(file).read_text())
+
+    encrypted = VaultEncrypted(**vault_dict)
+
+    def checker(candidate: str) -> bool:
+        try:
+            encrypted.find_master_key(candidate)
+            return True
+        except ValueError:
+            return False
+        
+
+    return checker
+
+def make_pykeepass_checker(file: str, **kwargs):
+
+    from pykeepass import PyKeePass
+    from pykeepass.exceptions import CredentialsError
+
+    def checker(candidate: str) -> bool:
+        try:
+            PyKeePass(file, password=candidate)
+            return True
+        except CredentialsError:
+            return False
+        
+
+    return checker
+
+
 def test_passwords_sequentially(
     candidates: Iterable[str],
     test_func: Callable[[str], bool],
@@ -274,6 +320,9 @@ def test_passwords_sequentially(
 
 default_password_protected_file_checker_factories = {
     ".7z" : make_7zip_checker,
+    ".json" : make_py_avdu_aegis_checker,
+    ".kdbx" : make_pykeepass_checker,
+    ".kdb" : make_pykeepass_checker,
 }
 
 
@@ -398,6 +447,8 @@ add_checker_factory_arg("--7zip", make_7zip_checker)
 add_checker_factory_arg("--7zip-persistent", make_persistent_7zip_checker)
 add_checker_factory_arg("--shell", make_subprocess_checker)
 add_checker_factory_arg("--py7zr", make_py7zr_checker)
+add_checker_factory_arg("--aegis", make_py_avdu_aegis_checker)
+add_checker_factory_arg("--keypassxc", make_pykeepass_checker)
 add_checker_factory_arg(
     "--pipe",
     make_password_candidate_piper,
@@ -453,7 +504,10 @@ def cli(args: list[str] = sys.argv[1:]) -> int:
     t1 = time.time()
 
     if result is None:
-        print_to_stderr(f"\n\nCould not find password. Try a different guess, or increasing max substitutions (-N) ? ")
+        if namespace.checker_factory is make_password_candidate_piper:
+            return 0
+
+        print_to_stderr("\n\nCould not find password. Try a different guess, or increasing max substitutions (-N) ? ")
         return 1
 
 

fiddlesticks-0.2.0/tests/checker_tests.py

@@ -0,0 +1,29 @@
+import subprocess
+
+import pytest
+
+from fiddlesticks import make_py_avdu_aegis_checker, make_pykeepass_checker
+
+from .helpers import IS_WINDOWS, KDBX_TEST_VAULT, avdu_test_vault
+
+
+@pytest.mark.skipif(IS_WINDOWS, reason="I haven't figured out the 7zip CLI on Windows yet")
+def test_is_7zip_installed():
+    args = ["7z", "--help"]
+    subprocess.check_call(args)
+
+
+def test_aegis_checker_against_avdu_vault(avdu_test_vault):
+    checker = make_py_avdu_aegis_checker(avdu_test_vault)
+    # """
+    # # Run using the encrypted test file. (Enter password "test" when prompted.)
+    # go run ./cmd/avdu -p test/data/aegis_encrypted.json -e
+    # https://github.com/Sammy-T/avdu/blob/master/README.md
+    # """
+    assert checker("test")
+    assert not checker("wrong_password")
+
+def test_pykeepass_checker_against_Test_vault():
+    checker = make_pykeepass_checker(KDBX_TEST_VAULT)
+    assert checker("test")
+    assert not checker("wrong_password")

fiddlesticks-0.2.0/tests/end_to_end_tests.py

@@ -0,0 +1,252 @@
+import shlex
+import shutil
+import stat
+import subprocess
+import tempfile
+from collections.abc import Callable
+from pathlib import Path
+
+import pytest
+from hypothesis import HealthCheck, Phase, given, settings
+
+import fiddlesticks
+
+from .helpers import (
+    IS_WINDOWS,
+    avdu_test_vault,
+    _assert_candidate_within_M_of_pwd,
+    _assert_files_same,
+    _create_password_protected_7z_archive,
+    file_names_and_contents,
+    guesses_and_num_subs_from_password,
+    passwords_guesses_and_num_subs,
+)
+
+
+def _collate_args(
+    num_subs: int,
+    guess: str,
+    *args: str,
+    shell: bool = False,
+    ) -> list[str]:
+    pwd_arg = f"--password-guess={guess}"
+    if shell:
+        pwd_arg = shlex.quote(pwd_arg)
+    return [
+        "fiddlesticks",
+        "--max-subs", f"{num_subs}",
+        pwd_arg,
+        *args,
+    ]
+
+def make_internal_checker_args_collater(
+    checker: str,
+    ) -> Callable[[int, Path, str, str], list[str]]:
+    def collater(num_subs: int, test_extracted_dir: Path, guess: str, archive: str):
+        return _collate_args(
+            num_subs,
+            guess,
+            checker, 
+            f"--extract-to={test_extracted_dir}", 
+            archive,
+        )
+    return collater
+
+def shell_collater(num_subs: int, test_extracted_dir: Path, guess: str, archive: str):
+    return _collate_args(
+        num_subs,
+        guess,
+        "--shell", 
+        "--", # Tell argparse all subsequent args are positional
+        "7z", # Taken from make_7zip_checker
+        "x",
+        f"-o{test_extracted_dir}",
+        archive,
+        "-p",
+    )
+
+def pipe_to_bash_while_loop_collater(
+    num_subs: int,
+    test_extracted_dir: Path,
+    guess: str,
+    archive: str):
+
+    script_text = fiddlesticks.PERSISTENT_7Z_CHECKER_OUTLINE.format(
+        extract_to=str(test_extracted_dir),
+        file=archive,
+    )
+    script = Path("persistent_checker.sh")
+    script.write_text(script_text)
+    script.chmod(script.stat().st_mode | stat.S_IXUSR | stat.S_IRUSR)
+
+    return _collate_args(
+        num_subs,
+        guess,
+        "--pipe",
+        "--",
+        "|",
+        str(script.resolve()),
+        shell=True,
+    )
+
+@pytest.mark.hypothesis
+@pytest.mark.slow
+@pytest.mark.skipif(IS_WINDOWS, reason="I haven't figured out the 7zip CLI on Windows yet")
+@settings(
+    max_examples=5,
+    suppress_health_check=[HealthCheck.too_slow, HealthCheck.data_too_large],
+    deadline=None,
+    database=None,
+    derandomize=True, # Without this, the test doesn't complete in less than 5 mins in Github Actions 
+    # (despite that the default is True in CI ???
+    # https://hypothesis.readthedocs.io/en/latest/reference/api.html#hypothesis.settings.derandomize )
+)
+@pytest.mark.parametrize("make_args,shell",[
+    (make_internal_checker_args_collater("--7zip"), False),
+    (make_internal_checker_args_collater("--7zip-persistent"), False),
+    (make_internal_checker_args_collater("--py7zr"), False),
+    (shell_collater,False),
+    (pipe_to_bash_while_loop_collater,True),
+])
+@given(
+    file_names_and_contents=file_names_and_contents,
+    password_guess_and_num_subs=passwords_guesses_and_num_subs(max_num_subs=3),
+)
+def test_7z_archives_extracted_via_fiddlesticks_CLI(
+    file_names_and_contents: list[tuple[str, bytes]],
+    password_guess_and_num_subs: tuple[str,str,int],
+    make_args: Callable[[int, Path, str,str], list[str]],
+    shell: bool,
+):  
+
+    password, guess, num_subs = password_guess_and_num_subs
+
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmp_path = Path(tmpdir)
+
+        archive_dir = tmp_path / "contents"
+
+        _create_password_protected_7z_archive(
+            archive_dir,
+            file_names_and_contents,
+            password,
+        )
+
+        archive = str(tmp_path / "archive.7z")
+
+        result = subprocess.run(
+            ["7z", "a", "-mhe=on", f"-p{password}", archive, str(archive_dir)],
+            capture_output=True,
+            check=False,
+        )
+        assert result.returncode == 0, f"Could not create 7z archive from: {password=}, containing: {file_names_and_contents}"
+
+        test_extracted_dir = tmp_path / "test_extracted"
+        test_extracted_dir.mkdir()
+
+        # Test if extraction directly with 7z actually works in the test env,
+        # before testing if fiddlesticks can do this too.
+        result = subprocess.run(
+            ["7z", "x", f"-p{password}", f"-o{test_extracted_dir}", archive],
+            capture_output=True,
+            check=False,
+        )
+        assert result.returncode == 0, f"Could not extract {archive} with known good: {password=}, with 7z directly"
+
+        _assert_files_same(test_extracted_dir / "contents", file_names_and_contents)
+
+        shutil.rmtree(test_extracted_dir)
+        test_extracted_dir.mkdir()
+
+        cmd_args = make_args(num_subs, test_extracted_dir, guess, archive)
+        if shell:
+            cmd_args = " ".join(cmd_args)
+        result = subprocess.run(
+            cmd_args,
+            capture_output=True,
+            check=False,
+            shell=shell,
+        )
+        assert result.returncode==0, f"Could not crack: {password} from: {guess=} for {archive}, {num_subs=}"
+
+        _assert_files_same(test_extracted_dir / "contents", file_names_and_contents)
+
+
+
+@pytest.mark.hypothesis
+@pytest.mark.slow
+@pytest.mark.skipif(IS_WINDOWS, reason="I haven't figured out the 7zip CLI on Windows yet")
+@settings(
+    max_examples=10,
+    phases=[Phase.explicit, Phase.reuse, Phase.generate],  # Skip shrinking
+    suppress_health_check=[HealthCheck.too_slow, HealthCheck.data_too_large],
+    deadline=None,
+    # derandomize=True, # Without this, the test doesn't complete in less than 5 mins in Github Actions 
+    # # (despite that the default is True in CI ???
+    # # https://hypothesis.readthedocs.io/en/latest/reference/api.html#hypothesis.settings.derandomize )
+)
+@given(
+    password_guess_and_num_subs=passwords_guesses_and_num_subs(max_num_subs=5),
+)
+def test_piping_candidates_to_stdout(
+    password_guess_and_num_subs: tuple[str,str,int],
+):  
+
+    password, guess, num_subs = password_guess_and_num_subs
+
+    result = subprocess.run(
+        _collate_args(num_subs, guess, "--pipe"),
+        capture_output=True,
+        check=False,
+    )
+    assert result.returncode==0, f"Could not --pipe candidate passwords, {num_subs=}, {guess=}"
+
+    candidates = set()
+    for candidate in result.stdout.decode().splitlines():
+        _assert_candidate_within_M_of_pwd(candidate, guess, M=num_subs)
+        candidates.add(candidate)
+
+    assert password in candidates, f"Did not find {password=} from {guess=}, {num_subs=}, {candidates=}"
+
+# """
+# # Run using the encrypted test file. (Enter password "test" when prompted.)
+# go run ./cmd/avdu -p test/data/aegis_encrypted.json -e
+# https://github.com/Sammy-T/avdu/blob/master/README.md
+# """
+@pytest.mark.hypothesis
+@pytest.mark.slow
+@given(guess_and_num_subs=guesses_and_num_subs_from_password("test", max_num_subs=4))
+@settings(
+    max_examples=10,
+    phases=[Phase.explicit, Phase.reuse, Phase.generate],  # Skip shrinking
+    suppress_health_check=[HealthCheck.too_slow, HealthCheck.data_too_large],
+    deadline=None,
+    # derandomize=True, # Without this, the test doesn't complete in less than 5 mins in Github Actions 
+    # # (despite that the default is True in CI ???
+    # # https://hypothesis.readthedocs.io/en/latest/reference/api.html#hypothesis.settings.derandomize )
+)
+def test_aegis_checker_from_CLI(guess_and_num_subs, avdu_test_vault):    
+    guess, num_subs = guess_and_num_subs
+    result = subprocess.run(
+        _collate_args(num_subs, guess, "--aegis", str(avdu_test_vault)),
+        capture_output=True,
+        check=False,    
+    )
+    assert result.returncode==0, f"Using Aegis encrypted vault checker, could not find 'test' from {guess=}, {num_subs=}"
+
+
+def test_aegis_checker_errors_from_CLI(avdu_test_vault):
+    num_subs = 4
+    guess = "abcd", # i.e. not "test" (but not too long either)
+    result = subprocess.run(
+        _collate_args(
+            num_subs,
+            guess,
+            "--aegis",
+            str(avdu_test_vault),
+        ),
+        capture_output=True,
+        check=False,    
+    )
+    assert result.returncode != 0, f"Failed to error on bad {guess=}, or unexpectedly found password ('test') of Aegis encrypted vault checker, {num_subs=}"

fiddlesticks-0.2.0/tests/helpers.py

@@ -0,0 +1,166 @@
+
+import string
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from hypothesis.strategies import (
+    binary,
+    composite,  # Can be slow
+    integers,
+    lists,
+    sampled_from,
+    text,
+    tuples,
+)
+
+import fiddlesticks
+
+IS_WINDOWS = sys.platform == "win32"
+BI_MAP = fiddlesticks.SHIFT_AND_LEET_BI_MAP
+KDBX_TEST_VAULT = Path(__file__).parent / "Test_vault_Do_Not_Use.kdbx"
+
+file_names = text(
+    alphabet=string.ascii_letters + string.digits,
+    # characters(
+    #     codec="ascii",
+    #     exclude_categories=["Cs", "Co", "Cn"],
+    # ),
+    min_size=1,
+    max_size=24,
+)
+file_names_and_contents = lists(
+    tuples(file_names, binary(min_size=1, max_size=1024)),
+    min_size=1,
+    max_size=20,
+    unique_by=lambda x: x[0],
+)
+
+password_chars = set(string.ascii_letters + string.digits + string.punctuation)
+
+# We use single quotes to pass the PW guess as a Bash literal string.  
+# Otherwise much more complicated escaping rules are required.
+password_chars -= {"'"}
+
+passwords = text(
+    alphabet="".join(password_chars),
+    min_size=1,
+    max_size=40,
+)
+
+
+def _create_password_protected_7z_archive(
+    dir_: Path,
+    file_names_and_contents: list[tuple[str, bytes]],
+    password: str,
+):
+    dir_.mkdir(exist_ok=True, parents=True)
+    for file_name, content in file_names_and_contents:
+        (dir_ / file_name).write_bytes(content)
+
+def _assert_files_same(
+    dir_: Path,
+    file_names_and_contents: list[tuple[str, bytes]],
+):
+    for file_name, content in file_names_and_contents:
+        actual = (dir_ / file_name).read_bytes()
+        assert actual == content, f"File did not round trip.  Expected: {content=}.  Got: {actual=}"
+
+@composite
+def _alts_and_num_subs_from_password(
+    draw,
+    password: str,
+    max_num_subs: int = 3,
+    ):
+
+    all_alts = []
+    for i, c in enumerate(password):
+        alts = set(BI_MAP.get(c))
+        # To allow passing of PW guesses in single quotes via Bash, 
+        alts -= {"'"}
+        if alts:
+            all_alts.append((i, "".join(alts)))
+
+    num_subs = draw(integers(min_value=0, max_value=min(max_num_subs, len(all_alts))))
+
+    selected_alts = draw(
+        lists(
+            sampled_from(all_alts),
+            min_size=num_subs,
+            max_size=num_subs,
+            unique=True,
+        )
+    )
+    return selected_alts, num_subs
+
+@composite
+def selected_alts_and_num_subs_from_password(
+    draw,
+    password: str,
+    max_num_subs: int = 3,
+    ):
+    selected_alts, num_subs = draw(_alts_and_num_subs_from_password(password, max_num_subs))
+    return selected_alts, num_subs
+
+@composite
+def guesses_from_alts(
+    draw,
+    password: str,
+    selected_alts: list[tuple[int,str]],
+    ):
+    
+    chars = list(password)
+    for i, alts in selected_alts:
+        chars[i] = draw(sampled_from(alts))
+    return "".join(chars)
+
+@composite
+def guesses_and_num_subs_from_password(
+    draw,
+    password: str,
+    max_num_subs: int = 3,
+    ):
+    selected_alts, num_subs = draw(selected_alts_and_num_subs_from_password(password, max_num_subs))
+    guess = draw(guesses_from_alts(password, selected_alts))
+    return guess, num_subs
+
+@composite
+def passwords_guesses_and_num_subs(
+    draw,
+    max_num_subs: int = 3,
+    ):
+    
+    password = draw(passwords)
+    guess, num_subs = draw(guesses_and_num_subs_from_password(password, max_num_subs))
+    return password, guess, num_subs
+
+
+
+
+def _assert_candidate_within_M_of_pwd(candidate: str, pwd: str, M: int) -> None:
+    # Current implementation preserves length
+    assert len(pwd) == len(candidate)
+    i = 0
+    for c1, c2 in zip(pwd, candidate):
+        if c1 != c2:
+            i += 1
+            assert c2 in BI_MAP[c1], f"Unrelated: {c1}, {c2}"
+    assert i <= M
+
+
+@pytest.fixture(scope="session")
+def avdu_test_vault(tmp_path_factory):
+    avdu_repo = tmp_path_factory.mktemp("avdu")
+    subprocess.run(
+        ["git",
+         "clone",
+         "--depth=1",
+         "https://github.com/Sammy-T/avdu/",
+         str(avdu_repo),
+        ],
+        check=True,
+        capture_output=True,
+    )
+    return avdu_repo / "test" / "data" / "aegis_encrypted.json"
+    

fiddlesticks-0.2.0/tests/pw_generator_tests.py

@@ -0,0 +1,24 @@
+
+import pytest
+from hypothesis import HealthCheck, given, settings
+
+import fiddlesticks
+
+from .helpers import (
+    _assert_candidate_within_M_of_pwd,
+    passwords_guesses_and_num_subs,
+)
+
+
+@pytest.mark.hypothesis
+@pytest.mark.slow
+@given(password_guess_and_num_subs=passwords_guesses_and_num_subs(max_num_subs=10))
+@settings(
+    deadline=None,
+    suppress_health_check=[HealthCheck.too_slow, HealthCheck.data_too_large],
+)
+def test_alt_chars_candidates_generator(password_guess_and_num_subs: tuple[str,list[tuple[int,str]],int]):
+    pwd, _guesses, M = password_guess_and_num_subs
+    _total, candidates = fiddlesticks.candidate_passwords_from_alt_chars(pwd, M)
+    for candidate in candidates:
+        _assert_candidate_within_M_of_pwd(candidate, pwd, M)

{fiddlesticks-0.0.0 → fiddlesticks-0.2.0}/tests/smoke_tests.py

@@ -1,5 +1,6 @@
 from fiddlesticks import candidate_passwords_from_alt_chars as candidates
-    
+
+
 def smoke_test():
     guesses = set(candidates("password123", max_subs=2))
     assert 'password12£' in guesses

fiddlesticks-0.0.0/.gitattributes

@@ -1 +0,0 @@
-* text eol=lf

fiddlesticks-0.0.0/.hypothesis/.gitignore

@@ -1,9 +0,0 @@
-# This .gitignore file was automatically created by Hypothesis. Hypothesis gitignores
-# .hypothesis by default, because we generally recommend that .hypothesis not be checked
-# into version control.
-#
-# If you *would* like to check .hypothesis into version control, you should delete this
-# file. Hypothesis will not re-create this .gitignore unless .hypothesis is deleted (and
-# if it does, that's a bug - please report it!)
-
-*

fiddlesticks-0.0.0/.hypothesis/constants/628818e30619470c

@@ -1,4 +0,0 @@
-# file: C:\Users\drjam\Coding\repos\fiddlesticks\src\fiddlesticks.py
-# hypothesis_version: 6.165.10
-
-[300, 1000, '!', '#', '#£', '$', '%', '&', "'", '(', ')', '*', '+', ',', '-', '--7zip', '--7zip-persistent', '--aegis-pyavdu', '--extract-to', '--help', '--max-subs', '--output-file', '--password-guess', '--pipe', '--print-passwords', '--py7zr', '--shell', '--shift_and_leet', '--verbosity', '-N', '-P', '-c', '-o', '-p', '-v', '-x', '.', '.7z', '/', '0', '0.0.0', '1', '2', '3', '4', '4@', '5', '6', '7', '7z', '8', '9', ':', ';', '<', '=', '>', '?', '@', '@"', 'Character map', 'Password checker', 'Success', '[', '\\', ']', '^', '_', '__main__', '`', 'a', 'alt_char_map', 'at', 'b', 'bash', 'checker_factory', 'count', 'e', 'extend', 'extras', 'fiddlesticks', 'g', 'i', 'o', 'output_file', 'r', 's', 'store_const', 'store_true', 't', 'x', '{', '|', '}', '~']

fiddlesticks-0.0.0/tests/end_to_end_tests.py

@@ -1,189 +0,0 @@
-from pathlib import Path
-import random
-import shutil
-import string
-import subprocess
-import sys
-import tempfile
-
-import pytest
-from hypothesis import given, settings, HealthCheck, Phase
-from hypothesis.strategies import (
-    lists,
-    tuples,
-    text,
-    characters,
-    binary,
-)
-
-import fiddlesticks
-
-IS_WINDOWS = sys.platform=="win32"
-
-@pytest.mark.skipif(IS_WINDOWS, reason="I haven't figured out the 7zip CLI on Windows yet")
-def test_is_7zip_installed():
-    args = ["7z", "--help"]
-    result = subprocess.run(args, capture_output=True)
-    assert result.returncode == 0
-
-file_names = text(
-    alphabet=string.ascii_letters + string.digits,
-    # characters(
-    #     codec="ascii",
-    #     exclude_categories=["Cs", "Co", "Cn"],
-    # ),
-    min_size=1,
-    max_size=24,
-)
-file_names_and_contents = lists(
-    tuples(file_names, binary(min_size=1, max_size=1024)),
-    min_size=1,
-    max_size=20,
-    unique_by=lambda x: x[0],
-)
-
-password_chars = set(string.ascii_letters + string.digits + string.punctuation)
-#To void password chars being parsed as control chars by Bash
-# password_chars -= set("\\"+r"'&;*:{$") 
-
-passwords = text(
-    alphabet="".join(password_chars),
-    min_size=1,
-    max_size=40,
-)
-
-BI_MAP = fiddlesticks.SHIFT_AND_LEET_BI_MAP
-
-# Don't include ' being interpreted as a Bash control char
-# in the tests
-del BI_MAP["'"]
-for k in list(BI_MAP):
-    if "'" in BI_MAP[k]:
-        del BI_MAP[k]
-
-def _get_num_subs(pwd: str) -> int:
-    L = len(pwd)
-    return min(L, 4)
-
-@pytest.mark.hypothesis
-@pytest.mark.slow
-@given(pwd=passwords)
-@settings(deadline=None, suppress_health_check=[HealthCheck.too_slow, HealthCheck.data_too_large])
-def test_alt_chars_candidates_generator(pwd: str):
-    M = _get_num_subs(pwd)
-    total, candidates = fiddlesticks.candidate_passwords_from_alt_chars(pwd, M)
-    for candidate in candidates:
-        # Current implementation preserves length
-        assert len(pwd) == len(candidate)
-        i = 0
-        for c1, c2 in zip(pwd, candidate):
-            if c1 != c2:
-                i += 1
-                assert c1 in BI_MAP[c2] or c2 in BI_MAP[c1], f"Unrelated: {c1}, {c2}"
-        assert i <= M
-
-def _create_password_protected_7z_archive(
-    dir_: Path,
-    file_names_and_contents: list[tuple[str, bytes]],
-    password: str,
-):
-    dir_.mkdir(exist_ok=True, parents=True)
-    for file_name, content in file_names_and_contents:
-        (dir_ / file_name).write_bytes(content)
-
-def _assert_files_same(
-    dir_: Path,
-    file_names_and_contents: list[tuple[str, bytes]],
-):
-    for file_name, content in file_names_and_contents:
-        actual = (dir_ / file_name).read_bytes()
-        assert actual == content, f"File did not round trip.  Expected: {content=}.  Got: {actual=}"
-
-def _guess_from_password(
-    password: str,
-    max_subs: int,
-) -> str:
-    indices_and_alt_chars_with_alts = []
-    for i, c in enumerate(password):
-        alts = BI_MAP.get(c)
-        if alts:
-            indices_and_alt_chars_with_alts.append((i, alts))
-
-    chars = list(password)
-    max_subs = min(max_subs, len(indices_and_alt_chars_with_alts))
-
-    for i, alts in random.sample(indices_and_alt_chars_with_alts, max_subs):
-        chars[i] = random.choice(alts)
-    return "".join(chars)
-
-@pytest.mark.hypothesis
-@pytest.mark.slow
-@pytest.mark.skipif(IS_WINDOWS, reason="I haven't figured out the 7zip CLI on Windows yet")
-@settings(
-    max_examples=50,
-    phases=[Phase.explicit, Phase.reuse, Phase.generate],  # Skip shrinking
-    suppress_health_check=[HealthCheck.too_slow, HealthCheck.data_too_large],
-    deadline=None,
-)
-@given(
-    file_names_and_contents=file_names_and_contents,
-    password=passwords,
-)
-def test_7zip_checker(
-    file_names_and_contents: list[tuple[str, bytes]],
-    password: str,
-):  
-    with tempfile.TemporaryDirectory(delete=False) as tmpdir:
-        tmp_path = Path(tmpdir)
-
-        archive_dir = tmp_path / "contents"
-
-        _create_password_protected_7z_archive(
-            archive_dir,
-            file_names_and_contents,
-            password,
-        )
-
-        archive = str(tmp_path / "archive.7z")
-
-        result = subprocess.run(
-            ["7z", "a", "-mhe=on", f"-p{password}", archive, str(archive_dir)],
-            capture_output=True,
-        )
-        assert result.returncode == 0, f"Could not create 7z archive from: {password=}, containing: {file_names_and_contents}"
-
-        test_extracted_dir = tmp_path / "test_extracted"
-        test_extracted_dir.mkdir()
-
-        result = subprocess.run(
-            ["7z", "x", f"-p{password}", f"-o{test_extracted_dir}", archive],
-            capture_output=True,
-        )
-        assert result.returncode == 0, f"Could not extract {archive} with known good: {password=}, with 7z directly"
-
-        _assert_files_same(test_extracted_dir / "contents", file_names_and_contents)
-
-        shutil.rmtree(test_extracted_dir)
-        test_extracted_dir.mkdir()
-
-        max_subs = _get_num_subs(password)
-        guess = _guess_from_password(password, max_subs)
-
-
-        result = subprocess.run(
-            ["fiddlesticks","--7zip", 
-             "--max-subs", f"{max_subs}",
-             f"--extract-to={test_extracted_dir}", 
-             f"--password-guess={guess}", archive
-            ],
-            capture_output=True,
-        )
-        assert result.returncode==0, f"Could not crack: {password} from: {guess=} for {archive}, {max_subs=}"
-
-        _assert_files_same(test_extracted_dir / "contents", file_names_and_contents)
-
-
-
-
-
-