From b392361c1bc4df9556d895f4ecbe36bc2136fb38 Mon Sep 17 00:00:00 2001 From: TPOALOS <351316698+TPOALOS@users.noreply.github.com> Date: Sun, 8 Nov 2026 01:39:36 +0300 Subject: [PATCH] Add owner tracking, update command, JSON output, packaging and CI (v1.1.0) --- .github/workflows/tests.yml | 30 ++++++++++++ CHANGELOG.md | 13 +++++ README.md | 10 +++- fimcheck.py | 49 ++++++++++++++----- pyproject.toml | 29 ++++++++++++ test_fimcheck.py | 94 +++++++++++++++++++++++++++++++++++++ 6 files changed, 211 insertions(+), 14 deletions(-) create mode 100644 .github/workflows/tests.yml create mode 100644 CHANGELOG.md create mode 100644 pyproject.toml diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..2bacbe6 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,30 @@ +name: tests + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + test: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest] + python-version: ["3.10", "3.12", "3.13"] + include: + - os: macos-latest + python-version: "3.9" + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 + with: + python-version: ${{ matrix.python-version }} + - name: Unit tests + run: python -m unittest -v diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..11dadbf --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,13 @@ +# Changelog + +## 1.1.0 + +- Owner (uid/gid) change detection; baselines from 1.0 still work +- `update` command to accept reviewed changes +- `--json` output for `check` and `update` +- Baselines are written atomically +- Installable with pip (`fimcheck` command), CI on Linux and macOS + +## 1.0.0 + +Initial release. diff --git a/README.md b/README.md index c4f8588..6495070 100644 --- a/README.md +++ b/README.md @@ -10,9 +10,17 @@ Standard library only; read-only on the monitored directory. python3 fimcheck.py init /etc/myapp -b baseline.json python3 fimcheck.py check /etc/myapp -b baseline.json python3 fimcheck.py check /srv/site -b baseline.json -x node_modules -x "*.log" +python3 fimcheck.py check /etc/myapp -b baseline.json --json # machine-readable +python3 fimcheck.py update /etc/myapp -b baseline.json # after you reviewed the changes +# or: pip install git+https://github.com/TPOALOS/fimcheck && fimcheck check ... ``` -Output lines look like `MODIFIED conf/app.ini`. Exit codes: `0` no changes, +Output lines look like `MODIFIED conf/app.ini`; the labels are `ADDED`, `REMOVED`, `MODIFIED`, `MODE_CHANGED` and +`OWNER_CHANGED` (uid/gid, recorded since 1.1; baselines from 1.0 are still readable and never raise owner alarms). +`update` prints what changed and then accepts the current state as the new baseline, so a legitimate change +does not keep alerting. Baselines are written atomically. + +Exit codes: Exit codes: `0` no changes, `1` changes detected, `2` error (bad directory or unreadable baseline). Notes: diff --git a/fimcheck.py b/fimcheck.py index 3dcd2d6..5cea657 100644 --- a/fimcheck.py +++ b/fimcheck.py @@ -13,7 +13,7 @@ import stat import sys -__version__ = "1.0.0" +__version__ = "1.1.0" def sha256_file(path): @@ -31,7 +31,7 @@ def excluded(rel, patterns): def snapshot(root, exclude=()): - """Return {relative_path: {sha256, mode}} for regular files under root. + """Return {relative_path: {sha256, mode, uid, gid}} for regular files under root. Symlinks are not followed and are not recorded. """ @@ -49,7 +49,8 @@ def snapshot(root, exclude=()): st = os.stat(full) if not stat.S_ISREG(st.st_mode): continue - snap[rel] = {"sha256": sha256_file(full), "mode": stat.S_IMODE(st.st_mode)} + snap[rel] = {"sha256": sha256_file(full), "mode": stat.S_IMODE(st.st_mode), + "uid": getattr(st, "st_uid", None), "gid": getattr(st, "st_gid", None)} except OSError: continue return snap @@ -59,30 +60,46 @@ def diff(old, new): """Compare two snapshots; return dict of sorted lists.""" added = sorted(set(new) - set(old)) removed = sorted(set(old) - set(new)) - modified, mode_changed = [], [] + modified, mode_changed, owner_changed = [], [], [] for p in sorted(set(old) & set(new)): if old[p]["sha256"] != new[p]["sha256"]: modified.append(p) - elif old[p]["mode"] != new[p]["mode"]: + continue + if old[p]["mode"] != new[p]["mode"]: mode_changed.append(p) + # baselines written by 1.0 carry no owner, so compare only when both sides have it + if old[p].get("uid") is not None and new[p].get("uid") is not None and \ + (old[p]["uid"], old[p].get("gid")) != (new[p]["uid"], new[p].get("gid")): + owner_changed.append(p) return {"added": added, "removed": removed, "modified": modified, - "mode_changed": mode_changed} + "mode_changed": mode_changed, "owner_changed": owner_changed} def has_changes(d): return any(d.values()) +def write_baseline(path, snap): + """Write atomically so an interrupted run cannot leave a half-written baseline.""" + tmp = path + ".tmp" + with open(tmp, "w") as fh: + json.dump({"version": 2, "files": snap}, fh, indent=2, sort_keys=True) + os.replace(tmp, path) + + def main(argv=None): ap = argparse.ArgumentParser(description="File integrity monitor (SHA-256 baseline).") ap.add_argument("--version", action="version", version=__version__) sub = ap.add_subparsers(dest="cmd", required=True) - for name, helptext in (("init", "create a baseline"), ("check", "compare against a baseline")): + for name, helptext in (("init", "create a baseline"), ("check", "compare against a baseline"), + ("update", "accept the current state as the new baseline (prints what changed)")): sp = sub.add_parser(name, help=helptext) sp.add_argument("directory") sp.add_argument("-b", "--baseline", default="fim-baseline.json") sp.add_argument("-x", "--exclude", action="append", default=[], help="glob pattern to skip (repeatable)") + if name != "init": + sp.add_argument("--json", action="store_true", help="machine-readable output") args = ap.parse_args(argv) if not os.path.isdir(args.directory): @@ -95,8 +112,7 @@ def main(argv=None): snap = snapshot(args.directory, exclude) if args.cmd == "init": - with open(args.baseline, "w") as fh: - json.dump({"version": 1, "files": snap}, fh, indent=2, sort_keys=True) + write_baseline(args.baseline, snap) print("fimcheck: baseline of %d file(s) written to %s" % (len(snap), args.baseline)) return 0 @@ -107,13 +123,20 @@ def main(argv=None): print("fimcheck: cannot read baseline: %s" % exc, file=sys.stderr) return 2 d = diff(old, snap) - for label in ("added", "removed", "modified", "mode_changed"): - for p in d[label]: - print("%-12s %s" % (label.upper(), p)) + if args.json: + print(json.dumps({"changes": d, "ok": not has_changes(d)}, indent=2)) + else: + for label in ("added", "removed", "modified", "mode_changed", "owner_changed"): + for p in d[label]: + print("%-13s %s" % (label.upper(), p)) + if args.cmd == "update": + write_baseline(args.baseline, snap) + print("fimcheck: baseline updated (%d file(s), %d change(s) accepted)" % ( + len(snap), sum(len(v) for v in d.values())), file=sys.stderr) + return 0 print("fimcheck: %s" % ("changes detected" if has_changes(d) else "no changes"), file=sys.stderr) return 1 if has_changes(d) else 0 - if __name__ == "__main__": sys.exit(main()) diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..3858004 --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,29 @@ +[build-system] +requires = ["setuptools>=61"] +build-backend = "setuptools.build_meta" + +[project] +name = "fimcheck" +version = "1.1.0" +description = "File integrity monitor: SHA-256 baseline, change report incl. permissions and owner, JSON output." +readme = "README.md" +requires-python = ">=3.9" +license = {text = "MIT"} +authors = [{name = "TPOALOS"}] +keywords = ["file-integrity-monitoring", "integrity", "sha256", "blue-team"] +classifiers = [ + "Environment :: Console", + "Intended Audience :: Developers", + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3", + "Topic :: Security", +] + +[project.urls] +Homepage = "https://github.com/TPOALOS/fimcheck" + +[project.scripts] +fimcheck = "fimcheck:main" + +[tool.setuptools] +py-modules = ["fimcheck"] diff --git a/test_fimcheck.py b/test_fimcheck.py index 217bb21..bde23b0 100644 --- a/test_fimcheck.py +++ b/test_fimcheck.py @@ -1,3 +1,6 @@ +import contextlib +import io +import json import os import tempfile import unittest @@ -68,5 +71,96 @@ def test_missing_baseline(self): self.assertEqual(fimcheck.main(["check", self.root, "-b", "/nonexistent/x.json"]), 2) +def run_main(*argv): + out, err = io.StringIO(), io.StringIO() + with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err): + code = fimcheck.main(list(argv)) + return code, out.getvalue(), err.getvalue() + + +class NewFeatureTests(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.TemporaryDirectory() + self.root = os.path.join(self.tmp.name, "tree") + os.makedirs(self.root) + write(self.root, "a.txt", "alpha") + write(self.root, "b.txt", "beta") + self.base = os.path.join(self.tmp.name, "base.json") + run_main("init", self.root, "-b", self.base) + + def tearDown(self): + self.tmp.cleanup() + + def test_snapshot_records_owner(self): + snap = fimcheck.snapshot(self.root) + self.assertEqual(snap["a.txt"]["uid"], os.stat(os.path.join(self.root, "a.txt")).st_uid) + + def test_owner_change_detected_when_both_sides_have_owner(self): + old = fimcheck.snapshot(self.root) + new = json.loads(json.dumps(old)) + new["a.txt"]["uid"] = old["a.txt"]["uid"] + 1 + d = fimcheck.diff(old, new) + self.assertEqual(d["owner_changed"], ["a.txt"]) + self.assertTrue(fimcheck.has_changes(d)) + + def test_old_baselines_without_owner_do_not_false_alarm(self): + old = {p: {"sha256": v["sha256"], "mode": v["mode"]} for p, v in fimcheck.snapshot(self.root).items()} + self.assertFalse(fimcheck.has_changes(fimcheck.diff(old, fimcheck.snapshot(self.root)))) + + def test_mode_and_owner_reported_independently(self): + old = fimcheck.snapshot(self.root) + new = json.loads(json.dumps(old)) + new["a.txt"]["uid"] += 1 + new["a.txt"]["mode"] ^= 0o001 + d = fimcheck.diff(old, new) + self.assertEqual((d["mode_changed"], d["owner_changed"]), (["a.txt"], ["a.txt"])) + + def test_content_change_takes_precedence(self): + old = fimcheck.snapshot(self.root) + new = json.loads(json.dumps(old)) + new["a.txt"]["sha256"] = "0" * 64 + new["a.txt"]["uid"] += 1 + d = fimcheck.diff(old, new) + self.assertEqual((d["modified"], d["owner_changed"]), (["a.txt"], [])) + + def test_check_json(self): + write(self.root, "a.txt", "tampered") + code, out, _ = run_main("check", self.root, "-b", self.base, "--json") + data = json.loads(out) + self.assertEqual(code, 1) + self.assertFalse(data["ok"]) + self.assertEqual(data["changes"]["modified"], ["a.txt"]) + + def test_check_json_clean(self): + code, out, _ = run_main("check", self.root, "-b", self.base, "--json") + self.assertEqual((code, json.loads(out)["ok"]), (0, True)) + + def test_update_accepts_changes_and_prints_them(self): + write(self.root, "a.txt", "tampered") + write(self.root, "new.txt", "x") + code, out, err = run_main("update", self.root, "-b", self.base) + self.assertEqual(code, 0) + self.assertIn("MODIFIED a.txt", out) + self.assertIn("ADDED new.txt", out) + self.assertIn("2 change(s) accepted", err) + self.assertEqual(run_main("check", self.root, "-b", self.base)[0], 0) + + def test_update_needs_an_existing_baseline(self): + code, _, err = run_main("update", self.root, "-b", os.path.join(self.tmp.name, "nope.json")) + self.assertEqual(code, 2) + self.assertIn("cannot read baseline", err) + + def test_baseline_written_atomically_and_versioned(self): + with open(self.base) as fh: + data = json.load(fh) + self.assertEqual(data["version"], 2) + self.assertFalse(os.path.exists(self.base + ".tmp")) + + def test_text_output_labels(self): + os.remove(os.path.join(self.root, "b.txt")) + _, out, _ = run_main("check", self.root, "-b", self.base) + self.assertIn("REMOVED b.txt", out) + + if __name__ == "__main__": unittest.main()