Back to scanning guides
Collector Field Guide

Run the VersionGopher™ Collector

Need a scan now? Download the right collector, run one command, then upload the generated JSONL. The deeper evidence notes are below for while the scan runs.

Start Here

Minimum path to first results

This is the whole required flow for a normal first scan. Use the rest of the page only when you need a different scan shape, scheduling, or evidence details.

1Download

In the dashboard, open Collectors and choose the file that matches the target operating system and CPU. Use that exact filename in the command.

2Run

Use one command below. Run as Administrator or root when possible so protected paths are included.

3Upload

Open Import > Upload File and select the generated versiongopher-*.jsonl.

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
Linux x64 shell; substitute the downloaded filename for other POSIX targets
chmod +x ./version_gopher-linux-x64
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-linux-x64 -s -m -J > "$out"
The -s flag scans the system, -m adds bounded metadata evidence for incident-response and supply-chain review, and Windows uses -o PREFIX -j so the collector writes UTF-8 JSONL itself.
More Control

Choose a different scan shape when needed

Use these patterns for focused directory scans, full system scans, constrained targets, repeat schedules, and deeper evidence handling.

1

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.
2

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
3

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.
4

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"
5

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.
Read While It Runs

Evidence and matching notes

These details explain what the collector records, when to change flags, and how the dashboard catches up after import.

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, package advisory, and malware hash 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, the PG18 durable PostgreSQL OSV/package-advisory catalog, and the offline malware hash catalog automatically. Out-of-band refreshes outside that schedule are handled by VersionGopher operations, 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 OSV checks, and the PG18 package catalog when it has been populated. Trusted malware hash matching uses collected SHA-256 values locally; scan browsing, search, and file review do not call live reputation APIs. 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.
6

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.
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.
OptionUse
-sScan the whole system. Windows scans all drives; Linux, macOS, ARM, OpenWrt/Entware ARMv7, MIPS, and PowerPC scan from /.
-d PATHRecursively scan one directory or mounted volume.
-f FILEScan one file.
-JStream 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-probeOpt 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.
-jWrite live newline-delimited JSON to PREFIX.jsonl without the legacy .txt output. This is the preferred Windows PowerShell path because the collector writes UTF-8 JSONL itself.
-o PREFIXUse PREFIX.txt, PREFIX.log, and optional PREFIX.jsonl.
-N, --no-file-hashSkip default SHA-256 file hash enrichment.
-B BYTES, --max-file-hash-bytes BYTESSkip default file hashes for emitted records larger than the limit. Supports K, M, and G suffixes; default is 1G.
-L, --hash-large-filesHash emitted files regardless of size for forensic runs where large archive/image hashes are required.
-x MODELegacy hash-only mode for md5, sha1, or sha256.