File / Directory Change

Detect changes to important files and folders compared with a stored baseline.

The File / Directory Change check is lightweight file-integrity monitoring. On its first run it stores a signature of the files and folders you specify as a baseline, and from then on it reports any deviation from it. This lets you notice, for example, when someone changes a configuration file, a hosts file or the contents of a program folder. The check runs through the octoja agent directly on the device, on Windows, Linux, and macOS (x64 and Arm64 each), every 60 minutes by default.

Steps

Go to Devices and open the device.
Click the Checks tab → Add Check → File / Directory Change.
Under Paths to watch, enter the files and folders the check should monitor.
Click Add Check.

Alternatively, assign the check with a config package.

Settings

Field	Type	Required	Default	Description
Paths to watch	List of strings	Yes	—	Files (content-hashed) or folders (metadata signature) to baseline
Include subdirectories	Boolean	No	Yes	For folders, also includes the files in all subfolders
Report change as critical	Boolean	No	No	Reports a detected change as Critical instead of Warning
Accept current state (reset baseline)	Boolean	No	No	Overwrite the stored baseline with the current state and clear the alert

Paths are used exactly as entered; wildcards such as * are not evaluated.

What is compared

Path type	Signature
File	SHA-256 hash of the file content. Any content change is detected; a timestamp-only change is not.
Folder	List of all contained files with relative path, size and last modification time. New, deleted, renamed, resized or re-saved files are detected. Empty subfolders and changes to the folders themselves do not count.
Missing	A missing path becomes part of the signature as “missing”. If a path later disappears or appears, that also counts as a change.

The signatures of all paths are combined into one overall signature and compared with the baseline.

Results

Situation	Result
First run (no baseline yet)	OK, the check details show Baseline established
Signature matches the baseline	OK, No change since baseline
Signature differs from the baseline	Warning, or Critical with Report change as critical; the check details show Change detected since baseline
Paths to watch is empty	Warning
A file cannot be read (for example locked or access denied)	Failure

The check details list each path with a shortened signature or the note missing.

Acknowledge a change

A detected change stays reported until you accept the new state — the check does not update the baseline on its own.

In the check configuration, enable Accept current state (reset baseline) and save.
Wait for the next run. The check stores the current state as the new baseline and reports OK.
Disable the option again.

Warning: While Accept current state (reset baseline) is enabled, every run overwrites the baseline and reports OK. The check detects no changes during that time.

Notes

A change that is made and reverted between two runs goes unnoticed.
The agent stores the baseline locally on the device, separately for each combination of path list and Include subdirectories. If you change the paths or this option, the next run creates a new baseline and reports OK.
Subfolders the agent cannot access are silently skipped in the folder signature.
For large files, the check reads the entire content on every run to calculate the hash.

Was this helpful?

Still need help? Ask the team