Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
124 lines (80 loc) · 3.01 KB

CONTRIBUTING.md

File metadata and controls

124 lines (80 loc) · 3.01 KB

Contributing to Uspector Network Scanner

Thank you for your interest in contributing to Uspector Network Scanner, Contributions of all kinds are welcome, code, documentation, testing, ideas, and feedback.

This project is an open-source, cross-platform Python tool designed for ethical network diagnostics, security awareness, and administrative auditing.

📜 Code of Conduct & Ethics

By contributing, you agree to uphold the following principles:

  • All contributions must support legal, ethical, and authorized network diagnostics only.
  • Do not add features intended to bypass security controls, evade detection, or facilitate unlawful activity.
  • Respect user privacy and organizational policies.

The maintainer reserves the right to reject contributions that conflict with these principles.

🧩 Ways to Contribute

You can help in many ways:

💻 Code Contributions

  • Bug fixes
  • Performance improvements
  • Cross-platform compatibility enhancements
  • Refactoring for readability and maintainability
  • Adding safe, ethical diagnostic features

📝 Documentation

  • Improve README clarity
  • Add usage examples
  • Fix typos or grammar
  • Improve comments and docstrings

🧪 Testing

  • Test on different Windows/Linux versions
  • Report bugs or edge cases
  • Validate scan accuracy and performance

💡 Ideas & Feedback

  • Feature requests (ethical and defensive only)
  • UX improvements for CLI output
  • Suggestions for better logging or reporting

🛠️ Development Guidelines

To keep the project clean and consistent, please follow these rules:

  • Python version: Python 3.x only
  • No external dependencies — standard library only
  • Keep the tool cross-platform (Windows & Linux)
  • Avoid OS-specific hacks unless clearly isolated
  • Write clear, readable, and well-commented code
  • Follow PEP8 where reasonable

🔒 Security-Focused Contributions

This tool is designed for defensive diagnostics, not exploitation.

✅ Acceptable:

  • Device discovery improvements
  • Scan accuracy enhancements
  • Safer port detection logic
  • Better error handling and timeouts

❌ Not acceptable:

  • Exploit payloads
  • Credential harvesting
  • Evasion techniques
  • Attack methods

🔀 How to Submit a Contribution

  1. Fork the repository
  2. Make your changes
  3. Test on at least one supported OS
  4. Commit with a clear message
  5. Open a Pull Request with:
    • What you changed
    • Why it’s useful
    • Any relevant notes or limitations

🐞 Reporting Bugs

When reporting a bug, please include:

  • OS and version
  • Python version
  • Command used
  • Expected vs actual behavior
  • Error output or logs (if available)

Clear reports help fix issues faster 👍

📄 Licensing

By contributing, you agree that your contributions will be licensed under the same license as this project.

🙏 Thank You

Every contribution, small or large, helps improve Uspector Network Scanner.

Thank you for supporting ethical, defensive, and responsible network diagnostics.