mirror of
https://github.com/scito/extract_otp_secret_keys.git
synced 2025-12-06 06:44:57 +01:00
improve build and README
- clean pip - do not use sudo anymore - add missing mypy-protobuf package - sort package dependencies - fix order of build calls - add frame color docu to README
This commit is contained in:
scito
Roland Kurmann
parent
2bef64e5f6
commit
851cb6532c
7 changed files with 156 additions and 88 deletions
54
README.md
54
README.md
|
|
@ -15,13 +15,13 @@
|
|||
The Python script `extract_otp_secrets.py` extracts one time password (OTP) secrets from QR codes exported by two-factor authentication (2FA) apps such as "Google Authenticator".
|
||||
The exported QR codes from authentication apps can be read in three ways:
|
||||
|
||||
1. Capture from the system camera using a GUI, _(new!)_
|
||||
2. Read image files containing the QR codes, and _(new!)_
|
||||
1. Capture from the system camera using a GUI, 🆕
|
||||
2. Read image files containing the QR codes, and 🆕
|
||||
3. Read text files containing the QR code data generated by third-party QR readers.
|
||||
|
||||
The secret and otp values can be exported to json or csv files, as well as printed or saved to PNG images.
|
||||
|
||||
**The project and the script were renamed from extract_otp_secret_keys to extract_otp_secrets in version 2.0.0.**
|
||||
⚡ **The project and the script were renamed from `extract_otp_secret_keys` to `extract_otp_secrets` in version 2.0.** ⚡
|
||||
|
||||
## Installation
|
||||
|
||||
|
|
@ -70,7 +70,7 @@ OpenCV requires [Visual C++ redistributable 2015](https://www.microsoft.com/en-u
|
|||
|
||||
## Usage
|
||||
|
||||
### Capture QR codes from camera (since version 2.0.0)
|
||||
### Capture QR codes from camera (🆕 since version 2.0)
|
||||
|
||||
1. Open "Google Authenticator" app on the mobile phone
|
||||
2. Export the QR codes from "Google Authenticator" app
|
||||
|
|
@ -81,7 +81,13 @@ OpenCV requires [Visual C++ redistributable 2015](https://www.microsoft.com/en-u
|
|||
|
||||
|
||||
|
||||
### With builtin QR decoder from image files (since version 2.0.0)
|
||||
Detected QR codes are surrounded with a frame. The color of the frame indicates the extracting result:
|
||||
|
||||
* Green: The QR code is detected, decoded and the OTP secret was successfully extracted.
|
||||
* Red: The QR code is detected and decoded, but could not be successfully extracted. This is the case if a QR code not containing OTP data is captured.
|
||||
* Magenta: The QR code is detected, but could not be decoded. The QR code should be presented better to the camera or another QR reader could be used.
|
||||
|
||||
### With builtin QR decoder from image files (🆕 since version 2.0)
|
||||
|
||||
1. Open "Google Authenticator" app on the mobile phone
|
||||
2. Export the QR codes from "Google Authenticator" app
|
||||
|
|
@ -177,13 +183,13 @@ python extract_otp_secrets.py = < example_export.png</pre>
|
|||
|
||||
* Free and open source
|
||||
* Supports Google Authenticator exports (and compatible apps like Aegis Authenticator)
|
||||
* Captures the the QR codes directly from the camera using different QR code libraries (based on OpenCV)
|
||||
* Captures the the QR codes directly from the camera using different QR code libraries (based on OpenCV) (🆕 since v2.0)
|
||||
* ZBAR: [pyzbar](https://github.com/NaturalHistoryMuseum/pyzbar) - fast and reliable, good for images and video capture (default and recommended)
|
||||
* QREADER: [QReader](https://github.com/Eric-Canas/QReader)
|
||||
* QREADER_DEEP: [QReader](https://github.com/Eric-Canas/QReader) - very slow in GUI
|
||||
* CV2: [QRCodeDetector](https://docs.opencv.org/4.x/de/dc3/classcv_1_1QRCodeDetector.html)
|
||||
* CV2_WECHAT: [WeChatQRCode](https://docs.opencv.org/4.x/dd/d63/group__wechat__qrcode.html)
|
||||
* Supports TOTP and HOTP standards
|
||||
* Supports [TOTP](https://www.ietf.org/rfc/rfc6238.txt) and [HOTP](https://www.ietf.org/rfc/rfc4226.txt) standards
|
||||
* Generates QR codes
|
||||
* Exports to various formats:
|
||||
* CSV
|
||||
|
|
@ -191,7 +197,8 @@ python extract_otp_secrets.py = < example_export.png</pre>
|
|||
* Dedicated CSV for KeePass
|
||||
* QR code images
|
||||
* Supports reading from stdin and writing to stdout, thus pipes can be used
|
||||
* Reads QR codes images: (See [OpenCV docu](https://docs.opencv.org/4.x/d4/da8/group__imgcodecs.html#ga288b8b3da0892bd651fce07b3bbd3a56))
|
||||
* Handles multiple input files (🆕 since v2.0)
|
||||
* Reads QR codes images: (See [OpenCV docu](https://docs.opencv.org/4.x/d4/da8/group__imgcodecs.html#ga288b8b3da0892bd651fce07b3bbd3a56)) (🆕 since v2.0)
|
||||
* Portable Network Graphics - *.png
|
||||
* WebP - *.webp
|
||||
* JPEG files - *.jpeg, *.jpg, *.jpe
|
||||
|
|
@ -199,8 +206,8 @@ python extract_otp_secrets.py = < example_export.png</pre>
|
|||
* Windows bitmaps - *.bmp, *.dib
|
||||
* JPEG 2000 files - *.jp2
|
||||
* Portable image format - *.pbm, *.pgm, *.ppm *.pxm, *.pnm
|
||||
* Prints errors and warnings to stderr
|
||||
* Prints colored output
|
||||
* Prints errors and warnings to stderr (🆕 since v2.0)
|
||||
* Prints colored output (🆕 since v2.0)
|
||||
* Many ways to run the script:
|
||||
* Native Python
|
||||
* pipenv
|
||||
|
|
@ -209,7 +216,7 @@ python extract_otp_secrets.py = < example_export.png</pre>
|
|||
* Docker
|
||||
* VSCode devcontainer
|
||||
* devbox
|
||||
* Prebuilt Docker images provided for amd64 and arm64
|
||||
* Prebuilt Docker images provided for amd64 and arm64 (🆕 since v2.0)
|
||||
* Compatible with major platforms:
|
||||
* Linux
|
||||
* macOS
|
||||
|
|
@ -308,7 +315,7 @@ curl -s https://raw.githubusercontent.com/scito/extract_otp_secrets/master/examp
|
|||
```
|
||||
git clone https://github.com/scito/extract_otp_secrets.git
|
||||
pip install -U -e extract_otp_secrets
|
||||
python -m extract_otp_secrets example_export.txt
|
||||
python -m extract_otp_secrets extract_otp_secrets/example_export.txt
|
||||
```
|
||||
|
||||
### pipenv
|
||||
|
|
@ -368,7 +375,7 @@ docker login -u USERNAME
|
|||
curl -s https://raw.githubusercontent.com/scito/extract_otp_secrets/master/example_export.png | docker run --pull always -i --rm -v "$(pwd)":/files:ro scit0/extract_otp_secrets =
|
||||
```
|
||||
|
||||
Capturing from camera in GUI (X Window system required on host):
|
||||
Capturing from camera in GUI window (X Window system required on host):
|
||||
|
||||
```
|
||||
docker run --pull always --rm -v "$(pwd)":/files:ro -i --device="/dev/video0:/dev/video0" --env="DISPLAY" -v /tmp/.X11-unix:/tmp/.X11-unix:ro scit0/extract_otp_secrets
|
||||
|
|
@ -447,6 +454,7 @@ Setup for running the tests in VSCode.
|
|||
### Build
|
||||
|
||||
```
|
||||
cd extract_otp_secrets/
|
||||
pip install -U -e .
|
||||
python src/extract_otp_secrets.py
|
||||
|
||||
|
|
@ -463,29 +471,37 @@ pip install -U -r requirements.txt
|
|||
|
||||
### Build docker images
|
||||
|
||||
#### Debian (full functionality)
|
||||
|
||||
Build and run the app within the container:
|
||||
|
||||
```bash
|
||||
docker build . -t extract_otp_secrets --pull --build-arg RUN_TESTS=false
|
||||
```
|
||||
|
||||
```bash
|
||||
docker build . -t extract_otp_secrets_only_txt --pull -f Dockerfile_only_txt --build-arg RUN_TESTS=false
|
||||
```
|
||||
|
||||
Run tests in docker container:
|
||||
|
||||
```bash
|
||||
docker run --entrypoint /extract/run_pytest.sh --rm -v "$(pwd)":/files:ro extract_otp_secrets
|
||||
```
|
||||
|
||||
|
||||
#### Alpine (only text file processing)
|
||||
|
||||
```bash
|
||||
docker run --entrypoint /extract/run_pytest.sh --rm -v "$(pwd)":/files:ro extract_otp_secrets_only_txt extract_otp_secrets_test.py -k "not qreader" --relaxed
|
||||
docker build . -t extract_otp_secrets_only_txt --pull -f Dockerfile_only_txt --build-arg RUN_TESTS=false
|
||||
```
|
||||
|
||||
Run tests in docker container:
|
||||
|
||||
```bash
|
||||
docker run --entrypoint /extract/run_pytest.sh --rm -v "$(pwd)":/files:ro extract_otp_secrets_only_txt tests/extract_otp_secrets_test.py -k "not qreader" --relaxed
|
||||
```
|
||||
|
||||
## Issues
|
||||
|
||||
* Known issue for macOS: https://github.com/opencv/opencv/issues/23072
|
||||
* Segmentation fault on macOS with CV2 4.7.0: https://github.com/opencv/opencv/issues/23072
|
||||
* CV2 window does not show icons: https://github.com/opencv/opencv-python/issues/585
|
||||
|
||||
## Problems and Troubleshooting
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue