Skip to content

README.md

Latest commit

 

History

History
145 lines (103 loc) · 6.1 KB

README.md

File metadata and controls

145 lines (103 loc) · 6.1 KB
Raw

RustHound

CI Rust License: Apache--2.0

RustHound is a Rust command-line log analyzer. It reads a log file, applies configured string and regular-expression rules, and can add frequency and correlation detections to console or JSON output.

This is a pre-1.0 portfolio project. The README describes the behavior verified in this repository; it does not claim universal platform support or benchmark numbers. See CHANGELOG.md for the change history.

Implemented behavior

  • Streaming line-by-line analysis for one file or a directory of .log files.
  • TOML rules for string patterns, regex patterns, frequency thresholds, and correlated events.
  • Console, JSON, and combined output modes.
  • Optional follow mode for newly appended log lines.
  • Minimum-severity filtering and a default configuration generator.
  • Analyzer unit tests for rule precedence, frequency tracking, correlation, and TOML parsing.

Requirements and build

  • Rust 1.85 or newer (edition 2021).
  • A log file and a TOML rules file for a meaningful run.
git clone https://github.com/rustfuture/RustHound.git
cd RustHound
cargo build --locked --release

Quick start

The repository includes a small sample log and rules file:

cargo run --locked -- \
  --file sample.log \
  --rules rules.toml \
  --output console

The verified sample run emits eight detections with severity and source-line context. Generate a starter rules file with:

cargo run --locked -- --init-config

For JSON output, use --output json; for both console and JSON, use --output both. The output file is one JSON array and a new non-follow scan replaces stale results instead of duplicating them. In --follow mode, new detections are appended while the file remains a valid JSON document. --dir PATH scans regular .log files in a directory.

Installation

setup.sh builds from the committed lockfile, installs the binary to ~/.local/bin, and installs the bundled rules.toml as the default:

./setup.sh

When --rules is not given, the binary looks for rules.toml in the platform configuration directory and falls back to the working directory. setup.sh writes to that same directory:

| Platform | Configuration path | | --- | --- |\n| macOS | ~/Library/Application Support/rusthound/rules.toml | | Linux | $XDG_CONFIG_HOME/rusthound/rules.toml (default ~/.config/rusthound/rules.toml) |

Re-running the installer never overwrites rules you have edited: the bundled default is written beside them as rules.toml.new. Uninstalling keeps your configuration unless you choose the purge option.

Rule configuration

The default rules.toml supports these sections:

[rules]
error_patterns = ["ERROR", "FATAL", "Exception"]
warning_patterns = ["WARN", "WARNING"]

[[regex_rules]]
name = "authentication_failure"
pattern = "authentication failure|Failed password for"
severity = "high"

[frequency_rules]
max_same_errors_per_minute = 10
time_window_seconds = 60

Correlated rules can model a sequence such as repeated authentication failures followed by a successful login. docs/rules-schema.md is the authoritative schema, including the severity values and the mistakes that produce rules which never fire.

Verification

cargo fmt --check
cargo check --locked --all-targets
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked
cargo +1.85.0 check --locked --all-targets

The current local run passes 15 library tests, no duplicate binary test suite, and the doctest target. The sample CLI invocation above is a real file-processing smoke test, not a benchmark.

Scope and limitations

  • The normal path processes files in a streaming manner; no throughput or memory number is published without a controlled benchmark environment.
  • Follow mode is a local file watcher, not a distributed ingestion service.
  • Cross-platform behavior beyond the tested macOS environment and CI’s Linux environment requires separate validation.
  • The repository publishes no cargo install package; the source build, or the tagged release's source archive, is the supported installation path.

Architecture

  • src/analyzer/ — pattern matching, frequency tracking, and correlation state.
  • src/config/ — TOML schema and rule loading.
  • src/watcher/ — file reading, offsets, and follow-mode notifications.
  • src/output/ — detection types, console rendering, and JSON writing.

docs/architecture.md covers the module map, the data flow, the pattern-matching priority, and the rule that follow mode must reuse one ScanState rather than rebuilding the engines per read.

Contributing

Build requirements, the exact checks CI runs, manual smoke commands, and the commit conventions are in CONTRIBUTING.md.

Versioning and support

RustHound follows 0.x semantics: the version number is a statement about scope, not a compatibility promise. While the major version is 0, a breaking change to the CLI, the rules-file schema, or the JSON output shape bumps the minor version, and a compatible fix bumps the patch version. Every change is recorded in CHANGELOG.md.

Platform Status
Linux Verified by CI on Rust 1.85 (the minimum supported version) and stable.
macOS Verified locally against the committed source; not part of the CI matrix.
Windows Not verified.

The minimum supported Rust version is 1.85; raising it is a minor-version change. A 1.0 would mean the existing command surface, rules schema, and JSON output have stopped moving, not that every idea in the issue tracker has been implemented.

License and attribution

Licensed under Apache-2.0 to provide enterprise patent grants and permissive commercial integration for log-pipeline and observability tooling. See LICENSE.