flowscope 0.16.0

[package]
name = "flowscope"
version = "0.16.0"
edition = "2024"
rust-version = "1.88"
license = "MIT OR Apache-2.0"
repository = "https://github.com/p13marc/flowscope"
homepage = "https://github.com/p13marc/flowscope"
authors = ["Marc Pardo <p13marc@gmail.com>"]
description = "Passive flow & session tracking for packet capture (runtime-free, cross-platform)"
keywords = ["flow", "session", "tcp", "packet", "passive"]
categories = ["network-programming", "parser-implementations"]
readme = "README.md"
documentation = "https://docs.rs/flowscope"
# Internal-only files — useful in-repo, not on crates.io.
# `target/` is auto-excluded.
exclude = ["plans/", "CLAUDE.md"]

[dependencies]
bitflags = "2"

# Always-on. Backs the lock-free MPMC queue under every
# `SlotHandle<M, K>` (plan 122). Sync-only, no async deps,
# transitively pulls only `crossbeam-utils`.
crossbeam-queue = "0.3"

# `extractors` feature
etherparse = { version = "0.16", optional = true }

# `tracker` feature
ahash = { version = "0.8", default-features = false, optional = true }
smallvec = { version = "1", optional = true }
arrayvec = { version = "0.7", optional = true }
lru = { version = "0.16", optional = true }

# `http` feature
httparse = { version = "1.10", optional = true }
bytes = { version = "1", optional = true }

# `tls` feature
tls-parser = { version = "0.12", optional = true }

# `tls-fingerprints` sub-feature deps (JA3 + JA4 client TLS
# fingerprints. Plan 131 collapsed the former `ja3` + `ja4`
# split into a single feature flag — see CHANGELOG 0.12.0.)
md-5 = { version = "0.10", optional = true }
hex = { version = "0.4", optional = true }
sha2 = { version = "0.10", optional = true }

# `dns` feature
simple-dns = { version = "0.10", optional = true }

# `pcap` feature
pcap-file = { version = "2", optional = true }

# `metrics` feature
metrics = { version = "0.24", optional = true }

# `tracing` feature
tracing = { version = "0.1", default-features = false, features = ["std", "attributes"], optional = true }

# `serde` feature
serde = { version = "1", features = ["derive"], optional = true }

# `emit-ndjson` sub-feature
serde_json = { version = "1", optional = true }

# `aggregate` feature — t-digest streaming quantile estimator
tdigest = { version = "0.2", optional = true }

# `chrono` feature — interop between `Timestamp` and chrono's
# `DateTime<Utc>`. We need `alloc` for the `to_rfc3339_opts`
# cross-check tests; the runtime path (`From` / `TryFrom`) is
# alloc-free regardless.
chrono = { version = "0.4", default-features = false, features = ["alloc"], optional = true }

[dev-dependencies]
proptest = "1"
pcap-file = "2"
metrics-util = "0.20"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }
criterion = { version = "0.5", features = ["html_reports"] }
serde_json = "1"
static_assertions = "1"

[features]
default = ["extractors", "tracker", "reassembler", "session"]

# Core layers — start small or take the lot.
extractors = ["dep:etherparse"]
tracker = ["dep:ahash", "dep:smallvec", "dep:arrayvec", "dep:lru"]
reassembler = ["tracker"]
session = ["tracker"]

# `test-helpers` exposes `extract::parse::test_frames` for proptest,
# fuzz harnesses, and fixture generation. Not for production use.
test-helpers = ["extractors"]

# Protocol parsers. Each is a self-contained module gated by its feature.
http = ["reassembler", "session", "dep:httparse", "dep:bytes"]
tls = ["reassembler", "session", "dep:tls-parser", "dep:bytes"]
# TLS fingerprint family (plan 131) — JA3 + JA4 TLS *client* fingerprints.
# Royalty-free / BSD-3-Clause-equivalent (JA3 = Salesforce, JA4 client =
# FoxIO BSD). JA4S is NOT here — it's FoxIO-licensed, see `ja4plus`.
tls-fingerprints = ["tls", "dep:md-5", "dep:sha2", "dep:hex"]
# JA4S server fingerprint (part of the JA4+ suite). Licensed under the
# **FoxIO License 1.1** (source-available, non-commercial; patent pending) —
# NOT MIT/Apache like the rest of flowscope. OFF BY DEFAULT and deliberately
# excluded from `l7` / `full` so the default build stays royalty-free.
# Commercial use requires a FoxIO OEM license. See LICENSE-FoxIO-1.1 + NOTICE.
ja4plus = ["tls-fingerprints"]
dns = ["extractors", "tracker", "session", "dep:simple-dns", "dep:bytes"]
icmp = ["extractors", "tracker", "session", "dep:bytes"]

# Umbrella: enable every shipped L7 protocol parser at once. Strict
# subset of `full` (no `pcap`, no observability).
l7 = ["http", "tls", "tls-fingerprints", "dns", "icmp"]

# pcap source adapter (offline replay).
pcap = ["extractors", "tracker", "dep:pcap-file"]

# Observability hooks (zero-cost when off).
metrics = ["tracker", "dep:metrics"]

# Serde Serialize + Deserialize on every public event / message /
# accessor / config type. Locks the snake_case wire vocabulary from
# 0.8 forward — once shipped, dashboards depend on field / variant
# names. Renames require a CHANGELOG-documented breaking change.
serde = ["dep:serde", "bytes?/serde", "arrayvec?/serde", "smallvec?/serde"]
tracing = ["tracker", "dep:tracing"]
# `tracing-messages` (deleted in 0.12.0 plan 131): per-message
# `tracing::trace!` emission is now always-on under `tracing`.
# Filter at runtime via `tracing-subscriber::EnvFilter`, e.g.
# `EnvFilter::new("info,flowscope.message=warn")`. The
# `SessionParser::Message: Debug` bound was already always-on,
# so the dedicated feature was redundant clutter.

# Structured event sinks (plan 101). `emit` ships the CSV + Zeek
# `conn.log` writers (no extra deps). `emit-ndjson` adds the
# newline-delimited-JSON writer; pulls in `serde_json`.
emit = ["tracker", "extractors"]
emit-ndjson = ["emit", "serde", "dep:serde_json"]
# Suricata EVE JSON writer (plan 123). Schema-compatible with
# Suricata 7.x; pipes into Filebeat / Splunk / Tenzir / ECS
# downstream pipelines without translation.
emit-eve = ["emit", "dep:serde_json"]

# File-hash sinks (plan 146, 0.12.0) — streaming SHA-256 / MD5
# hashing for the reassembled payload stream plus MIME-class
# detection from the first ~64 bytes. Bridges flowscope into
# DFIR / IR pipelines (VirusTotal hash matching, Suricata
# file_md5 / file_sha256 ergonomics) without storing the file
# bytes themselves.
file-hash = ["reassembler", "dep:sha2", "dep:md-5", "dep:hex"]

# Distribution / quantile primitives (plan 102 sub-B). Ships
# `Histogram` (no deps) + `Percentile` (wraps the `tdigest` crate).
aggregate = ["dep:tdigest"]

# `chrono` interop on `Timestamp` (plan 127). Adds
# `From<DateTime<Utc>>` + `TryFrom<Timestamp>` for
# `chrono::DateTime<chrono::Utc>` so consumers already on
# chrono can interop without a manual conversion.
chrono = ["dep:chrono"]

# Convenience: turn everything on.
full = ["http", "tls", "tls-fingerprints", "dns", "icmp", "pcap", "metrics", "tracing", "serde", "emit", "emit-ndjson", "emit-eve", "aggregate", "chrono", "file-hash"]

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

# `md-5` is published with package name `md-5` but exports the crate
# as `md5` (no hyphen). cargo-machete can't tell, so explicitly
# allow-list it.
[package.metadata.cargo-machete]
ignored = ["md-5"]

# ─── Examples (see examples/README.md for a catalog) ───

# ── 00 getting started ──────────────────────────────
[[example]]
name = "hello_pipeline"
path = "examples/00-getting-started/hello_pipeline.rs"
required-features = ["pcap", "extractors", "reassembler", "session"]

[[example]]
name = "inspect_packet"
path = "examples/00-getting-started/inspect_packet.rs"
required-features = ["pcap", "extractors"]

[[example]]
name = "unified_driver_demo"
path = "examples/00-getting-started/unified_driver_demo.rs"
required-features = ["pcap", "http", "dns"]

# ── 01 L7 message logging ────────────────────────────
[[example]]
name = "http_log"
path = "examples/01-l7-logging/http_log.rs"
required-features = ["http", "pcap"]

[[example]]
name = "http_exchanges"
path = "examples/01-l7-logging/http_exchanges.rs"
required-features = ["http", "pcap"]

[[example]]
name = "tls_observer"
path = "examples/01-l7-logging/tls_observer.rs"
required-features = ["tls", "pcap"]

[[example]]
name = "dns_log"
path = "examples/01-l7-logging/dns_log.rs"
required-features = ["dns", "pcap"]

# ── 02 forensics / IoC extraction ────────────────────
[[example]]
name = "extract_iocs"
path = "examples/02-forensics/extract_iocs.rs"
required-features = ["pcap", "http", "tls", "tls-fingerprints", "dns", "extractors"]

[[example]]
name = "tls_inventory"
path = "examples/02-forensics/tls_inventory.rs"
required-features = ["tls", "tls-fingerprints", "pcap"]

# ── 03 security / detection ──────────────────────────
[[example]]
name = "port_scan_detector"
path = "examples/03-detection/port_scan_detector.rs"
required-features = ["pcap", "extractors", "tracker"]

[[example]]
name = "dns_tunnel_detector"
path = "examples/03-detection/dns_tunnel_detector.rs"
required-features = ["pcap", "dns", "extractors"]

[[example]]
name = "c2_beacon_finder"
path = "examples/03-detection/c2_beacon_finder.rs"
required-features = ["pcap", "extractors", "tracker"]

[[example]]
name = "dga_finder"
path = "examples/03-detection/dga_finder.rs"
required-features = ["pcap", "dns", "extractors"]

[[example]]
name = "failed_auth_burst"
path = "examples/03-detection/failed_auth_burst.rs"
required-features = ["pcap", "http"]

[[example]]
name = "tcp_retransmit_audit"
path = "examples/03-detection/tcp_retransmit_audit.rs"
required-features = ["pcap", "extractors", "reassembler"]

# ── 04 observability / SRE ───────────────────────────
[[example]]
name = "top_talkers"
path = "examples/04-observability/top_talkers.rs"
required-features = ["pcap", "extractors", "tracker"]

[[example]]
name = "top_talkers_topk"
path = "examples/04-observability/top_talkers_topk.rs"
required-features = ["pcap", "extractors", "tracker"]

[[example]]
name = "http_error_rate"
path = "examples/04-observability/http_error_rate.rs"
required-features = ["pcap", "http"]

[[example]]
name = "bandwidth_by_protocol"
path = "examples/04-observability/bandwidth_by_protocol.rs"
required-features = ["pcap", "extractors", "tracker"]

[[example]]
name = "flow_duration_histogram"
path = "examples/04-observability/flow_duration_histogram.rs"
required-features = ["pcap", "aggregate"]

[[example]]
name = "conversation_timeline"
path = "examples/04-observability/conversation_timeline.rs"
required-features = ["pcap", "extractors", "reassembler"]

# 0.14 cycle (plan 174) — three runnable examples for the 0.14 surface.
[[example]]
name = "bandwidth_by_app"
path = "examples/04-observability/bandwidth_by_app.rs"
required-features = ["pcap", "extractors", "tracker"]

[[example]]
name = "icmp_explained_drops"
path = "examples/04-observability/icmp_explained_drops.rs"
required-features = ["pcap", "icmp", "extractors", "tracker"]

[[example]]
name = "direction_skew_anomaly"
path = "examples/04-observability/direction_skew_anomaly.rs"
required-features = ["pcap", "extractors", "tracker"]

# ── 05 data export ───────────────────────────────────
[[example]]
name = "flow_csv_export"
path = "examples/05-export/flow_csv_export.rs"
required-features = ["pcap", "emit"]

[[example]]
name = "flow_json_export"
path = "examples/05-export/flow_json_export.rs"
required-features = ["pcap", "emit-ndjson"]

[[example]]
name = "zeek_style_conn_log"
path = "examples/05-export/zeek_style_conn_log.rs"
required-features = ["pcap", "emit"]

[[example]]
name = "eve_writer"
path = "examples/05-export/eve_writer.rs"
required-features = ["pcap", "emit-eve"]

# ── 06 custom protocols ──────────────────────────────
[[example]]
name = "length_prefixed_pcap"
path = "examples/06-custom-protocols/length_prefixed_pcap.rs"
required-features = ["pcap", "session"]

[[example]]
name = "redis_protocol"
path = "examples/06-custom-protocols/redis_protocol.rs"
required-features = ["pcap", "extractors", "reassembler"]

[[example]]
name = "accumulating_line_parser"
path = "examples/06-custom-protocols/accumulating_line_parser.rs"
required-features = ["pcap", "extractors", "session"]

# ── 07 multi-protocol pipelines ──────────────────────
[[example]]
name = "multi_parser_pipeline"
path = "examples/07-multi-protocol/multi_parser_pipeline.rs"
required-features = ["pcap", "extractors", "reassembler", "session"]

[[example]]
name = "multi_protocol_monitor"
path = "examples/07-multi-protocol/multi_protocol_monitor.rs"
required-features = ["l7", "pcap"]

# ── 08 performance ───────────────────────────────────
[[example]]
name = "layer_fast_path"
path = "examples/08-performance/layer_fast_path.rs"
required-features = ["pcap", "extractors"]

[[example]]
name = "threaded_slot_drain"
path = "examples/08-performance/threaded_slot_drain.rs"
required-features = ["pcap", "http"]

[[example]]
name = "sharded_capture"
path = "examples/00-getting-started/sharded_capture.rs"
required-features = ["pcap", "http"]

[[example]]
name = "broadcast_subscribers"
path = "examples/00-getting-started/broadcast_subscribers.rs"
required-features = ["pcap", "http"]

# ── 09 reassembly / low-level ────────────────────────
[[example]]
name = "pcap_flow_summary"
path = "examples/09-low-level/pcap_flow_summary.rs"
required-features = ["pcap"]

[[example]]
name = "pcap_flow_keys"
path = "examples/09-low-level/pcap_flow_keys.rs"
required-features = ["pcap"]

[[example]]
name = "pcap_buffered_reassembly"
path = "examples/09-low-level/pcap_buffered_reassembly.rs"
required-features = ["pcap", "reassembler"]

# ── utilities (fixture generators) ───────────────────
[[example]]
name = "gen_fixtures"
path = "examples/utilities/gen_fixtures.rs"
required-features = ["test-helpers"]

[[example]]
name = "gen_length_prefixed_pcap"
path = "examples/utilities/gen_length_prefixed_pcap.rs"
required-features = ["test-helpers", "pcap"]

[[test]]
name = "http_parser"
required-features = ["http"]

[[test]]
name = "http_pcap"
required-features = ["http", "pcap"]

[[test]]
name = "tls_parser"
required-features = ["tls"]

[[test]]
name = "dns_parser"
required-features = ["dns"]

[[test]]
name = "pcap_integration"
required-features = ["pcap"]

[[test]]
name = "pcap_fixtures"
required-features = ["pcap", "test-helpers"]

[[test]]
name = "proptest_invariants"
required-features = ["test-helpers", "tracker"]

[[test]]
name = "parser_proptest"
required-features = ["http", "tls", "dns"]

[[test]]
name = "metrics_integration"
required-features = ["metrics", "extractors", "reassembler", "test-helpers"]

[[test]]
name = "length_prefixed_example"
required-features = ["pcap", "session", "extractors"]

[[test]]
name = "round_trip"
required-features = ["pcap", "session", "reassembler", "extractors", "test-helpers"]

[[test]]
name = "pcap_l7_iterators"
required-features = ["pcap", "session", "reassembler", "extractors"]

[[test]]
name = "display_impls"
required-features = ["tracker"]

[[test]]
name = "http_accessors"
required-features = ["http"]

[[test]]
name = "severity"
required-features = ["reassembler"]

[[test]]
name = "icmp_parser"
required-features = ["icmp"]

[[test]]
name = "parser_kind_constants"
required-features = ["session"]

[[test]]
name = "iter_active"
required-features = ["tracker", "extractors", "test-helpers"]

[[test]]
name = "force_close"
required-features = ["tracker", "extractors", "test-helpers"]

[[test]]
name = "dns_resolution_cache"
required-features = ["dns"]

[[test]]
name = "serde_round_trip"
required-features = ["serde", "tracker"]

[[test]]
name = "emit_csv"
required-features = ["emit"]

[[test]]
name = "emit_ndjson"
required-features = ["emit-ndjson"]

[[test]]
name = "emit_zeek"
required-features = ["emit"]

[[test]]
name = "emit_eve"
required-features = ["emit-eve", "tracker"]

[[test]]
name = "parser_helpers"
required-features = ["session"]

[[test]]
name = "http_exchange"
required-features = ["http"]

[[test]]
name = "dns_exchange"
required-features = ["dns"]

[[test]]
name = "driver"
required-features = ["test-helpers", "extractors", "session", "reassembler"]

[[test]]
name = "anomaly_fields"
required-features = ["extractors", "tracker"]

[[test]]
name = "key_fields"
required-features = ["extractors", "tracker"]

[[test]]
name = "driver_send"
required-features = ["test-helpers", "extractors", "session", "reassembler"]

[[test]]
name = "driver_deferred"
required-features = ["test-helpers", "extractors", "session", "reassembler"]

[[bench]]
name = "extractor"
harness = false
required-features = ["extractors", "test-helpers"]

[[bench]]
name = "tracker"
harness = false
required-features = ["tracker", "extractors", "test-helpers"]

[[bench]]
name = "reassembler"
harness = false
required-features = ["reassembler"]

[[bench]]
name = "session_driver"
harness = false
required-features = ["session", "reassembler", "extractors", "test-helpers"]

[[bench]]
name = "dedup"
harness = false
required-features = ["tracker"]

[[bench]]
name = "zero_alloc"
harness = false
required-features = [
    "session",
    "reassembler",
    "extractors",
    "http",
    "dns",
    "tls",
    "test-helpers",
]