PacketSafari
Log in

CLI automation

Run unattended investigations with protected secrets, durable job identities, and machine-readable results.

Use --format json for one final structured result or --format ndjson for streamed events. Progress is written to stderr, so stdout can be redirected safely. Add --quiet when a scheduler should suppress human progress lines.

POSIX shell example

Inject the API key through your CI or secret manager rather than storing it in the script:

#!/usr/bin/env bash
set -euo pipefail

: "${PACKETSAFARI_BASE_URL:?Set PACKETSAFARI_BASE_URL}"
: "${PACKETSAFARI_API_KEY:?Set PACKETSAFARI_API_KEY}"

PCAP="${1:?Usage: verify-capture CAPTURE.pcap}"
OUTPUT="${2:-packetsafari-result.json}"
test -f "$PCAP"

packetsafari investigate "$PCAP" \
  --goal security \
  --workflow fast \
  --format json \
  --quiet >"$OUTPUT"

python3 -m json.tool "$OUTPUT" >/dev/null
printf 'Saved %s\n' "$OUTPUT"

Retain the job ID printed in verbose output or returned in JSON. If the observer disconnects after submission, resume that same job instead of creating another:

packetsafari investigate --job-id JOB_ID --format json --quiet >result.json

Use an explicit --idempotency-key when your scheduler may retry submission. Reuse that key only for the same capture and effective settings.

PowerShell example

param(
  [Parameter(Mandatory = $true)][string]$Pcap,
  [string]$Output = 'packetsafari-result.json'
)

if (-not $env:PACKETSAFARI_BASE_URL) { throw 'Set PACKETSAFARI_BASE_URL' }
if (-not $env:PACKETSAFARI_API_KEY) { throw 'Set PACKETSAFARI_API_KEY' }
if (-not (Test-Path -LiteralPath $Pcap)) { throw "PCAP does not exist: $Pcap" }

packetsafari investigate $Pcap --goal security --workflow fast --format json --quiet |
  Set-Content -LiteralPath $Output -Encoding utf8

Get-Content -Raw -LiteralPath $Output | ConvertFrom-Json | Out-Null
Write-Host "Saved $Output"

Operational rules

  • Give each integration its own expiring API key.
  • Keep the key out of arguments, logs, repository files, and generated reports.
  • Treat HTTP acceptance as a receipt, not a completed or verified finding.
  • Persist the capture ID, investigation ID, requested settings, and final lifecycle status.
  • Retry observation and download independently from submission.
  • Check verificationStatus, securityScan, and report maturity before automating an action.
  • Use --verify or --workflow progressive when the decision requires more than a preliminary Fast Report.

For directory watchers and resumable uploads, use ingest. For direct HTTP integration, use the Investigations API.

Optional evidence screening

Use the normal packetsafari investigate or packetsafari alert verify command with an Agent model. Where configured, the Agent can use internal Jev evidence screening with its separate decision allowance. The Agent controls questions, evidence expansion and conclusions; screening is not independent verification.

The former --driver decisions mode is retired and rejected. Saved reports remain readable. The low-level decision API remains available to authorized internal/probe integrations.