Run the Collector - VersionGopher™

Back to scanning guides

Default behavior: normal scans extract versions and include a SHA-256 file_hash for emitted records up to 1 GB. PE, ELF, Mach-O, and plist parsers hash bytes they already read after a row is worth emitting; scripts, archive/container records, private-key exposure records, and crypto-wallet artifact records use a streaming fallback. Use --no-file-hash only when scan speed or tiny embedded storage matters more than hash lookup, and use --hash-large-files when a forensic run needs hashes for very large archives or images. The web search box accepts exact scanned-file hashes and collector-binary hashes shown in detail panels.

Signed collectors and signature evidence: production collectors are synchronized to the current release, and the Windows collector is Authenticode-signed by AstroSec LLC. Scans can preserve PE Authenticode, Mach-O code-signature, and Linux kernel-module signature evidence, including signed-content integrity and certificate endpoint URLs where available. Collector evidence is not the same as platform trust, revocation, timestamp, catalog, or kernel-keyring verification.

Version evidence: current collectors are intentionally skeptical of generic strings inside binaries. For ELF libraries, dependency requirement text such as OpenSSL >= 1.0.2 should not become the product version when stronger local product evidence exists. If a detail card says version evidence is weak, use package-manager context or a focused rescan before treating the CVE match as confirmed.

Deep metadata probes: for Miasma and other supply-chain incident-response scans, add -m so the JSONL includes bounded, read-only metadata clues such as build paths, compiler hints, embedded URLs, library names, and reverse-DNS identifiers. These clues are stored as evidence for triage and software lineage, not as direct vulnerability findings. The main dashboard search stays fast by searching common inventory fields; use Deep Search when looking for metadata-probe strings such as org.freedesktop.DBus.

Drift-ready scans: if you want the analytics dashboard to treat Software Genomics as a drift indicator, create a dedicated organization group such as Drift, Monthly Baseline, or Fleet Drift. Use that group only for repeatable scans of the same enterprise scope, such as the same endpoints, golden images, or controlled fleet slices, and keep the collector options, privileges, paths, and cadence as deterministic as possible. Random forensic images, mixed case folders, one-off evidence bundles, and unrelated downloads can share tools and hashes, but they should be read as software similarity instead of operational drift. See Groups, Similarity, And Drift for use-case guidance.

Scheduled inventory: VersionGopher does not need a resident agent for many IT workflows. Install the collector in a stable path, schedule it with the operating system's normal scheduler, and upload or import the timestamped JSONL files on your cadence. This is especially useful for developer workstations, build runners, monthly baselines, and repeatable fleet-drift groups.

CVE and package advisory cadence: collector scans do not update reference databases. Hosted production runs the background CVE matcher about every minute to process newly imported or stale scans. Scheduled feed jobs refresh the current NVD/CVE catalog and the PG18 durable PostgreSQL OSV/package-advisory catalog. Manual on-demand CVE and package catalog updates are platform-admin actions, and everyone can see the shared catalog status cards on the dashboard. Package Risk uses package evidence, stored per-scan OSV matches, imported OSV Scanner JSON, bounded platform-admin OSV checks, and the PG18 package catalog when it has been populated. Package evidence can exist even when the OSV catalog status is empty.

Import and matching performance: hosted PG18 imports now batch normal scan-row writes for large JSONL uploads, but import speed still depends on scan shape, database state, and whether protected encrypted-artifact dual-write is enabled. After upload, CVE filtering may briefly show a queued, running, or refresh-needed state while materialized CVE results are rebuilt with the current matcher generation. That is expected; the dashboard uses the readiness state instead of silently falling back to stale broad matches.

Download the matching collector

Choose the collector that matches the target CPU and operating system from the dashboard's Collectors button. Verify the displayed SHA-256 before moving it into a case folder or removable media kit.

Run a focused directory scan

Focused scans finish faster, avoid permission noise, and are usually best for first-pass triage.

Linux, macOS, ARM, OpenWrt/Entware ARMv7, MIPS, or PowerPC shell

chmod +x ./version_gopher
host=$(hostname 2>/dev/null || echo host); out="versiongopher-${host}-linux-x64-directory-usr-schema-v3-$(date +%Y%m%d-%H%M%S).jsonl"; ./version_gopher -d /usr -J > "$out"

Windows PowerShell

$prefix = "versiongopher-${env:COMPUTERNAME}-windows-x64-directory-program-files-schema-v3-$(Get-Date -Format yyyyMMdd-HHmmss)"; .\version_gopher-windows-x64.exe -d "C:\Program Files" -o $prefix -j

Run a full system scan when you need coverage

Use full scans for beta feedback, incident response, system baselines, and unknown software inventory. For Miasma response, keep -m in the command so metadata-probe evidence is imported with the scan. Run as Administrator or root when possible.

Linux, macOS, ARM, OpenWrt/Entware ARMv7, MIPS, or PowerPC shell

host=$(hostname 2>/dev/null || echo host); out="versiongopher-${host}-linux-x64-system-schema-v3-$(date +%Y%m%d-%H%M%S).jsonl"; sudo ./version_gopher -s -m -J > "$out"

Windows PowerShell as Administrator

$prefix = "versiongopher-${env:COMPUTERNAME}-windows-x64-system-schema-v3-$(Get-Date -Format yyyyMMdd-HHmmss)"; .\version_gopher-windows-x64.exe -s -m -o $prefix -j

Full scans without elevated privileges are supported, but protected files and directories will be skipped. JSONL output may look quiet at first while the collector moves past permission-denied paths.

Use opt-out hashing only for constrained scans

Hashes are valuable for threat-intel lookups and deduplication. VersionGopher avoids hashing files that do not produce records, avoids a second file read for binary and plist parsers where possible, and skips emitted files above 1 GB unless requested. Hashing still costs CPU on small ARM, OpenWrt/Entware ARMv7, MIPS, and PowerPC targets, so skip hashes only when the target is very slow, the filesystem is huge, or the goal is a quick version-only preview.

Version-only scan, no file hashes

host=$(hostname 2>/dev/null || echo host); out="versiongopher-${host}-linux-x64-directory-firmware-schema-v3-$(date +%Y%m%d-%H%M%S).jsonl"; ./version_gopher -d /firmware -J --no-file-hash > "$out"

Forensic scan, include hashes for large archives/images

host=$(hostname 2>/dev/null || echo host); out="versiongopher-${host}-linux-x64-directory-evidence-schema-v3-$(date +%Y%m%d-%H%M%S).jsonl"; ./version_gopher -d /evidence -J --hash-large-files > "$out"

Import the results

Open the dashboard, select Import, then upload the generated versiongopher-*.jsonl. Current collectors preserve rich PE, ELF, Mach-O, plist, archive, private-key exposure, crypto-wallet artifact, AI prompt artifact, and package/repository artifact evidence in JSONL records. Keep the raw scan file with case notes if you need reproducibility. For large uploads, wait for both import completion and the CVE readiness indicator before treating CVE totals as final.

Schedule repeat scans without installing an agent

For normal IT operations, schedule the collector as a recurring command with cron on Linux or Windows Task Scheduler on Windows. Keep output in a stable spool directory, use UTC or local timestamps consistently, and import the newest files into the same organization group. Use one task per scan scope when you need separate baseline groups, such as developer endpoints, build servers, and golden images.

Use the same collector binary, scan path, flags, privilege level, and schedule for drift-ready groups.
Do not overwrite output files. Let the timestamped file names preserve provenance outside the dashboard.
Package lockfiles, installed package metadata, and repository configuration are recorded as lightweight supply-chain evidence. Exact npm/PyPI identity peeks are bounded to small metadata windows so OSV matching can use real package/version evidence without running package managers. The dashboard separates Package Advisories from OSV MAL-* Malicious Packages so ordinary vulnerable-package matches do not look like confirmed supply-chain attack packages.
AI assistant prompt files such as .cursorrules, CLAUDE.md, and .cursor/rules are recorded as metadata-only artifacts. Hidden Unicode and prompt-risk markers are summarized, but prompt bodies and hidden payload text are not stored.
Crypto-wallet artifacts are detected from high-signal path/name evidence only. Wallet databases, browser-extension vault contents, seed phrases, and key material are not stored.
Protect the output directory because JSONL can include filenames, paths, host metadata, package metadata, private-key exposure indicators, crypto-wallet artifact indicators, and AI prompt-risk indicators.

Linux cron: daily system inventory

sudo install -m 0755 ./version_gopher-linux-x64 /opt/versiongopher/version_gopher
sudo install -d -m 0750 /var/lib/versiongopher/scans
sudo tee /opt/versiongopher/run-versiongopher.sh >/dev/null <<'SH'
#!/bin/sh
set -eu
host=$(hostname 2>/dev/null || echo host)
stamp=$(date -u +%Y%m%d-%H%M%S)
out="/var/lib/versiongopher/scans/versiongopher-${host}-linux-x64-system-schema-v3-${stamp}.jsonl"
/opt/versiongopher/version_gopher -s -J > "$out" 2>>/var/log/versiongopher-collector.log
SH
sudo chmod 0755 /opt/versiongopher/run-versiongopher.sh
sudo crontab -e

Add this cron line for a 02:17 daily scan

17 2 * * * /opt/versiongopher/run-versiongopher.sh

Windows PowerShell: Task Scheduler daily inventory

New-Item -ItemType Directory -Force "C:\ProgramData\VersionGopher\scans" | Out-Null
Copy-Item ".\version_gopher-windows-x64.exe" "C:\ProgramData\VersionGopher\version_gopher-windows-x64.exe" -Force
$script = "C:\ProgramData\VersionGopher\run-versiongopher.ps1"
@'
$ErrorActionPreference = "Stop"
$outDir = "C:\ProgramData\VersionGopher\scans"
New-Item -ItemType Directory -Force $outDir | Out-Null
$stamp = Get-Date -Format yyyyMMdd-HHmmss
$prefix = Join-Path $outDir "versiongopher-$env:COMPUTERNAME-windows-x64-system-schema-v3-$stamp"
& "C:\ProgramData\VersionGopher\version_gopher-windows-x64.exe" -s -o $prefix -j 2>> "C:\ProgramData\VersionGopher\collector.log"
'@ | Set-Content -Path $script -Encoding UTF8
$action = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-NoProfile -ExecutionPolicy Bypass -File `"$script`""
$trigger = New-ScheduledTaskTrigger -Daily -At 2:17am
Register-ScheduledTask -TaskName "VersionGopher Daily Inventory" -Action $action -Trigger $trigger -User "SYSTEM" -RunLevel Highest -Description "Daily VersionGopher software inventory scan"

Windows at is legacy. Prefer Task Scheduler through PowerShell or Group Policy. In Windows PowerShell 5, native > redirection can write UTF-16 output; use -o PREFIX -j so the collector writes UTF-8 JSONL itself. In managed environments, deploy the binary, script, and scheduled task with your normal endpoint management tool, then import the generated JSONL files into the matching VersionGopher organization group.

Option	Use
`-s`	Scan the whole system. Windows scans all drives; Linux, macOS, ARM, OpenWrt/Entware ARMv7, MIPS, and PowerPC scan from `/`.
`-d PATH`	Recursively scan one directory or mounted volume.
`-f FILE`	Scan one file.
`-J`	Stream newline-delimited JSONL to stdout for dashboard upload. Use this on POSIX shells or other environments where stdout redirection preserves UTF-8 bytes.
`-m`, `--metadata-probe`	Opt in to bounded metadata-only probe evidence such as classified strings. Use this for Miasma and other supply-chain incident-response scans. Default scans keep this generic probe disabled.
`-j`	Write a live `PREFIX.jsonl` sidecar in addition to text output. This is the preferred Windows PowerShell path because the collector writes UTF-8 JSONL itself.
`-o PREFIX`	Use `PREFIX.txt`, `PREFIX.log`, and optional `PREFIX.jsonl`.
`-N`, `--no-file-hash`	Skip default SHA-256 file hash enrichment.
`-B BYTES`, `--max-file-hash-bytes BYTES`	Skip default file hashes for emitted records larger than the limit. Supports `K`, `M`, and `G` suffixes; default is `1G`.
`-L`, `--hash-large-files`	Hash emitted files regardless of size for forensic runs where large archive/image hashes are required.
`-x MODE`	Legacy hash-only mode for `md5`, `sha1`, or `sha256`.

Run the VersionGopher™ Collector

Download the matching collector

Run a focused directory scan

Run a full system scan when you need coverage

Use opt-out hashing only for constrained scans

Import the results

Schedule repeat scans without installing an agent