proofbench-collector 1.0.0

ProofBench — local network discovery collector. Wraps nmap + passive ARP/mDNS, signs the bundle locally, uploads to proofbench.io for cryptographic counter-signing.

Provelab Collector

Local network discovery for SMBs. Runs on your laptop, signs the evidence, uploads to proofbench.io.

What it does in 90 seconds: wraps nmap + passive ARP/mDNS observation, normalizes results into the Provelab Run/Asset/Evidence schema, signs the bundle with HMAC-SHA256 using your collector's enrollment token, and POSTs the signed bundle to proofbench.io. The cloud verifies the signature and renders your inventory + Coalition cyber-insurance renewal questionnaire.

What it does NOT do: initiate any scan from the cloud, collect default credentials, run exploits, scan anything outside the CIDR you authorize, store data anywhere except ~/.config/provelab/ locally and your authorized ProofBench cloud bucket.

Install

macOS

brew install nmap
pipx install provelab-collector       # or: pip install --user provelab-collector

Linux (Debian / Ubuntu)

sudo apt install nmap avahi-utils
pipx install provelab-collector       # or: pip install --user provelab-collector

Windows (via WSL — native Windows native binary in v1.1)

# inside WSL Ubuntu
sudo apt install nmap
pipx install provelab-collector

Verify:

provelab --version
# provelab v0.0.1

Quick start

# 1. Enroll the collector with your ProofBench account
provelab enroll

# 2. Run a scan against your network
provelab scan 192.168.1.0/24

# 3. Upload the signed bundle to proofbench.io
provelab scan 192.168.1.0/24 --upload

After --upload, your dashboard at https://proofbench.io/app updates within ~10 seconds and your Trust Center URL at proofbench.io/trust/{your-slug} shows the new posture.

Commands

provelab enroll

Pairs this collector with your ProofBench organization. Interactive — opens an enrollment URL, you sign in, paste the one-time token back into the terminal. The token is stored locally at ~/.config/provelab/config.json with 0600 permissions.

provelab enroll
provelab enroll --api https://proofbench.io   # custom API base (default is proofbench.io)

provelab scan <cidr>

Run a discovery scan against a CIDR.

provelab scan 192.168.1.0/24                     # default profile: iot_ot_cautious
provelab scan 10.0.0.0/16 --profile passive_only  # passive observations only
provelab scan 192.168.1.0/24 --profile lab_permissive  # broader probes (lab only)
provelab scan 192.168.1.0/24 --output run.json   # save locally without uploading
provelab scan 192.168.1.0/24 --upload            # sign + upload in one step

Scan profiles:

Profile	What it does	When to use
passive_only	ARP + mDNS observation only. No active probes.	Quiet networks, sensitive OT environments, or pre-flight reconnaissance.
iot_ot_cautious (default)	Bounded probes: mDNS, SSDP, ICMP, selected TCP banners on common ports (22, 80, 443, 554, etc.).	Normal office and SMB networks. Safe for production.
lab_permissive	Broader TCP banner reads across more ports. Higher network activity.	Lab environments and explicit maintenance windows. Do not use on sensitive production OT.

Each profile has a strict allowlist of nmap flags. The CLI rejects anything outside the allowlist — you can't accidentally invoke an aggressive scan.

provelab status

Show the current collector configuration.

provelab status
# provelab v0.0.1
#   api_base:     https://proofbench.io
#   collector_id: collector-acme-corp-laptop
#   enrolled:     yes
#   config_path:  /Users/you/.config/provelab/config.json

provelab verify <bundle.json>

Verify the HMAC signature on a bundle file. Useful for offline review or for a customer to independently check that an uploaded bundle wasn't tampered with.

provelab verify provelab-run-20260601-...json
# [provelab] ✓ signature valid
#   run_id:        run-20260601-...
#   collector_id:  collector-acme-corp-laptop
#   completed_at:  2026-06-01T14:23:11Z
#   bundle_sha256: a3f9b12e...

What the bundle contains

The signed JSON has this shape (full schema in fixture-network-v0.json):

{
  "version": "1.0.0",
  "run_metadata": {
    "run_id": "run-20260601-...",
    "collector_id": "collector-acme-corp-laptop",
    "profile": "iot_ot_cautious",
    "scope": "192.168.1.0/24",
    "started_at": "2026-06-01T14:22:11Z",
    "completed_at": "2026-06-01T14:23:11Z",
    "asset_count": 47,
    "evidence_count": 132,
    "needs_review_count": 3
  },
  "assets": [
    {
      "id": "asset-a3f9b12e",
      "ip": "192.168.1.1",
      "mac": "aa:bb:cc:00:00:01",
      "hostname": "edge-firewall",
      "vendor": "Fortinet",
      "os_hint": "FortiOS 7.4.2",
      "identity_class": "router-firewall",
      "identity_label": "Edge firewall",
      "confidence": 98,
      "review_state": "accepted",
      "review_reason": "normal",
      "subnet": "192.168.1.0/24",
      "open_ports": [22, 443],
      "protocols_observed": ["ssh", "https", "snmp", "arp"],
      "evidence_ids": ["ev-a3f9b12e-arp", "ev-a3f9b12e-p22", "..."],
      "coalition_questions": ["Q22_internet_facing_inventory"]
    }
  ],
  "signature": {
    "version": "v1",
    "bundle_sha256": "...",
    "hmac_sha256": "..."
  }
}

Security notes

• Your enrollment token never leaves your machine except as the HMAC key used to sign bundles. The server stores only the SHA-256 hash of the token.
• Bundles are signed locally before upload. The signature binds the bundle hash to the collector ID, run ID, site ID, profile, and authorized scope. A signature for one bundle cannot be replayed against a different one.
• The cloud cannot forge a signature. It does not have your enrollment token, only its hash. Token compromise requires direct access to your laptop or your ~/.config/provelab/ directory.
• Bundles can be verified offline. provelab verify <bundle.json> re-runs the signature check locally. Anyone with the token (you) can verify; nobody else can.

Troubleshooting

"nmap not found" — install nmap via your package manager (see Install above).

"Permission denied" on ARP scans — nmap's -PR ARP discovery requires root. Run with sudo provelab scan .... The scan profiles use SYN scans (also root-required on Linux) for similar reasons.

Scan takes too long — the iot_ot_cautious profile has a 3-minute timeout per /24. Larger CIDRs scale linearly. For /16 networks, expect ~10 minutes.

"upload rejected: rate limit exceeded" — Free Forever tier allows 1 attested run per month. Upgrade to Solo ($49/mo) for unlimited runs at https://proofbench.io/upgrade.

"signature verification failed" — your enrollment token may be invalid. Re-enroll with provelab enroll.

No mDNS observations on macOS — v0 doesn't parse macOS dns-sd output. mDNS enrichment requires avahi-browse (Linux). The scan still works; mDNS just doesn't enrich.

Source

Open source. Apache 2.0. https://github.com/proofbench/provelab-collector

Bug reports + security disclosures: [e-mail]

---

Provelab by ProofBench · provelab-collector v0.0.1 · The evidence layer for SMB cyber posture.