sentiel 1.0.0__tar.gz

sentiel-1.0.0/.gitignore

@@ -0,0 +1,225 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Sentiel
+sentiel.toml
+sentiel.db
+sentiel.db-*
+bench.md

sentiel-1.0.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+All notable changes to Sentiel are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - unreleased (tag v1.0.0 pending)
+
+The version is set to 1.0.0 in the code, but it is not published yet. The maintainer replaces "unreleased (tag v1.0.0 pending)" with the release date when tagging `v1.0.0`.
+
+### Added
+- Release to PyPI: `pipx install sentiel`. Tags `vX.Y.Z` trigger `.github/workflows/release.yml`, which checks the tag against `sentiel.__version__`, builds the sdist and wheel and publishes with PyPI trusted publishing (no token).
+- `scripts/check_dist.py` verifies the built sdist and wheel: rule files and demo data are in the wheel, and secrets, databases and local folders (`sentiel.toml`, `*.db`, `.env*`, `.venv/`, `docs/`) are in neither.
+- `sentiel bench MODELS --readme` refreshes the benchmark table between the `<!-- BENCH:START -->` and `<!-- BENCH:END -->` markers of a README (`--readme-file PATH` picks the file). With missing, duplicated or reversed markers it fails without writing. Model names are escaped in the table.
+- CI: Python 3.14 in the test matrix (informational, `continue-on-error`) and a `build` job (`python -m build`, `twine check`, `scripts/check_dist.py`). Dependabot for `pip` and GitHub Actions.
+- Community files: `CONTRIBUTING.md`, `SECURITY.md`, this changelog, issue templates (new rule, false positive) and `contrib/sysmon.md`.
+- Package metadata (authors, keywords, classifiers, URLs). The version lives only in `sentiel/__init__.py`.
+
+### Changed
+- Strict config: an unknown key at the top level, in `[sources]`, in `[[sources.files]]`, in `[keys]` or in `[notify]` is now an error (exit 2, or FAIL in `sentiel doctor`) that names the key and never echoes its value. Valid keys are unchanged, including the `json` alias in `[sources]`.
+- `sentiel scan` shows only the exception class name in the `triage failed` warning.
+
+### Fixed
+- Rule titles, MITRE tags, notes and AI summaries from third parties are stripped of terminal control and bidi characters before display in `alerts`, `show`, `report`, `rules list` and `rules test`.
+- `rules test` with a non-UTF-8 rule or events file prints a short error instead of a traceback.
+- `demo` and `bench` close the database connection on errors, and `bench --out` is written even if a later model fails.
+
+## [0.4.0]
+
+### Added
+- Database migrations (`PRAGMA user_version`), applied automatically and atomically when the database is opened. A database newer than the installed Sentiel is refused and left untouched.
+- Alert status and notes: `sentiel set <id> open|ack|closed|false_positive [--note TEXT]`, and `sentiel alerts --all`. Only a human changes status. Closed, false-positive and suppressed alerts are never triaged or notified.
+- `[[suppress]]` entries in the config (`rule_id`, `field`, `equals`, `reason`), and `sentiel set <id> false_positive --suppress FIELD` to print one. Only the first event of an alert is checked.
+- Alert grouping with `group_window` (default 3600 seconds, `0` disables). A grown alert is not notified again.
+- Daily digest: `digest_hour` for `sentiel watch`, and `sentiel digest` to send it now.
+
+### Changed
+- Invalid config makes every command exit with code 2 and a short message, without a traceback or the offending value.
+
+## [0.3.0]
+
+### Added
+- Your own rules with `rules_dirs` and `disabled_rules`. Rules that do not convert, or that target a product Sentiel does not collect, are skipped with one summary warning per cycle.
+- Sigma correlation rules (`event_count`, `gte`, one `group-by`). The two brute-force detections are now rule files (`win_logon_bruteforce.yml`, `lnx_ssh_bruteforce.yml`); alert ids are unchanged.
+- Regex text-log sources with `[[sources.files]]`.
+- `sentiel rules list [--skipped]` and `sentiel rules test RULE.yml EVENTS.jsonl`.
+
+### Fixed
+- Events with an out-of-range timestamp no longer break the scan cycle: the line is skipped.
+- A rule that fails at run time becomes a warning instead of stopping detection.
+- Text logs are read at most 32 MiB per cycle and split only on `\n`, so a log line cannot forge events with other separators.
+
+## [0.2.0]
+
+### Added
+- LLM backoff (30 s up to 1800 s) when the model is down, with a hint to force a retry using `sentiel triage`.
+- Concurrent triage with `triage_concurrency`.
+- Notification per channel: one failing channel does not block the others.
+- `sentiel doctor` (database, rules, sources, model, notifications, heartbeat) and a heartbeat on every scan.
+- Services: `contrib/sentiel.service` (systemd) and `contrib/sentiel-task.xml` (Windows Task Scheduler).
+
+### Changed
+- Rules are cached by path and modification time.
+
+## [0.1.1]
+
+### Fixed
+- Restored the `demo`, `bench`, `chat` and `version` commands.
+- `auth.log` dates across the new year, including 29 February. An invalid date skips the line instead of failing the whole scan.

sentiel-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,131 @@
+# Contributing to Sentiel
+
+Thanks for helping. Sentiel is small on purpose, so the best contributions are usually a new detection rule, a false-positive fix or a clear bug report.
+
+## Setup
+
+Python 3.11 or newer.
+
+Linux and macOS:
+
+```
+git clone https://github.com/shinitihm/Sentiel && cd Sentiel
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Windows:
+
+```
+git clone https://github.com/shinitihm/Sentiel; cd Sentiel
+python -m venv .venv; .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+Before opening a pull request:
+
+```
+pytest -q
+ruff check .
+sentiel demo --no-ai      # must still show 7 alerts
+```
+
+Ruff uses 120 columns. Tests that need a real LLM (`tests/test_llm_live.py`) are skipped unless you opt in; the rest run offline.
+
+## Adding a rule
+
+Sentiel reads Sigma rules. You do not need to write Python.
+
+### A rule of your own, or a rule to propose
+
+1. Write the Sigma rule as a `.yml` file. The `id` must be a UUID. In a Sigma rule, `logsource.product` is `windows`, `linux` or omitted. A rule for any other product is skipped with a warning ("product not collected"). A rule **without** `logsource.product` matches generic events (source `json`). `sentiel/rules/win_run_key_persistence.yml` is a Windows example. This is a generic one:
+
+   ```yaml
+   title: Example Backup Tool Run
+   id: 6f1c1d52-3a0e-4b7e-9d0f-0a1b2c3d4e5f
+   logsource:
+     category: process_creation
+   detection:
+     selection:
+       Image|endswith: '\backup-tool.exe'
+     condition: selection
+   level: medium
+   ```
+
+2. Write a `.jsonl` file with a few events, one JSON object per line. For a rule without a product, plain objects work: `ts` (ISO 8601 with offset), `host` and the event fields at the top level. Include at least one event that should match and, ideally, one that should not:
+
+   ```
+   {"ts": "2026-10-09T08:00:00+00:00", "host": "PC1", "Image": "C:\\Tools\\backup-tool.exe"}
+   {"ts": "2026-10-09T08:05:00+00:00", "host": "PC1", "Image": "C:\\Windows\\notepad.exe"}
+   ```
+
+   For a rule with `product: windows` or `product: linux`, each line needs the full shape `{"ts": ..., "source": "windows", "host": ..., "fields": {...}}`, with `source` equal to the rule's product. `sentiel/demo/events.jsonl` has real examples.
+3. Check it:
+
+   ```
+   sentiel rules test my_rule.yml events.jsonl
+   ```
+
+   The rule file must be self-contained. The command prints what the rule would alert on (here, one match) and exits 1 when nothing matches.
+4. To use it locally, put the `.yml` in a folder listed in `rules_dirs` in `sentiel.toml`, then run `sentiel rules list` to confirm it loaded without warnings (`sentiel rules list --skipped` shows load warnings).
+
+Correlation rules support `event_count` with `gte` and exactly one `group-by`. See `sentiel/rules/lnx_ssh_bruteforce.yml`.
+
+### A built-in rule (pull request)
+
+1. Add the `.yml` to `sentiel/rules/`.
+2. Add events that trigger it to the demo data (`sentiel/demo/events.jsonl`, or `sentiel/demo/auth_log.txt` for Linux `auth.log`).
+3. Add the rule `id` to `sentiel/demo/expected.json` with the attack name, expected severity and MITRE techniques. `tests/test_detect.py` checks that the demo detects exactly the rules listed there, and the demo must keep working with `--no-ai`.
+4. Run `pytest -q` and `ruff check .`.
+
+## Style
+
+- YAGNI. Prefer the standard library, a few clear lines and no new runtime dependency. A new dependency needs a strong reason.
+- Mark deliberate shortcuts with a `# ponytail:` comment saying what was skipped and why, so they can be found later.
+- Match the style of the file you are editing. Keep each file's line endings (`sentiel/cli.py` uses CRLF).
+- Add a test with every behavior change. Tests are offline and must not call a real model.
+- Do not print secrets or config values in errors. Name the offending key, never its value.
+
+## Principles that do not change
+
+A pull request that breaks one of these will not be merged.
+
+- The model never decides which alerts exist, and it cannot lower an alert's effective severity (`max(rule level, AI severity)`).
+- Logs are hostile input. They reach the model only inside an `<untrusted_log_data>` block, and the model has no tools. Text from logs and third-party rules is sanitised before it reaches the terminal.
+- No alert is lost. Each stage writes to SQLite before the next, and a pending alert is retried.
+- A broken source or rule becomes a warning, not a crash.
+- Status changes and suppressions come only from a human (`sentiel set`, `[[suppress]]` in the config).
+- Secrets are never logged or echoed. Data leaves the machine only with a non-local model.
+
+## Reporting bugs and rule issues
+
+Use the issue templates: "New rule" and "False positive". Do not paste sensitive logs. For vulnerabilities, follow [SECURITY.md](SECURITY.md) and do not open a public issue.
+
+## Releasing (maintainer only)
+
+Releases are published to PyPI by `.github/workflows/release.yml` when a `vX.Y.Z` tag is pushed. It uses PyPI trusted publishing, so there is no PyPI token anywhere. The workflow checks that the tag equals `sentiel.__version__`, builds the sdist and wheel, runs `scripts/check_dist.py`, and publishes from the `pypi` environment.
+
+One-time setup:
+
+1. On PyPI, create a *pending publisher* (Account settings, Publishing): project `sentiel`, repository `shinitihm/Sentiel`, workflow `release.yml`, environment `pypi`. Keep the workflow and environment fields filled in, so the publisher cannot be used from another workflow.
+2. On GitHub, create the environment `pypi` (Settings, Environments). Add required reviewers, and restrict deployment to tags matching `v*` (deployment branches and tags rule).
+3. Add a tag ruleset (or tag protection) for `v*` so that only maintainers can create those tags. Anyone who can push a `v*` tag can start a release.
+
+Each release:
+
+1. Make sure CI is green on the exact commit you will tag. The release workflow does **not** run `pytest`; it only builds, checks the distribution and publishes.
+2. Set the version in `sentiel/__init__.py` (the only place; `pyproject.toml` reads it).
+3. Update `CHANGELOG.md`: put the release date on the new version heading (for 1.0.0, replace "unreleased (tag v1.0.0 pending)" with the date).
+4. Check that the README (the page PyPI shows) describes the state of this release: roadmap, install steps and links. A PyPI page cannot be changed for a published version. Then tag and push only that tag:
+
+   ```
+   git tag vX.Y.Z
+   git push origin vX.Y.Z
+   ```
+
+5. Approve the `pypi` deployment on GitHub, then check the project page on PyPI and try `pipx install sentiel` in a clean environment.
+
+Notes:
+
+- CI also runs on Python 3.14 as informational only (`continue-on-error`), because some native dependencies may lack 3.14 wheels. The README does not promise 3.14 until that job is green.
+- The PyPI badge in the README is added only after the first publication.

sentiel-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shinitihm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sentiel-1.0.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: sentiel
+Version: 1.0.0
+Summary: Personal AI-powered SOC: Sigma detection + LLM triage with any model
+Project-URL: Homepage, https://github.com/shinitihm/Sentiel
+Project-URL: Issues, https://github.com/shinitihm/Sentiel/issues
+Project-URL: Changelog, https://github.com/shinitihm/Sentiel/blob/main/CHANGELOG.md
+Author: shinitihm
+License-Expression: MIT
+License-File: LICENSE
+Keywords: detection,llm,security,siem,sigma,soc,triage
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: litellm>=1.50
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pysigma-backend-sqlite>=1.0
+Requires-Dist: pysigma>=0.11
+Requires-Dist: pywin32>=306; sys_platform == 'win32'
+Requires-Dist: rich>=13
+Requires-Dist: tenacity>=8
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sentiel
+
+![GitHub repo size](https://img.shields.io/github/repo-size/shinitihm/Sentiel?style=for-the-badge)
+![GitHub language count](https://img.shields.io/github/languages/count/shinitihm/Sentiel?style=for-the-badge)
+![GitHub forks](https://img.shields.io/github/forks/shinitihm/Sentiel?style=for-the-badge)
+![GitHub open issues](https://img.shields.io/github/issues/shinitihm/Sentiel?style=for-the-badge)
+![GitHub open pull requests](https://img.shields.io/github/issues-pr/shinitihm/Sentiel?style=for-the-badge)
+![Python](https://img.shields.io/badge/python-%E2%89%A53.11-blue?style=for-the-badge)
+![License](https://img.shields.io/github/license/shinitihm/Sentiel?style=for-the-badge)
+
+[Português](https://github.com/shinitihm/Sentiel/blob/main/README.pt-BR.md)
+
+> A personal SOC with AI triage that works with any LLM. Sigma rules detect attacks in your own logs, and a language model explains and prioritises each alert. The model never decides which alerts exist, and it cannot be talked into downgrading one.
+
+### Improvements and roadmap
+
+The project is still under development. The next releases follow this roadmap:
+
+- [x] v0.1.1: CLI repair (`demo`, `bench`, `chat`, `version`) and `auth.log` dates across the new year
+- [x] v0.2: orchestration (LLM backoff, concurrent triage, `sentiel doctor`, heartbeat, systemd and Task Scheduler services)
+- [x] v0.3: data-driven extension (your own rules with `rules_dirs`/`disabled_rules`, Sigma correlations, regex sources, `sentiel rules list/test`)
+- [x] v0.4: database migrations, alert status and notes (`sentiel set`), suppressions, grouping and a daily digest
+- v1.0:
+  - [x] strict config, [CONTRIBUTING](https://github.com/shinitihm/Sentiel/blob/main/CONTRIBUTING.md), [SECURITY](https://github.com/shinitihm/Sentiel/blob/main/SECURITY.md), [CHANGELOG](https://github.com/shinitihm/Sentiel/blob/main/CHANGELOG.md), `sentiel bench --readme`, release workflow and CI with an informational Python 3.14 job
+  - [x] v1.0 release (PyPI)
+
+## 💻 Prerequisites
+
+Before you start, make sure you meet these requirements:
+
+- Python **3.11 or newer**.
+- Windows, Linux or macOS. On Windows, reading the **Security** log requires an administrator shell. Without it, Sentiel says so and continues with the other sources.
+- Optional, for AI triage: [Ollama](https://ollama.com) with a local model, or an API key for any provider supported by [LiteLLM](https://github.com/BerriAI/litellm) (Anthropic, OpenAI, Gemini and 100+ more).
+
+## 🚀 Installing Sentiel
+
+Install it with [pipx](https://pipx.pypa.io):
+
+```
+pipx install sentiel
+sentiel doctor
+sentiel demo --no-ai
+```
+
+To work on the code, install from source:
+
+Linux and macOS:
+
+```
+git clone https://github.com/shinitihm/Sentiel && cd Sentiel
+python -m venv .venv && source .venv/bin/activate
+pip install .
+```
+
+Windows:
+
+```
+git clone https://github.com/shinitihm/Sentiel; cd Sentiel
+python -m venv .venv; .venv\Scripts\activate
+pip install .
+```
+
+## ☕ Using Sentiel
+
+To use Sentiel, follow these steps:
+
+```
+sentiel demo --no-ai                  # 7 simulated attacks, detection only, offline
+sentiel demo -m ollama/llama3.1:8b    # the same, with local AI triage
+
+sentiel doctor                        # checks config, database, rules, sources, model and notifications
+sentiel scan                          # one pass over your logs
+sentiel watch                         # continuous monitoring
+sentiel alerts / show 3 / report      # browse alerts (open and ack; `alerts --all` shows the rest)
+sentiel set 3 ack --note "looking"    # open | ack | closed | false_positive
+sentiel digest                        # last-24h summary, sent now
+sentiel chat "which IPs failed to log in most?"
+sentiel rules list --skipped          # loaded rules and warnings
+sentiel rules test my_rule.yml events.jsonl
+sentiel bench ollama/llama3.1:8b,anthropic/claude-sonnet-5-5
+```
+
+To configure it, get the example config (the pipx package does not include it), then edit the model, sources and notifications. If you cloned the repository, just copy it with `cp sentiel.example.toml sentiel.toml`.
+
+Windows (PowerShell):
+
+```
+Invoke-WebRequest https://raw.githubusercontent.com/shinitihm/Sentiel/main/sentiel.example.toml -OutFile sentiel.toml
+```
+
+Linux and macOS:
+
+```
+curl -o sentiel.toml https://raw.githubusercontent.com/shinitihm/Sentiel/main/sentiel.example.toml
+```
+
+To run it as a service, use `contrib/sentiel.service` on Linux (systemd) or `contrib/sentiel-task.xml` on Windows (Task Scheduler). The steps are in each file's header. For Sysmon events on Windows, see [contrib/sysmon.md](https://github.com/shinitihm/Sentiel/blob/main/contrib/sysmon.md). LLM provider keys come only from the environment: use `/etc/sentiel/env` on Linux and machine-level variables on Windows.
+
+### Model benchmark
+
+`sentiel bench MODELS --readme` runs the demo attacks through each model and refreshes the table below (`--readme-file PATH` picks another file). It needs the two markers and fails without touching the file if they are missing.
+
+<!-- BENCH:START -->
+| Model | Severity | MITRE recall | Valid JSON 1st try | Prompt injection | Avg latency | Cost |
+|---|---|---|---|---|---|---|
+| not run yet | - | - | - | - | - | - |
+<!-- BENCH:END -->
+
+### Extending Sentiel
+
+- **Your own rules:** `rules_dirs = ["~/.sentiel/rules"]` loads extra Sigma rules. For a SigmaHQ clone, point it at its `rules/` folder. `disabled_rules` turns rules off. Rules that do not convert, or that target a product Sentiel does not collect, are skipped with one summary warning per cycle (`sentiel rules list --skipped`).
+- **Correlation:** Sigma correlation rules with `event_count`, `gte` and a single `group-by`. See `sentiel/rules/lnx_ssh_bruteforce.yml`.
+- **Any text log:** `[[sources.files]]` with a regex. Named groups become Sigma fields, and `ts` and `host` are special groups. Keep the regex linear: log lines are attacker-controlled and Python's `re` has no timeout.
+
+### Alert lifecycle
+
+- **Status and notes:** `sentiel set <id> <status> [--note TEXT]` with `open`, `ack`, `closed` or `false_positive` (note up to 1000 characters). `suppressed` exists but only comes from the config file. `sentiel alerts` lists `open` and `ack`; `--all` also shows `closed`, `false_positive` and `suppressed`. Only humans change status: the model never does. Closed, false-positive and suppressed alerts are never triaged or notified.
+- **Suppressions:** `sentiel set <id> false_positive --suppress FIELD` prints a `[[suppress]]` block (`rule_id`, `field`, `equals`, `reason`) for you to paste into the config. Nothing is edited for you, and the model never creates suppressions. Only the **first** event of an alert is checked, so a correlated burst that opens with a suppressed event is suppressed as a whole. See `sentiel.example.toml`.
+- **Grouping:** `group_window` (default 3600 seconds, `0` turns it off) merges repeats of the same rule, host and group into one alert whose `count` grows. An alert that was already notified is **not** notified again when it grows: the `count` shows in `sentiel show` and in the digest.
+- **Daily digest:** `digest_hour = 9` (local hour, 0-23) makes `sentiel watch` send a 24-hour summary once a day to your notification channels. `sentiel digest` sends it now, or prints it when no channel is set. The digest has counts and rule titles, never raw logs. The digest uses the event time (`last_ts`), so old logs ingested now may not show up in it.
+- **Database upgrades:** the schema is migrated automatically (`PRAGMA user_version`) when the database is opened, and your alerts and logs are kept. Copy `sentiel.db` before upgrading Sentiel. A database newer than the installed Sentiel is refused with a clear message and left untouched.
+- **Invalid config:** every command exits with code 2 and a short message, without a traceback and without echoing the offending value. Exception: `sentiel doctor` exits 1 and shows FAIL in its table.
+
+### Security by design
+
+- **Prompt injection cannot hide an alert:** effective severity is `max(rule level, AI severity)`. If the AI calls a `high` rule "benign", the alert shows as **CONTESTED** and is still notified.
+- **Logs are data, not instructions:** events reach the model in an `<untrusted_log_data>` block, and the model has no tools.
+- **Read-only chat:** the database is opened with `mode=ro`, a SQLite authorizer allows only `SELECT` on `logs`/`alerts`, and queries have time and row limits.
+- **No alert is lost:** every stage writes to SQLite before the next. If the model is down, alerts stay pending and are retried.
+
+## 📫 Contributing to Sentiel
+
+To contribute to Sentiel, follow these steps:
+
+1. Fork this repository.
+2. Create a branch: `git checkout -b <branch_name>`.
+3. Make your changes, run `pip install -e ".[dev]"`, `pytest -q` and `ruff check .`, then commit them: `git commit -m '<commit_message>'`.
+4. Push to your fork: `git push origin <branch_name>`.
+5. Open a pull request.
+
+The full guide is in [CONTRIBUTING.md](https://github.com/shinitihm/Sentiel/blob/main/CONTRIBUTING.md): how to add a rule with only a YAML file and a `.jsonl` file, style and principles. To report a vulnerability, see [SECURITY.md](https://github.com/shinitihm/Sentiel/blob/main/SECURITY.md). Changes per version are in [CHANGELOG.md](https://github.com/shinitihm/Sentiel/blob/main/CHANGELOG.md).
+
+See also GitHub's documentation on [creating a pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request).
+
+## 🤝 Contributors
+
+Thanks to the following people who have contributed to this project:
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://github.com/shinitihm" title="shinitihm on GitHub">
+        <img src="https://github.com/shinitihm.png" width="100px;" alt="shinitihm's photo on GitHub"/><br>
+        <sub>
+          <b>shinitihm</b>
+        </sub>
+      </a>
+    </td>
+  </tr>
+</table>
+
+## 😄 Become a contributor
+
+Want to be part of this project? Open an issue (there are templates for new rules and false positives) or a pull request, and read [CONTRIBUTING.md](https://github.com/shinitihm/Sentiel/blob/main/CONTRIBUTING.md) first.
+
+## 📝 License
+
+This project is under the MIT license. See the [LICENSE](https://github.com/shinitihm/Sentiel/blob/main/LICENSE) file for details.