fiddlesticks 0.2.0__tar.gz → 0.3.0__tar.gz

fiddlesticks-0.3.0/.gitattributes

@@ -0,0 +1,2 @@
+* text eol=lf
+*.kdbx,*.7z binary

fiddlesticks-0.3.0/.github/workflows/lint.yml

@@ -0,0 +1,25 @@
+name: Run pre-commit hooks
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v7
+
+    - name: Install uv and set the python version
+      uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+      with:
+        version: 0.12.7
+        python-version: "3.14"
+
+    - name: uv Sync project with all dependency groups (for type checker)
+      run: uv sync --group dev
+
+    - name: Run pre-commit
+      run: uv run pre-commit run --all-files --show-diff-on-failure --color=always
+      shell: bash

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

@@ -0,0 +1,27 @@
+name: Tests
+
+on:
+  workflow_dispatch:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    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 . --group=test
+
+    - name: Run PyTest (via Coverage)
+      run: |
+        coverage run -m pytest -rA --tb=short tests && coverage combine && coverage report

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

@@ -11,3 +11,7 @@ wheels/
 
 # Virtual environments
 .venv
+
+# Dev environment lock file
+# (to avoid confusion with possible application lock files)
+uv.lock

fiddlesticks-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+- repo: local
+  hooks:
+    - id: ruff-check
+      name: ruff check
+      entry: uv run ruff check
+      language: system
+      pass_filenames: false
+    - id: ruff-format
+      name: ruff format
+      entry: uv run ruff format
+      language: system
+      pass_filenames: false
+    - id: ty
+      name: ty
+      entry: uv run ty check .
+      language: system
+      pass_filenames: false
+
+- repo: https://github.com/pre-commit/pre-commit-hooks
+  rev: v6.0.0
+  hooks:
+    - id: check-yaml

fiddlesticks-0.3.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.5
+Name: fiddlesticks
+Version: 0.3.0
+Summary: Password recovery tool for encrypted files (.7z archives .kdbx files, and Aegis archives).
+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'
+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)
+![Code qual](https://github.com/Hazardous-Area/fiddlesticks/actions/workflows/lint.yml/badge.svg)
+
+Version 0.3.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).  .7z, .kdbx and Aegis archives 
+are directly supported, but Fiddlesticks can also call any shell command, that accepts 
+a candidate password.
+
+### 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 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` 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). 
+ - Specifically, password owners may only need to consider every candidate within some 
+ maximum [Weighted-Levenshtein distance](https://en.wikipedia.org/wiki/Edit_distance#Types_of_edit_distance) 
+ from their best guess of the forgotten password, lets say a total of `M`.  
+ - Fiddlesticks is intended to assist recovering passwords from "close enough" guesses, 
+ when `M` is much smaller than `2**N`.
+ - If Fiddlesticks can crack an archive's password with a starting guess of an empty string, 
+(if `2**N` is also small enough to be feasible, with no guess) then anyone with the 
+archive can also do so - the password wasn't strong enough.
+ - If Fiddlesticks fails to crack an archive's password given some starting guess, a lower
+ bound on how similar the actual password is to the starting guess can still be deduced
+ (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 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 single file.
+
+#### General security audit
+If considering using any password recovery program at all, perhaps consider the following:
+ - does it contain code contained in string literals or obfuscated code?
+ - does it utilise arbitrary code execution functions (e.g. `eval`, `exec` and `compile`)?
+ - is all the source code visible?
+ - does it contain thousands of lines of code?
+ - does it require hundreds of third-party dependencies?
+ - does it contain compiled binary executables, that are not easily readable?
+ - is the code statically typed (so run-time features of dynamic languages are minimised)?
+ - is all the code tested?
+ - is it tested with high coverage (so all the code really is run, somewhere in the tests)?
+ - does it import or install any libraries that allow communication across a network, that
+ could be used for exfiltration purposes?
+ - does it require root privileges to run?
+ - can it be run on any operating system, and in any Docker container?
+
+Full disclaimer:  Fiddlesticks does actually contain 8 lines of Bash in a string 
+literal (to avoid the overhead of `subprocess.run` for every single candidate to be 
+tested, and to demonstrate how any command line program could read 
+password candidates from stdin).  Otherwise we hope the answers to all the other questions
+with regards to Fiddlesticks, are all reassuring.
+
+### Usage
+```
+uvx fiddlesticks
+```
+
+For 7z archives, it is possible to simply to automate attempts to open the file via a stock
+7zip installed in the system, e.g. from:
+```
+sudo apt update && sudo apt-get install 7zip
+```
+
+Fiddlesticks can also 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 partial external Bash command that a candidate password can be appended to (that exits with return code 0
+for the correct password, otherwise some non-zero exit code).  Specify `--shell` or by default if the partial command is specified after `--`.
+
+Secondly with `--pipe` candidate passwords can be sent to stdout, from where they can be piped to stdin of a user's own external program or code (all the normal output from fiddlesticks goes to stderr).
+
+Thirdly, if py7zr is also installed, with `--py7zr` fiddlesticks can use it to test passwords for 7z archives,
+ entirely within Python.
+
+### Main options
+#### Password guesses
+If no password is specified, and if a password guess is requires for the selected command,
+the user will be prompted to enter their password guesses securely (via Python's `getpass.getpass`).  
+For convenience passwords may also be supplied on separate lines of a text file specified 
+in `--input-file`, or directly on the command line, each after `--password-guess` or `-p`.  If using
+the latter in Bash and similar shells, please be aware the full command entered may be saved 
+in the Bash history.  After using Fiddlesticks you should run `history -a` and 
+asome `history -d $(history 1 | awk '{print $1}')` command to clear this.
+
+#### Number of substitutions
+For candidate password generation strategies that use character substitutions (the only ones supported so far)
+the number of substitutions required for each candidate can be capped by setting `--max-subs`
+
+#### Output control & verbosity
+If a file is specified in `--output-file` or `-o` Fiddlesticks will write a successfully found 
+password to it.  Unless `-P` or `--print-passwords` is set, Fiddlesticks does not print any 
+candidate passwords by default (on successfully finding a password, the
+candidate number is printed; candidate generation is deterministic).
+The number of output messages (printed to stderr) can be increased by raising 
+the verbosity, by setting `-v` or `--verbosity`, once or twice (e.g. `-vv`).
+"Two" is the maximum verbosity available. 
+
+### Custom alternative character maps
+
+Any custom JSON file supplied to `--char-map` containing a mapping of characters to alternatives can be used (instead of the default L33t substitutions and capitalisations ascii-based map).  To assist creating this, the default map (or the relevant
+sub-mapping applicable for a specified password guess) can be printed to stderr with `--print-char-map` (and `>>`ed 
+to a local file, where its JSON can be customised in any text editor).  This provides a simple method for
+limiting the substitutions to specific characters in a password guess.
+
+### 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 
+ account data too.
+ - If Fiddlesticks fails to 'crack' or find a known password, this should not be taken as 
+ proof of the password's strength.  It won't ever be possible to think everything, and
+ we certainly don't wish users to draw a false sense of security from Fiddlesticks.
+
+## Alternatives
+ - https://github.com/philsmd/7z2hashcat
+ - https://en.wikipedia.org/wiki/Dictionary_attack#Dictionary_attack_software
+
+[^0] Truly random passwords are difficult for humans to remember (without writing them down or saving them).
+At the very least, real world adversaries (posessing a stolen file or password hash) are likely to first attempt a [dictionary attack](https://en.wikipedia.org/wiki/Dictionary_attack#Dictionary_attack_software)

fiddlesticks-0.3.0/README.md

@@ -0,0 +1,163 @@
+# 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)
+![Code qual](https://github.com/Hazardous-Area/fiddlesticks/actions/workflows/lint.yml/badge.svg)
+
+Version 0.3.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).  .7z, .kdbx and Aegis archives 
+are directly supported, but Fiddlesticks can also call any shell command, that accepts 
+a candidate password.
+
+### 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 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` 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). 
+ - Specifically, password owners may only need to consider every candidate within some 
+ maximum [Weighted-Levenshtein distance](https://en.wikipedia.org/wiki/Edit_distance#Types_of_edit_distance) 
+ from their best guess of the forgotten password, lets say a total of `M`.  
+ - Fiddlesticks is intended to assist recovering passwords from "close enough" guesses, 
+ when `M` is much smaller than `2**N`.
+ - If Fiddlesticks can crack an archive's password with a starting guess of an empty string, 
+(if `2**N` is also small enough to be feasible, with no guess) then anyone with the 
+archive can also do so - the password wasn't strong enough.
+ - If Fiddlesticks fails to crack an archive's password given some starting guess, a lower
+ bound on how similar the actual password is to the starting guess can still be deduced
+ (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 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 single file.
+
+#### General security audit
+If considering using any password recovery program at all, perhaps consider the following:
+ - does it contain code contained in string literals or obfuscated code?
+ - does it utilise arbitrary code execution functions (e.g. `eval`, `exec` and `compile`)?
+ - is all the source code visible?
+ - does it contain thousands of lines of code?
+ - does it require hundreds of third-party dependencies?
+ - does it contain compiled binary executables, that are not easily readable?
+ - is the code statically typed (so run-time features of dynamic languages are minimised)?
+ - is all the code tested?
+ - is it tested with high coverage (so all the code really is run, somewhere in the tests)?
+ - does it import or install any libraries that allow communication across a network, that
+ could be used for exfiltration purposes?
+ - does it require root privileges to run?
+ - can it be run on any operating system, and in any Docker container?
+
+Full disclaimer:  Fiddlesticks does actually contain 8 lines of Bash in a string 
+literal (to avoid the overhead of `subprocess.run` for every single candidate to be 
+tested, and to demonstrate how any command line program could read 
+password candidates from stdin).  Otherwise we hope the answers to all the other questions
+with regards to Fiddlesticks, are all reassuring.
+
+### Usage
+```
+uvx fiddlesticks
+```
+
+For 7z archives, it is possible to simply to automate attempts to open the file via a stock
+7zip installed in the system, e.g. from:
+```
+sudo apt update && sudo apt-get install 7zip
+```
+
+Fiddlesticks can also 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 partial external Bash command that a candidate password can be appended to (that exits with return code 0
+for the correct password, otherwise some non-zero exit code).  Specify `--shell` or by default if the partial command is specified after `--`.
+
+Secondly with `--pipe` candidate passwords can be sent to stdout, from where they can be piped to stdin of a user's own external program or code (all the normal output from fiddlesticks goes to stderr).
+
+Thirdly, if py7zr is also installed, with `--py7zr` fiddlesticks can use it to test passwords for 7z archives,
+ entirely within Python.
+
+### Main options
+#### Password guesses
+If no password is specified, and if a password guess is requires for the selected command,
+the user will be prompted to enter their password guesses securely (via Python's `getpass.getpass`).  
+For convenience passwords may also be supplied on separate lines of a text file specified 
+in `--input-file`, or directly on the command line, each after `--password-guess` or `-p`.  If using
+the latter in Bash and similar shells, please be aware the full command entered may be saved 
+in the Bash history.  After using Fiddlesticks you should run `history -a` and 
+asome `history -d $(history 1 | awk '{print $1}')` command to clear this.
+
+#### Number of substitutions
+For candidate password generation strategies that use character substitutions (the only ones supported so far)
+the number of substitutions required for each candidate can be capped by setting `--max-subs`
+
+#### Output control & verbosity
+If a file is specified in `--output-file` or `-o` Fiddlesticks will write a successfully found 
+password to it.  Unless `-P` or `--print-passwords` is set, Fiddlesticks does not print any 
+candidate passwords by default (on successfully finding a password, the
+candidate number is printed; candidate generation is deterministic).
+The number of output messages (printed to stderr) can be increased by raising 
+the verbosity, by setting `-v` or `--verbosity`, once or twice (e.g. `-vv`).
+"Two" is the maximum verbosity available. 
+
+### Custom alternative character maps
+
+Any custom JSON file supplied to `--char-map` containing a mapping of characters to alternatives can be used (instead of the default L33t substitutions and capitalisations ascii-based map).  To assist creating this, the default map (or the relevant
+sub-mapping applicable for a specified password guess) can be printed to stderr with `--print-char-map` (and `>>`ed 
+to a local file, where its JSON can be customised in any text editor).  This provides a simple method for
+limiting the substitutions to specific characters in a password guess.
+
+### 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 
+ account data too.
+ - If Fiddlesticks fails to 'crack' or find a known password, this should not be taken as 
+ proof of the password's strength.  It won't ever be possible to think everything, and
+ we certainly don't wish users to draw a false sense of security from Fiddlesticks.
+
+## Alternatives
+ - https://github.com/philsmd/7z2hashcat
+ - https://en.wikipedia.org/wiki/Dictionary_attack#Dictionary_attack_software
+
+[^0] Truly random passwords are difficult for humans to remember (without writing them down or saving them).
+At the very least, real world adversaries (posessing a stolen file or password hash) are likely to first attempt a [dictionary attack](https://en.wikipedia.org/wiki/Dictionary_attack#Dictionary_attack_software)

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "fiddlesticks"
-description = "Password recovery tool for encrypted archives (currently only .7z files supported)."
+description = "Password recovery tool for encrypted files (.7z archives .kdbx files, and Aegis archives)."
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -13,14 +13,8 @@ authors = [
 ]
 requires-python = ">=3.12"
 dynamic=["version"]
-dependencies = []
-
-[project.optional-dependencies]
-py7zr = ["py7zr"]
-aegis = ["py-avdu"]
-keepassxc = ["pykeepass"]
-tests = ["pytest", "hypothesis"]
 
+dependencies = []
 
 [project.urls]
 GitHub = "https://github.com/Hazardous-Area/fiddlesticks"
@@ -28,6 +22,37 @@ GitHub = "https://github.com/Hazardous-Area/fiddlesticks"
 [project.scripts]
 fiddlesticks = "fiddlesticks:cli"
 
+[project.optional-dependencies]
+py7zr = [
+    "py7zr",
+]
+aegis = [
+    "py-avdu",
+]
+keepassxc = [
+    "pykeepass",
+]
+
+[dependency-groups]
+dev = [
+    {include-group = "lint"},
+    {include-group = "test"},
+]
+test = [
+    "fiddlesticks[py7zr,aegis,keepassxc]",
+    "pytest",
+    "hypothesis",
+    "coverage>=7.13",
+    "covdefaults",
+]
+lint = [
+    "ruff",
+    "ty",
+    "pre-commit",
+]
+
+
+
 [tool.hatch.build.targets.wheel]
 only-include = ["src"]
 sources = {"src" = ""}  # move from "src" directory for wheel
@@ -35,7 +60,6 @@ sources = {"src" = ""}  # move from "src" directory for wheel
 [tool.hatch.version]
 path = "src/fiddlesticks.py" 
 
-
 [tool.pytest.ini_options]
 markers = [
     "slow: marks other tests that cause bottlenecks",
@@ -43,3 +67,10 @@ markers = [
 ]
 python_files = "test_*.py *_test.py *_tests.py"
 
+[tool.coverage.run]
+source = ["src"]
+omit = ["tests/*"]
+patch = ["subprocess"]
+plugins = [
+    "covdefaults",
+]