Lumen LabsMIT · 0.1.0

Lumen community tools

Two small, inspectable Linux tools, generalized from practical storage and migration work. Version 0.1.0, prepared 7 November 2026.

Released under the MIT License. Copyright (c) 2026 Valentyn Shapovalov and SREIF LLC. See LICENSE for the full permission notice and warranty disclaimer. COPYRIGHT_NOTICE.md contains a separate owner-provided notice; the MIT License text is unchanged.

What is included

Tool · What it does · What it never does

disk_inventory.py · Counts regular files and their logical/allocated size in an explicitly chosen directory · Reads file contents, deletes files, inspects processes, changes packages, or accesses the network

file_manifest.py · Makes and checks SHA-256 manifests for an explicit list of files · Transfers files, authenticates a remote host, creates keys, writes into the inspected directory, or performs a restore

safe_files.py · Shared path and file-opening checks · Grants permissions or follows symlinks

Keep the three files together. They use the Python standard library only; no pip packages or installer are needed. They are designed for Linux with Python 3.10 or newer; file verification requires a normal mounted /proc filesystem. They are not a Windows, macOS, NAS, Btrfs snapshot or backup product.

Run with an ordinary account that can read the intended directory. Do not run as root just to eliminate permission warnings. A partial report is useful and is clearly marked. Review a program before giving it more access.

1. Find where storage is going

python3 -B disk_inventory.py /srv/example-site

The default report contains totals and counters, not filenames or the root path. It reads directory entries and metadata, not file contents. To see the ten largest regular files by logical size:

python3 -B disk_inventory.py /srv/example-site --show-paths --top 10

That opt-in output contains relative filenames, which may be sensitive. Inspect and redact it before posting it in an issue, chat or support ticket.

The scan defaults to 100,000 entries, depth 64 and 30 seconds. Permission errors and exhausted limits make complete false and exit with code 1. Symlinks, special files and boundaries to another filesystem are skipped and counted. The complete field means the eligible scope was visited, not that excluded mounts or links were inspected.

Hard-linked files count once, but copy-on-write/shared extents do not. allocated_file_bytes uses Linux st_blocks and excludes directory metadata, filesystem metadata and reserved space; do not expect it to equal df. Files and directories may change during a scan. This is an approximate live inventory, not an atomic snapshot or a deletion recommendation.

2. Check a copied set of files

Create a manifest from the source with explicitly selected relative paths:

python3 -B file_manifest.py make /srv/example-export index.html assets/site.css > manifest.json

Keep manifest.json outside the inspected source directory. Shell redirection writes the output file; the tool itself only writes JSON to standard output. Never redirect output onto one of the files you are checking.

After transferring those files by your normal authorized method, check the destination against the unchanged manifest:

python3 -B file_manifest.py check /srv/example-copy < manifest.json

The tool refuses absolute paths, dot/parent components, symlink components, special files and other-filesystem files. It pins a Linux file descriptor and checks its type before opening the regular file for reading, rather than opening device nodes or FIFOs for I/O. It compares file metadata before and after reading to catch ordinary concurrent changes. It cannot make a live filesystem atomic or defend against a privileged attacker changing the operating system. Do not use untrusted live trees or device directories as the root.

Limits: 1,000 files, 1 GiB per file, 8 GiB of bytes read (including reads for files that later fail verification), a 1 MiB serialized manifest and a 120-second cooperative time budget. The writer refuses output larger than its reader accepts. If your data exceeds these conservative limits, split it into explicit batches or use a maintained backup/checksum tool designed for larger sets. The time budget is checked between operations and is not a hard timeout on blocked kernel/filesystem calls.

A matching hash is not proof of authenticity or a complete backup. Obtain the manifest through a trusted channel and keep it unchanged. A hostile manifest chooses which files under the explicit root are read. The manifest contains relative filenames, sizes and hashes; do not publish it if those reveal private information. A successful check covers only the listed file bytes, not permissions, ownership, databases, application compatibility or successful restore.

Reading can update access times depending on mount options. Neither tool is intended for forensic preservation.

Exit status

• 0: inventory completed in its eligible scope, or all explicitly listed hashes match.

• 1: partial inventory or verification mismatch/read error.

• 2: invalid input, unavailable root, unsupported platform or a refused operation before a complete result.

Do not parse only the exit code; inspect complete, counters and individual results.

Test locally

python3 -B -m unittest discover -s tests -v

Tests use temporary synthetic data. They cover symlinks, FIFO handling, hard links, bounds, unusual names, invalid JSON, duplicate keys, changed/missing files, CLI status codes and unchanged target contents. No test contacts a server or uses production files. See VALIDATION.md for the actual tested environment and limits.

Why this limited first release?

The original operational work involved machine-specific paths, credentials, service ownership and private state. Publishing those scripts unchanged would be unsafe and not useful on another server. These tools are new generalized implementations of the useful read-only techniques. They contain no operational hostnames, addresses, keys, mailbox data or command-and-control endpoints.

Automatic cleanup, privileged brokers, credential migration and service cutover are deliberately outside this package. They need a separate threat model and deployment-specific review, not a generic “run this as root” script.

Credits and contribution plans

Created by Lumen SI, with direction and review by Valentyn Shapovalov. Published by SREIF LLC. No third-party source code is bundled; Python remains under its own license. A GitHub repository and contribution process are planned but do not exist as part of this release. Do not submit private logs, credentials or personal files in public reports.