# Gitks Security Best Practices

This document outlines security best practices for the gitks project.

## Input Validation

### Revision Strings
All revision strings (branch names, commit hashes, refs) are validated using `sanitize::validate_revision()`:
- Prevents command injection via `~N` and `^N` operators
- Limits revision string length to 256 characters
- Limits ancestry depth to 10000 to prevent DoS attacks
- Validates branch name characters to prevent shell metacharacter injection

### File Paths
File paths are validated using `sanitize::validate_file_path()`:
- Rejects absolute paths
- Blocks path traversal attacks (`..`)
- Prevents null byte injection
- Blocks `.git` directory access
- On Windows, blocks reserved device names (CON, PRN, AUX, NUL, COM1-9, LPT1-9)

### Git Configuration Keys
Configuration keys are validated using `sanitize::validate_config_key()`:
- Blocks dangerous keys that could execute arbitrary commands (core.sshCommand, core.hooksPath)
- Blocks network-related keys (http.proxy, https.proxy, remote.*.url)
- Blocks credential helpers
- Only allows alphanumeric characters, dots, hyphens, and underscores

### Relative Paths
Relative paths are validated using `sanitize::validate_relative_path()`:
- Rejects absolute paths
- Blocks path traversal attacks (`..`)

## Path Security

### TOCTOU Prevention
Path validation uses a unified approach to prevent Time-Of-Check-Time-Of-Use vulnerabilities:
1. Canonicalize the path if it exists
2. If path doesn't exist, validate parent directory and filename separately
3. Verify canonical path starts with allowed prefix
4. Reject any path that escapes the allowed directory

### Cache Invalidation
Cache entries are invalidated when repositories are modified:
- Uses precise substring matching on relative path
- Invalidates all cache keys containing the modified repository path
- Prevents stale data from being served after modifications

## Message Decoding Security

### String Decoding
The `decode_strings()` function in `actor/message.rs` includes:
- Total message size limit (50MB)
- Individual string length limit (10MB)
- Overflow protection using `checked_add()`
- Graceful degradation on malformed data

## Cluster Registration

### Primary/Replica Role Assignment
When registering repositories in a cluster:
- Single node: registers as PRIMARY
- Multiple nodes: registers as REPLICA initially
- Final role determination happens at query time via `route_repository`
- This conservative approach prevents split-brain scenarios

## Testing

All security-critical functions have comprehensive unit tests:
- `tests/sanitize_test.rs`: Input validation tests
- `tests/macro_test.rs`: Revision resolution tests
- Tests cover both valid and malicious inputs

## Code Quality

- All code passes `cargo clippy --all-targets --all-features` with zero warnings
- Code is formatted with `cargo fmt`
- All tests pass with `cargo test`
- No known security vulnerabilities in dependencies (verified with `cargo deny`)

## Recommendations for Users

1. **Never trust user input**: Always validate revisions, paths, and config keys
2. **Use the sanitize module**: All user-provided strings should go through validation
3. **Keep dependencies updated**: Run `cargo update` regularly and check for security advisories
4. **Monitor logs**: Watch for validation failures which may indicate attack attempts
5. **Limit cluster size**: The cluster registration logic assumes a reasonable number of nodes
6. **Use HTTPS**: When deploying in production, use TLS for gRPC connections
7. **Audit configuration**: Regularly review which git config keys are allowed

## Reporting Security Issues

If you discover a security vulnerability, please report it responsibly by:
1. Creating a private security advisory
2. Providing detailed reproduction steps
3. Allowing maintainers time to address the issue before public disclosure