Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
304 lines (229 loc) · 6.14 KB

CONTRIBUTING.md

File metadata and controls

304 lines (229 loc) · 6.14 KB

Contributing to SecureBox

Thank you for your interest in contributing to SecureBox! This document provides guidelines for contributing to this project.

Table of Contents

Code of Conduct

  • Be respectful and constructive
  • Focus on technical merit
  • Help maintain a welcoming environment
  • No harassment or discrimination

How Can I Contribute?

Reporting Bugs

When reporting bugs, please include:

  • Description: Clear description of the issue
  • Steps to reproduce: Detailed steps
  • Expected behavior: What should happen
  • Actual behavior: What actually happens
  • Hardware: ESP32-S3 model, flash chip details
  • Software: Arduino IDE version, Python version
  • Logs: Serial output, error messages

Suggesting Features

Feature requests should include:

  • Use case: Why is this needed?
  • Proposed solution: How would it work?
  • Alternatives: Other approaches considered
  • Impact: Security, performance implications

Code Contributions

Areas where contributions are welcome:

  • Bug fixes
  • Documentation improvements
  • New features (discuss first!)
  • Security enhancements
  • Performance optimizations
  • Additional platform support
  • Test coverage

Development Setup

Hardware Requirements:

  • ESP32-S3 development board
  • W25Q128 SPI flash chip
  • USB cable
  • (Optional) Logic analyzer for debugging

Software Requirements:

For Firmware:

# Arduino IDE 2.x
# Install ESP32 board support
# Required libraries:
- mbedTLS (included in ESP32 core)
- ArduinoJson
- NimBLE (for Bluetooth)

For Applications:

# Python 3.8+
pip install pyserial
pip install tkinter  # Usually included with Python
pip install flask

Getting Started:

# Clone the repository
git clone https://github.com/Vanderhell/SecureBox.git
cd SecureBox

# Upload firmware
# Open SecureBox_Internal/SecureBox_Internal.ino in Arduino IDE
# Select board: ESP32-S3 Dev Module
# Upload

# Test connection
cd SecureBoxApps
python test_securebox.py

# Run GUI app
python gui-tkinter/securebox_gui.py

Coding Standards

Firmware (C/C++):

// Use clear, descriptive names
void Crypto_EncryptData(uint8_t* input, size_t len);

// Comment non-obvious code
// Derive KEK from master password using PBKDF2
mbedtls_pkcs5_pbkdf2_hmac(...);

// Error handling
if (!Storage_Init()) {
    Serial.println("[ERROR] Flash initialization failed");
    return false;
}

// Memory safety
Crypto_SecureWipe(buffer, sizeof(buffer));

// Constants in UPPER_CASE
#define MAX_ENTRIES 100
#define AES_KEY_SIZE 32

Python:

# PEP 8 style guide
# Use type hints
def unlock_device(password: str) -> bool:
    """Unlock device with master password.

    Args:
        password: Master password string

    Returns:
        True if unlocked successfully, False otherwise
    """
    pass

# Clear variable names
entry_count = 0
is_unlocked = False

# Error handling
try:
    response = send_command("UNLOCK", password)
except SerialException as e:
    logger.error(f"Communication error: {e}")
    return False

Documentation:

  • Clear: Use simple, precise language
  • Complete: Cover all parameters and return values
  • Examples: Provide usage examples
  • Security: Note security implications

Pull Request Process

Before Submitting:

  1. Test thoroughly:

    • Firmware compiles without warnings
    • Applications run without errors
    • All features work as expected
    • No security regressions

  2. Check code quality:

    • Follow coding standards
    • Add comments for complex logic
    • Remove debug code
    • No hardcoded secrets

  3. Update documentation:

    • Update README.md if needed
    • Add comments to code
    • Update SECURITY_ANALYSIS.md for security changes

Pull Request Template:

## Description
Brief description of changes

## Motivation
Why is this change needed?

## Changes
- List of specific changes
- Including new files
- Modified functions

## Testing
How was this tested?
- Hardware: ESP32-S3 Mini
- Test cases: password unlock, entry CRUD
- Results: all pass

## Security Impact
Any security implications?
- Encryption changes: No
- New attack vectors: No
- Backward compatibility: Yes

## Checklist
- [ ] Code compiles without warnings
- [ ] Tests pass
- [ ] Documentation updated
- [ ] No security issues
- [ ] Follows coding standards

Review Process:

  1. Submit PR with clear description
  2. Automated checks (if configured)
  3. Code review by maintainers
  4. Address feedback
  5. Approval and merge

Security Issues

Reporting Security Vulnerabilities:

DO NOT open public issues for security vulnerabilities!

Instead:

  1. Email: Vanderhell@gmail.com

  2. Include:

    • Description of vulnerability
    • Steps to reproduce
    • Potential impact
    • Suggested fix (if any)

  3. We will:

    • Acknowledge within 48 hours
    • Investigate and develop fix
    • Release patch
    • Credit you (if desired)

Security Review Checklist:

When contributing security-related code:

  • No hardcoded secrets
  • Proper key derivation (PBKDF2)
  • Secure random generation
  • Memory wiping after use
  • No timing attacks
  • Input validation
  • Error handling doesn't leak info
  • Reviewed by security-conscious developer

Types of Contributions We're Looking For:

High Priority:

  • Security improvements
  • Bug fixes
  • Documentation improvements
  • Test coverage

Medium Priority:

  • Performance optimizations
  • New platform support (Android, iOS)
  • UI/UX improvements
  • Additional encryption algorithms

Low Priority (discuss first):

  • Major architectural changes
  • New communication protocols
  • Breaking changes

Questions?

  • Open an issue for general questions
  • Email for security concerns
  • Check existing issues first

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for contributing to SecureBox!