README
¶
pkg/io
This package provides utilities for input and output operations in KSail.
Purpose
Provides safe and secure file I/O operations with built-in protection against path traversal attacks and other security vulnerabilities. The package includes utilities for reading and writing files safely within specified base directories, along with helpers for working with filesystem paths.
Features
- Safe File Reading:
ReadFileSafeprevents path traversal attacks by ensuring files are within the specified base directory - Path Validation: Resolves and validates file paths to prevent access outside intended directories
- Home Directory Expansion:
ExpandHomePathconverts~/prefixes into the user's absolute home directory while preserving other paths unchanged - Security: Protects against accidental file inclusion and malicious path manipulation
- Clean Path Handling: Automatically cleans and normalizes file paths
Security
The package includes ErrPathOutsideBase error to indicate when a file path is outside the specified base directory, providing protection against:
- Path traversal attacks (e.g.,
../../../etc/passwd) - Symlink attacks
- Accidental access to system files
Subpackages
- pkg/io/generator/ - Resource generation utilities
- pkg/io/marshaller/ - Data marshalling utilities
Usage
import "github.com/devantler-tech/ksail-go/pkg/io"
// Safely read a file within a base directory
baseDir := "/safe/working/directory"
filePath := "config/settings.yaml"
data, err := io.ReadFileSafe(baseDir, filePath)
if err != nil {
if errors.Is(err, io.ErrPathOutsideBase) {
log.Fatal("Security violation: file outside base directory")
}
log.Fatal("Failed to read file:", err)
}
Documentation
¶
Overview ¶
Package io provides utilities for input and output operations.
This package contains utilities for reading from and writing to files, along with various I/O helper functions for file operations.
Index ¶
- Variables
- func ExpandHomePath(path string) (string, error)
- func FindFile(filePath string) (string, error)
- func GetWriter(quiet bool) io.Writer
- func ReadFileSafe(basePath, filePath string) ([]byte, error)
- func TryWrite(content string, writer io.Writer) (string, error)
- func TryWriteFile(content string, output string, force bool) (string, error)
- func WriteFileSafe(content, basePath, filePath string, force bool) error
Constants ¶
This section is empty.
Variables ¶
var ErrBasePath = errors.New("base path cannot be empty")
ErrBasePath is returned when the base path is empty.
var ErrEmptyOutputPath = errors.New("output path cannot be empty")
ErrEmptyOutputPath is returned when the output path is empty.
var ErrPathOutsideBase = errors.New("invalid path: file is outside base directory")
ErrPathOutsideBase is returned when a file path is outside the specified base directory.
Functions ¶
func ExpandHomePath ¶
ExpandHomePath expands a path beginning with ~/ to the user's home directory.
func FindFile ¶
FindFile resolves a file path with directory traversal. For absolute paths, returns the path as-is. For relative paths, traverses up from the current directory to find the file. Returns the resolved absolute path if found, or the original path if not found.
func GetWriter ¶
GetWriter returns an appropriate writer based on the quiet flag. If quiet is true, returns io.Discard to silence output. If quiet is false, returns os.Stdout for normal output.
func ReadFileSafe ¶
ReadFileSafe reads the file at path only if it is located within baseDir. It resolves absolute paths and rejects reads where the resolved path is outside baseDir (prevents path traversal and accidental file inclusion).
func TryWriteFile ¶
TryWriteFile writes content to a file path, handling force/overwrite logic. It validates that the output path doesn't contain path traversal attempts.
func WriteFileSafe ¶
WriteFileSafe writes content to a file path only if it is within the specified base directory. It prevents path traversal attacks by validating the path is within baseDir.
Types ¶
This section is empty.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package generator provides an interface for generating files from code.
|
Package generator provides an interface for generating files from code. |
|
k3d
Package k3dgenerator provides utilities for generating k3d cluster configurations.
|
Package k3dgenerator provides utilities for generating k3d cluster configurations. |
|
kind
Package kindgenerator provides utilities for generating kind cluster configurations.
|
Package kindgenerator provides utilities for generating kind cluster configurations. |
|
kustomization
Package kustomizationgenerator provides utilities for generating kustomization.yaml files.
|
Package kustomizationgenerator provides utilities for generating kustomization.yaml files. |
|
testutils
Package testutils provides generator-specific test utilities.
|
Package testutils provides generator-specific test utilities. |
|
yaml
Package yamlgenerator provides YAML generation functionality for arbitrary models.
|
Package yamlgenerator provides YAML generation functionality for arbitrary models. |
|
Package marshaller provides functionality for marshaling and unmarshaling resources.
|
Package marshaller provides functionality for marshaling and unmarshaling resources. |
|
yaml
Package yamlmarshaller provides functionality for marshaling and unmarshaling YAML documents.
|
Package yamlmarshaller provides functionality for marshaling and unmarshaling YAML documents. |