ivuorinen/f2b
1
0
Fork 0
mirror of https://github.com/ivuorinen/f2b.git synced 2026-03-07 18:58:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

fix: repair Renovate config, convert Makefile to go run, update GitHub Actions (#120)

Browse Source 
* fix: repair Renovate config and convert Makefile to go run (#117)

- Remove non-existent `github>renovatebot/presets:golang` preset that
  broke Renovate PR creation
- Replace deprecated `fileMatch` with `managerFilePatterns` in
  customManagers
- Rewrite regex to match new Makefile pattern (renovate comment above
  version variable assignment)
- Fix `matchFileNames` glob pattern (`*.mk` -> `**/*.mk`)
- Convert all tool invocations from `go install` + global binary to
  `go run tool@version` for reproducible builds
- Convert npm global tools to `npx --yes` invocations
- Remove `dev-deps` and `check-deps` targets (tools auto-download)
- Add mdformat pre-commit hook with GFM support and config
- Add `fmt-md` Makefile target for manual markdown formatting
- Update local golangci-lint pre-commit hook to use `go run`
- Apply golangci-lint v2.10.1 auto-fixes (fmt.Fprintf optimization)
- Add nolint:gosec annotations for legitimate exec.Command usage
- Exclude .serena/ from mdformat and megalinter
- Add markdown indent_size=unset in .editorconfig for CommonMark compat

* chore(deps): update GitHub Actions to latest versions

- anthropics/claude-code-action: v1.0.34 -> v1.0.64
- actions/setup-go: v6.2.0 -> v6.3.0
- actions/upload-artifact: v6.0.0 -> v7.0.0
- goreleaser/goreleaser-action: v6.4.0 -> v7.0.0
- docker/login-action: v3.6.0 -> v3.7.0
- ivuorinen/actions: v2026.01.21 -> v2026.02.24

* fix: address code review feedback

- Fix issue template YAML frontmatter (replace underscore separators
  with proper --- delimiters); exclude templates from mdformat
- Replace string(rune(n)) with strconv.Itoa(n) in test files to produce
  deterministic numeric directory names instead of Unicode characters
- Remove stale `make dev-deps` reference in README, replace with
  `make dev-setup`
- Extract ban/unban format strings into shared.MetricsFmtBanOperations
  and shared.MetricsFmtUnbanOperations constants
- Replace hardcoded coverage percentages in README with evergreen
  phrasing

* fix: address round 2 code review feedback for PR #120

- Fix corrupted path traversal example in docs/security.md
- Fix Renovate .mk regex to match nested paths (.*\.mk$)
- Update checkmake pre-commit hook to v0.3.2 to match Makefile
- Add sync.WaitGroup to unsynchronized goroutines in security tests
- Fix fmt-md target to use pre-commit run mdformat
- Pin markdownlint-cli2 to v0.21.0 in lint-md target
- Standardize //nolint:gosec to // #nosec annotations for gosec CLI

* fix(ci): install PyYAML dependency for PR lint workflow

The pr-lint workflow uses ivuorinen/actions/pr-lint which internally
calls validate-inputs running a Python script that imports yaml.
Python was set up but PyYAML was never installed, causing
ModuleNotFoundError at runtime.

* fix: address round 3 code review feedback for PR #120

- Wrap Windows-style path traversal example in backtick code span so
  backslashes render literally in docs/security.md
- Add Renovate-managed MARKDOWNLINT_CLI2_VERSION variable in Makefile
  to match the pattern used by all other tool versions
This commit is contained in:
Ismo Vuorinen
2026-03-01 19:09:17 +02:00
committed by GitHub
parent 605f2b9580
commit 98b53d84b5
33 changed files with 281 additions and 345 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
docs/api.md
View File

@@ -239,14 +239,14 @@ const (
The configuration system supports the following environment variables:
| Variable | Description | Default |
| -------- | ----------- | ------- |
| `F2B_LOG_DIR` | Log directory path | `/var/log` |
| `F2B_FILTER_DIR` | Filter directory path | `/etc/fail2ban/filter.d` |
| `F2B_LOG_LEVEL` | Log level | `info` |
| `F2B_COMMAND_TIMEOUT` | Command timeout | `30s` |
| `F2B_FILE_TIMEOUT` | File operation timeout | `10s` |
| `F2B_PARALLEL_TIMEOUT` | Parallel operation timeout | `60s` |
| Variable | Description | Default |
| ---------------------- | -------------------------- | ------------------------ |
| `F2B_LOG_DIR` | Log directory path | `/var/log` |
| `F2B_FILTER_DIR` | Filter directory path | `/etc/fail2ban/filter.d` |
| `F2B_LOG_LEVEL` | Log level | `info` |
| `F2B_COMMAND_TIMEOUT` | Command timeout | `30s` |
| `F2B_FILE_TIMEOUT` | File operation timeout | `10s` |
| `F2B_PARALLEL_TIMEOUT` | Parallel operation timeout | `60s` |
### Path Security
@@ -550,30 +550,30 @@ func (h *HTTPHandler) writeError(w http.ResponseWriter, code int, err error) {
### Error Handling Best Practices
1. Always use contextual errors for user-facing messages
2. Provide remediation hints where possible
3. Log errors with appropriate context
4. Use error categories for systematic handling
1. Provide remediation hints where possible
1. Log errors with appropriate context
1. Use error categories for systematic handling
### Context Usage
1. Always use context for operations that can timeout
2. Propagate context through the call chain
3. Add relevant context values for logging
4. Use context cancellation for cleanup
1. Propagate context through the call chain
1. Add relevant context values for logging
1. Use context cancellation for cleanup
### Testing
1. Use the fluent testing framework for command tests
2. Always use mock environments for integration tests
3. Test both success and failure scenarios
4. Include timeout testing for long-running operations
1. Always use mock environments for integration tests
1. Test both success and failure scenarios
1. Include timeout testing for long-running operations
### Performance
1. Use the metrics system to monitor performance
2. Implement proper caching where appropriate
3. Use object pooling for frequently allocated objects
4. Profile and optimize hot paths
1. Implement proper caching where appropriate
1. Use object pooling for frequently allocated objects
1. Profile and optimize hot paths
This documentation provides a comprehensive overview of the f2b internal APIs and patterns.
For specific implementation details, refer to the source code and inline documentation.

42
docs/architecture.md
View File

@@ -35,17 +35,21 @@ validation caching, and parallel processing capabilities for enterprise-grade re
### fail2ban/ Package
- **Purpose**: Core business logic and system interaction
- **Key Interfaces**:
- `Client`: Main interface for fail2ban operations with context support
- `Runner`: Command execution interface
- `SudoChecker`: Privilege validation interface
- **Implementations**:
- `RealClient`: Production fail2ban client with timeout handling
- `MockClient`: Comprehensive test double with thread-safe operations
- `NoOpClient`: Safe fallback implementation
- **Advanced Features**:
- Context-aware operations with timeout and cancellation support
- Validation caching system with thread-safe operations
- Optimized ban record parsing with object pooling
@@ -105,14 +109,14 @@ validation caching, and parallel processing capabilities for enterprise-grade re
### Command Execution Flow
1. **CLI Parsing**: Cobra processes command-line arguments
2. **Context Creation**: Create context with timeout for operation
3. **Validation**: Input validation with caching and sanitization
4. **Privilege Check**: Determine if sudo is required
5. **Metrics Start**: Begin performance metrics collection
6. **Business Logic**: Execute fail2ban operations via Client interface with context
7. **Parallel Processing**: Use parallel workers for multi-jail operations
8. **Metrics End**: Record operation timing and success/failure
9. **Output**: Format and display results (plain or JSON)
1. **Context Creation**: Create context with timeout for operation
1. **Validation**: Input validation with caching and sanitization
1. **Privilege Check**: Determine if sudo is required
1. **Metrics Start**: Begin performance metrics collection
1. **Business Logic**: Execute fail2ban operations via Client interface with context
1. **Parallel Processing**: Use parallel workers for multi-jail operations
1. **Metrics End**: Record operation timing and success/failure
1. **Output**: Format and display results (plain or JSON)
### Dependency Flow
@@ -170,25 +174,25 @@ fail2ban/client.go
### Adding New Commands
1. Create new file in `cmd/` package
2. Implement command using established patterns with context support
3. Use dependency injection for testability
4. Add performance metrics collection
5. Implement fluent testing framework patterns
6. Add comprehensive tests with mocks and context-aware operations
1. Implement command using established patterns with context support
1. Use dependency injection for testability
1. Add performance metrics collection
1. Implement fluent testing framework patterns
1. Add comprehensive tests with mocks and context-aware operations
### Adding New Backends
1. Implement the `Client` interface
2. Add any new required interfaces (Runner, etc.)
3. Update main.go to support new backend
4. Add configuration options
1. Add any new required interfaces (Runner, etc.)
1. Update main.go to support new backend
1. Add configuration options
### Adding New Output Formats
1. Extend output formatting helpers
2. Update command implementations
3. Add format validation
4. Test with existing commands
1. Update command implementations
1. Add format validation
1. Test with existing commands
## Testing Architecture

18
docs/faq.md
View File

@@ -8,7 +8,7 @@
extensible, and user-friendly alternative to Bash scripts for interacting with Fail2Ban, with automatic sudo
privilege management, shell completion, and comprehensive security features.
---
______________________________________________________________________
## Installation & Setup
@@ -34,7 +34,7 @@ Or install globally:
go install github.com/ivuorinen/f2b@latest
```
---
______________________________________________________________________
## Usage
@@ -171,7 +171,7 @@ f2b --command-timeout=45s ban 192.168.1.100
f2b --parallel-timeout=120s banned all
```
---
______________________________________________________________________
## Troubleshooting
@@ -193,9 +193,9 @@ f2b --parallel-timeout=120s banned all
This means you need elevated privileges for the operation you're trying to perform:
1. **Check your privileges:** Run `f2b --log-level=debug version` to see your privilege status
2. **Add sudo:** Try `sudo f2b [command]`
3. **Join sudo group:** Ask your admin to add you to the sudo group
4. **Test sudo access:** Run `sudo -n true` to check if you can use sudo
1. **Add sudo:** Try `sudo f2b [command]`
1. **Join sudo group:** Ask your admin to add you to the sudo group
1. **Test sudo access:** Run `sudo -n true` to check if you can use sudo
### The CLI says "permission denied" or "operation not permitted"
@@ -265,7 +265,7 @@ ls -la /etc/fail2ban/
sudo fail2ban-client ping
```
---
______________________________________________________________________
## Development
@@ -279,11 +279,11 @@ go test ./...
See the `CONTRIBUTING.md` and the Contributing section in the README.
---
______________________________________________________________________
## Still need help?
- Open an issue on GitHub: https://github.com/ivuorinen/f2b/issues
- Contact the maintainer: ismo@ivuorinen.net
---
______________________________________________________________________

24
docs/linting.md
View File

@@ -225,11 +225,11 @@ Both workflows now use unified pre-commit:
### Before Committing
1. **Read configuration files first**: `.editorconfig`, `.golangci.yml`,
`.markdownlint.json`, `.yamlfmt.yaml`, `.pre-commit-config.yaml`
2. **Apply configuration rules** during development
3. **Run pre-commit checks**: `pre-commit run --all-files`
4. **Fix all issues** across the project
5. **Run tests**: `go test ./...`
`.markdownlint.json`, `.yamlfmt.yaml`, `.pre-commit-config.yaml`
1. **Apply configuration rules** during development
1. **Run pre-commit checks**: `pre-commit run --all-files`
1. **Fix all issues** across the project
1. **Run tests**: `go test ./...`
### Recommended IDE Setup
@@ -303,19 +303,19 @@ All YAML files include schema references for better IDE support:
### Debugging Tips
1. **Run individual hooks** to isolate issues
2. **Use `--verbose` flag** with pre-commit
3. **Check configuration files** for rule customizations
4. **Verify tool versions** match CI environment
1. **Use `--verbose` flag** with pre-commit
1. **Check configuration files** for rule customizations
1. **Verify tool versions** match CI environment
## Adding New Linting Rules
### Process
1. Update configuration files (`.markdownlint.json`, `.yamlfmt.yaml`, etc.)
2. Test changes locally: `pre-commit run --all-files`
3. Update `.pre-commit-config.yaml` if adding new hooks
4. Document changes in this file
5. Consider backward compatibility
1. Test changes locally: `pre-commit run --all-files`
1. Update `.pre-commit-config.yaml` if adding new hooks
1. Document changes in this file
1. Consider backward compatibility
### Best Practices

64
docs/security.md
View File

@@ -57,13 +57,13 @@ f2b intelligently manages sudo requirements through a comprehensive privilege ch
### Privilege Escalation Process
1. **Pre-flight Check**: Determine user capabilities before command execution
2. **Context Creation**: Create context with timeout for the operation
3. **Command Classification**: Identify if the operation requires privileges
4. **Smart Escalation**: Only add sudo when necessary for specific commands
5. **Validation**: Ensure privilege escalation succeeded with timeout protection
6. **Execution**: Run command with appropriate privileges and context
7. **Timeout Handling**: Gracefully handle hanging operations with cancellation
8. **Audit**: Log privileged operations with context information
1. **Context Creation**: Create context with timeout for the operation
1. **Command Classification**: Identify if the operation requires privileges
1. **Smart Escalation**: Only add sudo when necessary for specific commands
1. **Validation**: Ensure privilege escalation succeeded with timeout protection
1. **Execution**: Run command with appropriate privileges and context
1. **Timeout Handling**: Gracefully handle hanging operations with cancellation
1. **Audit**: Log privileged operations with context information
### Error Handling
@@ -358,10 +358,10 @@ func setupSecureTestEnvironment(t *testing.T) {
- **Issue**: Insufficient path validation against sophisticated attacks
- **Impact**: Access to files outside intended directories
- **Fix**: Comprehensive path traversal protection with extensive test cases covering:
- Unicode normalization attacks (\u002e\u002e)
- Unicode normalization attacks (\\u002e\\u002e)
- Mixed case traversal (/var/LOG/../../../etc/passwd)
- Multiple slashes (/var/log////../../etc/passwd)
- Windows-style paths on Unix (/var/log\..\..\..\etc\passwd)
- Windows-style paths on Unix (`/var/log\..\..\..\etc\passwd`)
- URL encoding variants (%2e%2e%2f)
- Null byte injection attacks
@@ -382,15 +382,15 @@ func setupSecureTestEnvironment(t *testing.T) {
### Defense in Depth
1. **Input Validation**: First line of defense against malicious input with caching
2. **Advanced Path Traversal Protection**: Extensive sophisticated attack vector protection
3. **Privilege Validation**: Ensure user has necessary permissions with timeout protection
4. **Context-Aware Execution**: Use argument arrays with timeout and cancellation support
5. **Safe Execution**: Never use shell strings, always use context-aware operations
6. **Error Handling**: Fail safely without information leakage, include context information
7. **Audit Logging**: Track privileged operations with contextual information
8. **Test Isolation**: Prevent test-time security compromises with comprehensive mocks
9. **Performance Security**: Validation caching prevents DoS through repeated validation
10. **Timeout Protection**: Prevent resource exhaustion through hanging operations
1. **Advanced Path Traversal Protection**: Extensive sophisticated attack vector protection
1. **Privilege Validation**: Ensure user has necessary permissions with timeout protection
1. **Context-Aware Execution**: Use argument arrays with timeout and cancellation support
1. **Safe Execution**: Never use shell strings, always use context-aware operations
1. **Error Handling**: Fail safely without information leakage, include context information
1. **Audit Logging**: Track privileged operations with contextual information
1. **Test Isolation**: Prevent test-time security compromises with comprehensive mocks
1. **Performance Security**: Validation caching prevents DoS through repeated validation
1. **Timeout Protection**: Prevent resource exhaustion through hanging operations
### Security Boundaries
@@ -403,13 +403,13 @@ User Input → Context → Validation → Path Traversal → Privilege Check →
**Enhanced Security Flow:**
1. **Context Creation**: Establish timeout and cancellation context
2. **Input Sanitization**: Clean and validate all user input
3. **Cache Validation**: Check validation cache for performance and DoS protection
4. **Path Traversal Protection**: Block extensive sophisticated attack vectors
5. **Privilege Verification**: Confirm user permissions with timeout protection
6. **Context-Aware Execution**: Execute with timeout and cancellation support
7. **Timeout Handling**: Gracefully handle hanging operations
8. **Comprehensive Auditing**: Log all operations with context information
1. **Input Sanitization**: Clean and validate all user input
1. **Cache Validation**: Check validation cache for performance and DoS protection
1. **Path Traversal Protection**: Block extensive sophisticated attack vectors
1. **Privilege Verification**: Confirm user permissions with timeout protection
1. **Context-Aware Execution**: Execute with timeout and cancellation support
1. **Timeout Handling**: Gracefully handle hanging operations
1. **Comprehensive Auditing**: Log all operations with context information
## Incident Response
@@ -418,17 +418,17 @@ User Input → Context → Validation → Path Traversal → Privilege Check →
**For security vulnerabilities:**
1. **Do not** open public GitHub issues
2. Email: `ismo@ivuorinen.net` with subject "SECURITY: f2b vulnerability"
3. Include: Description, impact assessment, reproduction steps
4. Expect: Acknowledgment within 48 hours
1. Email: `ismo@ivuorinen.net` with subject "SECURITY: f2b vulnerability"
1. Include: Description, impact assessment, reproduction steps
1. Expect: Acknowledgment within 48 hours
### Security Update Process
1. **Assessment**: Evaluate impact and affected versions
2. **Development**: Create fix with security tests
3. **Testing**: Comprehensive security testing
4. **Release**: Coordinated disclosure with security advisory
5. **Communication**: Notify users via GitHub security advisories
1. **Development**: Create fix with security tests
1. **Testing**: Comprehensive security testing
1. **Release**: Coordinated disclosure with security advisory
1. **Communication**: Notify users via GitHub security advisories
## Security Best Practices

10
docs/testing.md
View File

@@ -604,11 +604,11 @@ go tool cover -func=coverage.out | grep total
### Avoid These Mistakes
1. **Real sudo execution in tests** - Always use MockSudoChecker
2. **Hardcoded file paths** - Use temporary files or mocks
3. **Network dependencies** - Mock all external calls
4. **Race conditions** - Use proper synchronization in concurrent tests
5. **Leaked goroutines** - Clean up background processes
6. **Platform dependencies** - Write portable tests
1. **Hardcoded file paths** - Use temporary files or mocks
1. **Network dependencies** - Mock all external calls
1. **Race conditions** - Use proper synchronization in concurrent tests
1. **Leaked goroutines** - Clean up background processes
1. **Platform dependencies** - Write portable tests
### Enhanced Security Testing Checklist