VoidCrawler
Project History & Documentation

Philosophy & Use

VoidCrawler is purpose-built as a reconnaissance tool, not a full-featured file manager. It strips noise, surfaces operational files, and presents a minimal, militarized UI ideal for server operations, forensic mapping, and admin dashboards.

• Recursively map directories with natural sort order.
• Collapsible folder UI for focused navigation.
• Top-level "Direct Downloads" console for quick retrieval.
• Filter out common web-app clutter (.htaccess, .php, .html, .db, .png, etc.).

Key Capabilities

How it works — core idea

VoidCrawler enumerates directory contents with a recursive function, separates directories from allowed files, sorts results using natural ordering, and renders two primary UI blocks:

1. Directories — left column collapsible tree
2. Direct Downloads — top-level file console for immediate download

PHP-era core recursive logic (excerpt)

function myScanDir($dir, $level, $rootLen)
{
    global $pathLen;

    if ($handle = opendir($dir)) {
        $allFiles = [];

        while (false !== ($entry = readdir($handle))) {
            if ($entry != "." && $entry != ".." && $entry != ".htaccess") {
                if (is_dir($dir . "/" . $entry)) {
                    $allFiles[] = "D: " . $dir . "/" . $entry;
                } else if (!in_array(strtolower(pathinfo($entry, PATHINFO_EXTENSION)), ['php', 'html', 'db', 'png'])) {
                    $allFiles[] = "F: " . $dir . "/" . $entry;
                }
            }
        }

        closedir($handle);
        natsort($allFiles);

        // ...output folders and files with collapse UI...
    }
}

PHP versions (1.0 → 2.1.x)

Quick install

1. Create a folder on your server (example: /var/www/html/voidcrawler).
2. Drop the VoidCrawler PHP file (eg index.php or voidcrawler.php) into that folder.
3. Ensure the webserver user can read files: chmod -R 755 /var/www/html/voidcrawler.
4. Open in browser: https://yourdomain.com/voidcrawler/ (or visit login.php if 2.1.0 secure mode is enabled).

Note: VoidCrawler reads directories only. It performs no writes, no command execution, and makes no remote API calls.

Go versions (2.2.0+)

Starting with 2.2.0 VoidCrawler moved to Go. The application can run as a standalone server in any directory and can serve files from a different local directory when invoked accordingly.

Example usage (binary named vcu):

# scan current directory
./vcu

# scan a specific path
./vcu /home/username/Documents

Warning: scanning very large directories may consume significant CPU and memory.

CLI & drag-and-drop (2.0.1 details)

Early versions support drag-and-drop (browser FileReader + webkitdirectory) for local-only workflows (no server interaction) — ideal for offline repo previews or local inspections. PHP server required for single-file server behavior.

For full functionality in pre-2.2.0 releases, run on Apache/Nginx/IIS with PHP 7.4+ and the fileinfo extension enabled.

Important rules

• Do not expose VoidCrawler on a public route without authentication — it reveals directory structure and file names.
• Restrict access via server authentication, IP filtering, or VPN when running in production.
• If using 2.1.0 secured mode, deploy the PHP login files (auth.php, config.php, login.php, logout.php) in a protected environment.
• Prefer absolute paths to limit scan scope and reduce accidental exposure.

2.1.0 Security additions (PHP)

Version 2.1.0 introduced a secured login system (MySQL-backed authentication) and expanded hidden files/extensions to reduce accidental disclosure.

LOG OUT button and improved UI styling were added for authenticated sessions.