Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
@@ -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
13 changes: 13 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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.
10 changes: 9 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
49 changes: 36 additions & 13 deletions fimcheck.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
import stat
import sys

__version__ = "1.0.0"
__version__ = "1.1.0"


def sha256_file(path):
Expand All @@ -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.
"""
Expand All @@ -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
Expand All @@ -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):
Expand All @@ -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

Expand All @@ -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())
29 changes: 29 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
@@ -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"]
94 changes: 94 additions & 0 deletions test_fimcheck.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
import contextlib
import io
import json
import os
import tempfile
import unittest
Expand Down Expand Up @@ -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()
Loading