Azreyo/Carbon
1
1
Fork 0
Code Actions Packages Projects Releases Wiki Activity

docs: Add contributing and security policy documentation

Browse Source
This commit is contained in:
Azreyo
2025-12-11 23:13:33 +01:00
parent e564f6f292
commit 0616e5124e
2 changed files with 557 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

339
CONTRIBUTING.md Normal file
View 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
View 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)