Skip to main content

Analyze an existing network capture

Inspect authorized PCAP/PCAPNG files locally and upload normalized TLS findings. This workflow requires scanner 0.12.0 or newer from the verified discovery bundle. It does not upload capture files or start live capture.

Prepare your machine​

Install a trusted, patched TShark 4.6 release (4.6.9 or newer in that minor series). Use an ordinary account with read access to the authorized file. Reading a saved capture does not require administrator/root privileges or a packet-capture driver.

Analyze locally​

python scanner/qr.py capture authorized.pcapng --tshark "C:/Program Files/Wireshark/tshark.exe" --source capture-review --output findings.json

On macOS/Linux, omit --tshark if the executable is on PATH, or pass its trusted absolute path. Both PCAP and PCAPNG decoding have been validated with real TShark 4.6.9 on Windows. Other operating systems still need validation.

Review and upload​

Review findings.json. It contains observed server IP addresses/ports, capture timestamps, a capture SHA-256, frame references, selected cipher/group identifiers and your source label. Capture payloads, local paths, client addresses, SNI and TLS random bytes are excluded. Choose a source label appropriate for your workspace.

Inject a separate scoped ingestor credential as QR_TOKEN and set QR_ENDPOINT to https://qscan.dev. Polling-agent credentials cannot upload standalone scans.

python scanner/qr.py upload findings.json

Find the resulting TLS assets in Cryptographic inventory and inspect their evidence. Passive-capture findings remain separate from active TLS probes. The uploader refuses reports marked incomplete. Decoder failure produces no uploadable report; exit code 2 indicates invalid or ambiguous extracted fields.

Queue or schedule analysis through an agent​

Agent-managed capture jobs require scanner 0.13.0 or newer. In Getting started, enroll an agent with the Offline capture capability and select an approved local capture directory. Download its local configuration. For Windows, a minimal configuration is:

{
  "source": "capture-agent",
  "captureRoots": ["C:/Captures/approved"],
  "tsharkExecutable": "C:/Program Files/Wireshark/tshark.exe",
  "pollSeconds": 15
}

Set QR_ENDPOINT and the enrolled agent's QR_TOKEN using the setup instructions. Check the configuration before starting:

python scanner/qr.py doctor --config agent.local.json
python scanner/qr.py agent --config agent.local.json

Doctor checks directory access and runs TShark's version command without analyzing a capture. In Scans, select Offline capture file, the capture-enabled agent, and the absolute path of an existing file, such as C:/Captures/approved/session.pcapng. The file stays on that machine. The API accepts target paths up to 300 characters. Relative paths, directories and files outside the approved roots are rejected.

Use Schedules to repeat analysis of the same configured pathname. Publish a complete replacement file atomically between runs if that pathname represents a rotating export. This does not watch directories or collect packets. Reanalyzing unchanged files can create repeated evidence.

For cloud-managed configuration, enable managedConfiguration locally, then publish capture directories from Agents > Configure agent. Cloud settings can narrow the local directory permissions; they cannot select a decoder executable or supply command-line arguments. Keep tsharkExecutable in the local configuration. Omit captureRoots when managing older agents. If cancellation or lease loss is detected at a job checkpoint, the running decoder is terminated before upload.

Interpret the evidence​

Only TLS ServerHello over TCP is analyzed. HelloRetryRequest is excluded; ambiguous multi-handshake rows are rejected. Authentication remains unknown. The reader does not validate certificates, prove handshake completion, or infer TLS 1.3 key exchange from a cipher suite. Recognized classical selected groups are labeled; other group IDs remain unknown. TLS 1.2 key exchange remains unknown in this workflow.

Repeated endpoint/protocol/cipher/group combinations are deduplicated within one file. The first retained occurrence supplies its timestamp and frame reference. An empty result means no supported ServerHello was found, not that the network is safe. analysisComplete means the selected fields were processed without errors; it does not prove a complete capture or network assessment.

Processing limits​

  • Uncompressed PCAP/PCAPNG input: at most 64 MiB.
  • Decoder runtime: 60 seconds; output: 16 MiB; unique findings: 5,000.
  • A temporary local snapshot binds provenance to the decoded bytes and is removed afterward.
  • Name resolution is disabled. The child process receives no QR credentials or SSLKEYLOGFILE and uses a temporary Wireshark configuration directory.

The decoder is trusted local software, not a sandbox. Run it with ordinary permissions and keep it patched. Do not supply decryption keys. Live capture, QUIC, SSH capture analysis, certificate-chain analysis and OS capture helpers remain in development.

For decoder errors, check the executable version and capture integrity locally; do not upload the capture or secrets to support. Split oversized captures using your approved local tooling.

References: TShark command-line options, TLS field reference.