FileDefender - File Integrity Monitoring (FIM) System

An audit-ready, production-grade File Integrity Monitoring (FIM) system, named FileDefender, built using Python (FastAPI, watchdog) and React (Vite, Tailwind CSS v4, Recharts).

The system continuously scans and monitors designated directories recursively, computes cryptographic baseline hashes (SHA-256) of files, tracks changes in real-time, alerts on unauthorized filesystem activity (creations, deletions, modifications, and renames), and presents analytics through a responsive dark-mode-first security console.

---

🏗️ Folder Structure

├── backend/
│   ├── Dockerfile
│   ├── requirements.txt
│   ├── app/
│   │   ├── __init__.py
│   │   ├── config.py             # System & Cryptography settings
│   │   ├── main.py               # FastAPI server & observer setup
│   │   ├── api/
│   │   │   ├── __init__.py
│   │   │   └── routes.py         # REST Endpoints & WebSockets
│   │   ├── db/
│   │   │   ├── __init__.py
│   │   │   ├── models.py         # SQLAlchemy DB models (Files, Alerts, AuditLogs, Users)
│   │   │   └── session.py        # Database connection configurations
│   │   ├── schemas/
│   │   │   ├── __init__.py
│   │   │   └── schemas.py        # Pydantic Schemas
│   │   └── services/
│   │       ├── __init__.py
│   │       ├── auth.py           # JWT generation & password hashing (bcrypt)
│   │       ├── monitor.py        # Watchdog filesystem event driver
│   │       ├── report.py         # CSV & PDF exporter (FPDF2)
│   │       ├── scanner.py        # Concurrent multi-threaded baseline scanner
│   │       └── verifier.py       # Integrity verification & scoring engine
│   └── tests/
│       ├── __init__.py
│       └── test_fim.py           # Pytest unit tests suite
│
├── frontend/
│   ├── Dockerfile
│   ├── index.html
│   ├── package.json
│   ├── vite.config.js
│   └── src/
│       ├── App.css
│       ├── App.jsx               # Security Dashboard logic & layouts
│       ├── index.css             # Tailwind CSS v4 import
│       └── main.jsx
│
├── sandbox/                      # Configured local monitoring test directory
├── docker-compose.yml            # System orchestrator
└── README.md

---

🛡️ Database Schema

SQLite is used for local high-speed metadata persistence:

• users: RBAC accounts (ADMIN or AUDITOR roles with hashed passwords).
• files: Paths, SHA-256 hashes, sizes, and timestamps of monitored directories' baselines.
• alerts: High-detail logs capturing file event types, old/new cryptographic hashes, severity, and timestamps.
• audit_logs: Tracks admin/auditor actions (e.g. manual scan triggers, integrity checks, logon success/failure).

---

📈 Security Alerts & Severities

Severity	Event Trigger	Description
CRITICAL	Sensitive File Deleted	Deletion of files matching .env, .pem, .key, id_rsa, secrets.
HIGH	File Modified / Critical Modified	SHA-256 mismatch on configuration/scripts (.json, .conf, .py, .sh).
MEDIUM	File Renamed / Moved	Watchdog moves (src_path ➔ dest_path rename matching).
LOW	New File Added	Creating any file under the monitored directory.

---

🔌 API Documentation

Method	Endpoint	Description	Auth Required
POST	/api/auth/login	Authenticate and obtain JWT access token.	None (Rate Limited)
GET	/api/files	List all monitored files.	Admin / Auditor
GET	/api/alerts	Get history of security alerts (searchable/filterable).	Admin / Auditor
GET	/api/alerts/{id}	Retrieve a single alert's details (inspect old vs new hashes).	Admin / Auditor
GET	/api/statistics	Retrieve threat analytics, weekly trends, target directories.	Admin / Auditor
POST	/api/scan	Manually run/update baseline scan (multi-threaded).	Admin Only
POST	/api/verify	Manually verify filesystem hashes against SQLite baseline.	Admin / Auditor
GET	/api/audit-logs	Retrieve administrator audit trails.	Admin Only
GET	/api/export	Download audit report as CSV or PDF.	Admin / Auditor
WS	/api/ws/alerts	WebSocket server for real-time security alerts.	Client WebSockets

---

🚀 Quickstart Guide

Option 1: Run Locally (Developer Mode)

1. Start the Backend

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Backend API will run at http://localhost:8000 (SQLite DB fim_database.db and logs fim_system.log will be initialized).

2. Start the Frontend

cd frontend
npm install
npm run dev

Frontend console will open at http://localhost:5173.

Option 2: Run via Docker Compose (Recommended)

docker-compose up --build

• Backend starts on http://localhost:8000
• Frontend console starts on http://localhost:3001

---

🔐 Pre-seeded User Accounts

Username	Default Password	Role
admin	admin_pass_123	ADMIN (Full dashboard controls, baseline rescan, audits)
auditor	auditor_pass_123	AUDITOR (View statistics, export reports, manual verify)

---

🧪 Running Unit Tests

Validate integrity calculation, scanner multi-threading, and JWT logic:

cd backend
pytest -v