Documentation
¶
Overview ¶
Package rules manages cryptographic detection rules, including loading, validation, and filtering of both local and remote rule sets.
Package rules manages cryptographic detection rules, including loading, validation, and filtering of both local and remote rule sets.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type LocalRuleSource ¶
type LocalRuleSource struct {
// contains filtered or unexported fields
}
LocalRuleSource handles loading and validation of local rule files.
func NewLocalRuleSource ¶
func NewLocalRuleSource(rulePaths, ruleDirs []string) *LocalRuleSource
NewLocalRuleSource creates a new local rule source.
Parameters:
- rulePaths: Individual rule file paths (from --rules flags)
- ruleDirs: Rule directory paths (from --rules-dir flags)
Returns:
- *LocalRuleSource: Source configured to load from local paths and directories
func (*LocalRuleSource) Info ¶ added in v0.4.0
func (l *LocalRuleSource) Info() entities.RulesInfo
Info returns a content fingerprint of the loaded rule files. The ChecksumSHA256 is computed deterministically: paths are sorted, then each file's SHA256 is concatenated into a single hash. Two scans with the same rule files produce the same checksum regardless of `--rules-dir` argument order or filesystem walk order.
For local rules there is no manifest, so Name and Version are empty. Source is "local" whenever Load() has been called and produced at least one path; the zero RulesInfo is returned before Load(). I/O errors during hashing degrade to an empty RulesInfo with a warning log — the scan already succeeded.
func (*LocalRuleSource) Load ¶
func (l *LocalRuleSource) Load() ([]string, error)
Load validates and collects all rule file paths from individual files and directories. Returns absolute paths to all valid YAML rule files.
Returns:
- []string: All validated rule file paths (absolute paths)
- error: If any path is invalid or doesn't exist
func (*LocalRuleSource) Name ¶
func (l *LocalRuleSource) Name() string
Name returns a descriptive name for this rule source.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager orchestrates rule loading from multiple sources. It provides a central coordination point for aggregating rules from various sources (local files, remote URLs, etc.) and will handle caching and validation in the future.
func NewManager ¶
func NewManager(sources ...RuleSource) *Manager
NewManager creates a new rules manager with the specified sources. Sources are loaded and aggregated when Load() is called.
Parameters:
- sources: Variable number of RuleSource implementations to aggregate
Returns:
- *Manager: Manager configured with the specified sources
Example:
manager := rules.NewManager(
rules.NewLocalRuleSource(rulePaths, ruleDirs),
// Future: rules.NewRemoteRuleSource(url, cache),
)
func (*Manager) Info ¶ added in v0.4.0
Info returns the first non-empty RulesInfo across the configured sources, matching MultiSource.Info semantics. Call after a successful Load() — before that, returns the zero RulesInfo.
type MultiSource ¶
type MultiSource struct {
// contains filtered or unexported fields
}
MultiSource aggregates rule paths from multiple sources. It loads rules from all sources and merges them, removing duplicates.
func NewMultiSource ¶
func NewMultiSource(sources ...RuleSource) *MultiSource
NewMultiSource creates a new MultiSource that aggregates rules from multiple sources. Sources are loaded in the order provided. Rule paths are deduplicated automatically.
Parameters:
- sources: Variable number of RuleSource implementations
Returns:
- *MultiSource: Aggregator for multiple rule sources
func (*MultiSource) Info ¶ added in v0.4.0
func (m *MultiSource) Info() entities.RulesInfo
Info returns the first non-empty RulesInfo across the configured sources. We prefer the first non-empty over a "merged" representation because downstream stamps a single (rules_version, checksum) on each result row; a mixed-source scan is a niche operator decision and the chosen source is the most informative single label. If you operate in mixed mode and want reproducibility, prefer one source per scan.
func (*MultiSource) Load ¶
func (m *MultiSource) Load() ([]string, error)
Load retrieves and merges rule paths from all configured sources. If any source fails to load, the error is returned immediately. Empty paths from sources are filtered out automatically.
Returns:
- []string: Deduplicated merged rule paths from all sources
- error: First error encountered while loading sources, if any
func (*MultiSource) Name ¶
func (m *MultiSource) Name() string
Name returns a descriptive name for this multi-source.
type RemoteRuleSource ¶
type RemoteRuleSource struct {
// contains filtered or unexported fields
}
RemoteRuleSource loads rules from a remote ruleset via API and caches them locally. It returns the path to the cached ruleset directory.
func NewRemoteRuleSource ¶
func NewRemoteRuleSource( ctx context.Context, rulesetName string, version string, cacheManager *cache.Manager, ) *RemoteRuleSource
NewRemoteRuleSource creates a new remote rule source
Parameters:
- ctx: Context for API requests and cancellation
- rulesetName: Name of the ruleset to fetch (e.g., "dca")
- version: Version of the ruleset (e.g., "latest", "v1.0.0")
- cacheManager: Cache manager for downloading and caching rulesets
Returns:
- *RemoteRuleSource: Configured remote rule source
func (*RemoteRuleSource) Info ¶ added in v0.4.0
func (r *RemoteRuleSource) Info() entities.RulesInfo
Info returns the ruleset version and checksum recorded in .cache-meta.json alongside the cached ruleset. Call after Load(); before Load() it returns the zero RulesInfo.
Failure modes (missing metadata file, parse error) are logged at warn but returned as an empty RulesInfo rather than as an error — the scan itself already succeeded; missing metadata is a degraded telemetry state, not a scan failure.
func (*RemoteRuleSource) Load ¶
func (r *RemoteRuleSource) Load() ([]string, error)
Load retrieves the path to the cached ruleset directory. If the ruleset is not cached or has expired, it will be downloaded. The returned path points to a directory containing the ruleset's .yaml files.
Returns:
- []string: Slice containing the absolute path to the cached ruleset directory
- error: Error if download/cache retrieval fails
func (*RemoteRuleSource) Name ¶
func (r *RemoteRuleSource) Name() string
Name returns a human-readable identifier for this source.
type RuleSource ¶
type RuleSource interface {
// Load retrieves absolute paths to rule files from the source.
// Returns an empty slice if the source has no rules (not an error).
// Returns an error only if the source exists but cannot be read/parsed.
Load() ([]string, error)
// Name returns a human-readable identifier for this source.
// Used for logging and debugging purposes.
Name() string
// Info returns a snapshot of which ruleset this source loaded, used for
// stamping on the InterimReport so consumers can correlate findings to a
// specific rules version. Must be called after Load(); behavior before
// Load() is implementation-defined (typically returns the zero value).
// The zero value (Source == "") is acceptable when no version is knowable.
Info() entities.RulesInfo
}
RuleSource defines an interface for loading rule file paths from various sources. Implementations can load rules from local files, remote URLs, databases, etc. Each source returns absolute paths to YAML rule files.
Source Files