FileChecker by CyberHeroes*

Static malware triage tool. Drop a suspicious file into the web UI and get back hashes, entropy, extracted strings, suspicious API patterns, PE header details, and archive contents — all processed locally with no data sent anywhere.

What it does

• Hashes — MD5, SHA-1, SHA-256 with direct VirusTotal / MalwareBazaar lookup links
• File type detection — magic byte identification independent of file extension
• Entropy analysis — overall and per-section; high entropy is a packing/encryption indicator
• Suspicious pattern scanning — regex-based detection across seven categories: Networking, Process Injection, Persistence, Evasion/Anti-Analysis, File/System Access, Credential Access, Encryption/Obfuscation
• PE header analysis — machine type, subsystem, compile timestamp, imports (with suspicious API highlighting), exports, TLS callbacks, sections
• Archive inspection — lists every file inside ZIP, RAR, 7-Zip, and TAR/GZ/BZ2/XZ archives, flagging executables, double extensions, magic-byte mismatches, encrypted entries, and zip-bomb expansion ratios
• Risk score — 0–100 composite score derived from all of the above, with a breakdown of contributing factors

Nothing is executed. All analysis is static.

---

Running locally (no Docker)

Requirements: Python 3.11+, pip

pip install -r requirements.txt
python main.py

Open http://localhost:8000 in your browser.

Note: RAR support requires unrar on your PATH. On Windows install WinRAR or unrar via Chocolatey (choco install unrar). On Linux: sudo apt install unrar-free.

---

Running with Docker sandboxing (recommended)

When Docker sandboxing is enabled every uploaded file is analysed inside a fresh throwaway container that is destroyed the moment analysis finishes. This means:

• Malicious payloads, exploits, or memory-corruption attempts are contained inside the container
• The container has no network access, a read-only filesystem, no Linux capabilities, and a hard memory cap
• Your host OS is never touched by the analysed file

Setup

1. Build the worker image (one-time, or after code changes):

docker build -t filechecker-worker -f Dockerfile.worker .

2. Run the web app on your host:

pip install fastapi uvicorn python-multipart   # host only needs these three
python main.py

Open http://localhost:8000. Each upload will now spin up and tear down a filechecker-worker container automatically.

Check that everything is wired up:

GET http://localhost:8000/health

Returns {"status": "ok"} when Docker is reachable and the worker image exists.

What the sandbox looks like

Every docker run that handles an upload includes:

Flag	Effect
--rm	Container deleted immediately after analysis
--network none	No inbound or outbound network access
--read-only	Root filesystem is immutable
--tmpfs /tmp:size=128m,noexec	Writable scratch space; extracted files cannot be executed
--cap-drop ALL	All Linux capabilities removed
--security-opt no-new-privileges	Process cannot gain new privileges
--memory 512m --memory-swap 512m	Hard 512 MB RAM cap, no swap
--cpus 1	Capped at one logical CPU

The file never touches disk on the host — it is piped to the container via stdin and the JSON result is read back from stdout.

Optional: run everything in Docker

If you prefer not to install Python on the host at all you can run the web app inside a container too. It mounts the Docker socket so it can still spawn worker containers.

docker compose build
docker compose up web

On Windows with Docker Desktop the socket path is the same (/var/run/docker.sock) when using the WSL 2 backend.

---

Configuration

Both options below can be set as environment variables before starting main.py or in docker-compose.yml:

Variable	Default	Description
FILECHECKER_WORKER_IMAGE	filechecker-worker	Name of the worker image to spawn
FILECHECKER_WORKER_TIMEOUT	30	Seconds before an analysis is killed

---

File size limit

50 MB per upload. Configurable via MAX_FILE_SIZE in main.py.

---

Project layout

filechecker/
├── analyzer.py            # all analysis logic (shared by host and worker)
├── worker.py              # worker entry point: stdin → analyze → stdout
├── main.py                # FastAPI web app; spawns Docker containers per upload
├── static/index.html      # single-page UI
├── Dockerfile.worker      # sandbox image (pefile, py7zr, rarfile, unrar)
├── Dockerfile             # web app image (fastapi + docker CLI only)
├── docker-compose.yml     # builds both images; runs the web service
├── requirements.txt       # all deps for running locally without Docker
└── requirements_worker.txt  # deps baked into the worker image