sentinel-watch 0.3.0__tar.gz

sentinel_watch-0.3.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.3.0
+
+- add `check` with risk clean/warn/high plus json and sarif
+- add `why` to explain one file score
+- add `diff` using vault copies
+- add `protect` vault fill and restore clean
+- add `update` fast rehash
+- add `learn` to suggest burst
+- add `timeline`, `serve` with /json, `config-init`, `doctor`
+- add `watch --daemon`, rename and delete storm rules
+- store entropy at baseline time
+- add mail alerts, sarif output
+- add mkdocs site plus pages and ci workflows
+- human pass over all code and docs
+
+## 0.2.0
+
+- add `scan`, `report`, `events`, `snaps`, `restore`, `status`, `clean`
+- add yaml config plus `.sentinelignore`
+- add ransom note and ext scoring
+- add json logs and html report
+- add webhook, desktop note, optional kill
+- add docs folder and examples
+- threaded baseline
+
+## 0.1.0
+
+- first cut: `init`, `verify`, `watch`, `demo`
+- burst plus entropy plus canary

sentinel_watch-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing
+
+## Setup
+
+```bash
+pip install -e .[dev]
+pytest -q
+```
+
+## Style
+
+- short comments, plain words
+- no banners, no em dashes in code
+- keep functions small
+- add a test for each rule tweak
+
+## PRs
+
+1. fork and branch
+2. add test in `tests/`
+3. run `pytest -q` and `sentinel demo`
+4. explain what real folder you tried it on
+
+Thanks.

sentinel_watch-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sentinel contributors
+
+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.

sentinel_watch-0.3.0/MANIFEST.in

@@ -0,0 +1,7 @@
+# keep sdist handy
+include README.md LICENSE CHANGELOG.md CONTRIBUTING.md
+include config.example.yaml mkdocs.yml
+recursive-include docs *.md
+recursive-include examples *
+global-exclude __pycache__ *.pyc *.pyo
+global-exclude .sentinel demo_run demo_ci site dist build *.egg-info

sentinel_watch-0.3.0/PKG-INFO

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: sentinel-watch
+Version: 0.3.0
+Summary: tiny folder watchdog that spots ransomware-ish behavior
+Author-email: HahaAhhDev <theabsolutesmartest@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/HahaAhhDev/sentinel
+Project-URL: Documentation, https://hahaahhdev.github.io/sentinel
+Project-URL: Issues, https://github.com/HahaAhhDev/sentinel/issues
+Project-URL: Changelog, https://github.com/HahaAhhDev/sentinel/blob/main/CHANGELOG.md
+Keywords: security,ransomware,watchdog,integrity,monitoring
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: System Administrators
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: System :: Filesystems
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: watchdog
+Requires-Dist: typer
+Requires-Dist: rich
+Requires-Dist: pyyaml
+Requires-Dist: psutil
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: mkdocs; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# sentinel
+
+![python](https://img.shields.io/badge/python-3.10%2B-blue)
+![license](https://img.shields.io/badge/license-MIT-green)
+![version](https://img.shields.io/badge/version-0.3.0-orange)
+![docs](https://img.shields.io/badge/docs-github%20pages-blue)
+![ci](https://github.com/HahaAhhDev/sentinel/actions/workflows/ci.yml/badge.svg)
+
+Tiny folder watchdog that spots ransomware-like behavior. Baseline it, watch it, get told before it is too late.
+
+Docs site: https://hahaahhdev.github.io/sentinel/
+
+```
+pip install sentinel-watch
+sentinel init ~/Documents
+sentinel watch ~/Documents
+```
+
+That is the pitch. No server. No signup. Files stay local.
+
+---
+
+## Why this one
+
+Most integrity tools are built for servers and need setup. Most crypto detectors only scan once and miss live hits.
+
+Sentinel does both, plus two things others skip:
+
+- vault of clean copies, so `protect --restore-clean all` brings back pre hit text, not post hit junk
+- one risk number via `check`, so CI and humans read the same line
+
+Live rules plus one shot scan plus real restores. That combo is rare.
+
+## Demo in 30 seconds
+
+```bash
+pip install -e .
+sentinel demo
+sentinel scan ./demo_run
+sentinel check ./demo_run
+sentinel report ./demo_run --out report.html
+```
+
+You get entropy, file scores, and a risk line like `risk warn 55`. Open `report.html` for the pretty page.
+
+## Install
+
+```bash
+pip install sentinel-watch
+```
+
+From source:
+
+```bash
+git clone https://github.com/HahaAhhDev/sentinel
+cd sentinel
+pip install -e .
+```
+
+Needs Python 3.10+. Pulls `watchdog`, `typer`, `rich`, `pyyaml`, `psutil`. Dev extras add `pytest`, `mkdocs`, `mkdocs-material`.
+
+## Quickstart
+
+```bash
+sentinel init ~/Documents
+sentinel verify ~/Documents
+sentinel scan ~/Documents
+sentinel check ~/Documents
+sentinel watch ~/Documents
+```
+
+Full walk is in [docs](https://hahaahhdev.github.io/sentinel/) under Quickstart. Short version: `init` once, `check` often, `watch` when it matters.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init` | Hash all, fill vault |
+| `update` | Rehash only changed |
+| `status` | Counts, dates, vault size |
+| `verify` | Diff vs baseline |
+| `diff` | Text diffs via vault |
+| `scan` | Score files, json or sarif |
+| `why FILE` | Explain one file |
+| `check` | Verify plus scan plus risk, for CI |
+| `watch` | Live loop, canary, notes, storms |
+| `learn` | Watch quiet, suggest burst |
+| `protect` | Fill vault or restore clean |
+| `events`, `timeline` | Last hits |
+| `snaps`, `restore` | Quarantine packs |
+| `report`, `serve` | HTML page, local web |
+| `config-init`, `doctor` | Scaffold yaml, self test |
+| `clean`, `demo` | Wipe, fake hit |
+
+See `docs/CLI.md` or the [web CLI page](https://hahaahhdev.github.io/sentinel/CLI/) for flags and copy paste samples.
+
+## How it spots trouble
+
+Four small rules that stack, plus one risk roll up.
+
+- burst: N events in M secs, stock 25 in 10
+- entropy: Shannon on first 1MB, stock line 7.5, zips and pics skipped by magic
+- canary: `.sentinel/canary.txt` touched means now
+- notes and exts: `.locked`, `READ_ME.txt`, words like `bitcoin` and `decrypt`
+
+`scan` scores 0 to 100 per file. `check` rolls verify plus scan into risk `clean`, `warn`, `high`. Details in [Rules](https://hahaahhdev.github.io/sentinel/RULES/).
+
+Tune with `learn`:
+
+```bash
+sentinel learn ~/Documents --secs 60
+```
+
+Work like normal for a minute, it tells you a sane burst.
+
+## Config
+
+```bash
+sentinel config-init
+```
+
+Writes `sentinel.yaml`. Sentinel finds `sentinel.yaml`, `.sentinel.yaml`, `.sentinel/config.yaml` by walking up. Flags beat file.
+
+```yaml
+burst: 25
+window: 10
+cooldown: 30
+entropy_line: 7.5
+vault_max_mb: 5
+risk_warn: 40
+risk_high: 70
+webhook: ""
+notify: false
+kill: false
+```
+
+Ignores merge from built ins, `.sentinelignore`, and yaml `ignore:`. Full list in [Config](https://hahaahhdev.github.io/sentinel/CONFIG/).
+
+## Alerts and restores
+
+Hits go to terminal, `.sentinel/sentinel.log`, `.sentinel/events.jsonl`. Optional webhook, mail via local smtp, desktop popup.
+
+Two safety nets:
+
+- quarantine in `.sentinel/quarantine/<ts>/`, post hit copies for forensics
+- vault in `.sentinel/vault/`, pre hit clean copies for restores
+
+```bash
+sentinel snaps .
+sentinel protect . --restore-clean all
+```
+
+Most tools only do the first. Vault is why restores actually work.
+
+## CI and web
+
+```bash
+sentinel check ./uploads --fail-warn
+sentinel scan . --sarif > results.sarif
+sentinel report . --out report.html
+sentinel serve . --port 8000
+```
+
+Sarif feeds GitHub code scanning. Html is one offline file. Serve adds `/json` for scripts. Workflow samples in `examples/` and [Actions](https://hahaahhdev.github.io/sentinel/ACTIONS/).
+
+Web docs build with mkdocs material. `mkdocs serve` to preview, push to `main` to publish via Pages. How to in [Web docs](https://hahaahhdev.github.io/sentinel/WEB/).
+
+## Layout
+
+```
+sentinel/
+  cli.py       # commands
+  baseline.py  # hash, sqlite, diff
+  detect.py    # entropy, notes, risk
+  vault.py     # clean copies
+  watcher.py   # live loop
+  respond.py   # logs, webhook, mail, sarif
+  report.py    # html
+  serve.py     # local web
+  learn.py     # auto tune
+  proc.py      # top writer, kill
+  config.py    # yaml
+docs/          # pages source
+examples/
+tests/
+```
+
+## Contributing
+
+See `CONTRIBUTING.md`. Fork, `pip install -e .[dev]`, `pytest -q`, PR with a test and what folder you tried it on.
+
+## License
+
+MIT, see `LICENSE`.

sentinel_watch-0.3.0/README.md

@@ -0,0 +1,194 @@
+# sentinel
+
+![python](https://img.shields.io/badge/python-3.10%2B-blue)
+![license](https://img.shields.io/badge/license-MIT-green)
+![version](https://img.shields.io/badge/version-0.3.0-orange)
+![docs](https://img.shields.io/badge/docs-github%20pages-blue)
+![ci](https://github.com/HahaAhhDev/sentinel/actions/workflows/ci.yml/badge.svg)
+
+Tiny folder watchdog that spots ransomware-like behavior. Baseline it, watch it, get told before it is too late.
+
+Docs site: https://hahaahhdev.github.io/sentinel/
+
+```
+pip install sentinel-watch
+sentinel init ~/Documents
+sentinel watch ~/Documents
+```
+
+That is the pitch. No server. No signup. Files stay local.
+
+---
+
+## Why this one
+
+Most integrity tools are built for servers and need setup. Most crypto detectors only scan once and miss live hits.
+
+Sentinel does both, plus two things others skip:
+
+- vault of clean copies, so `protect --restore-clean all` brings back pre hit text, not post hit junk
+- one risk number via `check`, so CI and humans read the same line
+
+Live rules plus one shot scan plus real restores. That combo is rare.
+
+## Demo in 30 seconds
+
+```bash
+pip install -e .
+sentinel demo
+sentinel scan ./demo_run
+sentinel check ./demo_run
+sentinel report ./demo_run --out report.html
+```
+
+You get entropy, file scores, and a risk line like `risk warn 55`. Open `report.html` for the pretty page.
+
+## Install
+
+```bash
+pip install sentinel-watch
+```
+
+From source:
+
+```bash
+git clone https://github.com/HahaAhhDev/sentinel
+cd sentinel
+pip install -e .
+```
+
+Needs Python 3.10+. Pulls `watchdog`, `typer`, `rich`, `pyyaml`, `psutil`. Dev extras add `pytest`, `mkdocs`, `mkdocs-material`.
+
+## Quickstart
+
+```bash
+sentinel init ~/Documents
+sentinel verify ~/Documents
+sentinel scan ~/Documents
+sentinel check ~/Documents
+sentinel watch ~/Documents
+```
+
+Full walk is in [docs](https://hahaahhdev.github.io/sentinel/) under Quickstart. Short version: `init` once, `check` often, `watch` when it matters.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `init` | Hash all, fill vault |
+| `update` | Rehash only changed |
+| `status` | Counts, dates, vault size |
+| `verify` | Diff vs baseline |
+| `diff` | Text diffs via vault |
+| `scan` | Score files, json or sarif |
+| `why FILE` | Explain one file |
+| `check` | Verify plus scan plus risk, for CI |
+| `watch` | Live loop, canary, notes, storms |
+| `learn` | Watch quiet, suggest burst |
+| `protect` | Fill vault or restore clean |
+| `events`, `timeline` | Last hits |
+| `snaps`, `restore` | Quarantine packs |
+| `report`, `serve` | HTML page, local web |
+| `config-init`, `doctor` | Scaffold yaml, self test |
+| `clean`, `demo` | Wipe, fake hit |
+
+See `docs/CLI.md` or the [web CLI page](https://hahaahhdev.github.io/sentinel/CLI/) for flags and copy paste samples.
+
+## How it spots trouble
+
+Four small rules that stack, plus one risk roll up.
+
+- burst: N events in M secs, stock 25 in 10
+- entropy: Shannon on first 1MB, stock line 7.5, zips and pics skipped by magic
+- canary: `.sentinel/canary.txt` touched means now
+- notes and exts: `.locked`, `READ_ME.txt`, words like `bitcoin` and `decrypt`
+
+`scan` scores 0 to 100 per file. `check` rolls verify plus scan into risk `clean`, `warn`, `high`. Details in [Rules](https://hahaahhdev.github.io/sentinel/RULES/).
+
+Tune with `learn`:
+
+```bash
+sentinel learn ~/Documents --secs 60
+```
+
+Work like normal for a minute, it tells you a sane burst.
+
+## Config
+
+```bash
+sentinel config-init
+```
+
+Writes `sentinel.yaml`. Sentinel finds `sentinel.yaml`, `.sentinel.yaml`, `.sentinel/config.yaml` by walking up. Flags beat file.
+
+```yaml
+burst: 25
+window: 10
+cooldown: 30
+entropy_line: 7.5
+vault_max_mb: 5
+risk_warn: 40
+risk_high: 70
+webhook: ""
+notify: false
+kill: false
+```
+
+Ignores merge from built ins, `.sentinelignore`, and yaml `ignore:`. Full list in [Config](https://hahaahhdev.github.io/sentinel/CONFIG/).
+
+## Alerts and restores
+
+Hits go to terminal, `.sentinel/sentinel.log`, `.sentinel/events.jsonl`. Optional webhook, mail via local smtp, desktop popup.
+
+Two safety nets:
+
+- quarantine in `.sentinel/quarantine/<ts>/`, post hit copies for forensics
+- vault in `.sentinel/vault/`, pre hit clean copies for restores
+
+```bash
+sentinel snaps .
+sentinel protect . --restore-clean all
+```
+
+Most tools only do the first. Vault is why restores actually work.
+
+## CI and web
+
+```bash
+sentinel check ./uploads --fail-warn
+sentinel scan . --sarif > results.sarif
+sentinel report . --out report.html
+sentinel serve . --port 8000
+```
+
+Sarif feeds GitHub code scanning. Html is one offline file. Serve adds `/json` for scripts. Workflow samples in `examples/` and [Actions](https://hahaahhdev.github.io/sentinel/ACTIONS/).
+
+Web docs build with mkdocs material. `mkdocs serve` to preview, push to `main` to publish via Pages. How to in [Web docs](https://hahaahhdev.github.io/sentinel/WEB/).
+
+## Layout
+
+```
+sentinel/
+  cli.py       # commands
+  baseline.py  # hash, sqlite, diff
+  detect.py    # entropy, notes, risk
+  vault.py     # clean copies
+  watcher.py   # live loop
+  respond.py   # logs, webhook, mail, sarif
+  report.py    # html
+  serve.py     # local web
+  learn.py     # auto tune
+  proc.py      # top writer, kill
+  config.py    # yaml
+docs/          # pages source
+examples/
+tests/
+```
+
+## Contributing
+
+See `CONTRIBUTING.md`. Fork, `pip install -e .[dev]`, `pytest -q`, PR with a test and what folder you tried it on.
+
+## License
+
+MIT, see `LICENSE`.

sentinel_watch-0.3.0/config.example.yaml

@@ -0,0 +1,32 @@
+# copy to sentinel.yaml and tweak
+# all of these have sane defaults
+
+path: "."
+burst: 25
+window: 10
+cooldown: 30
+entropy_line: 7.5
+webhook: ""
+notify: false
+kill: false
+
+# vault keeps clean copies for restores
+vault_max_mb: 5
+
+# risk lines for check
+risk_warn: 40
+risk_high: 70
+
+# local web view
+serve_port: 8000
+
+# mail, blank means off
+mail_to: ""
+mail_from: "sentinel@localhost"
+smtp_host: "localhost"
+smtp_port: 25
+
+# extra ignore globs on top of .sentinelignore
+ignore:
+  - "*.tmp"
+  - "*.log"

sentinel_watch-0.3.0/docs/ACTIONS.md

@@ -0,0 +1,94 @@
+# Actions and CI
+
+Pipes and GitHub.
+
+## The one command
+
+```bash
+sentinel check ./data
+sentinel check ./data --fail-warn
+echo $?
+```
+
+Fails on high or drift. Add `--fail-warn` to fail on warn too. Best gate for uploads and golden data.
+
+Json for scripts:
+
+```bash
+sentinel check ./uploads --json > check.json
+sentinel verify ./uploads --json > verify.json
+sentinel scan ./uploads --json > scan.json
+```
+
+Sarif for code scanning:
+
+```bash
+sentinel scan . --sarif > results.sarif
+sentinel check . --sarif > results.sarif
+```
+
+Upload with `github/codeql-action/upload-sarif`.
+
+## Verify gate
+
+```bash
+sentinel verify ./data --fail
+```
+
+Exit 1 on changed or deleted. New files do not fail. Good when baseline is committed.
+
+## Full workflow
+
+See `examples/github-action.yml`. Minimal job:
+
+```yaml
+- uses: actions/checkout@v4
+- uses: actions/setup-python@v5
+  with:
+    python-version: "3.12"
+- run: pip install -e .
+- run: sentinel check . --json > check.json
+- uses: actions/upload-artifact@v4
+  with:
+    name: sentinel-check
+    path: check.json
+```
+
+Sarif job:
+
+```yaml
+- run: sentinel scan . --sarif > results.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: results.sarif
+```
+
+Docs build runs in `ci.yml` too via `mkdocs build --strict`.
+
+## HTML artifacts
+
+```bash
+sentinel report ./uploads --out report.html
+```
+
+One offline file. Upload it, link it in PRs.
+
+## Pre commit
+
+```yaml
+- repo: local
+  hooks:
+    - id: sentinel-check
+      name: sentinel check
+      entry: sentinel check .
+      language: system
+      pass_filenames: false
+```
+
+## Alerts in prod
+
+```bash
+sentinel watch ./uploads --webhook "$WEBHOOK_URL"
+```
+
+Body is `{"text": "title\ndetail"}`. Works for Slack and Discord. Add mail via yaml `mail_to` plus local smtp if you run your own box.

sentinel_watch-0.3.0/docs/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.3.0
+
+- add `check` with risk clean/warn/high plus json and sarif
+- add `why` to explain one file score
+- add `diff` using vault copies
+- add `protect` vault fill and restore clean
+- add `update` fast rehash
+- add `learn` to suggest burst
+- add `timeline`, `serve` with /json, `config-init`, `doctor`
+- add `watch --daemon`, rename and delete storm rules
+- store entropy at baseline time
+- add mail alerts, sarif output
+- add mkdocs site plus pages and ci workflows
+- human pass over all code and docs
+
+## 0.2.0
+
+- add `scan`, `report`, `events`, `snaps`, `restore`, `status`, `clean`
+- add yaml config plus `.sentinelignore`
+- add ransom note and ext scoring
+- add json logs and html report
+- add webhook, desktop note, optional kill
+- add docs folder and examples
+- threaded baseline
+
+## 0.1.0
+
+- first cut: `init`, `verify`, `watch`, `demo`
+- burst plus entropy plus canary