CephFS Guard

CephFS Guard watches a CephFS file system for ransomware and other destructive activity, records what it finds, and can react on its own by snapshotting the file system and evicting the client responsible. It is built into croit: enable it per file system, pick the servers it runs on, and triage what it catches from the croit UI.

How it works

CephFS Guard watches the file system as it changes and reacts on its own:

1. Watch: every file and directory change on the protected file system is seen as it happens.
2. Detect: six independent detectors score the recent event stream, each looking for a different signature of a ransomware run.
3. Aggregate: the scores are combined into one confidence value. When it is high enough, CephFS Guard raises a detection.
4. React: CephFS Guard records the detection and, if you enabled the actions, takes a snapshot of the file system and evicts the client responsible.
5. Report: the detection is stored in croit, listed on the Detections tab, and raised as a Task Advisor warning until you triage it.

Detectors

Detector	What it looks for
Extension Change	Files renamed to extensions used by known ransomware families.
Filename Change	Rename operations whose new names match ransomware naming patterns.
Bulk Operations	The sheer operation rate of a mass-encryption run.
Ransom Note	Creation of files that look like ransom notes.
Encryption (High Entropy)	A surge of random-looking file content, the hallmark of encryption.
Timeline Analysis	The multi-phase behavioural pattern of an encryption run.

Enabling CephFS Guard

CephFS Guard needs your cluster to run a croit Enhanced OS image.

Open File Storage → CephFS Guard, then on the Volumes tab:

1. Select the file system and click Enable CephFS Guard.
2. Choose the servers to deploy CephFS Guard services on.
3. Choose the network interface each service listens on. This is the address the MDS sends change events to, so pick an interface reachable from the MDS.

A server hosts one service per file system, so the same server can protect several file systems at once.

Configuring detection and response

Select a guarded file system on the Volumes tab and click Settings. Each detector can be turned off individually there.

Actions

Action	Default	What it does
Snapshot	Off	Takes a CephFS snapshot of the file system root when a detection fires, named cephfs-guard-<timestamp>. Rate-limited to one snapshot per 15 minutes, and snapshots are kept (no automatic cleanup).
Evict Malicious Clients	Off	Evicts and blocklists the client behind the detection for 72 hours. This cuts the attacker off, and also cuts off any legitimate workload sharing that client.

Alerting webhooks

Add the URLs you want to be notified on, each with its own timeout (for example 5s). CephFS Guard sends every detection to all of them, so you hear about an attack without watching the croit UI.

Each notification is an HTTP POST with a Content-Type: application/json body:

{
  "timestamp": "2026-07-28T09:14:22Z",
  "detector_name": "extension-change",
  "client_id": 4128,
  "session_id": "0f3c1d9a-2b4e-4c77-9a11-6d2e5f8c3b90",
  "confidence": 0.87,
  "reason": "24 of 31 files renamed to suspicious extensions within 10s",
  "total_files": 31,
  "suspicious_files": 24,
  "suspicious_percent": 77.4,
  "sample_paths": [
    "/projects/finance/q3-report.xlsx.locked",
    "/projects/finance/budget.docx.locked"
  ],
  "suggested_actions": ["log", "alert", "snapshot"]
}

Field	Description
timestamp	When the detection was raised, RFC 3339.
detector_name	Which detector fired, e.g. extension-change, file-entropy.
client_id	The CephFS client behind the activity.
session_id	The client's session, to correlate with Ceph logs.
confidence	Combined confidence, 0.0 to 1.0.
reason	Human-readable summary of what the detector saw.
total_files	Files the detector considered.
suspicious_files	How many of them looked malicious.
suspicious_percent	suspicious_files as a percentage of total_files.
sample_paths	A sample of the affected paths, not the full list.
suggested_actions	What CephFS Guard recommends: log, alert, snapshot, block. These are recommendations from the detector; what actually happens is what you enabled under Actions.

Triaging detections

The Detections tab lists what CephFS Guard has found, newest first.

Every detection starts as New. A file system with a new detection reports Degraded even when all its services are healthy, and croit raises a Task Advisor warning. Both clear once nothing is left in New.

Status	Meaning
New	Not yet looked at. This is the only status that keeps the Task Advisor warning up.
Acknowledged	Seen and handled.
False positive	Not an attack. Excluded from the warning; useful for spotting workloads that trip a detector.
Important	Marked for someone to re-examine. Survives Acknowledge all so it is not swept away with the rest, and is marked with a red dot in the list.

Acknowledge all and Prune act on everything the current filter matches, across all pages, never on rows outside it. Prune deletes acknowledged detections older than a number of days you choose, optionally including false positives; New and Important rows are never pruned.

Monitoring the services

The Volumes tab's status column aggregates a file system's services:

Status	Meaning
Healthy	Every service is running and reporting healthy, and no detection is active.
Degraded	A service is unhealthy, or a detection is still active.
No Services	Enabled, but no service is deployed.
Disabled	CephFS Guard is not enabled for this file system.

Verifying your setup

Run this on a client with the file system mounted. It writes a batch of files and renames them the way ransomware does, which trips the Extension Change detector:

mkdir -p /mnt/cephfs/guard-test && cd /mnt/cephfs/guard-test
for i in $(seq 1 30); do head -c 4096 /dev/urandom > "file$i.dat"; done
for i in $(seq 1 30); do mv "file$i.dat" "file$i.dat.locked"; done

The detection appears on the Detections tab within a few seconds.

Use a scratch directory: with the snapshot or eviction action enabled, a test detection triggers the real response.