diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b0fc77b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,339 @@ +# Contributing to Carbon HTTP Server + +Thank you for your interest in contributing to Carbon! This document provides guidelines and instructions for contributing. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [How to Contribute](#how-to-contribute) +- [Coding Standards](#coding-standards) +- [Testing](#testing) +- [Pull Request Process](#pull-request-process) +- [License](#license) + +## Code of Conduct + +By participating in this project, you agree to maintain a respectful and inclusive environment. Please: + +- Be respectful and considerate in all interactions +- Accept constructive criticism gracefully +- Focus on what is best for the project and community +- Show empathy towards other contributors + +## Getting Started + +### Prerequisites + +Before contributing, ensure you have: + +- Linux operating system (kernel 2.6.27+) +- GCC 4.8+ or Clang 3.4+ +- Make build system +- Required dependencies installed + +### Installing Dependencies + +```bash +# Debian/Ubuntu/Raspberry Pi OS +make install-deps + +# Or manually: +sudo apt-get install -y \ + libssl-dev \ + libmagic-dev \ + libnghttp2-dev \ + build-essential \ + pkg-config \ + zlib1g-dev +``` + +## Development Setup + +1. **Fork the repository** + + Click the "Fork" button on GitHub to create your own copy. + +2. **Clone your fork** + + ```bash + git clone https://github.com/YOUR_USERNAME/Carbon.git + cd Carbon + ``` + +3. **Add upstream remote** + + ```bash + git remote add upstream https://github.com/Azreyo/Carbon.git + ``` + +4. **Build the project** + + ```bash + # Standard build + make + + # Debug build (with symbols, no optimization) + make debug + + # Release build (maximum optimization) + make release + ``` + +5. **Run the server** + + ```bash + ./server + # Or with a custom config + ./server server.conf + ``` + +## How to Contribute + +### Reporting Bugs + +1. Check existing issues to avoid duplicates +2. Use the bug report template if available +3. Include: + - Clear description of the issue + - Steps to reproduce + - Expected vs actual behavior + - System information (OS, compiler version) + - Relevant log output + +### Suggesting Features + +1. Check existing issues and discussions +2. Describe the feature and its use case +3. Explain why it would benefit the project +4. Consider implementation complexity + +### Submitting Code + +1. **Create a feature branch** + + ```bash + git checkout -b feature/your-feature-name + # or + git checkout -b fix/bug-description + ``` + +2. **Make your changes** + + - Follow the [coding standards](#coding-standards) + - Keep commits focused and atomic + - Write meaningful commit messages + +3. **Test your changes** + + ```bash + # Build and test + make clean && make + ./server + + # Test with Docker + docker-compose up --build + ``` + +4. **Submit a pull request** + +## Coding Standards + +### C Code Style + +- **Indentation**: 4 spaces (no tabs) +- **Brace style**: Allman style (braces on new lines) +- **Line length**: Maximum 100 characters +- **Naming conventions**: + - Functions: `snake_case` + - Variables: `snake_case` + - Constants/Macros: `UPPER_SNAKE_CASE` + - Types/Structs: `snake_case_t` suffix + +### Example Code Style + +```c +// Good example +typedef struct +{ + int socket_fd; + SSL *ssl; + bool is_https; +} connection_t; + +static int handle_connection(connection_t *conn) +{ + if (!conn) + { + return -1; + } + + // Process connection + return 0; +} + +#define MAX_BUFFER_SIZE 8192 +``` + +### Documentation + +- Add comments for complex logic +- Document public functions with purpose and parameters +- Update `DOCUMENTATION.md` for new features +- Keep `README.md` current + +### Security Considerations + +When contributing code: + +- Validate all input +- Use bounded string operations (`snprintf`, not `sprintf`) +- Check return values +- Avoid buffer overflows +- Handle errors gracefully +- Don't log sensitive information + +### Compiler Warnings + +All code must compile without warnings using: + +```bash +gcc -Wall -Wextra -Werror +``` + +## Project Structure + +``` +Carbon/ +├── src/ +│ ├── server.c # Main server implementation +│ ├── config_parser.c # Configuration file parser +│ ├── server_config.c # Server configuration defaults +│ ├── server_config.h # Configuration structures +│ ├── http2.c # HTTP/2 implementation +│ ├── http2.h # HTTP/2 headers +│ ├── websocket.c # WebSocket implementation +│ ├── websocket.h # WebSocket headers +│ ├── performance.c # Performance optimizations +│ ├── performance.h # Performance headers +│ ├── logging.c # Logging system +│ └── logging.h # Logging headers +├── www/ # Static web files +├── server.conf # Default configuration +├── Makefile # Build system +├── Dockerfile # Container build +├── docker-compose.yml # Container orchestration +├── README.md # Project overview +├── DOCUMENTATION.md # Detailed documentation +├── SECURITY.md # Security policy +├── CONTRIBUTING.md # This file +└── LICENSE # License terms +``` + +## Testing + +### Manual Testing + +```bash +# Basic HTTP test +curl http://localhost:8080/ + +# HTTPS test (if enabled) +curl -k https://localhost:8443/ + +# WebSocket test +# Open www/websocket-test.html in browser + +# HTTP/2 test +curl --http2 -k https://localhost:8443/ +``` + +### Docker Testing + +```bash +# Build and run +docker-compose up --build + +# Check logs +docker logs carbon-http-server + +# Health check +curl http://localhost:8080/ +``` + +### Performance Testing + +```bash +# Using Apache Benchmark +ab -n 10000 -c 100 http://localhost:8080/ + +# Using wrk +wrk -t4 -c100 -d30s http://localhost:8080/ +``` + +## Pull Request Process + +1. **Ensure your code**: + - Compiles without warnings + - Follows coding standards + - Is properly documented + - Doesn't break existing functionality + +2. **Update documentation** if needed: + - `README.md` for user-facing changes + - `DOCUMENTATION.md` for technical details + - Code comments for complex logic + +3. **Create the pull request**: + - Use a clear, descriptive title + - Reference any related issues + - Describe what changes were made and why + - Include testing steps + +4. **Review process**: + - Maintainers will review your PR + - Address any requested changes + - Be patient and responsive + +### PR Title Format + +``` +feat: Add new feature description +fix: Fix bug description +docs: Update documentation +refactor: Code refactoring +perf: Performance improvement +security: Security fix +``` + +## Areas for Contribution + +Current areas where contributions are welcome: + +- [ ] Unit test implementation +- [ ] Additional HTTP/2 features +- [ ] Performance optimizations +- [ ] Documentation improvements +- [ ] Bug fixes +- [ ] Security enhancements +- [ ] Cross-platform support research +- [ ] CI/CD pipeline improvements + +## Questions? + +If you have questions about contributing: + +1. Check existing documentation +2. Search closed issues +3. Open a discussion or issue + +## License + +By contributing to Carbon, you agree that your contributions will be licensed under the same [MIT License (Modified - Non-Commercial)](LICENSE) that covers the project. + +**Important**: Commercial use of contributions requires explicit permission from the copyright holders. See the LICENSE file for full terms. + +--- + +Thank you for contributing to Carbon HTTP Server! 🔥 diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..61d7627 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,218 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +| ------- | ------------------ | +| 1.x | :white_check_mark: | + +## Reporting a Vulnerability + +If you discover a security vulnerability in Carbon HTTP Server, please report it responsibly: + +1. **Do NOT** open a public GitHub issue for security vulnerabilities +2. Email your findings to the maintainers privately +3. Include detailed steps to reproduce the vulnerability +4. Allow reasonable time for a fix before public disclosure + +## Security Features + +Carbon HTTP Server implements multiple layers of security: + +### SSL/TLS Encryption + +- Full HTTPS support with OpenSSL integration +- Modern cipher suites with TLS 1.2+ support +- ALPN (Application-Layer Protocol Negotiation) for HTTP/2 +- Configurable certificate and key paths + +```conf +use_https = true +ssl_cert_path = ssl/cert/cert.pem +ssl_key_path = ssl/key/key.key +``` + +### Security Headers + +All responses include security headers by default: + +| Header | Value | Purpose | +|--------|-------|---------| +| `X-Content-Type-Options` | `nosniff` | Prevents MIME-type sniffing | +| `X-Frame-Options` | `SAMEORIGIN` | Clickjacking protection | +| `X-XSS-Protection` | `1; mode=block` | XSS filter protection | +| `Content-Security-Policy` | `default-src 'self'` | CSP protection | +| `Strict-Transport-Security` | `max-age=31536000` | HTTPS enforcement (when enabled) | +| `Referrer-Policy` | `strict-origin-when-cross-origin` | Referrer information control | + +### Rate Limiting + +Dynamic rate limiting protects against abuse and DDoS attacks: + +- Configurable request limits per time window +- CPU-based adaptive rate limiting +- Per-IP tracking with automatic cleanup +- Returns `429 Too Many Requests` when limits exceeded + +### Input Validation & Sanitization + +- URL sanitization to prevent path traversal attacks +- Request size limits (`MAX_REQUEST_SIZE = 16384`) +- Filename and path validation +- Buffer overflow protection with bounded string operations + +### Memory Safety + +- Stack protector enabled (`-fstack-protector-strong`) +- FORTIFY_SOURCE level 2 +- Position Independent Executable (PIE) +- RELRO (Relocation Read-Only) linking +- No strict overflow (`-fno-strict-overflow`) + +### Docker Security + +When running in Docker, additional security measures are applied: + +```yaml +security_opt: + - no-new-privileges:true +cap_drop: + - ALL +read_only: true +``` + +- Non-root user execution (`carbon:carbon`) +- Dropped capabilities +- Read-only root filesystem +- Temporary filesystem for `/tmp` +- No privilege escalation + +## Secure Configuration Recommendations + +### Production Checklist + +1. **Enable HTTPS** + ```conf + use_https = true + ``` + +2. **Use valid SSL certificates** + - Obtain certificates from a trusted CA (e.g., Let's Encrypt) + - Keep private keys secure with proper file permissions + +3. **Set appropriate log mode** + ```conf + log_mode = classic # Avoid debug/advanced in production + ``` + +4. **Limit connections and threads** + ```conf + max_threads = 4 + max_connections = 1024 + ``` + +5. **Restrict network binding** + ```conf + server_name = 127.0.0.1 # Or specific interface + ``` + +### File Permissions + +```bash +# Server binary +chmod 500 server + +# Configuration files +chmod 600 server.conf + +# SSL certificates +chmod 600 ssl/cert/cert.pem +chmod 600 ssl/key/key.key + +# WWW directory (read-only) +chmod -R 444 www/ +chmod 555 www/ +``` + +### Firewall Rules + +```bash +# Allow HTTP (if needed) +sudo ufw allow 8080/tcp + +# Allow HTTPS +sudo ufw allow 8443/tcp + +# Deny all other incoming +sudo ufw default deny incoming +``` + +## Known Security Considerations + +### WebSocket Security + +When enabling WebSocket support: + +- WebSocket connections validate the `Sec-WebSocket-Key` header +- Frame masking is enforced per RFC 6455 +- UTF-8 validation for text frames +- Proper close frame handling + +```conf +enable_websocket = true # Only enable if needed +``` + +### HTTP/2 Security + +HTTP/2 is only available over HTTPS (h2), not cleartext (h2c): + +```conf +use_https = true +enable_http2 = true +``` + +### Logging Security + +- Sensitive data is sanitized in log output +- Log files should have restricted permissions +- Consider log rotation to prevent disk exhaustion + +```conf +log_file = log/server.log +log_mode = classic +``` + +## Build Security + +The Makefile includes security-focused compiler flags: + +```makefile +CFLAGS += -fstack-protector-strong +CFLAGS += -fPIE -D_FORTIFY_SOURCE=2 +CFLAGS += -Wformat -Wformat-security -Werror=format-security +LDFLAGS = -Wl,-z,relro,-z,now -pie +``` + +## Security Updates + +- Monitor the repository for security updates +- Keep dependencies (OpenSSL, nghttp2, zlib) updated +- Rebuild after dependency updates + +## Disclaimer + +Carbon HTTP Server is provided for educational and testing purposes. While security measures are implemented, the software: + +- Has not undergone formal security audit +- May contain undiscovered vulnerabilities +- Should be thoroughly tested before production use + +**Always perform your own security assessment before deploying in production environments.** + +## References + +- [OWASP Secure Headers Project](https://owasp.org/www-project-secure-headers/) +- [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/) +- [RFC 6455 - WebSocket Protocol](https://tools.ietf.org/html/rfc6455) +- [RFC 7540 - HTTP/2](https://tools.ietf.org/html/rfc7540) +- [OpenSSL Security](https://www.openssl.org/policies/secpolicy.html)