---
agent: env-validator
status: COMPLETE
timestamp: 2026-06-26T12:00:00Z
findings_count: 3
errors: []
---

# Env Validation — BigBrother Public Release

## FAIL

1. **[operator_setup.sh:707-712] Webhook and Matrix tokens written to `/root/bb-config.env` on SD card**
   - PRIORITY: P1 (Secret in deployed artifact)
   - Issue: Matrix tokens (`BB_ALERTER_MATRIX_TOKEN`), webhook URLs (`BB_ALERTER_WEBHOOK`), and Tailscale auth keys are written to `/root/bb-config.env` on the flashed SD card in plaintext
   - Risk: Anyone with physical or filesystem access to the device can extract active alerter credentials
   - Fix: Store these secrets in Infisical on the target device only. At deployment time, the first-boot script should retrieve them from Infisical CLI rather than from bb-config.env

2. **[setup.sh:266-271] .env file created with plaintext Matrix credentials at `/opt/net_alerter/.env`**
   - PRIORITY: P1 (Secret in service environment file)
   - Issue: Matrix tokens are written to `/opt/net_alerter/.env` during service setup. This file persists on the device and can be read by any user or process with filesystem access
   - Risk: Compromised device filesystem leaks all alerter credentials
   - Fix: Credentials should be retrieved from Infisical via `creds` CLI at service startup time, not cached to .env

## WARN

3. **[net_alerter/test_ble_alerter.py:113,130,149,166] Test file uses placeholder token `"syt_test"`**
   - PRIORITY: P3 (Harmless test data)
   - Detail: The test file correctly uses a placeholder token that is not a valid Matrix token. This is acceptable for unit tests as it does not represent a real credential
   - Status: ACCEPTABLE — test tokens are explicitly non-secret and cannot authenticate to real servers

## PASS

- Secrets in source code: CLEAN — No GitHub tokens, AWS keys, Stripe keys, or bearer tokens found in .py, .sh, .yml, .yaml, or .json files
- Git history (recent commits): CLEAN — Only one commit in repo (initial public release), no secrets leaked in history
- `BB_CREDS_BIN` environment variable pattern: CORRECTLY IMPLEMENTED
  - `/utils/credential_encryption.py:14-68` implements proper Infisical CLI integration
  - Encryption key (`CREDENTIAL_ENCRYPTION_KEY`) is retrieved at runtime via `creds get`
  - Key is cached in module memory only, not written to disk
  - Fallback to plaintext with warning if key retrieval fails
  - Credential payload encryption/decryption follows secure design pattern
- SSH key management: GOOD
  - Private keys generated at deployment time, stored in Infisical immediately
  - Local copy saved to operator's `~/.ssh/` with restrictive permissions (600)
  - No hardcoded SSH keys in source code

## Recommendations

### High Priority (Deploy Blocker)
1. **Move alerter secrets from bb-config.env to Infisical**
   - operator_setup.sh should prompt for secrets but NOT write them to the SD card
   - Instead, configure them in Infisical under a `bigbrother/{device_id}/` namespace
   - First-boot script: retrieve via `creds get BB_ALERTER_MATRIX_TOKEN bigbrother/{device_id}` and pass directly to service
   - Rationale: Eliminates plaintext secret artifact on physical media

2. **Refactor setup.sh to retrieve credentials from Infisical, not from bb-config.env**
   - Current: `cat > /opt/net_alerter/.env <<ALERTENV` with plaintext token
   - Better: Pass credentials via systemd EnvironmentFile + start-time Infisical retrieval
   - Pattern (for reference only):
     ```bash
     # setup.sh
     cat > /etc/default/net-alerter << 'EOF'
     BB_CREDS_BIN=/usr/local/bin/creds
     BB_DEVICE_NAMESPACE=bigbrother/${DEVICE_ID}
     EOF
     
     # net_alerter.service
     [Service]
     EnvironmentFile=/etc/default/net-alerter
     ExecStart=/opt/net_alerter/net_alerter.py  # retrieves from Infisical via BB_CREDS_BIN
     ```

3. **Do NOT commit .env files to version control**
   - Verify `.gitignore` contains `*.env`, `bb-config.env`, `/opt/*/env`
   - CI/CD should have no step that writes secrets to disk

### Medium Priority
- Document the Infisical setup required for BigBrother deployments (which folders, which keys)
- Add a validation script that checks Infisical has all required keys before first boot

### Summary
The codebase demonstrates strong cryptographic and credential management patterns (credential_encryption.py is well-designed), but the deployment flow undermines this by writing alerter secrets to persistent plaintext .env files. The fix is to retrieve these secrets from Infisical at runtime instead of storing them on the device.

