Metadata-Version: 2.4
Name: proofbench-collector
Version: 1.0.2
Summary: ProofBench — local network discovery collector. Wraps nmap + passive ARP/mDNS, signs the bundle locally, uploads to proofbench.io for cryptographic counter-signing.
Project-URL: Homepage, https://proofbench.io
Project-URL: Documentation, https://proofbench.io/about/architecture
Project-URL: Repository, https://github.com/proofbench/proofbench-collector
Project-URL: Issues, https://github.com/proofbench/proofbench-collector/issues
Author-email: "ProofBench, Inc." <rayve@eftconsultants.com>
License: Apache-2.0
Keywords: attestation,compliance,cyber-insurance,cybersecurity,mcp,network-discovery
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.9
Requires-Dist: requests<3.0,>=2.31
Provides-Extra: dev
Requires-Dist: mypy>=1.7; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Description-Content-Type: text/markdown

# 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

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

### Linux (Debian / Ubuntu)

```bash
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)

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

Verify:

```bash
provelab --version
# provelab v0.0.1
```

## Quick start

```bash
# 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.

```bash
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.

```bash
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.

```bash
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.

```bash
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`):

```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: rayve@eftconsultants.com

---

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