commit 9ef72771dc0b5162829847288763bf79bfba3081 Author: Eun0us Date: Thu Jan 15 00:04:00 2026 +0100 ε - Init Sources diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5e162c2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,103 @@ +# ESP-IDF Build System +espilon_bot/build/ +espilon_bot/sdkconfig +espilon_bot/sdkconfig.old +espilon_bot/.config +espilon_bot/.config.old + +# Managed Components (downloaded dependencies) +espilon_bot/managed_components/ +espilon_bot/dependencies.lock + +# Firmware binaries +espilon_bot/firmware/ +*.bin +*.elf +*.map + +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +*.egg-info/ +dist/ +build/ +venv/ +env/ +ENV/ +.venv + +# Tools - Python dependencies +tools/c2/__pycache__/ +tools/c3po/__pycache__/ +tools/flasher/__pycache__/ +*.pyc + +# Configuration files with secrets +tools/flasher/devices.json +tools/flasher/devices.*.json +tools/c2/config.json +tools/c3po/config.json +**/config.local.json + +# Logs +*.log +logs/ +espilon_bot/logs/ + +# IDE and Editor +.vscode/ +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +.idea/ +*.swp +*.swo +*~ +.DS_Store + +# OS +Thumbs.db +.DS_Store +*.bak + +# Credentials and Secrets +*.pem +*.key +*.crt +*.p12 +secrets/ +credentials/ +.env +.env.local + +# Temporary files +*.tmp +*.temp +.cache/ + +# Documentation build +docs/_build/ +docs/.doctrees/ +site/ + +# Test coverage +.coverage +htmlcov/ +.pytest_cache/ + +# nanoPB generated files (if you want to regenerate them) +# Uncomment if you want to track generated .pb.c/.pb.h files +# espilon_bot/components/core/nanoPB/*.pb.c +# espilon_bot/components/core/nanoPB/*.pb.h + +# Backup files +*.backup +*_backup + +# Hardware-specific configs (optional) +# Uncomment if you don't want to track these +# espilon_bot/partitions.csv diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8e41d9f --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,634 @@ +# Contributing to Espilon + +Thank you for your interest in contributing to Espilon! This document provides guidelines and instructions for contributing to the project. + +--- + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) +- [Development Setup](#development-setup) +- [Coding Standards](#coding-standards) +- [Commit Guidelines](#commit-guidelines) +- [Pull Request Process](#pull-request-process) +- [Security Contributions](#security-contributions) +- [Community](#community) + +--- + +## Code of Conduct + +### Our Standards + +- **Be respectful**: Treat everyone with respect and kindness +- **Be collaborative**: Work together to improve the project +- **Be responsible**: This is a security tool - use it ethically +- **Be professional**: Maintain professional communication +- **Be patient**: Help newcomers learn and grow + +### Unacceptable Behavior + +- Harassment, discrimination, or offensive comments +- Sharing malicious code or exploits for illegal purposes +- Unauthorized testing against third-party systems +- Trolling, insulting, or derogatory comments +- Publishing others' private information + +**Violations**: Please report to project maintainers. Serious violations may result in being banned from the project. + +--- + +## How Can I Contribute? + +### Reporting Bugs + +**Before submitting a bug report**: +1. Check the [documentation](docs/) for common issues +2. Search [existing issues](https://github.com/yourusername/epsilon/issues) to avoid duplicates +3. Try to reproduce with the latest version + +**Good bug reports include**: +- Clear, descriptive title +- Steps to reproduce the issue +- Expected vs actual behavior +- ESP32 variant and board type +- ESP-IDF version +- Configuration (`sdkconfig` relevant parts) +- Serial output/logs +- Screenshots (if applicable) + +**Bug Report Template**: +```markdown +## Description +[Clear description of the bug] + +## Steps to Reproduce +1. Configure device with... +2. Execute command... +3. Observe error... + +## Expected Behavior +[What should happen] + +## Actual Behavior +[What actually happens] + +## Environment +- ESP32 Variant: ESP32/ESP32-S2/ESP32-S3/etc. +- Board: DevKit/ESP32-CAM/Custom +- ESP-IDF Version: v5.3.2 +- Espilon Version: commit hash or version + +## Logs +``` +[Paste relevant logs here] +``` + +## Additional Context +[Any other relevant information] +``` + +### Suggesting Features + +**Feature requests should**: +- Have a clear use case +- Align with project goals (security research/education) +- Consider resource constraints (ESP32 limitations) +- Include implementation ideas (if possible) + +**Feature Request Template**: +```markdown +## Feature Description +[Clear description of the proposed feature] + +## Use Case +[Why is this feature needed? What problem does it solve?] + +## Proposed Implementation +[How could this be implemented? Consider:] +- Memory requirements +- CPU usage +- Network bandwidth +- Module structure +- Configuration options + +## Alternatives Considered +[Other approaches you've thought about] + +## Additional Context +[Mockups, examples, references] +``` + +### Contributing Code + +**Types of contributions welcome**: + +- Bug fixes +- New modules or commands +- Documentation improvements +- Code quality improvements (refactoring, optimization) +- Tests and test infrastructure +- Security enhancements +- Translations +- Tool improvements (C2, flasher, etc.) + +**Getting started**: + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Test thoroughly +5. Submit a pull request + +--- + +## Development Setup + +### Prerequisites + +- ESP-IDF v5.3.2 or compatible +- Python 3.8+ +- Git +- ESP32 development board (for testing) + +### Fork and Clone + +```bash +# Fork repository on GitHub, then: +git clone https://github.com/YOUR-USERNAME/epsilon.git +cd epsilon + +# Add upstream remote +git remote add upstream https://github.com/original-owner/epsilon.git +``` + +### Set Up Development Environment + +```bash +# Install ESP-IDF +cd ~/esp +git clone --recursive --branch v5.3.2 https://github.com/espressif/esp-idf.git +cd esp-idf +./install.sh esp32 +. ./export.sh + +# Install Python dependencies (for C2) +cd /path/to/epsilon/tools/c2 +pip3 install -r requirements.txt +``` + +### Create Feature Branch + +```bash +# Update your fork +git checkout main +git pull upstream main + +# Create feature branch +git checkout -b feature/your-feature-name +``` + +**Branch naming conventions**: +- `feature/feature-name` - New features +- `fix/bug-description` - Bug fixes +- `docs/topic` - Documentation updates +- `refactor/component-name` - Code refactoring +- `test/test-description` - Test additions + +--- + +## Coding Standards + +### C Code (ESP32 Firmware) + +**Style Guide**: +- **Indentation**: 4 spaces (NO tabs) +- **Braces**: K&R style (opening brace on same line) +- **Naming**: + - Functions: `snake_case` (e.g., `process_command`) + - Variables: `snake_case` (e.g., `device_id`) + - Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_BUFFER_SIZE`) + - Macros: `UPPER_SNAKE_CASE` + - Structs: `snake_case_t` (e.g., `command_t`) + +**Example**: +```c +#include "esp_log.h" +#include "utils.h" + +#define TAG "MODULE" +#define MAX_RETRIES 3 + +typedef struct { + char name[32]; + int value; +} config_t; + +static int process_data(const uint8_t *data, size_t len) +{ + if (data == NULL || len == 0) { + ESP_LOGE(TAG, "Invalid parameters"); + return -1; + } + + for (size_t i = 0; i < len; i++) { + // Process data + } + + return 0; +} +``` + +**Best Practices**: +- Use ESP_LOG* macros for logging (not printf) +- Check return values and handle errors +- Free allocated memory (no leaks) +- Use const for read-only parameters +- Validate input parameters +- Document complex logic with comments +- Keep functions small and focused +- No global mutable state (use static or pass context) +- No magic numbers (use named constants) +- No commented-out code (use git history) + +### Python Code (C2 Server) + +**Style Guide**: [PEP 8](https://pep8.org/) +- **Indentation**: 4 spaces +- **Line length**: 100 characters max +- **Naming**: + - Functions: `snake_case` + - Classes: `PascalCase` + - Constants: `UPPER_SNAKE_CASE` + - Private: `_leading_underscore` + +**Example**: +```python +import logging +from typing import List, Optional + +logger = logging.getLogger(__name__) + +class DeviceManager: + """Manages connected ESP32 devices.""" + + def __init__(self): + self._devices = {} + + def add_device(self, device_id: str, connection) -> None: + """Add a new device to the registry.""" + if not device_id: + raise ValueError("device_id cannot be empty") + + self._devices[device_id] = connection + logger.info(f"Device added: {device_id}") + + def get_device(self, device_id: str) -> Optional[object]: + """Retrieve device by ID.""" + return self._devices.get(device_id) +``` + +**Best Practices**: +- Type hints for function signatures +- Docstrings for classes and public functions +- Use logging module (not print statements) +- Handle exceptions appropriately +- Use context managers (`with` statements) +- Run `black` for formatting +- Run `flake8` for linting + +**Tools**: +```bash +# Format code +black tools/c2/ + +# Check style +flake8 tools/c2/ + +# Type checking +mypy tools/c2/ +``` + +### Documentation + +**Markdown Style**: +- Use ATX-style headers (`#`, `##`, `###`) +- Code blocks with language specifiers +- Tables for structured data +- Lists for sequential or unordered items + +**Code Comments**: +- Explain **why**, not **what** (code shows what) +- Keep comments up-to-date with code +- Use TODO/FIXME/NOTE for temporary notes +- Remove obsolete comments + +--- + +## Commit Guidelines + +### Commit Message Format + +``` +(): + + + +