CanaryGuard: A Ransomware Canary and File-System Monitor for College Lab Machines

CanaryGuard is a defensive early-warning system for the department's computer labs, where a single ransomware incident could wipe months of student project work and lab material. It combines two proven endpoint-defence ideas: canary files — decoys like fee_receipts.xlsx or lab_manual_v2.docx that no legitimate user or program ever opens, so any change to them is an alarm — and file-system behaviour monitoring, which watches real shared folders for the signature almost every encryptor shows: a burst of renames and modifications in a short window.

A lightweight Python agent (built on the Watchdog library — inotify on Linux, ReadDirectoryChangesW on Windows) runs on each lab machine. It evaluates four transparent heuristics — canary touched, rename/modification burst rate, rising Shannon entropy in modified files, and a configurable bank of known ransom-extension patterns — and on a match posts a signed evidence bundle to a central Node.js server within seconds. The server stores alerts and agent heartbeats in MySQL, and a React dashboard shows agent health, a live event timeline, the evidence (which files, how many, how fast, entropy trend) and an acknowledge-and-escalate workflow aligned with the college's incident process and CERT-In's six-hour reporting expectation.

Nothing in the project touches real malware: detection quality is measured with a benign load generator that bulk-renames and rewrites its own dummy files, plus unit tests and a week-long false-positive measurement on clean lab activity. The result is a lab-safe JNTUH major project spanning file-system internals, cryptography-lab concepts (hashing, entropy) and a measurable detection result.

The department's computer labs hold irreplaceable files — student project work, lab manuals, internal marks — protected only by a signature-based antivirus that cannot catch a new ransomware variant during the minutes it takes to encrypt a shared folder. There are no canary files on any machine, no file-system monitoring, and no early-warning path to the lab in-charge; in practice an incident would be discovered only when users find their files renamed and unreadable, by which time every mapped machine is affected and recovery means restoring yesterday's backup and losing a day of everyone's work.

What is needed is a behaviour-based early-warning layer built and operated by the department itself: decoy files whose tampering is an unambiguous alarm, transparent heuristics that detect mass-modification behaviour in seconds, an evidence bundle a human can verify in under a minute, and a central dashboard with a clear acknowledge-and-escalate workflow — all measurable (false-positive rate on clean traffic, recall against a benign simulator) and completely safe to build and demo in a college lab.

Abstract

Ransomware no longer needs to reach a server to destroy a college lab — one infected laptop mapping the lab share is enough. CanaryGuard detects that in seconds: canary files plus file-system behaviour heuristics, a Python agent per lab PC, and a Node.js + MySQL server with a React dashboard for the lab in-charge to see, acknowledge and escalate alerts. Detection is measured, not assumed — false positives from a week of clean lab activity, recall from a benign load generator imitating encryption behaviour without any malware.

Introduction

The department stores project work, lab manuals and internal marks on lab machines. Ransomware incidents at Indian institutions — colleges losing marks records and submissions — show the threat is real, while lab defences are one antivirus product whose signatures lag new families by hours. Behaviour-based early detection is the missing layer, and the file system is where ransomware betrays itself: it must touch hundreds of files quickly — including decoys nobody else ever opens.

Existing System

• A single antivirus product, updated daily: signature-based, blind to new variants, and silent during the minutes an encryptor needs.
• Backups exist on an external drive, but restoring costs a day of work, and nothing detects the incident while it happens.
• No canary files on lab machines, no file-integrity monitoring on the share, and no quick path for the lab in-charge to learn of an incident.
• Limitations: signature-only detection; no early warning, no evidence trail, and no data on how noisy a monitor would be on our real workload.

Proposed System

• Canary layer: a seeder plants decoys with tempting names in monitored directories and registers their hashes; any change to a canary is a high-severity alert, because legitimate software never touches them.
• Behaviour layer: the agent tracks modification/rename rates per directory against a sliding-window threshold and samples modified files for a Shannon-entropy trend — encryption drives entropy toward the 7.5–8.0 bits/byte ceiling for most touched files.
• Alert pipeline: the agent posts a JSON evidence bundle (counts, rename list, entropy series, process name) to the server; alerts are deduplicated, stored in MySQL and shown on the dashboard with acknowledge → escalate states.
• Measurement: a benign load generator bulk-renames and rewrites its own dummy files to imitate encryptor behaviour (no malware, no persistence, no network activity), giving recall; a clean week of lab traffic gives false positives per machine-day.

Feasibility Study

• Technical: Watchdog is mature and documented; the heuristics are simple arithmetic over events; the server is a small Express application. Entropy estimation reuses CS703PC cryptography-lab material (hashing, byte distributions), so nothing is beyond the syllabus.
• Economic: ₹0 licences — agents run on existing lab machines, the server on the department's lab server.
• Operational: Agents run as background services with heartbeats and no user interaction; the dashboard is one screen. An alert triggers the existing incident checklist; a confirmed incident is reported to CERT-In within six hours per its 2022 directions.

In scope

• Windows and Linux lab machines; monitored directories are lab-shared folders and designated project-work areas on the college's own systems.
• Canary files with realistic decoy names, hash-registered, auto-restored after events or tests.
• Four transparent heuristics with configurable thresholds; alerts carry a JSON evidence bundle (triggering process name, file counts, sampled rename list, entropy series).
• One central server (Node.js + MySQL) for up to 30 agents; React dashboard with acknowledge/escalate workflow; CSV export; agent heartbeat monitoring with an offline flag.
• A benign load generator for safe recall testing, and a one-week clean-traffic measurement for false-positive rate.

Out of scope (v1)

• Any handling, execution or analysis of real malware samples — detection is measured against benign simulation only.
• Active response (killing processes, disabling shares, network isolation) — v1 observes and alerts; automated containment is future scope.
• Hardening the agent against a deliberately attacking adversary (anti-tamper, service protection) — noted as future work.
• Network-share-wide discovery, e-mail attachment scanning, and integration with the college antivirus console.

The project follows an iterative-incremental model with a measurement loop, appropriate for JNTUH Project Stage-II: each increment ends with a supervisor review, and the final increment exists to tune thresholds from measured data rather than guesses. Stage-I (CS705PC, Semester IV-1) already produced the literature review, objectives and plan of action; Stage-II executes and measures.

Testing approach: unit tests for every heuristic against synthetic event streams; an entropy-estimator validation suite over files of known entropy (plain text, ZIP, random bytes) asserting ±0.1 bits/byte; integration tests of the signed alert API; scenario tests with the benign load generator at escalating burst rates recording detection latency; and a soak test on three lab machines for a week with FP rate reported per machine-day.

CanaryGuard is an agent–server system with three planes: sensing (agents), aggregation (server), and human response (dashboard).

1. Agent (Python + Watchdog): seeds canaries, attaches recursive observers to configured directories, funnels raw events through the heuristic engine (burst-rate sliding window, canary check, sampled entropy), and emits alerts with HMAC-signed JSON evidence bundles. It also posts a heartbeat every 60 seconds and buffers alerts locally when the server is unreachable.
2. Server (Node.js + MySQL): verifies signatures, deduplicates alert storms, stores agents, alerts and events, exposes the REST API the dashboard consumes, and e-mails a summary to the lab in-charge on a high-severity alert.
3. Dashboard (React): agent health grid (live/offline, last heartbeat), event timeline, evidence viewer (rename list, file counts, entropy sparkline), acknowledge → escalate workflow, and CSV export of any period.

flowchart LR
  subgraph LAB["Lab machines (college-owned)"]
    A1["Agent: canary seeder"] --> A2["Watchdog observers"]
    A2 --> A3["Heuristic engine: burst, canary, entropy, extensions"]
  end
  U(["Benign load generator (test only)"]) -->|"bulk renames its own dummy files"| A2
  A3 -->|"HMAC-signed JSON alert"| SRV["Node.js alert server"]
  A3 -->|"heartbeat / 60 s"| SRV
  SRV --> DB[("MySQL: agents, alerts, events")]
  SRV -->|"high-severity summary"| MAIL["E-mail to lab in-charge"]
  DB --> UI["React dashboard: timeline, evidence, ACK/escalate"]
  LC(["Lab in-charge"]) --> UI
  LC -->|"confirmed incident → report within 6 h"| CERT(["CERT-In workflow"])

ER diagram

erDiagram
  AGENT ||--o{ ALERT : raises
  AGENT ||--o{ HEARTBEAT : sends
  ALERT ||--o{ EVIDENCE_ITEM : contains
  CANARY }o--|| AGENT : "seeded by"
  USER ||--o{ ALERT_ACTION : "acknowledges / escalates"

  AGENT {
    int id PK
    string machineName
    string osFamily
    string agentVersion
    datetime lastHeartbeat
    string status
  }
  CANARY {
    int id PK
    int agentId FK
    string filePath
    string sha256
    datetime seededAt
    string state
  }
  ALERT {
    bigint id PK
    int agentId FK
    string kind "canary | burst | entropy | extension"
    string severity
    datetime raisedAt
    string state "open | ack | escalated | closed"
    string signature "HMAC of payload"
  }
  EVIDENCE_ITEM {
    int id PK
    bigint alertId FK
    string filePath
    string changeType
    double entropyDelta
  }
  HEARTBEAT {
    int id PK
    int agentId FK
    datetime sentAt
    int eventCount
  }
  USER {
    int id PK
    string email UK
    string passwordHash
    string role
  }
  ALERT_ACTION {
    int id PK
    bigint alertId FK
    int userId FK
    string action
    string remark
    datetime actedAt
  }

Alert state machine

flowchart TD
  O(["Alert raised"]) --> OPEN["open"]
  OPEN -->|"lab in-charge reviews evidence"| ACK["acknowledged"]
  ACK -->|"false positive"| CLOSED["closed with remark"]
  ACK -->|"confirmed incident"| ESC["escalated: disconnect machine, restore, report"]
  ESC --> CLOSED

The design deliberately keeps every component observable and reversible: canaries restore themselves, alerts require a human decision before any escalation, and nothing in the pipeline can modify anything beyond its own directories and database.

• Automated containment: on a high-severity alert, unmap the share and suspend the triggering process pending human confirmation, with a strict allow-list to prevent accidents.
• Anti-tamper hardening: run the agent as a protected service with watchguard re-spawn and config signing, closing the obvious "delete the agent first" gap.
• YARA-style extension intelligence: periodically refresh the ransom-extension bank and canary-name patterns from threat advisories.
• Cross-machine correlation: one machine touching canaries on several lab shares simultaneously is a worm-style pattern the server can detect centrally.
• Backup-integrity watchdog: verify that backup copies of canaries and sample project files remain unmodified, catching attacks aimed at backups first.
• A department playbook: link each escalated alert to a one-page incident checklist aligned with CERT-In's six-hour reporting expectation, making the project operationally real.