🦆 Quackdoor

Honk Honk!
Quackdoor is a CLI tool written in Python that generates DuckyScript to execute arbitrary Python code on a target machine. It is best used for crafting payloads for Flipper Zero's BadUSB app.

🔧 Features

• Embeds Python scripts into an executable DuckyScript
• Supports external Python libraries (via -r and -p flags)
• Tailored for use with macOS and Zsh environments
• Ideal for authorized security testing and educational purposes

⚠️ Limitations & Considerations

• The target system must have Python 3 installed
• All local Python code must reside in a single file; other local modules will not be compiled into the payload
• External libraries are supported and will be installed globally on the target via pip
• Payload may leave recoverable traces on the target system—use with caution
• Assumes the Zsh shell and standard macOS filesystem on the target

🚀 Getting Started

Clone the repository:

git clone https://github.com/your-org/quackdoor.git

Generate a payload:

cd quackdoor
python3 quackdoor.py -i your_script.py -o output_file_name.txt

Optional flags for additional customization:

• -r dependency1 dependency2 – Provide a space delimited list of dependencies to install
• -p – Pip-time, or how long for the resulting DuckyScript to wait after running pip install (if there are dependencies provided)

✅ Development Best Practices

We follow the GitHub Flow for all development work:

1. Create a new branch from main:

   git checkout -b feature/my-feature
   

2. Make your changes and commit them:

   git commit -m "#123 Brief description of the change"
   

   • Always reference the GitHub issue number with a #, e.g. #42
   • Write clear and descriptive commit messages

3. Push your branch:

   git push origin feature/my-feature
   

4. Open a Pull Request targeting the main branch

5. Request review and ensure all checks pass

6. Once approved, squash and merge

📦 Release Process

1. Bump the version in pyproject.toml
2. Edit the version field to the new release number:

version = "0.1.1"

Commit the change:

git add pyproject.toml
git commit -m "Bump version to 0.1.1"

3. Tag the release Tag should match the version in pyproject.toml exactly, prefixed with v:

git tag v0.1.1
git push origin v0.1.1

Create the GitHub Release

1. Go to the GitHub "Releases" page

2. Click "Draft a new release"

3. Select the tag you just pushed

4. Fill in release notes. Include a changelog with a compare url like:

https://github.com/mah5057/quackdoor/compare/v0.1.0...v0.1.1

5. Click "Publish release"

Publishing to PyPI

The CI workflow will automatically build and publish the new version to PyPI once the GitHub release is published.

📄 License

MIT License. See LICENSE for details.

🛡️ Disclaimer

This software is provided for educational and authorized testing purposes only.
The author is not responsible for misuse, damage, or legal consequences resulting from the use of this tool.

Use responsibly. Honk responsibly. 🦆