gitks/CLAUDE.md

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