Malware Scope

Malware Scope is a local, containerized interface for browsing malware samples and running bounded static-analysis tools (strings, Detect It Easy and ndisasm). It is intended for authorized research and education.

Security model

• The web service listens on 127.0.0.1:8080 by default.
• The sample collection is mounted read-only.
• Every requested path is resolved canonically and must remain below /var/www/malware; traversal and escaping symlinks are rejected.
• Analysis commands do not use a shell and are limited by file size, execution time, output size, CPU, memory and process count.
• The application filesystem is read-only and the container has no external network access at runtime.
• Optional HTTP Basic authentication can be enabled through APP_USERNAME and APP_PASSWORD.

This is defense in depth, not a malware sandbox. The application performs static inspection only. Do not expose it directly to the Internet and never execute samples inside this container.

Quick start

Requirements: Docker and Docker Compose.

mkdir -p malware
# Copy authorized samples into malware/
bash start.sh

Open http://127.0.0.1:8080/. The malware/ directory is deliberately excluded from Git.

To require credentials, copy .env.example to .env, set both values, and restart the stack. Basic authentication is suitable only for local or TLS-protected access.

Configuration

Variable	Default	Purpose
APP_USERNAME / APP_PASSWORD	empty	Enable authentication when both are set
ANALYSIS_TIMEOUT_SECONDS	15	Maximum duration of one analysis
ANALYSIS_MAX_OUTPUT_BYTES	2000000	Maximum combined stdout/stderr
ANALYSIS_MAX_FILE_BYTES	100000000	Maximum file size accepted by analysis tools
MALWARE_BASE_PATH	/var/www/malware	Canonical sample root (mainly useful for tests)

Development and tests

PHP 8.2 or newer is required outside Docker.

composer install
composer test

The browser UI is self-contained: it does not fetch Tailwind, JavaScript libraries or fonts from a CDN. File descriptions use PHP's fileinfo extension rather than starting one file process per row.

Architecture

• src/index.php: routing, authentication and security headers.
• src/controllers/MalwareController.php: listing, pagination, downloads and analysis orchestration.
• src/services/PathGuard.php: canonical path confinement.
• src/services/AnalysisRunner.php: bounded process execution.
• src/models/Malware.php: directory enumeration and metadata.
• src/views/explorer.php: server-rendered UI and analysis modal.

Operational notes

start.sh builds and starts only this Compose project. It does not prune global Docker images, volumes or networks. Stop the service with docker compose down; follow logs with docker compose logs -f.

The Detect It Easy package is pinned in the Dockerfile because upstream packages are distribution-specific. Review and test that pin deliberately before upgrading the PHP/Debian base image.

License

MIT. See LICENSE.