feat(api): extend commit and diff services with new functionality

- Add FindCommit, ListCommitsByOid, CommitIsAncestor RPCs to CommitService - Add CheckObjectsExist, CommitsByMessage, GetCommitStats RPCs to CommitService - Add LastCommitForPath, CountCommits, CountDivergingCommits RPCs to CommitService - Add RawDiff, RawPatch, FindChangedPaths RPCs to DiffService - Add FindMergeBase, WriteRef, SearchFilesByContent RPCs to RepositoryService - Add SearchFilesByName, ObjectsSize, RepositorySize RPCs to RepositoryService - Add FindLicense, OptimizeRepository, GetRawChanges RPCs to RepositoryService - Add FetchRemote, CreateRepositoryFromURL RPCs to RepositoryService - Implement server handlers for all new RPC methods - Add new modules for commit counting, finding, and querying features - Add new modules for diff changed paths and raw operations - Add new modules for refs and remote operations - Remove unnecessary comments from various source files - Update proto definitions with new message types and service methods
2026-06-08 15:37:08 +08:00
parent 8f472a0443
commit 66afd932ed
43 changed files with 3070 additions and 75 deletions
@@ -0,0 +1,96 @@
+# 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