Scanfile

Scanfile is a multi-engine file analysis web application. Users upload files, which are scanned in parallel by multiple analysis engines. Results are aggregated into a risk score and displayed through a web interface.

Features

• Multi-engine scanning -- Files are analyzed by several engines simultaneously:
  • Basic properties (file type, hashes via libmagic)
  • Detect-It-Easy (file type detection, compiler/linker identification)
  • YARA rule matching (Yara-Forge full rule collection)
  • CAPA capability detection (MITRE ATT&CK, MBC)
  • Microsoft Office analysis (OLE, VBA macros, olevba)
  • ICAP-based external scanners (ClamAV antivirus)
  • Email analysis (header extraction, attachment scanning)
  • Archive content listing and extraction (ZIP, 7z, tar, RAR and more)
  • CAPEv2 sandbox integration (optional, submits PE/ELF files)
• Aggregate risk scoring -- Scanner results are combined into a 0-100 score with configurable weights
• Download controls -- Operators can toggle download permission per file; automatic download allowed below configurable score threshold
• User management -- Three roles: user, operator, administrator
• OAuth SSO -- Configurable OAuth providers with group-to-role mapping
• ICAP server -- Built-in ICAP server for proxy integration, plus ICAP client to forward files to external scanners
• Download container -- Optional browser-in-a-container (linuxserver/firefox) for isolated file downloads
• REST API -- Full API with Swagger documentation at /swagger/
• Web UI -- Vue 3 SPA with dark mode and mobile-responsive layout

Architecture

                    +-----------+
                    | PostgreSQL|
                    +-----+-----+
                          |
+-------------------+-----+----+-------------------+
| Go Server   (port 8080)     |                   |
| - REST API                   |                   |
| - Worker pool (async scans)  |                   |
| - User sessions + auth       |                   |
| - Scoring engine             |                   |
+----+----+----+----+----+----+                   |
     |    |    |    |    |                         |
+----+ +--+-+ +--+-+ +--+-+ +----+ +----+ +-------+  |
|File| |OLE| |CAPA| |YARA| |Clam| |Mail| |Archive|  |
|Scan| |Scan| |Scan| |Scan| |AV  | |Scan| |Scan   |  |
+----+ +----+ +----+ +----+ +----+ +----+ +-------+

Quick Start

Prerequisites

• Go 1.26+
• PostgreSQL 17+
• Python 3.13+
• Node.js 22+

Setup

make deps          # Install Go, Python, and Node dependencies

Copy and edit the configuration:

cp config.example.toml config.toml
cp scoring.example.toml scoring.toml
# Edit config.toml with your database credentials

Create the database and apply migrations:

createdb scanfile
make migrate-up

Running

Start the Go server (with auth bypass for development):

make run

Or start all services (Go server + scanner microservices):

make dev

The web UI is at http://localhost:3000 (Vite dev server proxies API calls to :8080).

Production Build

make build          # Builds Vue app and compiles Go server
./main.out          # Run the compiled binary

Configuration

Configuration uses TOML files with environment variable overrides (prefix SF_).

Key config sections

Section	Description
[web]	Server host, port, TLS, upload limits, download controls
[db]	PostgreSQL connection
[auth]	Authentication settings, OAuth providers
[processing]	Scanner URLs, worker pool size, ICAP servers
[log]	Log format and level

See config.example.toml for all options.

Scoring

The aggregate risk score (0-100) is configurable via scoring.toml:

• YARA -- per-rule score, max contribution
• CAPA -- per-capability score, per-tactic score, per-MBC score, specific capability overrides
• ICAP -- score when infection detected
• MSOffice -- fine-grained scores for verdict, VBA stomping, auto-exec macros, suspicious indicators, IOCs, encryption
• CAPEv2 -- malscore and detection counts contribute to the aggregate score

See scoring.example.toml for defaults.

API

Full API documentation is available at /swagger/ when the server is running.

Key endpoints

Method	Endpoint	Description
POST	/api/v0/submit	Upload a file
POST	/api/v0/submit-url	Submit a file from a URL
GET	/api/v0/files	List files
GET	/api/v0/files/{uuid}	Get file details
PATCH	/api/v0/files/{uuid}	Update file metadata (operator+)
DELETE	/api/v0/files/{uuid}	Delete file
GET	/api/v0/files/{uuid}/download	Download file
GET	/api/v0/files/{uuid}/properties	Hashes and libmagic
GET	/api/v0/files/{uuid}/diec	Detect-It-Easy results
GET	/api/v0/files/{uuid}/capa	CAPA analysis
GET	/api/v0/files/{uuid}/msoffice	Office document analysis
GET	/api/v0/files/{uuid}/yara	YARA match results
GET	/api/v0/files/{uuid}/icap	ICAP scan results
GET	/api/v0/files/{uuid}/cape	CAPEv2 sandbox results
GET	/api/v0/files/{uuid}/pdf	PDF structural analysis
GET	/api/v0/files/{uuid}/mail	Email analysis results
GET	/api/v0/files/{uuid}/archive	Archive contents listing
POST	/api/v0/files/{uuid}/archive/submit	Extract and submit archive entry
POST	/api/v0/files/{uuid}/rescan	Re-run all scanners
POST	/api/v0/files/{uuid}/rescan/{scanner}	Re-run specific scanner
POST	/api/v0/register	Register user
POST	/api/v0/login	Login
POST	/api/v0/logout	Logout
GET	/api/v0/me	Current user info
PATCH	/api/v0/me	Update profile
GET	/api/v0/jobs	List processing jobs
GET	/api/v0/jobs/{id}	Get job details
POST	/api/v0/jobs/{id}/retry	Retry failed job
GET	/api/v0/admin/users	List users (admin)
PATCH	/api/v0/admin/users/{id}	Update user (admin)
DELETE	/api/v0/admin/users/{id}	Delete user (admin)
GET	/api/v0/container/status	Container feature status
POST	/api/v0/container	Start download container
GET	/api/v0/container	List download containers
DELETE	/api/v0/container/{name}	Stop download container
GET	/api/v0/container/{name}/proxy/	Proxy to container web UI
GET	/api/v0/container/{name}/downloads	List container downloads
POST	/api/v0/container/{name}/downloads/{filename}	Submit container file
GET	/api/v0/oauth/providers	List OAuth providers
GET	/api/v0/oauth/{provider}	Initiate OAuth login
GET	/api/v0/oauth/{provider}/callback	OAuth callback

Scanner Microservices

Each scanner is an independent microservice:

Scanner	Port	Language	Technology
File (basic)	5003	Python	aiohttp, python-magic, die-python
OLE / MSOffice	5000	Python	aiohttp, oletools
CAPA	5001	Python	aiohttp, flare-capa
YARA	5002	Python	aiohttp, yara-python
ClamAV (ICAP)	5004	Python	aiohttp, clamd
Mail	5005	Python	aiohttp, email
Archive	5006	Python	aiohttp, py7zr, rarfile
PDF	5007	Python	aiohttp, oletools (pdfid)

Docker

docker compose up -d

This starts all services: Go server, PostgreSQL, and all scanner microservices.

Development

make dev            # Start all services with live reload
make dev-host       # Same, but bind to 0.0.0.0 for LAN access
make vue-dev        # Vue dev server only
make watch          # Go server with air live reload

Testing

make test           # Unit tests (Go, Rust, Python)
make e2e-test       # End-to-end API tests via Hurl

Database Migrations

make migrate-up     # Apply pending migrations
make migrate-down   # Roll back last migration

API Documentation

make swagger-gen    # Regenerate Swagger docs from annotations

License

GPLv3 -- see LICENSE.