PCAP Hunter

繁體中文版 README (Traditional Chinese)

PCAP Hunter is an AI-enhanced threat hunting workbench that bridges manual packet analysis and automated security monitoring. It empowers SOC analysts and threat hunters to rapidly ingest, analyze, and extract actionable intelligence from raw PCAP files.

By combining industry-standard network analysis tools (Zeek, Tshark, PyShark) with Large Language Models (LLMs) and OSINT APIs, PCAP Hunter automates the tedious parts of packet analysis — parsing, correlation, and enrichment — so analysts can focus on detection and response.

📖 User Manual (English) | 中文說明 (Traditional Chinese)

Table of Contents

• Visual Tour
• Key Features
• Integrations API
• Architecture
• Installation
• Quick Start
• Usage Guide
• Configuration
• Development
• Documentation
• License

Visual Tour

1. Upload — load one or many PCAPs

Drag-and-drop .pcap / .pcapng files or paste a container path. Multiple files trigger batch mode with cross-file correlation, and a dismissable getting-started panel walks first-time users through the workflow.

2. Progress — transparent 10-stage pipeline

Every stage reports live progress with a skippable per-stage control. PyShark and Zeek run in parallel, then DNS, TLS, beaconing, and carving fan out concurrently — you always know what's running and how far it has to go.

3. Dashboard — at-a-glance threat summary

The Dashboard surfaces the highest-signal findings first: overall risk level with a "Why this risk level?" explainability expander, a one-line severity color legend, alert count, beacon candidates (with progress-bar scores), YARA hits, and certificate issues. Sections that ran clean say so explicitly — no ambiguous blank panels. A global traffic map, protocol distribution, and UTC-labelled activity timeline put the capture in visual context.

4. LLM Analysis — AI-generated threat report

A nine-section narrative — Executive Summary through Recommended Actions, plus an IOC Summary table and a Risk Matrix rendered as a real Markdown table — with confidence qualifiers and MITRE ATT&CK mapping. Generate locally via LM Studio (section-by-section) or in a single full-context call via OpenAI or Anthropic. Reports in 9 languages, including Traditional Chinese (zh-TW).

5. OSINT — multi-provider IOC enrichment

Prioritized IOC table with VirusTotal, AbuseIPDB, GreyNoise, Shodan, OTX, and VT Domain signals merged into one view. Provider-status pills report each provider honestly (OK / cached / rate-limited / key-rejected / no data), an explicit WHOIS lookup selectbox + button complements row-click dialogs, and IOC search offers a show-all-results toggle. Sub-tabs expose Domains, Detail Cards, Geo Map, Infrastructure ASN clustering, Export, Devices, and Notes.

6. Raw Data — Zeek logs, flows, carved payloads, YARA matches

Every underlying data source is available: the flow table (with explicit First/Last Seen (UTC) timestamp columns), DNS and TLS analyses, NXDOMAIN analysis, JA3/JA3S fingerprints, Zeek conn.log/dns.log/http.log/ssl.log, carved HTTP payloads, and YARA scan results. Export any view as CSV or JSON with CSV-injection protection.

7. Cases — persistent investigation tracking

Promote any capture and its findings into a case. Cases carry IOCs, severity, tags, investigation notes, status, and search — stored in a local SQLite database.

8. API Keys — manage programmatic access

Create, revoke, and monitor API keys for the Integrations API. Each key has its own scope (full or feed-only), optional expiration, per-key rate limits, and a usage sparkline. Environment-variable keys are shown as read-only bootstrap entries.

9. Config — centralized settings

An LLM Integration section with three providers (LM Studio, OpenAI, Anthropic), a YARA Rules section with a configurable rules directory, OSINT provider keys with a Test Providers live-check button, home location for the world map, binary paths, and pipeline thresholds — all in one place with per-section clear buttons. API keys are PBKDF2-encrypted at rest.

Choosing an LLM provider

Pick the backend that fits your environment: LM Studio for local, air-gapped analysis (chunked per-section generation), or OpenAI / Anthropic for single-shot full-context cloud reports. Each provider keeps its own credentials and model picker.

Key Features

AI-Powered Threat Analysis

• Multi-Provider LLM Support — three interchangeable backends behind one Config section:
  • LM Studio (local) — privacy-first, air-gapped friendly; reports are generated section-by-section to fit small context windows.
  • OpenAI (cloud) — single-shot report with the entire evidence corpus in one full-context call.
  • Anthropic (cloud) — Claude via the official anthropic SDK (claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5), single-shot with streaming.
• Evidence-Grounded Reporting — SOC-ready reports with severity-calibrated assessments, false-positive awareness, confidence qualifiers, a Risk Matrix rendered as a real Markdown table, and an IOC Summary table.
• Multi-Language Reports — 9 languages with region-specific terminology: English, Traditional Chinese (Taiwan), Simplified Chinese, Japanese, Korean, Italian, Spanish, French, German.
• MITRE ATT&CK Mapping — Automated mapping of detected behaviors and IOCs to ATT&CK techniques and Kill Chain phases.
• Attack Narrative Synthesis — Translates raw events into a coherent, actionable security story.

IOC Priority Scoring

• Tiered Signal Architecture — Dynamically ranks indicators as Critical, High, Medium, or Low using a three-tier model:
  • Tier 1 (Definitive): OSINT confirmations (VirusTotal, GreyNoise malicious) — any single Tier 1 hit sets a score floor.
  • Tier 2 (Behavioral): C2 beaconing, flow asymmetry, DNS tunneling, DGA domains.
  • Tier 3 (Contextual): AbuseIPDB, self-signed certs, expired certs, YARA matches.
• Tier 3 signals alone never exceed "medium"; corroboration from multiple tiers is required for "high" or "critical".
• Explainable Risk — the Dashboard's "Why this risk level?" expander shows exactly which signals drove the verdict.

Cross-Indicator Correlation Engine

• Independence-complement formula — Uses 1 − Π(1 − wᵢsᵢ) (Bayesian independence model) instead of linear summation, producing diminishing returns while allowing multiple weak signals to compound meaningfully.
• Strong-signal floors — A confirmed VirusTotal detection automatically sets a minimum score regardless of other factors.
• Aggregates signals across all analysis modules (OSINT, beaconing, DNS, TLS, YARA, flow analysis).
• Produces composite threat scores per indicator with verdict classification (critical / high / medium / low).

Flow Analysis & Exfiltration Detection

• Data Exfiltration Detection — Identifies suspicious outbound:inbound byte ratios per src/dst pair (default threshold: 10:1, minimum 1 MB).
• Port Anomaly Detection — Flags non-standard port usage, C2 common ports (4444, 5555, 6666, etc.), and high port pairs.
• Memory-Bounded Sampling — per-flow packet timestamps/lengths are capped at 5,000 samples while true byte/packet totals and first/last-seen times are kept exact.

Multi-PCAP Batch Processing

• Multi-File Upload — Upload and analyze multiple PCAP files simultaneously.
• Cross-File Correlation — Detects shared IPs, domains, and JA3 fingerprints across files.
• Merged Dashboard — Aggregated results with per-file detail cards and batch summary.
• Resource Limits — Configurable limits: 1 GB per file, 50 files max, 5 GB total.

Concurrent Pipeline Execution

• PyShark + Zeek in parallel — the two heaviest stages run concurrently via ThreadPoolExecutor.
• Four-way analysis fan-out — after the parse join, DNS, TLS, beaconing, and HTTP carving all run concurrently.
• Per-run artifact isolation — Zeek and carve outputs go to data/zeek|carved/<case>_<uuid8>/ so concurrent runs never clobber each other; stale run dirs are pruned automatically after 7 days.
• Bounded subprocesses — every external tool call (zeek, tshark counting/carving/TLS extraction) runs under an explicit timeout.
• Tshark -c optimization — packet limit enforced at the tshark level for zero-waste I/O.

Deep Packet Inspection & Flow Analysis

• Multi-Engine Pipeline: PyShark for granular inspection, Tshark for high-speed statistics.
• Protocol Parsing: Automatically extracts metadata for HTTP, DNS, TLS/SSL, and SMB protocols.

Zeek Integration

• Automated Zeek execution on uploaded PCAPs — no manual CLI required.
• Parses and correlates core Zeek logs: conn.log, dns.log, http.log, ssl.log.

Advanced DNS & TLS Forensics

• DGA Detection — Shannon entropy-based Domain Generation Al