loghunter-cli 0.1.0.dev0__py3-none-any.whl

loghunter/data/config_example.toml

@@ -0,0 +1,144 @@
+# LogHunter configuration. Every key is optional — omit any to take the default.
+# Generate this for your environment with `loghunter init`.
+
+[loghunter]
+
+# Base dir for any RELATIVE path below. "" resolves relative paths from the
+# current dir. Absolute (/…) and ~-anchored paths ignore it. Set it once and
+# write export_dir = "exports". Env override: LOGHUNTER_ROOT.
+root = "~/.loghunter"
+
+# Detectors to run: "all" | "dns, beacon" | "all, !syslog". --detect overrides.
+detect = "all"
+
+# ── Log sources (read) ──────────────────────────────────────────────
+# Directories holding your logs. Conventional locations shown; uncomment the
+# others if you have them.
+zeek_dir   = "/var/log/zeek"
+syslog_dir = "/var/log"
+# pihole_dir     = "/var/log/pihole"
+# cloudtrail_dir = "/var/log/cloudtrail"
+
+# ── Network ─────────────────────────────────────────────────────────
+# Networks treated as internal for traffic-direction. Topology, not tuning.
+home_net = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
+
+# ── Output (write) ──────────────────────────────────────────────────
+# Findings print to your terminal. Set report_dir (or pass --out) to write
+# files instead — reports land in their own dir, never mixed with pulled logs.
+# report_dir = "reports/"
+# export_dir is a directory BASE: each export auto-segments per source into
+# <base>/<source>/ (e.g. exports/syslog/, exports/cloudtrail/) so pulled logs
+# of different families never share a directory. Override per backend or per
+# query (below) to pin a literal dir; --out is always literal.
+export_dir    = "exports/"
+output_format = "text"
+
+# ── Analysis window ─────────────────────────────────────────────────
+# default_window: lookback for a directory with no --since/--days ("1d","7d",
+#   "24h"; "" or "all" = whole archive; --all overrides one run).
+# warn_above: prompt before analyzing more than this many records.
+default_window = "1d"
+warn_above     = 5_000_000
+
+# Per-detector total cap on rendered TEXT findings (json/csv/html ignore it —
+# machine formats never truncate). Cap operates post severity-sort; a disclosure
+# line is shown when it trips. 0 = unlimited.
+max_findings_per_detector = 100
+
+[allowlist]
+
+# Shipped domain lists load automatically; add your own (one glob per line).
+# connection_rules: local-only flow suppressions — start blank, add after review.
+# allowlist_dir: TOML classification stanzas (all *.toml loaded).
+domain_patterns  = ["~/.loghunter/allowlist.d/domains_user.txt"]
+connection_rules = ["~/.loghunter/allowlist.d/connections.txt"]
+allowlist_dir    = "~/.loghunter/allowlist.d/"
+
+# ════════════════════════════════════════════════════════════════════
+# Export backends (configure only what you use)
+# ════════════════════════════════════════════════════════════════════
+# Splunk — a non-empty host activates it. Prefer env LOGHUNTER_SPLUNK_USER /
+# _PASS over plaintext credentials. A query named "default" runs with a bare
+# `loghunter export`; run others by name (`loghunter export auth`).
+#
+# [export.splunk]
+# host = "192.0.2.20"
+# port = 8089
+# Per-backend export_dir: a LITERAL final dir for every query on this backend
+# (no per-source auto-segment). Uncomment to override the global base.
+# export_dir = "/srv/exports/splunk/"
+#
+# [export.splunk.query.default]
+# spl = "search index=main sourcetype=syslog | table _time, host, _raw"
+# output_basename = "syslog"
+# Per-query export_dir: the finest grain, a LITERAL final dir for this query
+# only (no auto-segment). Wins over the per-backend and global tiers.
+# export_dir = "/srv/exports/syslog/"
+#
+# [export.splunk.query.auth]
+# spl = "search index=main sourcetype=linux_secure | table _time, host, _raw"
+# output_basename = "auth"
+#
+# CloudTrail — a non-empty path activates it. AWS auth is NOT here; authenticate
+# your shell and boto3 resolves it.
+#
+# [export.cloudtrail]
+# path = "s3://example-bucket/AWSLogs/"
+# egress_warn_gb = 5.0
+# export_dir = "/srv/exports/cloudtrail/"   # literal dir override (no auto-segment)
+
+# ════════════════════════════════════════════════════════════════════
+# Detector tuning — the engine room. You rarely need any of this; every
+# detector ships sensible defaults. The values shown ARE those defaults —
+# uncomment a line and change it to tune. Full surface per detector:
+# `loghunter <detector> --help`.
+# ════════════════════════════════════════════════════════════════════
+
+# beacon — periodic C2-style callbacks (FFT over connection timing).
+# [detectors.beacon]
+# threshold       = 0.5    # min composite score to report (0–1)
+# min_connections = 20     # min connections for a flow to qualify
+# bin_seconds     = 30     # FFT bin; leave at 30 — 10 aliases a 60s beacon
+
+# scan — vertical / horizontal / block / slow port scans.
+# [detectors.scan]
+# vertical_threshold   = 15     # distinct ports on one target → vertical
+# horizontal_threshold = 15     # distinct hosts on one port → horizontal
+# block_port_threshold = 20     # ports AND…
+# block_host_threshold = 20     # …hosts, both met → block scan
+# block_state_min      = 0.30   # min scan-state ratio for block/slow gates
+# slow_state_min       = 0.30
+# window_secs          = 3600   # detection window for vert/horiz/block
+# slow_min_ports       = 8      # slow scan: min ports across the dataset…
+# slow_min_buckets     = 4      # …over this many active time windows
+
+# duration — abnormally long-lived connections.
+# [detectors.duration]
+# min_duration_seconds = 1800   # 30m floor to flag (LOW; verbose-only)
+
+# dns — DNS clustering (HDBSCAN over per-query behavior).
+# [detectors.dns]
+# min_cluster_size    = 2000
+# min_samples         = 100
+# threshold           = 1.5     # keep ≤ thresh_high_entropy
+# thresh_high_entropy = 1.8     # the operative filter — raise to quiet noise
+# [detectors.dns.pihole]        # Pi-hole path clusters aggregated per-domain
+# min_cluster_size = 25         # rows, so its sizes run much smaller
+# min_samples      = 10
+
+# syslog — rare-event / reboot surfacing (drain3 templating + rarity).
+# [detectors.syslog]
+# lookback_days = 7      # default window when no --since/--days
+# rarity_pct    = 10     # bottom-N percentile of template count = rare
+# max_count     = 1      # templates seen ≤ this many times always flag
+
+# aws — per-principal CloudTrail surfacing (rarity + weirdness + bursts).
+# [detectors.aws]
+# min_events                 = 50    # interactive principals below this are set aside
+# burst_gap_seconds          = 300   # first-seen actions closer than this = one burst
+# burst_min_firsts           = 3     # min first-seen actions to form a burst
+# burst_high_error_rate      = 0.5   # burst → HIGH escalation gate
+# burst_high_service_count   = 3     # burst → HIGH escalation gate
+# composite_medium_threshold = 2.0   # ranked-principal severity bands (absolute
+# composite_low_threshold    = 1.0   # z, never rank position)

loghunter/detectors/__init__.py

@@ -0,0 +1,5 @@
+"""Detector plugins. Each module exposes DETECTOR_NAME and run(context) -> list[Finding].
+
+The framework discovers detectors automatically by scanning this package for modules
+that define DETECTOR_NAME. No registry file, no import needed here.
+"""

loghunter/detectors/auth.py

@@ -0,0 +1,27 @@
+"""Auth detector — authentication pattern analysis from syslog. (planned)
+
+Analyzes auth.log and secure log files for brute-force attempts, unusual
+authentication patterns, privilege escalation, and new account activity.
+"""
+
+from __future__ import annotations
+
+from loghunter.common.finding import DetectorContext, Finding
+
+DETECTOR_NAME = "auth"
+STATUS = "planned"
+
+REQUIRED_LOGS = [
+    {"source": "syslog_dir", "pattern": "auth.log*"},
+]
+
+OPTIONAL_LOGS = [
+    {"source": "syslog_dir", "pattern": "secure*"},
+]
+
+DEFAULT_CONFIG: dict = {}
+
+
+def run(context: DetectorContext) -> list[Finding]:
+    """Detect anomalous authentication patterns in syslog auth files."""
+    raise NotImplementedError("auth detector is planned — not yet implemented")