Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
135 lines (92 loc) · 5.24 KB

CONTRIBUTING.md

File metadata and controls

135 lines (92 loc) · 5.24 KB
Raw

🤝 Contributing to SpyEye

Contributions Welcome! License: MIT

First off, thank you for considering contributing to SpyEye! This project is driven by the community, and every contribution helps make it a more powerful and stable tool for security researchers.

This document provides guidelines for contributing, whether it's through reporting a bug, suggesting a new feature, or submitting code.

📜 Code of Conduct

Before contributing, please take a minute to read our CODE_OF_CONDUCT.md. We enforce this code strictly to ensure that the SpyEye community remains a professional, welcoming, and inclusive environment for everyone.

Table of Contents
  1. How Can I Contribute?
  2. Setting Up Your Development Environment
  3. Pull Request (PR) Workflow
  4. Coding Style Guides

💡 How Can I Contribute?

🐞 Reporting Bugs

If you find a bug, please open a new Issue on our GitHub repository. A good bug report is essential for us to fix it. Please include:

  • A clear, descriptive title: e.g., "Crash when selecting interface in [CONFIG] menu."
  • Your Environment: What OS (e.g., Kali Linux 2024.1), Python version (e.g., 3.10), and ESP-IDF version are you using?
  • Steps to Reproduce: Provide a clear, step-by-step guide on how to trigger the bug.
  • Expected Behavior: What did you expect to happen?
  • Actual Behavior: What happened instead? (Include full terminal output, logs, or screenshots).

✨ Suggesting Enhancements or New Features

We'd love to hear your ideas! Please open a new Issue and use the "Feature Request" template (if available).

  • Describe the feature: What should it do? Why is it needed?
  • Pitch the solution: How do you imagine it working?
  • Provide context: How does this fit into the existing SpyEye architecture (e.g., is this a C2 feature, an ESP32 attack, or a new Captive Portal template)?

🛠️ Setting Up Your Development Environment

SpyEye has a hybrid architecture, so you may need to set up one or both parts depending on what you're contributing to.

1. Python C2 (Host) Setup

This is for working on the main main.py, the cli.py, flask_app.py, or other Python modules.

git clone [https://github.com/YOUR-USERNAME/SpyEye.git](https://github.com/YOUR-USERNAME/SpyEye.git)
cd SpyEye

python3 -m venv venv
source venv/bin/activate

pip3 install -r requirements.txt

You will also need the core Linux dependencies installed, as mentioned in the main README.md (hostapd, dnsmasq, iptables).

2.ESP32 Probe (Firmware) Setup

This is for working on the C-based firmware in the ESP32/ESP-SpyEye directory.

This is critical: This project is built using ESP-IDF v4.4 Using other versions may result in build errors.

# 1. Navigate to the firmware directory
cd SpyEye/ESP32/ESP-SpyEye

# 2. Set up the ESP-IDF v4.4 toolchain
# (Follow the official Espressif documentation for your OS)
# ...
# 
# 3. Once installed, activate the IDF environment
source /path/to/esp-idf-v4.4/export.sh

idf.py build

🚀 Pull Request (PR) Workflow

Ready to submit your code? Follow these steps to ensure a smooth review process.

  • Fork the Repository: Create your own copy of Delta-Sec/SpyEye.
  • Create a Feature Branch: Branch off main to keep your changes isolated.
git checkout -b feature/my-awesome-feature
  • Commit Your Changes: Make your changes and write clear, descriptive commit messages.
git commit -m "feat(esp32): Add new parser for X frame"
git commit -m "fix(c2): Resolve crash in config menu"
  • Push to Your Branch:
git push origin feature/my-awesome-feature

  • Open a Pull Request (PR):

    • Go to the main SpyEye repository and click "New Pull Request".

    • Provide a clear title and a detailed description of your changes.

    • Explain what you changed and why.

    • If you are fixing an existing issue, link it (e.g., "Closes #33").

✍️ Coding Style Guides

To maintain consistency in the codebase, we adhere to the following styles:

  • Python: We follow PEP 8. Please run a linter (like flake8) over your code before submitting.

  • C (ESP-IDF): We follow the official Espressif IDF C Code Style.

By contributing to SpyEye, you agree that your contributions will be licensed under its MIT License.