{"id":51120447,"url":"https://github.com/NotYuSheng/TracePcap","last_synced_at":"2026-07-13T08:00:57.710Z","repository":{"id":335706648,"uuid":"1146618872","full_name":"NotYuSheng/TracePcap","owner":"NotYuSheng","description":"Self-hosted PCAP analysis platform with LLM-powered incident triage, signature-based threat detection, and AI-generated incident narratives. Features network change monitoring across captures, deep packet inspection via nDPI, and automated Wireshark filter generation. Runs fully offline with local LLMs (Ollama, LM Studio).","archived":false,"fork":false,"pushed_at":"2026-07-03T03:20:05.000Z","size":10879,"stargazers_count":27,"open_issues_count":60,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-03T03:24:40.158Z","etag":null,"topics":["ai","blue-team","cyber-defense","cybersecurity","dfir","incident-response","llm","ndpi","network-forensics","network-monitoring","ollama","packet-analysis","pcap","pcap-analyzer","protocol-analysis","soc","threat-hunting","triage","tshark","wireshark"],"latest_commit_sha":null,"homepage":"https://notyusheng.github.io/TracePcap/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/NotYuSheng.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-31T11:53:19.000Z","updated_at":"2026-07-02T02:32:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/NotYuSheng/TracePcap","commit_stats":null,"previous_names":["notyusheng/tracecap","notyusheng/tracepcap"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/NotYuSheng/TracePcap","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NotYuSheng%2FTracePcap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NotYuSheng%2FTracePcap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NotYuSheng%2FTracePcap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NotYuSheng%2FTracePcap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/NotYuSheng","download_url":"https://codeload.github.com/NotYuSheng/TracePcap/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/NotYuSheng%2FTracePcap/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35414732,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","blue-team","cyber-defense","cybersecurity","dfir","incident-response","llm","ndpi","network-forensics","network-monitoring","ollama","packet-analysis","pcap","pcap-analyzer","protocol-analysis","soc","threat-hunting","triage","tshark","wireshark"],"created_at":"2026-06-25T02:00:22.244Z","updated_at":"2026-07-13T08:00:57.697Z","avatar_url":"https://github.com/NotYuSheng.png","language":"TypeScript","funding_links":[],"categories":["ai"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eTracePcap\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eBlack-box network analysis from PCAP captures — no prior knowledge of the network required\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e •\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e •\n  \u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e •\n  \u003ca href=\"#documentation\"\u003eDocumentation\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Spring_Boot-6DB33F?style=flat\u0026logo=springboot\u0026logoColor=white\" alt=\"Spring Boot\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/React-61DAFB?style=flat\u0026logo=react\u0026logoColor=black\" alt=\"React\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/PostgreSQL-4169E1?style=flat\u0026logo=postgresql\u0026logoColor=white\" alt=\"PostgreSQL\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Docker-2496ED?style=flat\u0026logo=docker\u0026logoColor=white\" alt=\"Docker\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/MinIO-C72E49?style=flat\u0026logo=minio\u0026logoColor=white\" alt=\"MinIO\"/\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Java-21-007396?style=flat\u0026logo=openjdk\u0026logoColor=white\" alt=\"Java 21\"/\u003e\n\u003c/p\u003e\n\n---\n\nTracePcap is a self-hosted PCAP analysis workbench designed for situations where you work from the **traffic itself** — with no prior knowledge of the network. Upload one or more PCAP captures and the tool characterises devices, maps topology, reconstructs sessions, tracks changes over time, and generates AI-powered narratives — all derived purely from observed traffic.\n\nThis makes it well-suited for:\n\n- **Network audits and third-party assessments** — handed a PCAP with no documentation; build the picture from scratch\n- **Incident response** — incomplete network records; reconstruct what happened from packet evidence\n- **Penetration test reconnaissance** — map an unknown or scarcely-documented network from captured traffic\n- **Research and education** — explore any capture without needing context about the environment\n\n\u003cdiv align=\"center\"\u003e\n\n![TracePcap Demo](https://raw.githubusercontent.com/NotYuSheng/TracePcap/main/sample-files/TracePcap-Demo.gif)\n\n\u003c/div\u003e\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **PCAP Upload \u0026 Management** | Upload and manage PCAP/PCAPNG/CAP files (upload limit derived from `APP_MEMORY_MB`, 512MB by default) with MinIO object storage; duplicate detection and configurable upload limits |\n| **Network Visualization** | Interactive network topology using Sigma.js (WebGL) + graphology with ForceAtlas2 / ELK layouts, a rich filter panel (IP, port, device type, protocol, risk), fullscreen toggle, layout controls, and clickable node detail panels |\n| **nDPI Security Detection** | Deep packet inspection via nDPI v5: application identification, traffic categories, risk/alert flags, JA3/JA3S TLS fingerprints, SNI extraction, and TLS certificate metadata per conversation |\n| **Conversation Tracking** | Paginated conversation list with advanced filtering (IP, port, protocol, app, risk, custom rules, device type, country, payload pattern), multi-column sorting, column picker, and bulk PCAP export |\n| **Session Reconstruction** | TCP/UDP application-layer payload decoding with a hex+ASCII viewer for inspecting raw packet payloads |\n| **File Extraction** | HTTP object extraction and raw TCP/UDP stream extraction; automatic MIME type detection; bulk download |\n| **Geolocation \u0026 Device Classification** | Country/ASN enrichment for external IPs; automatic device-type inference (Router, Server, IoT, Mobile, Laptop/Desktop) from traffic behaviour and manufacturer data |\n| **MAC Manufacturer Lookup** | Wireshark OUI database integration for vendor identification from MAC addresses |\n| **Timeline Analysis** | Chronological traffic visualization with configurable time granularity and protocol breakdown |\n| **AI Filter Generator** | LLM-powered Wireshark/tcpdump filter generation from natural language queries with confidence scores and packet-level results |\n| **Story Mode** | AI-generated narrative reconstruction of network activities with an interactive LLM Q\u0026A chat, custom context input, and story timeline |\n| **Network Monitor** | Load multiple PCAPs as ordered snapshots to track device, IP, protocol, and topology changes over time — useful for repeated audits or ongoing capture sessions |\n| **Subnet Detection \u0026 Labelling** | Infer subnet structure from traffic patterns or define CIDRs manually; group observed IPs by subnet across all snapshots |\n| **Node Role Annotation** | Annotate any IP or device with a role label (e.g. \"SCADA Controller\", \"Historian\"); AI-suggested from traffic signals, human-confirmable |\n| **Custom Signature Rules** | YAML-based detection rules matched against IP, CIDR, port, JA3, hostname, app, and protocol fields; live-reloaded without restart |\n| **Export Options** | PDF report (with live topology capture), per-conversation PCAP, bulk PCAP export, and CSV export |\n| **Real-time Processing** | Asynchronous analysis with detailed progress tracking |\n| **Multi-protocol Support** | TCP, UDP, ICMP, and application-layer protocols including TLS, HTTP, DNS, QUIC, and L2 protocols (ARP, STP, LLDP, CDP) |\n\n## Quick Start\n\n### Prerequisites\n\n| Software | Version | Purpose |\n|----------|---------|---------|\n| Docker | Latest | Container runtime |\n| Docker Compose | Latest | Multi-container orchestration |\n| LLM Server | Any OpenAI-compatible API | AI features (e.g., LM Studio, Ollama, OpenAI) |\n\n**Minimum Hardware:**\n- RAM: 4GB (8GB+ recommended)\n- Storage: 10GB (for database, PCAP files, and object storage)\n\n### Installation\n\n**1. Clone and setup:**\n```bash\ngit clone https://github.com/NotYuSheng/TracePcap.git\ncd TracePcap\ncp .env.example .env\n```\n\n**2. Configure `.env`:**\n```env\n# Memory \u0026 Upload Configuration\n# Upload limits are derived from this single value (max upload = 25% of it).\nAPP_MEMORY_MB=2048  # 512MB max upload (default)\n\n# Nginx Port Configuration\nNGINX_PORT=80  # Change if port 80 is already in use\n\n# LLM Configuration (Local LLM Server)\nLLM_API_BASE_URL=http://localhost:1234/v1\nLLM_API_KEY=\nLLM_MODEL=Qwen2.5-14B-Coder-Instruct\nLLM_TEMPERATURE=0.7\nLLM_MAX_TOKENS=8000\n```\n\n**3. Start the application:**\n```bash\ndocker compose up -d\n```\n\n**4. Access TracePcap:**\n\nOpen **http://localhost:80** in your browser.\n\n\u003e **Note**: First startup may take a minute while PostgreSQL and MinIO initialise. AI features require a running LLM server pointed to by `LLM_API_BASE_URL`; all other features work without it.\n\n## Usage\n\n### Single-file Analysis\n\n1. **Upload** — Drag-and-drop a PCAP/PCAPNG file; optionally enable nDPI analysis and file extraction\n2. **Analyze** — File is processed asynchronously; a progress view shows each analysis stage\n3. **Overview** — Review detected applications, protocols, risk alerts, and custom signature matches\n4. **Visualize** — Explore the interactive network topology with filters, layout controls, and node detail panels\n5. **Conversations** — Review flows with advanced filtering, session reconstruction, and payload inspection\n6. **Story Mode** — Read the AI-generated narrative and ask follow-up questions via LLM chat\n7. **Extracted Files** — Browse and download files recovered from HTTP responses and raw streams\n8. **Generate Filters** — Use AI to create Wireshark/tcpdump filters from natural language\n9. **Export** — Download a PDF report, per-conversation or bulk PCAP, or CSV\n\n### Multi-file Network Monitor\n\nThe Network Monitor lets you build a picture of an unknown network from multiple captures taken at different points in time — and track how it changes between them.\n\n1. **Create a Network** — Give the network a name (e.g. \"Client Site — Building A\")\n2. **Add Snapshots** — Upload PCAPs in capture order; each becomes a snapshot ordered by capture time\n3. **Review the Diagram** — Click any snapshot filename to open the network diagram; changed nodes are highlighted by severity\n4. **Track Drift** — Device, IP, protocol, and VPN changes are detected automatically between consecutive snapshots\n5. **Define Subnets** — Use \"Detect Subnets\" to infer CIDR blocks from traffic, or add them manually; IPs are then grouped by subnet in the IP Addresses panel\n6. **Annotate Nodes** — Click any IP or device to assign a role label; use \"Suggest with AI\" to auto-generate one from traffic signals\n7. **Correlate Events** — Log real-world events (maintenance windows, incidents) to correlate with observed network changes\n8. **Generate Insights** — Use the AI insights panel to get a narrative explanation of all changes across snapshots\n\n### Supported File Formats\n\nPCAP, PCAPNG, CAP (max 512MB default, derived from `APP_MEMORY_MB`)\n\n## How Network Monitor Works\n\nThe Monitor is designed for black-box retrospective analysis — it assumes you know nothing about the network upfront and builds understanding from the traffic itself:\n\n- **No prior knowledge needed** — subnet structure, device roles, and topology are all inferred from observed traffic\n- **Snapshots, not agents** — there is no persistent sensor; you feed in PCAPs and the tool compares them\n- **Bottom-up inventory** — devices and IPs are discovered from ARP, MAC addresses, and IP conversations; not imported from a CMDB\n- **Inference over assumption** — device types, manufacturers, and roles are estimated from traffic patterns and can be confirmed or corrected by the analyst\n- **Change detection without a baseline** — the first snapshot becomes the implicit baseline; every subsequent snapshot is compared against the one before it\n\nThis is intentionally different from a blue team SIEM or EDR: there is no always-on agent, no rule engine with predefined baselines, and no assumption that you have network documentation. The tool is most useful when you are the one trying to *produce* that documentation.\n\n### Change Detection\n\nChanges are compared between consecutive snapshots (ordered by capture time):\n\n| Severity | Event Type | Description |\n|----------|-----------|-------------|\n| CRITICAL | `IP_MAC_DRIFT` | An IP is now claimed by a different MAC — possible ARP spoofing or device swap |\n| CRITICAL | `GATEWAY_CHANGE` | Default gateway IP changed between snapshots |\n| WARNING | `MAC_ADDED` | A new MAC address appeared — new device on the network |\n| WARNING | `IP_MAC_DRIFT` | A known MAC moved to a new IP — possible DHCP drift |\n| INFO | `PROTOCOL_ADDED` | A new layer-7 protocol appeared |\n| INFO | `APP_ADDED` | A new application name appeared |\n| INFO | `ASN_CHANGE` | The top external peer shifted ISP/ASN |\n| INFO | `VPN_DRIFT` | VPN usage appeared or disappeared |\n\n## Tech Stack\n\n| Component | Technology |\n|-----------|------------|\n| **Backend** | Spring Boot 3.2.1, Java 21, Maven, Lombok, MapStruct |\n| **Frontend** | React 19, Vite, TypeScript, SGDS React |\n| **Visualization** | Sigma.js + graphology + ELK (network topology), React Flow (Network Intelligence cluster graph), Recharts, D3.js |\n| **Reverse Proxy** | Nginx |\n| **Packet Parsing** | tshark / Wireshark, nDPI v5 (deep packet inspection) |\n| **Database** | PostgreSQL 15 with Flyway migrations |\n| **Object Storage** | MinIO (S3-compatible) |\n| **Containerization** | Docker, Docker Compose |\n| **API Documentation** | SpringDoc OpenAPI (Swagger UI) |\n\n## Documentation\n\nFull documentation is available at **https://notyusheng.github.io/TracePcap**.\n\nAPI documentation is also available via Swagger UI at **http://localhost:80/swagger-ui.html** when the application is running.\n\n## Common Tasks\n\n### View Logs\n\n```bash\n# All services\ndocker compose logs -f\n\n# Specific service\ndocker compose logs -f tracepcap-backend\ndocker compose logs -f postgres\ndocker compose logs -f minio\n```\n\n### Restart Services\n\n```bash\ndocker compose restart\ndocker compose restart tracepcap-backend\n```\n\n### Backup Data\n\n```bash\n# Backup database\ndocker exec tracepcap-postgres pg_dump -U tracepcap_user tracepcap \u003e backup.sql\n\n# Backup MinIO data (PCAP files)\ndocker exec tracepcap-minio mc mirror minio/tracepcap-files ./backup-pcaps/\n\n# Backup all volumes\nsudo tar -czf tracepcap_backup.tar.gz /var/lib/docker/volumes/tracepcap_*\n```\n\n### Access Database\n\n```bash\ndocker exec -it tracepcap-postgres psql -U tracepcap_user tracepcap\n```\n\n### Access MinIO Console\n\nNavigate to **http://localhost:9001** and login with `minioadmin` / `minioadmin`.\n\n### Access Swagger API Documentation\n\nNavigate to **http://localhost:80/swagger-ui.html** to explore the API interactively.\n\n## Deployment\n\nTracePcap is designed for self-hosted deployment.\n\n### Offline / Air-gapped Deployment\n\nFor environments without internet access:\n\n**On an internet-connected machine:**\n\n\u003e **Windows users**: These scripts require a Bash shell. Use **Git Bash** or **WSL** — not CMD or PowerShell.\n\n```bash\n# Pull all third-party images, build local images, and save everything as .tar files\nbash scripts/pull-and-save-images.sh\n```\n\n**Transfer to the offline machine:** the generated `images/` directory, `docker-compose.offline.yml`, `scripts/load-images.sh`, and your configured `.env`.\n\n**On the offline machine:**\n\n```bash\nbash scripts/load-images.sh\ndocker compose -f docker-compose.offline.yml up -d\n```\n\n\u003e The offline compose file defaults `LLM_API_BASE_URL` to `http://localhost:1234/v1` (LM Studio). Configure a locally-hosted LLM before starting if you want AI features.\n\n---\n\n**Production hardening:**\n- Change default MinIO credentials in `docker-compose.yml`\n- Update PostgreSQL password\n- Configure reverse proxy with SSL/TLS\n- Adjust `APP_MEMORY_MB` based on your needs (upload limit is derived from it)\n- Add an authentication layer for multi-user deployments\n\n## Security\n\n- **Local Processing**: All PCAP analysis runs on your server — packet data never leaves your infrastructure\n- **Offline-capable**: GeoIP uses a bundled DB-IP MMDB as fallback; LLM queries use a configurable local endpoint\n- **No Authentication by default**: runs fully open; turn on OIDC/Keycloak auth before exposing to multiple users (see [Authentication](#authentication-oidc--keycloak))\n- **Object Storage**: MinIO provides S3-compatible secure file storage; not exposed outside the Docker network\n\n## Authentication (OIDC / Keycloak)\n\nAuthentication is **disabled by default** — the base `docker-compose.yml` runs the app fully open, exactly as before (suitable for single-user / trusted-network deployments like Lanturn).\n\nTo run with login enabled, use the production overlay, which bundles a Keycloak identity provider and rebuilds the frontend with the OIDC client. Set `PUBLIC_URL` to the exact origin you browse to (scheme + host + port):\n\n```bash\nPUBLIC_URL=http://localhost:8888 \\\n  docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build\n```\n\nThe Keycloak admin console is reachable at `${PUBLIC_URL}/admin` — default `user` / `P@ssw0rd`. **Override `KEYCLOAK_ADMIN` / `KEYCLOAK_ADMIN_PASSWORD` for any real deployment.**\n\nSet `PUBLIC_URL` to the exact origin you browse to. For any non-`localhost` deployment this must be an **HTTPS** origin (see the secure-context note below); plain-HTTP LAN/Tailscale IPs only work if you terminate TLS in front of nginx. It defaults to `http://localhost:${NGINX_PORT:-8888}`.\n\n\u003e **⚠️ Requires a secure context (HTTPS or localhost).** OIDC login uses the browser Web Crypto API (PKCE), which browsers expose **only over HTTPS or via `http://localhost`**. Serving the app over plain HTTP on a LAN/VPN IP (e.g. `http://192.168.x.x:8888` or a Tailscale `http://100.x.y.z:8888`) will fail at login with *\"Crypto.subtle is available only in secure contexts\"*. Put TLS in front and set `PUBLIC_URL` to the HTTPS origin — e.g. a reverse proxy that terminates TLS, or, on a tailnet, `tailscale serve --bg --https=443 http://localhost:8888` (browse to the `https://\u003cmachine\u003e.\u003ctailnet\u003e.ts.net` MagicDNS name). For single-admin use, an SSH tunnel to `http://localhost:8888` also works (localhost is a secure context).\n\nThis:\n\n- Starts **Keycloak** (auto-importing the `tracepcap` realm from [`keycloak/realm-export.json`](keycloak/realm-export.json) — a public PKCE SPA client `tracepcap-frontend` and a demo user) and **proxies it through nginx on the same origin as the app**. The browser reaches the identity provider at the same host:port it loaded the app from — no second exposed port, no CORS.\n- Gates the entire backend API behind a valid Keycloak JWT (Spring OAuth2 resource server).\n- Redirects unauthenticated users to the Keycloak login page and adds a user chip + logout button to the header.\n\n**Default demo login:** `analyst` / `analyst` — change this (and the Keycloak admin password) for any real deployment. The Keycloak admin console is proxied at `${PUBLIC_URL}/admin` (`admin` / `admin` by default).\n\n### How it works\n\n| Concern | Where |\n| --- | --- |\n| Master switch | `TRACEPCAP_AUTH_ENABLED` (backend) + `VITE_AUTH_ENABLED` (frontend build arg), both default `false` |\n| Backend security | `com.tracepcap.config.security` — two env-gated `SecurityFilterChain`s: permit-all when off, JWT-required when on |\n| Public origin | `PUBLIC_URL` pins Keycloak's `KC_HOSTNAME` (token issuer) and the backend's `KEYCLOAK_ISSUER_URI`. The browser must load the app via this same origin |\n| Issuer vs. keys | Backend validates the token `iss` against `KEYCLOAK_ISSUER_URI` (public) but fetches signing keys from `KEYCLOAK_JWK_SET_URI` (internal `keycloak:8080`), so the two hostnames need not match in Docker |\n| Same-origin proxy | nginx proxies `/realms`, `/resources`, `/admin`, `/js` to Keycloak (see `nginx/nginx.conf.template`); the SPA derives its OIDC authority from `window.location` at runtime |\n| Frontend | `src/auth/` — `react-oidc-context` provider mounted only when auth is enabled |\n\nData is **shared across all authenticated users** (no per-user ownership) in this version — so disabling auth never strands data behind a missing user. Per-user scoping and concurrent-edit conflict handling are tracked separately (issues #360, #444).\n\n\u003e The overlay keeps the working runtime profile (it does not switch Spring to the `prod` profile, which expects external log volumes and additional required env vars). It changes only what auth needs: the Keycloak service, the auth env vars, and the frontend build args.\n\n## Custom Signature Rules\n\nTracePcap supports user-defined detection rules matched against every conversation after nDPI analysis. Matched rule names appear as colour-coded badges in the Conversations tab and Overview.\n\n### Rule format\n\n```yaml\nsignatures:\n  - name: rule_name_shown_in_ui   # shown as a badge\n    description: Human-readable description\n    severity: low                  # low | medium | high | critical\n    match:\n      ip: \"203.0.113.42\"           # exact match against srcIp OR dstIp\n```\n\nRules fire when **all** specified match fields are satisfied. All fields are optional.\n\n### Match fields\n\n| Field | Type | Description | Example |\n|-------|------|-------------|---------|\n| `ip` | string | Exact match against srcIp or dstIp | `\"203.0.113.42\"` |\n| `cidr` | string | CIDR range match against srcIp or dstIp | `\"10.0.0.0/8\"` |\n| `srcPort` | number | Exact source port | `67` |\n| `dstPort` | number | Exact destination port | `4444` |\n| `ja3` | string | Exact JA3S fingerprint hash | `\"82f0d8a75fa483d1cfe4b7085b784d7e\"` |\n| `hostname` | string | Exact or wildcard SNI hostname — `*.evil.com` matches any subdomain | `\"*.evil.com\"` |\n| `app` | string | Case-insensitive nDPI application name | `\"Telegram\"`, `\"TOR\"` |\n| `protocol` | string | Case-insensitive transport protocol | `\"TCP\"`, `\"UDP\"` |\n\nClick **Custom Detection Rules** in the navbar to open the built-in YAML editor. Changes take effect on the next analysis run — no restart required.\n\nA full set of demo rules covering every match field is in [`signatures.sample.yml`](signatures.sample.yml). The script [`sample-files/gen_demo.py`](sample-files/gen_demo.py) generates a PCAP that triggers all 12 rules.\n\n## Sample Files\n\nThe [`sample-files/`](sample-files/) directory contains example PCAPs:\n\n- `atm_capture1.cap` — ATM network traffic sample\n- `free5gc.pcap` — 5G core network traffic sample\n- `demo_all_rules.pcap` — Triggers all 12 custom signature demo rules\n- `dns_demo.pcap` — Two LAN resolvers answering a variety of DNS record types (A, AAAA, CNAME, MX, TXT, PTR, SRV) for the Network Intelligence \"DNS Servers\" view. Regenerate with [`sample-files/gen_dns_demo.py`](sample-files/gen_dns_demo.py)\n- `http_demo.pcap` — A JSON API server, a plain website, and a host under endpoint enumeration (mostly 404s) — drives the web/API-server classification and the node-modal HTTP endpoint log. Regenerate with [`sample-files/gen_http_demo.py`](sample-files/gen_http_demo.py)\n- `monitor_large/` — 8 weekly snapshots of a simulated 550-node office network for testing the Network Monitor\n\n## Star History\n\n\u003ca href=\"https://www.star-history.com/?type=date\u0026repos=NotYuSheng%2FTracePcap\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=NotYuSheng/TracePcap\u0026type=date\u0026theme=dark\u0026legend=top-left\u0026sealed_token=bP8r_g4hzyQiVmI8sv4l49OQlHsb4JgXkHd7e_SD-EsBU427XgUNLZrj3jHG2BmXS33vDA_RcWG-GetRWhnuGp-n6THTA8SGwhYM-J3FLrLAl499lnoRk4CFLUg8qy-4XwTJ_0sqcFWPcjtco8CDoIcF9aPuNmoRdSFWblxjwy2a3y2SxttHUlzDc4Uv\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=NotYuSheng/TracePcap\u0026type=date\u0026legend=top-left\u0026sealed_token=bP8r_g4hzyQiVmI8sv4l49OQlHsb4JgXkHd7e_SD-EsBU427XgUNLZrj3jHG2BmXS33vDA_RcWG-GetRWhnuGp-n6THTA8SGwhYM-J3FLrLAl499lnoRk4CFLUg8qy-4XwTJ_0sqcFWPcjtco8CDoIcF9aPuNmoRdSFWblxjwy2a3y2SxttHUlzDc4Uv\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=NotYuSheng/TracePcap\u0026type=date\u0026legend=top-left\u0026sealed_token=bP8r_g4hzyQiVmI8sv4l49OQlHsb4JgXkHd7e_SD-EsBU427XgUNLZrj3jHG2BmXS33vDA_RcWG-GetRWhnuGp-n6THTA8SGwhYM-J3FLrLAl499lnoRk4CFLUg8qy-4XwTJ_0sqcFWPcjtco8CDoIcF9aPuNmoRdSFWblxjwy2a3y2SxttHUlzDc4Uv\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n## License\n\nThis project is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNotYuSheng%2FTracePcap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FNotYuSheng%2FTracePcap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FNotYuSheng%2FTracePcap/lists"}