docs: Add contributing and security policy documentation
This commit is contained in:
339
CONTRIBUTING.md
Normal file
339
CONTRIBUTING.md
Normal file
@@ -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! 🔥
|
||||
218
SECURITY.md
Normal file
218
SECURITY.md
Normal file
@@ -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)
|
||||
Reference in New Issue
Block a user