FileOrb v1.0 — Smart File Organizer + Intelligence Suite

Organize. Analyse. Protect.
A fully-featured desktop file organizer built in pure Python — no external dependencies required.

---

Author: Instagram @x404ctl | GitHub @MAliXCS
Email: Alizarghunrajput@gmail.com

---

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Tab Reference
  • Organize
  • Extensions
  • Rules
  • Analytics
  • Intelligence
  • Live Logs
  • Settings
• Keyboard Shortcuts
• Real-Time Watcher
• File Intelligence & Security
• VirusTotal Integration
• FAQ
• License

---

Overview

FileOrb v1.0 is a desktop application that does two things most file organizers don't:

1. Organizes your files intelligently using a 270+ extension rule map, custom sorting rules, and an optional flat-output mode — with full undo/redo, dry-run preview, and real-time folder watching.

2. Analyses files for security threats, metadata leaks, entropy anomalies, EXIF/GPS data, and mismatched file types — using only Python's standard library. Hash generation (MD5/SHA1/SHA256) and optional VirusTotal lookup are built in.

Everything runs locally. No internet connection required (except for optional VirusTotal lookups). No pip installs needed.

---

Features

Category	Feature
Organizing	270+ file extension rules, custom destination folders
Organizing	Flat output mode (all files in one folder)
Organizing	Real-time folder watcher (auto-adds new files)
Organizing	Dry-run preview before moving anything
Organizing	Undo / Redo with 50-step history
Organizing	Ctrl+C / Ctrl+X / Ctrl+V clipboard support
Organizing	Multi-select with Ctrl+A, Shift+Click, drag
Intelligence	Magic-byte file type detection (independent of extension)
Intelligence	SHA256 / SHA1 / MD5 hash generation
Intelligence	Shannon entropy analysis with visual graph
Intelligence	JPEG EXIF reader (camera, GPS, datetime, settings)
Intelligence	Hex dump viewer (first 512 bytes)
Intelligence	Type mismatch detection (e.g. .txt that is actually an EXE)
Intelligence	Double-extension masking detection
Security	Suspicious extension flagging
Security	Symlink detection and warning
Security	High-entropy non-archive detection (possible packing/malware)
Security	VirusTotal hash lookup via free API
UI	Mouse wheel + touchpad scroll everywhere
UI	Column sorting on all tables
UI	Live activity log with search and level filter
UI	Analytics dashboard with category breakdown
UI	Export logs to .txt

---

Installation

Requirements: Python 3.8 or newer. That's it.

# Clone the repository
git clone https://github.com/MAliXCS/fileorb.git
cd fileorb

# Run directly — no pip install needed
python fileorb_v1.0.py

On Windows you can also double-click fileorb_v1.0.py if Python is associated with .py files.

Optional: For VirusTotal lookups, get a free API key at virustotal.com and paste it into Settings → VirusTotal API Key.

---

Quick Start

1. Run python fileorb_v1.0.py
2. Go to Settings → set your Watch Folder (where your messy files are) and Output Folder (where organized files go)
3. Click Scan in the Organize tab to preview what will be moved
4. Review the file list — approve, skip, or change destinations
5. Click Apply All to move files on disk

That's the core workflow. Everything else is optional.

---

Tab Reference

Organize Tab

The main working area. Shows all files queued for organization.

Toolbar buttons:

Button	Action
Scan	Scans the Watch Folder and loads all files into the table
Apply All	Moves all Pending/Approved files to their destinations on disk
Undo All	Resets all Moved files back to Pending status
Add Files	Browse and manually add specific files to the queue
Select All	Selects every visible row in the table
[RT] Watch: OFF	Toggles real-time folder monitoring on/off

Table columns:

Column	Description
Icon	Short label for the file type category
File Name	Original filename
Category	Detected category (Images, Code, Audio, etc.)
Size	Human-readable file size
Age	File modification time (relative)
Destination	Target subfolder path where the file will be moved
Confidence	How certain the classifier is (shown as a progress bar)
Status	Pending / Approved / Moved / Skipped
Note	Free-text note (auto-filled for pasted or RT-detected files)

Right-click context menu:

• Approve — mark selected files as approved for moving
• Skip — exclude selected files from the next Apply
• Change Destination — override the auto-detected destination folder
• View Details — popup with full file info
• Analyse in Intelligence — sends the file to the Intelligence tab for deep scan
• Remove from list — removes rows (does not delete files from disk)

Bottom bar:

• Selection count indicator
• All files in one folder checkbox — when checked, Apply All puts every file directly into the Output Folder root instead of subfolders
• Approve / Skip / Change Dest quick-action buttons

Filter bar: Click any category name (Images, Code, Audio, etc.) to filter the table to that type only. Click All to show everything.

---

Extensions Tab

A searchable, sortable reference table of all 270+ supported file extensions.

• Shows: extension, category, and auto-destination folder for every known type
• Use the Search box (top right) to filter by extension name, category, or destination
• Click any column header to sort ascending/descending
• Useful for checking where a specific file type will be sent before running a scan

---

Rules Tab

Custom sorting rules that override or supplement the built-in extension map.

Each rule has:

• Pattern — glob-style pattern like *.jpg, *.png or invoice_*
• Destination — the target folder path
• Active toggle — enable/disable without deleting

Toolbar buttons:

Button	Action
Add	Create a new custom rule
Edit	Edit the selected rule
Delete	Permanently remove the selected rule
Toggle	Enable or disable the selected rule

Double-click any rule to toggle it on/off instantly.

Rules are evaluated top-to-bottom. More specific rules (e.g. invoice_*) should go above general ones (e.g. *.pdf).

---

Analytics Tab

A visual dashboard showing statistics about the current file queue.

• Files by Category — card grid showing count per category
• Status Overview — horizontal bar chart: Pending / Approved / Moved / Skipped
• Top Extensions — bar chart of the 15 most common extensions in the queue

Click Refresh to recalculate all charts after changes.

---

Intelligence Tab

The file analysis engine. Select any real file to get a full forensic-style report.

Click Browse File or right-click any row in the Organize tab → Analyse in Intelligence.

Sub-tabs:

Metadata & Properties

Full stat dump for the selected file:

• Size (bytes and human-readable)
• Timestamps: Created, Modified, Accessed
• File permissions (octal)
• Hidden file flag
• Symlink detection
• Extension vs. magic-byte detected type
• Type mismatch alert if extension doesn't match actual content

Double-click any row to copy its value to the clipboard.

Entropy Graph

Shannon entropy plotted block by block (4KB chunks) across the entire file.

• Blue bars — normal entropy (structured/plain data)
• Orange bars — mixed content
• Red bars — high entropy (above 7.2 threshold)

High entropy in a non-archive file (e.g. a .docx that reads as highly random) can indicate encryption, packing, or embedded malware.

EXIF / GPS

For JPEG and JPG files, extracts embedded EXIF metadata using a pure-Python parser:

• Camera Make and Model
• Date/Time taken
• GPS block presence and offset
• ISO speed, aperture, shutter speed, focal length, flash
• Image dimensions, software, artist, orientation

No Pillow or external library needed.

Security Flags

A formatted terminal-style report covering:

• Overall threat level: CLEAN / MEDIUM / HIGH
• All suspicious flags with descriptions
• Entropy assessment
• Type detection and mismatch details
• All three hashes (MD5, SHA1, SHA256)
• VirusTotal results (after lookup)

Structure / Hex Preview

First 512 bytes of the file rendered as:

Offset    Hex Dump                                       ASCII
--------  -----------------------------------------------  ----------------
00000000  25 50 44 46 2D 31 2E 34 0A 25 E2 E3 CF D3 0A ...  %PDF-1.4.%......

Null bytes are dimmed. Useful for confirming the actual file type from raw bytes.

Threat Summary Panel (right side — always visible):

Field	Description
Threat Level	CLEAN / MEDIUM / HIGH
Flags	Count and summary of suspicious findings
Entropy	Shannon entropy value
Type Match	Whether extension matches magic bytes
Symlink	Whether file is a symbolic link

Hash values (MD5, SHA1, SHA256) are shown in copyable fields below the summary.

---

Live Logs Tab

A full-featured terminal-style log viewer for all application activity.

Toolbar:

Button	Action
Pause/Resume	Freeze log output without losing entries
Jump to End	Scroll to the most recent entry
Export	Save all log entries to a .txt file
Clear All	Delete all log entries

Search bar: Filter log entries by text in real time.

Level filter: Show ALL, INFO, SUCCESS, WARNING, or ERROR entries only.

Double-click any log line to copy it to the clipboard.

The sidebar on the left also shows a compact live activity log at all times.

---

Settings Tab

Folder Configuration:

Setting	Description
Watch Folder	The folder FileOrb will scan and monitor for files
Output Folder	Where organized files will be moved to
All files in one folder	Flat mode — skip subfolders, dump everything into Output Folder root

Safety Settings:

Option	Default	Description
Send to Recycle Bin	On	Never permanently delete — always move to trash
Confirm 100+ files	On	Ask before bulk-moving large batches
Confirm 1GB+ data	On	Ask before moving very large total sizes
Warn for files < 24h old	On	Extra confirmation for recently created files
ML active learning	On	Learns from your destination corrections
Cloud sync awareness	Off	Detect Dropbox/OneDrive folders
Real-time monitoring	Off	Auto-scan when new files appear

Organize Real Files on Disk Now: One-click button to immediately scan and move all files in Watch Folder to organized subfolders in Output Folder (bypasses the preview table).

VirusTotal API Key: Paste your free VT API key here. The key is masked by default — click Show to reveal it.

Save Settings: Saves current configuration.

---

Keyboard Shortcuts

Shortcut	Action	Scope
Ctrl+A	Select all visible rows	File table
Ctrl+C	Copy selected rows as TSV to clipboard	File table
Ctrl+X	Cut selected rows (removes from list, undoable)	File table
Ctrl+V	Paste rows from clipboard	File table
Ctrl+Z	Undo last action	Global
Ctrl+Y	Redo	Global
Ctrl+Shift+Z	Redo (alternative)	Global
Delete	Skip selected files	File table
Double-click	View file details	File table
Double-click	Toggle rule on/off	Rules table
Double-click	Copy value to clipboard	Intelligence metadata
Double-click	Copy line to clipboard	Live Logs
Right-click	Context menu	File table
Scroll Wheel	Scroll vertically	All tables and panels
Shift+Scroll	Scroll horizontally	All tables

---

Real-Time Watcher

The real-time watcher polls your Watch Folder every 2 seconds and automatically adds any new files to the Organize queue.

To enable:

1. Set your Watch Folder in Settings
2. Click [RT] Watch: OFF in the Organize toolbar — it turns green and reads [RT] Watch: ON
3. Drop files into your Watch Folder — they appear in the table instantly, flagged as auto-detected
4. Click again to stop watching

The watcher only reacts to new files that appear after it was started — it ignores files that were already present.

---

File Intelligence & Security

FileOrb's Intelligence tab uses only Python's standard library to perform file forensics that usually require specialized tools.

Magic Byte Detection

FileOrb reads the first 32 bytes of every file and compares them against 28 known file signatures. This works completely independently of the file extension. If a file is named document.txt but starts with MZ (PE executable header), FileOrb will flag it as a type mismatch.

Shannon Entropy

Entropy measures how "random" a file's bytes are, on a scale of 0.0 to 8.0:

Range	Meaning
0.0 – 3.5	Plain text, structured data, sparse files
3.5 – 5.5	Mixed content, typical executables
5.5 – 7.2	Compressed or encrypted sections
7.2 – 8.0	Highly random — likely encrypted, packed, or obfuscated

A .docx file with entropy of 7.8 is suspicious. A .zip with entropy of 7.8 is expected.

EXIF Privacy

JPEG photos taken on phones or cameras embed significant metadata in the EXIF block, including GPS coordinates, device make/model, and timestamps. FileOrb extracts this without any external library so you can identify and clean privacy-sensitive files before sharing them.

Hash Generation

All three hashes are computed in streaming 64KB chunks so even multi-gigabyte files can be hashed without loading them entirely into RAM.

---

VirusTotal Integration

FileOrb can query the VirusTotal database for any analysed file using its SHA256 hash.

Setup:

1. Create a free account at virustotal.com
2. Go to your profile → API Key
3. Paste the key into FileOrb Settings → VirusTotal API Key

Usage:

1. Open the Intelligence tab and analyse a file
2. Click VT Lookup in the right panel
3. Results appear instantly: detection count, total engines, and the names of any engines that flagged the file as malicious

The free VirusTotal API allows 4 lookups per minute and 500 per day. No file content is ever uploaded — only the hash is sent.

---

FAQ

Does FileOrb permanently delete files?
No. The Safety Settings default to Recycle Bin mode. Files are moved, never deleted outright.

Do I need an internet connection?
Only for VirusTotal lookups. All other features work completely offline.

Can I add my own file type rules?
Yes — the Rules tab lets you create glob patterns with custom destination folders. You can also edit the EXT dictionary in the source code for permanent additions.

What happens if a destination file already exists?
FileOrb automatically renames the incoming file to filename_copy.ext rather than overwriting.

Does it support subfolders in the Watch Folder?
The current scan uses Path.iterdir() (one level deep). For recursive scanning, enable real-time mode which watches continuously.

Why does my file show HIGH entropy?
High entropy means the file's bytes are very random. This is normal for ZIP, RAR, MP4, MP3, and other compressed/encoded formats. It is suspicious in a .docx, .exe, or .py file and may indicate packing or obfuscation.

---

License

MIT License — free to use, modify, and distribute with attribution.

---

Made with Python by Muhammad Ali
Instagram @x404ctl | GitHub @MAliXCS | Alizarghunrajput@gmail.com