Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company đŸ‘‡
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
feat(ja3-ja4-tls-fingerprinting): M11 forensic pcap report, criterion benches, TLS miss-rate counter
CarterPerez-dev4bb95fdb9750
diff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/Cargo.lock b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/Cargo.lockindex 0bc75fc4..2ca28d4d 100644--- a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/Cargo.lock+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/Cargo.lock@@ -79,6 +79,12 @@ dependencies = ["alloc-no-stdlib",]+[[package]]+name = "anes"+version = "0.1.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"+[[package]]name = "anstream"version = "1.0.0"@@ -286,6 +292,12 @@ version = "1.11.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"+[[package]]+name = "cast"+version = "0.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"+[[package]]name = "cc"version = "1.2.63"@@ -302,6 +314,33 @@ version = "1.0.4"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"+[[package]]+name = "ciborium"+version = "0.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "42e69ffd6f0917f5c029256a24d0161db17cea3997d185db0d35926308770f0e"+dependencies = [+ "ciborium-io",+ "ciborium-ll",+ "serde",+]++[[package]]+name = "ciborium-io"+version = "0.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "05afea1e0a06c9be33d539b876f1ce3692f4afea2cb41f740e7743225ed1c757"++[[package]]+name = "ciborium-ll"+version = "0.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "57663b653d948a338bfb3eeba9bb2fd5fcfaecb9e199e87e1eda4d9e8b240fd9"+dependencies = [+ "ciborium-io",+ "half",+]+[[package]]name = "cipher"version = "0.4.4"@@ -400,6 +439,46 @@ dependencies = ["cfg-if",]+[[package]]+name = "criterion"+version = "0.5.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"+dependencies = [+ "anes",+ "cast",+ "ciborium",+ "clap",+ "criterion-plot",+ "is-terminal",+ "itertools",+ "num-traits",+ "once_cell",+ "oorandom",+ "regex",+ "serde",+ "serde_derive",+ "serde_json",+ "tinytemplate",+ "walkdir",+]++[[package]]+name = "criterion-plot"+version = "0.5.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"+dependencies = [+ "cast",+ "itertools",+]++[[package]]+name = "crunchy"+version = "0.2.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"+[[package]]name = "crypto-common"version = "0.1.7"@@ -452,6 +531,12 @@ dependencies = ["subtle",]+[[package]]+name = "either"+version = "1.16.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "91622ff5e7162018101f2fea40d6ebf4a78bbe5a49736a2020649edf9693679e"+[[package]]name = "equivalent"version = "1.0.2"@@ -662,6 +747,17 @@ dependencies = ["polyval",]+[[package]]+name = "half"+version = "2.7.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"+dependencies = [+ "cfg-if",+ "crunchy",+ "zerocopy",+]+[[package]]name = "hashbrown"version = "0.14.5"@@ -701,6 +797,12 @@ version = "0.5.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"+[[package]]+name = "hermit-abi"+version = "0.5.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"+[[package]]name = "hex"version = "0.4.3"@@ -838,12 +940,32 @@ dependencies = ["generic-array",]+[[package]]+name = "is-terminal"+version = "0.4.17"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"+dependencies = [+ "hermit-abi",+ "libc",+ "windows-sys 0.61.2",+]+[[package]]name = "is_terminal_polyfill"version = "1.70.2"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"+[[package]]+name = "itertools"+version = "0.10.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"+dependencies = [+ "either",+]+[[package]]name = "itoa"version = "1.0.18"@@ -1044,6 +1166,12 @@ version = "1.70.2"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"+[[package]]+name = "oorandom"+version = "11.1.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"+[[package]]name = "opaque-debug"version = "0.3.1"@@ -1316,6 +1444,15 @@ version = "1.0.23"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"+[[package]]+name = "same-file"+version = "1.0.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"+dependencies = [+ "winapi-util",+]+[[package]]name = "scopeguard"version = "1.2.0"@@ -1538,6 +1675,16 @@ dependencies = ["cfg-if",]+[[package]]+name = "tinytemplate"+version = "1.2.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "be4d6b5f19ff7664e8c98d03e2139cb510db9b0a60b55f8e8709b689d939b6bc"+dependencies = [+ "serde",+ "serde_json",+]+[[package]]name = "tlsfp"version = "0.1.0"@@ -1571,6 +1718,7 @@ version = "0.1.0"dependencies = ["aes","aes-gcm",+ "criterion","etherparse","hex","hkdf",@@ -1839,6 +1987,16 @@ dependencies = ["libc",]+[[package]]+name = "walkdir"+version = "2.5.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"+dependencies = [+ "same-file",+ "winapi-util",+]+[[package]]name = "wasi"version = "0.11.1+wasi-snapshot-preview1"@@ -1958,6 +2116,15 @@ version = "0.4.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"+[[package]]+name = "winapi-util"+version = "0.1.11"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"+dependencies = [+ "windows-sys 0.61.2",+]+[[package]]name = "winapi-x86_64-pc-windows-gnu"version = "0.4.0"diff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/Cargo.toml b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/Cargo.tomlindex febc79e0..6e79636d 100644--- a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/Cargo.toml+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/Cargo.toml@@ -31,3 +31,8 @@ aes-gcm.workspace = truehex.workspace = trueproptest = "1"serde_json.workspace = true+criterion = { version = "0.5", default-features = false, features = ["cargo_bench_support"] }++[[bench]]+name = "fingerprint"+harness = falsediff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/benches/fingerprint.rs b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/benches/fingerprint.rsnew file mode 100644index 00000000..e3cdca35--- /dev/null+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/benches/fingerprint.rs@@ -0,0 +1,215 @@+// ©AngelaMos | 2026+// fingerprint.rs++//! Throughput benchmarks for the fingerprinting hot path.+//!+//! Two questions matter for a passive sensor: how fast it parses one handshake,+//! and how fast it carries a whole capture through the pipeline. The first+//! benchmark isolates parsing and hashing a single ClientHello; the second+//! replays a vendored capture frame by frame, reporting fingerprints per second+//! against the project target of ten thousand. The capture is read into memory+//! once at setup so the file system never enters the measured loop.++use std::hint::black_box;+use std::path::Path;++use criterion::{Criterion, Throughput, criterion_group, criterion_main};++use tlsfp_core::ja3::ja3;+use tlsfp_core::ja4::{Transport, ja4};+use tlsfp_core::parse::parse_client_hello;+use tlsfp_core::pipeline::source::{PacketSource, PcapFileSource, RawFrame};+use tlsfp_core::pipeline::{Pipeline, PipelineConfig};++/// Captures replayed by the pipeline benchmark, named for the report.+const PCAPS: [(&str, &str); 2] = [+ (+ "tls-handshake",+ concat!(+ env!("CARGO_MANIFEST_DIR"),+ "/../../testdata/pcap/tls-handshake.pcapng"+ ),+ ),+ (+ "browsers-x509",+ concat!(+ env!("CARGO_MANIFEST_DIR"),+ "/../../testdata/pcap/browsers-x509.pcapng"+ ),+ ),+];++/// One captured frame copied into an owned buffer for replay.+struct OwnedFrame {+ ts_nanos: u64,+ link_type: i32,+ data: Vec<u8>,+}++/// Reads every frame of a capture into memory so the benchmark loop measures+/// the pipeline rather than the file system.+fn load_frames(path: &str) -> Vec<OwnedFrame> {+ let mut source = PcapFileSource::open(Path::new(path)).expect("open capture");+ let mut frames = Vec::new();+ while let Some(frame) = source.next_frame().expect("read frame") {+ frames.push(OwnedFrame {+ ts_nanos: frame.ts_nanos,+ link_type: frame.link_type,+ data: frame.data.to_vec(),+ });+ }+ frames+}++/// Replays preloaded frames through a fresh pipeline, returning the event count.+fn replay(frames: &[OwnedFrame]) -> u64 {+ let mut pipeline = Pipeline::new(PipelineConfig::default());+ for frame in frames {+ let raw = RawFrame {+ ts_nanos: frame.ts_nanos,+ link_type: frame.link_type,+ data: &frame.data,+ };+ pipeline.feed(&raw, &mut |event| {+ black_box(&event);+ });+ }+ pipeline.finish();+ pipeline.counters().events+}++fn bench_pipeline(c: &mut Criterion) {+ let mut group = c.benchmark_group("pipeline");+ for (name, path) in PCAPS {+ let frames = load_frames(path);+ let events = replay(&frames).max(1);+ group.throughput(Throughput::Elements(events));+ group.bench_function(name, |b| {+ b.iter(|| black_box(replay(black_box(&frames))));+ });+ }+ group.finish();+}++fn bench_fingerprint(c: &mut Criterion) {+ let body = client_hello_body();+ let hello = parse_client_hello(&body).expect("the benchmark hello parses");++ let mut group = c.benchmark_group("fingerprint");+ group.bench_function("parse_client_hello", |b| {+ b.iter(|| black_box(parse_client_hello(black_box(&body)).expect("parse")));+ });+ group.bench_function("ja3", |b| b.iter(|| black_box(ja3(black_box(&hello)))));+ group.bench_function("ja4", |b| {+ b.iter(|| black_box(ja4(black_box(&hello), Transport::Tcp)));+ });+ group.finish();+}++/// Assembles a representative TLS 1.3 ClientHello body, the input the parser and+/// the hash functions take. The exact bytes are not pinned to any published+/// vector here: this is a throughput fixture, and the conformance vectors live+/// in the integration tests.+fn client_hello_body() -> Vec<u8> {+ const CIPHERS: [u16; 15] = [+ 0x1301, 0x1302, 0x1303, 0xc02b, 0xc02f, 0xc02c, 0xc030, 0xcca9, 0xcca8, 0xc013, 0xc014,+ 0x009c, 0x009d, 0x002f, 0x0035,+ ];+ const GROUPS: [u16; 4] = [0x001d, 0x0017, 0x0018, 0x0019];+ const SIG_ALGS: [u16; 8] = [+ 0x0403, 0x0804, 0x0401, 0x0503, 0x0805, 0x0501, 0x0806, 0x0601,+ ];+ const VERSIONS: [u16; 2] = [0x0304, 0x0303];+ const OPAQUE: [u16; 4] = [0x0005, 0x0017, 0x0023, 0xff01];++ let mut body = Vec::new();+ body.extend_from_slice(&0x0303u16.to_be_bytes());+ body.extend_from_slice(&[0u8; 32]);+ body.push(0);++ let mut ciphers = Vec::new();+ for suite in CIPHERS {+ ciphers.extend_from_slice(&suite.to_be_bytes());+ }+ push_u16(&mut body, &ciphers);+ push_u8(&mut body, &[0]);++ let mut exts = Vec::new();+ add_ext(&mut exts, 0x0000, &sni("example.com"));+ add_ext(&mut exts, 0x000a, &u16_list_u16(&GROUPS));+ add_ext(&mut exts, 0x000b, &u8_list(&[0]));+ add_ext(&mut exts, 0x000d, &u16_list_u16(&SIG_ALGS));+ add_ext(&mut exts, 0x0010, &alpn(&[b"h2", b"http/1.1"]));+ add_ext(&mut exts, 0x002b, &u8_list_u16(&VERSIONS));+ for ext in OPAQUE {+ add_ext(&mut exts, ext, &[]);+ }+ push_u16(&mut body, &exts);+ body+}++fn push_u8(out: &mut Vec<u8>, data: &[u8]) {+ out.push(u8::try_from(data.len()).expect("length fits a byte"));+ out.extend_from_slice(data);+}++fn push_u16(out: &mut Vec<u8>, data: &[u8]) {+ out.extend_from_slice(+ &u16::try_from(data.len())+ .expect("length fits two bytes")+ .to_be_bytes(),+ );+ out.extend_from_slice(data);+}++fn add_ext(out: &mut Vec<u8>, ext_type: u16, data: &[u8]) {+ out.extend_from_slice(&ext_type.to_be_bytes());+ push_u16(out, data);+}++fn sni(host: &str) -> Vec<u8> {+ let mut entry = vec![0u8];+ push_u16(&mut entry, host.as_bytes());+ let mut data = Vec::new();+ push_u16(&mut data, &entry);+ data+}++fn alpn(protocols: &[&[u8]]) -> Vec<u8> {+ let mut list = Vec::new();+ for protocol in protocols {+ push_u8(&mut list, protocol);+ }+ let mut data = Vec::new();+ push_u16(&mut data, &list);+ data+}++fn u16_list_u16(values: &[u16]) -> Vec<u8> {+ let mut list = Vec::new();+ for value in values {+ list.extend_from_slice(&value.to_be_bytes());+ }+ let mut data = Vec::new();+ push_u16(&mut data, &list);+ data+}++fn u8_list_u16(values: &[u16]) -> Vec<u8> {+ let mut list = Vec::new();+ for value in values {+ list.extend_from_slice(&value.to_be_bytes());+ }+ let mut data = Vec::new();+ push_u8(&mut data, &list);+ data+}++fn u8_list(values: &[u8]) -> Vec<u8> {+ let mut data = Vec::new();+ push_u8(&mut data, values);+ data+}++criterion_group!(benches, bench_pipeline, bench_fingerprint);+criterion_main!(benches);diff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/src/pipeline/mod.rs b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/src/pipeline/mod.rsindex 83e951a2..989b8cd6 100644--- a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/src/pipeline/mod.rs+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp-core/src/pipeline/mod.rs@@ -102,6 +102,10 @@ pub struct Counters {pub segments_dropped: u64,pub events: u64,pub streams_capped: u64,+ /// TCP streams recognized as TLS that yielded a complete ClientHello or+ /// ServerHello. The denominator, with `unfinished_tls_streams`, of the miss+ /// rate: how many handshakes the tool actually read.+ pub tls_handshakes_fingerprinted: u64,pub unfinished_tls_streams: u64,/// QUIC long header Initial packets observed, both directions.pub quic_initials: u64,@@ -113,6 +117,28 @@ pub struct Counters {pub quic_version_unsupported: u64,}+impl Counters {+ /// The share of recognized TLS streams the capture clipped before a+ /// complete handshake message could be read.+ ///+ /// A fingerprinting tool that cannot say what it failed to read is one+ /// whose silence gets mistaken for absence. A truncated or multi segment+ /// ClientHello whose later segments never arrived counts as a miss here, so+ /// an operator can tell a clean link from a clipped capture before trusting+ /// the count of fingerprints. Zero recognized streams reports a zero rate+ /// rather than dividing by nothing.+ #[must_use]+ #[allow(clippy::cast_precision_loss)]+ pub fn tls_miss_rate(&self) -> f64 {+ let recognized = self.tls_handshakes_fingerprinted + self.unfinished_tls_streams;+ if recognized == 0 {+ 0.0+ } else {+ self.unfinished_tls_streams as f64 / recognized as f64+ }+ }+}+/// One direction of one tracked flow.struct StreamHalf {reassembler: StreamReassembler,@@ -300,8 +326,15 @@ impl Pipeline {if outcome == PushOutcome::Grew {let mut emitted = 0u64;+ let mut tls_fingerprinted = 0u64;tls::advance(&mut half.protocol, half.reassembler.data(), &mut |event| {emitted += 1;+ if matches!(+ event,+ StreamEvent::ClientHello { .. } | StreamEvent::ServerHello { .. }+ ) {+ tls_fingerprinted += 1;+ }sink(FingerprintEvent {ts_nanos: frame.ts_nanos,src,@@ -310,6 +343,7 @@ impl Pipeline {});});self.counters.events += emitted;+ self.counters.tls_handshakes_fingerprinted += tls_fingerprinted;if half.protocol.finished() && !half.reassembler.released() {half.reassembler.release();}@@ -595,6 +629,47 @@ mod tests {assert!(events[1].to_string().contains("http_request"));}+ #[test]+ fn miss_rate_arithmetic_is_misses_over_recognized() {+ use super::Counters;+ let none = Counters::default();+ assert!(none.tls_miss_rate().abs() < 1e-9);++ let clean = Counters {+ tls_handshakes_fingerprinted: 4,+ unfinished_tls_streams: 0,+ ..Counters::default()+ };+ assert!(clean.tls_miss_rate().abs() < 1e-9);++ let clipped = Counters {+ tls_handshakes_fingerprinted: 3,+ unfinished_tls_streams: 1,+ ..Counters::default()+ };+ assert!((clipped.tls_miss_rate() - 0.25).abs() < 1e-9);+ }++ #[test]+ fn clipped_tls_handshake_counts_as_a_miss() {+ let client = ([10, 0, 0, 1], 40002);+ let server = ([10, 0, 0, 2], 443);+ let clipped_client_hello = [+ 0x16, 0x03, 0x01, 0x01, 0x00, 0x01, 0x00, 0x00, 0xfa, 0x03, 0x03,+ ];++ let frames = vec![tcp_frame(client, server, 1000, &clipped_client_hello)];+ let mut pipeline = Pipeline::new(PipelineConfig::default());+ let events = feed_all(&mut pipeline, &frames);+ pipeline.finish();++ assert!(events.is_empty());+ let counters = pipeline.counters();+ assert_eq!(counters.tls_handshakes_fingerprinted, 0);+ assert_eq!(counters.unfinished_tls_streams, 1);+ assert!((counters.tls_miss_rate() - 1.0).abs() < 1e-9);+ }+#[test]fn pressure_eviction_keeps_the_table_bounded() {let config = PipelineConfig {diff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/cli.rs b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/cli.rsindex 2f0993fe..00733510 100644--- a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/cli.rs+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/cli.rs@@ -3,7 +3,7 @@use std::io::Write as _;use std::path::{Path, PathBuf};-use std::time::Duration;+use std::time::{Duration, Instant};use anyhow::{Context, Result};use clap::{Parser, Subcommand};@@ -12,6 +12,7 @@ use tracing_subscriber::EnvFilter;use tlsfp_core::{FingerprintEvent, PcapFileSource, Pipeline, PipelineConfig, SourceError};use crate::live::{DEFAULT_BPF_FILTER, LiveConfig, LiveSource};+use crate::report::ReportBuilder;use crate::serve::{self, ServeConfig, Source};use tlsfp_intel::{Alert, FpKind, IntelStore, MatchReport, MatchStrength, default_db_path};@@ -54,6 +55,16 @@ pub enum Command {#[arg(long)]detect: bool,+ /// Print a single forensic summary of the whole capture instead of one+ /// line per handshake. When an intelligence database is present it also+ /// folds in match verdicts and detection alerts.+ #[arg(long)]+ report: bool,++ /// How many rows each ranked section of the report shows.+ #[arg(long, default_value_t = crate::report::DEFAULT_TOP)]+ top: usize,+/// Path to the intelligence database, defaulting to the data directory.#[arg(long)]db: Option<PathBuf>,@@ -251,8 +262,10 @@ impl Cli {json,intel,detect,+ report,+ top,db,- } => run_pcap(&path, json, intel, detect, db.as_deref()),+ } => run_pcap(&path, json, intel, detect, report, top, db.as_deref()),Command::Live {interface,json,@@ -318,7 +331,19 @@ impl IntelCommand {/// The summary goes to the log rather than stdout so that piping the output/// into a tool sees only events, while a human still learns how much of the/// capture was readable and whether the file was cut short mid packet.-fn run_pcap(path: &Path, json: bool, intel: bool, detect: bool, db: Option<&Path>) -> Result<()> {+#[allow(clippy::fn_params_excessive_bools)]+fn run_pcap(+ path: &Path,+ json: bool,+ intel: bool,+ detect: bool,+ report: bool,+ top: usize,+ db: Option<&Path>,+) -> Result<()> {+ if report {+ return run_pcap_report(path, json, top, db);+ }let mut source = PcapFileSource::open(path).with_context(|| format!("cannot open capture {}", path.display()))?;let mut store = open_for_run(intel, detect, db)?;@@ -356,7 +381,9 @@ fn run_pcap(path: &Path, json: bool, intel: bool, detect: bool, db: Option<&Pathquic_initials = counters.quic_initials,quic_decrypted = counters.quic_decrypted,quic_version_unsupported = counters.quic_version_unsupported,+ tls_handshakes = counters.tls_handshakes_fingerprinted,unfinished_tls_streams = counters.unfinished_tls_streams,+ tls_miss_rate = counters.tls_miss_rate(),segments_dropped = counters.segments_dropped,"capture processed");@@ -366,6 +393,70 @@ fn run_pcap(path: &Path, json: bool, intel: bool, detect: bool, db: Option<&PathOk(())}+/// Reads a whole capture and prints one forensic summary instead of a stream+/// of events.+///+/// Unlike the streaming path, the report builds an in process picture of every+/// endpoint, fingerprint, and miss before printing, so it folds intelligence+/// and detection in automatically whenever a database is present rather than+/// asking for the flags. With no database it falls back to a pure fingerprint+/// inventory. The intel lookups and detection writes are the same calls the+/// streaming path makes, so the report can never disagree with a live sensor+/// pointed at the same store.+fn run_pcap_report(path: &Path, json: bool, top: usize, db: Option<&Path>) -> Result<()> {+ let mut source = PcapFileSource::open(path)+ .with_context(|| format!("cannot open capture {}", path.display()))?;+ let mut store = open_for_report(db)?;+ let enabled = store.is_some();+ let mut pipeline = Pipeline::new(PipelineConfig::default());+ let mut builder = ReportBuilder::new(&path.display().to_string());++ let started = Instant::now();+ pipeline.run(&mut source, |event| {+ let reports = if enabled {+ enrich(store.as_ref(), &event)+ } else {+ Vec::new()+ };+ let alerts = detect_event(store.as_mut(), enabled, &event);+ builder.observe(&event, &reports, &alerts);+ })?;+ let elapsed = started.elapsed();++ let report = builder.finish(*pipeline.counters(), source.truncated(), elapsed, top);+ let stdout = std::io::stdout().lock();+ let mut out = std::io::BufWriter::new(stdout);+ if json {+ serde_json::to_writer_pretty(&mut out, &report).context("writing report as JSON")?;+ writeln!(out).context("writing report as JSON")?;+ } else {+ write!(out, "{}", report.render_text()).context("writing report")?;+ }+ out.flush().context("flushing the report to stdout")?;+ Ok(())+}++/// Opens the store for a report run. A report folds in intelligence and+/// detection whenever a database is there to answer, so this opens an existing+/// database but never creates one: a forensic read of a capture should not+/// quietly leave a new database behind, and with none present the report is+/// still a complete fingerprint inventory.+fn open_for_report(db: Option<&Path>) -> Result<Option<IntelStore>> {+ let path = db.map_or_else(default_db_path, Path::to_path_buf);+ if path.exists() {+ tracing::info!(+ path = %path.display(),+ "matching and recording detections against the intelligence database"+ );+ return Ok(Some(open_or_create(&path)?));+ }+ tracing::info!(+ path = %path.display(),+ "no intelligence database found; reporting fingerprints only, run 'tlsfp intel seed' to add verdicts"+ );+ Ok(None)+}+/// Builds the dashboard configuration from the command line and starts the/// server. The live feed is a replayed capture, a live interface, or, by/// default, the alerts an external sensor tails into the same database.@@ -507,7 +598,9 @@ async fn drive_live(quic_initials = counters.quic_initials,quic_decrypted = counters.quic_decrypted,quic_version_unsupported = counters.quic_version_unsupported,+ tls_handshakes = counters.tls_handshakes_fingerprinted,unfinished_tls_streams = counters.unfinished_tls_streams,+ tls_miss_rate = counters.tls_miss_rate(),segments_dropped = counters.segments_dropped,"live capture stopped");diff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/main.rs b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/main.rsindex 2c216670..d16dddbe 100644--- a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/main.rs+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/main.rs@@ -3,6 +3,7 @@mod cli;mod live;+mod report;mod serve;use anyhow::Result;diff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/report.rs b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/report.rsnew file mode 100644index 00000000..5ddac4e0--- /dev/null+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/src/report.rs@@ -0,0 +1,727 @@+// ©AngelaMos | 2026+// report.rs++//! The forensic batch report for a capture file.+//!+//! Where the streaming `pcap` output prints one line per handshake as it is+//! read, the report holds the whole capture in mind and answers the questions+//! an analyst asks after the fact: who spoke, what they presented, which+//! fingerprints the intelligence database recognised, what the detection rules+//! flagged, and, just as important, how much of the capture the tool could not+//! read. The last part is the honesty section: a miss rate and a throughput+//! that let a reader tell a clean capture from a clipped one before trusting an+//! absence of fingerprints.+//!+//! The aggregation is fed one event at a time so a multi gigabyte capture never+//! has to be held in memory at once; only the distinct fingerprints, endpoints,+//! and names survive between events. The [`Report`] it produces serialises+//! straight to JSON and renders to aligned text, and the builder is unit tested+//! on synthetic events with no capture file in the picture.++use std::collections::{BTreeMap, BTreeSet, HashMap, HashSet};+use std::fmt::Write as _;+use std::net::IpAddr;+use std::time::Duration;++use serde::Serialize;++use tlsfp_core::{Counters, FingerprintEvent, StreamEvent};+use tlsfp_intel::{Alert, MatchReport, Verdict};++/// How many rows each ranked section shows by default.+pub const DEFAULT_TOP: usize = 15;++/// One endpoint's running inventory while the capture is being read.+#[derive(Default)]+struct EndpointAgg {+ events: u64,+ ja4: BTreeSet<String>,+ ja4s: BTreeSet<String>,+ ja4t: BTreeSet<String>,+ ja4h: BTreeSet<String>,+ ja4x: BTreeSet<String>,+ sni: BTreeSet<String>,+ user_agents: BTreeSet<String>,+ worst_verdict: Option<Verdict>,+ alerts: u64,+}++/// One intelligence finding's running aggregate, keyed by fingerprint.+struct IntelAgg {+ verdict: Verdict,+ threat_score: f64,+ label: String,+ source: String,+ endpoints: BTreeSet<String>,+}++/// Accumulates a capture into a [`Report`], one event at a time.+pub struct ReportBuilder {+ source: String,+ first_ts: Option<u64>,+ last_ts: Option<u64>,+ endpoints: HashMap<IpAddr, EndpointAgg>,+ by_kind: BTreeMap<&'static str, u64>,+ ja4_counts: HashMap<String, u64>,+ ja4_endpoints: HashMap<String, HashSet<IpAddr>>,+ sni_counts: HashMap<String, u64>,+ intel: HashMap<(String, String), IntelAgg>,+ alerts: Vec<Alert>,+}++impl ReportBuilder {+ #[must_use]+ pub fn new(source: &str) -> Self {+ Self {+ source: source.to_owned(),+ first_ts: None,+ last_ts: None,+ endpoints: HashMap::new(),+ by_kind: BTreeMap::new(),+ ja4_counts: HashMap::new(),+ ja4_endpoints: HashMap::new(),+ sni_counts: HashMap::new(),+ intel: HashMap::new(),+ alerts: Vec::new(),+ }+ }++ /// Folds one event, with any intelligence and alerts it produced, into the+ /// running aggregates.+ pub fn observe(&mut self, event: &FingerprintEvent, reports: &[MatchReport], alerts: &[Alert]) {+ self.first_ts = Some(+ self.first_ts+ .map_or(event.ts_nanos, |t| t.min(event.ts_nanos)),+ );+ self.last_ts = Some(+ self.last_ts+ .map_or(event.ts_nanos, |t| t.max(event.ts_nanos)),+ );++ let ip = event.src.ip();+ *self.by_kind.entry(kind_label(&event.event)).or_insert(0) += 1;+ let endpoint = self.endpoints.entry(ip).or_default();+ endpoint.events += 1;++ match &event.event {+ StreamEvent::ClientHello { ja4, sni, .. } => {+ endpoint.ja4.insert(ja4.hash.clone());+ *self.ja4_counts.entry(ja4.hash.clone()).or_insert(0) += 1;+ self.ja4_endpoints+ .entry(ja4.hash.clone())+ .or_default()+ .insert(ip);+ if let Some(name) = sni {+ endpoint.sni.insert(name.clone());+ *self.sni_counts.entry(name.clone()).or_insert(0) += 1;+ }+ }+ StreamEvent::ServerHello { ja4s, .. } => {+ endpoint.ja4s.insert(ja4s.hash.clone());+ }+ StreamEvent::Certificate { ja4x } => {+ endpoint.ja4x.insert(ja4x.clone());+ }+ StreamEvent::HttpRequest {+ ja4h, user_agent, ..+ } => {+ endpoint.ja4h.insert(ja4h.hash.clone());+ if let Some(agent) = user_agent {+ endpoint.user_agents.insert(agent.clone());+ }+ }+ StreamEvent::TcpSyn { ja4t } => {+ endpoint.ja4t.insert(ja4t.clone());+ }+ StreamEvent::TcpSynAck { .. } => {}+ }++ for report in reports {+ endpoint.worst_verdict = Some(worse(endpoint.worst_verdict, report.verdict));+ let key = (report.kind.as_str().to_owned(), report.observed.clone());+ let best = report+ .hits+ .iter()+ .max_by(|a, b| a.strength.weight().total_cmp(&b.strength.weight()));+ let agg = self.intel.entry(key).or_insert_with(|| IntelAgg {+ verdict: report.verdict,+ threat_score: report.threat_score,+ label: best.map_or_else(|| "-".to_owned(), |hit| hit.label.clone()),+ source: best.map_or_else(|| "-".to_owned(), |hit| hit.source.clone()),+ endpoints: BTreeSet::new(),+ });+ agg.threat_score = agg.threat_score.max(report.threat_score);+ agg.endpoints.insert(ip.to_string());+ }++ endpoint.alerts += u64::try_from(alerts.len()).unwrap_or(u64::MAX);+ self.alerts.extend_from_slice(alerts);+ }++ /// Closes the books and produces the report from the running aggregates,+ /// the pipeline's final counters, and the wall clock the run took.+ #[must_use]+ pub fn finish(+ self,+ counters: Counters,+ truncated: bool,+ elapsed: Duration,+ top: usize,+ ) -> Report {+ let duration_secs = match (self.first_ts, self.last_ts) {+ (Some(first), Some(last)) => nanos_to_secs(last.saturating_sub(first)),+ _ => 0.0,+ };++ let mut endpoints: Vec<EndpointSummary> = self+ .endpoints+ .into_iter()+ .map(|(ip, agg)| EndpointSummary {+ ip: ip.to_string(),+ events: agg.events,+ ja4: agg.ja4.into_iter().collect(),+ ja4s: agg.ja4s.into_iter().collect(),+ ja4t: agg.ja4t.into_iter().collect(),+ ja4h: agg.ja4h.into_iter().collect(),+ ja4x: agg.ja4x.into_iter().collect(),+ sni: agg.sni.into_iter().collect(),+ user_agents: agg.user_agents.into_iter().collect(),+ verdict: agg.worst_verdict.map(|v| v.as_str().to_owned()),+ alerts: agg.alerts,+ })+ .collect();+ endpoints.sort_by(|a, b| b.events.cmp(&a.events).then_with(|| a.ip.cmp(&b.ip)));++ let top_ja4 = rank(&self.ja4_counts, top, |value| FpCount {+ value: value.clone(),+ count: self.ja4_counts[value],+ endpoints: self.ja4_endpoints.get(value).map_or(0, HashSet::len),+ });+ let top_sni = rank(&self.sni_counts, top, |value| NameCount {+ name: value.clone(),+ count: self.sni_counts[value],+ });+ let by_kind = self+ .by_kind+ .iter()+ .map(|(kind, count)| KindCount {+ kind: (*kind).to_owned(),+ count: *count,+ })+ .collect();++ let mut intel: Vec<IntelFinding> = self+ .intel+ .into_iter()+ .map(|((kind, value), agg)| IntelFinding {+ kind,+ value,+ verdict: agg.verdict.as_str().to_owned(),+ threat_score: agg.threat_score,+ label: agg.label,+ source: agg.source,+ endpoints: agg.endpoints.into_iter().collect(),+ })+ .collect();+ intel.sort_by(|a, b| {+ b.threat_score+ .total_cmp(&a.threat_score)+ .then_with(|| a.value.cmp(&b.value))+ });+ intel.truncate(top);++ let alerts = AlertSummary::from_alerts(&self.alerts, top);++ Report {+ capture: CaptureSummary {+ source: self.source,+ frames: counters.frames,+ bytes: counters.bytes,+ tcp_segments: counters.tcp_segments,+ udp_datagrams: counters.udp_datagrams,+ events: counters.events,+ flows: counters.flows_created,+ duration_secs,+ truncated,+ },+ distribution: Distribution {+ by_kind,+ top_ja4,+ top_sni,+ },+ endpoints,+ intel,+ alerts,+ coverage: Coverage::derive(&counters, elapsed),+ }+ }+}++/// The full forensic report, ready to serialise or render.+#[derive(Debug, Serialize)]+pub struct Report {+ pub capture: CaptureSummary,+ pub distribution: Distribution,+ pub endpoints: Vec<EndpointSummary>,+ pub intel: Vec<IntelFinding>,+ pub alerts: AlertSummary,+ pub coverage: Coverage,+}++#[derive(Debug, Serialize)]+pub struct CaptureSummary {+ pub source: String,+ pub frames: u64,+ pub bytes: u64,+ pub tcp_segments: u64,+ pub udp_datagrams: u64,+ pub events: u64,+ pub flows: u64,+ pub duration_secs: f64,+ pub truncated: bool,+}++#[derive(Debug, Serialize)]+pub struct Distribution {+ pub by_kind: Vec<KindCount>,+ pub top_ja4: Vec<FpCount>,+ pub top_sni: Vec<NameCount>,+}++#[derive(Debug, Serialize)]+pub struct KindCount {+ pub kind: String,+ pub count: u64,+}++#[derive(Debug, Serialize)]+pub struct FpCount {+ pub value: String,+ pub count: u64,+ pub endpoints: usize,+}++#[derive(Debug, Serialize)]+pub struct NameCount {+ pub name: String,+ pub count: u64,+}++#[derive(Debug, Serialize)]+pub struct EndpointSummary {+ pub ip: String,+ pub events: u64,+ pub ja4: Vec<String>,+ pub ja4s: Vec<String>,+ pub ja4t: Vec<String>,+ pub ja4h: Vec<String>,+ pub ja4x: Vec<String>,+ pub sni: Vec<String>,+ pub user_agents: Vec<String>,+ pub verdict: Option<String>,+ pub alerts: u64,+}++#[derive(Debug, Serialize)]+pub struct IntelFinding {+ pub kind: String,+ pub value: String,+ pub verdict: String,+ pub threat_score: f64,+ pub label: String,+ pub source: String,+ pub endpoints: Vec<String>,+}++#[derive(Debug, Serialize)]+pub struct AlertSummary {+ pub total: u64,+ pub by_rule: Vec<RuleCount>,+ pub recent: Vec<Alert>,+}++impl AlertSummary {+ fn from_alerts(alerts: &[Alert], top: usize) -> Self {+ let mut by_rule: BTreeMap<&'static str, u64> = BTreeMap::new();+ for alert in alerts {+ *by_rule.entry(alert.rule.as_str()).or_insert(0) += 1;+ }+ let mut counts: Vec<RuleCount> = by_rule+ .into_iter()+ .map(|(rule, count)| RuleCount {+ rule: rule.to_owned(),+ count,+ })+ .collect();+ counts.sort_by(|a, b| b.count.cmp(&a.count).then_with(|| a.rule.cmp(&b.rule)));++ let recent = alerts.iter().rev().take(top).cloned().collect();+ Self {+ total: u64::try_from(alerts.len()).unwrap_or(u64::MAX),+ by_rule: counts,+ recent,+ }+ }+}++#[derive(Debug, Serialize)]+pub struct RuleCount {+ pub rule: String,+ pub count: u64,+}++#[derive(Debug, Serialize)]+pub struct Coverage {+ pub counters: Counters,+ pub tls_miss_rate: f64,+ pub quic_decrypt_rate: f64,+ pub events_per_sec: f64,+ pub frames_per_sec: f64,+ pub megabits_per_sec: f64,+}++impl Coverage {+ #[allow(clippy::cast_precision_loss)]+ fn derive(counters: &Counters, elapsed: Duration) -> Self {+ let secs = elapsed.as_secs_f64();+ let per_sec = |n: u64| if secs > 0.0 { n as f64 / secs } else { 0.0 };+ let quic_decrypt_rate = if counters.quic_initials == 0 {+ 0.0+ } else {+ counters.quic_decrypted as f64 / counters.quic_initials as f64+ };+ Self {+ counters: *counters,+ tls_miss_rate: counters.tls_miss_rate(),+ quic_decrypt_rate,+ events_per_sec: per_sec(counters.events),+ frames_per_sec: per_sec(counters.frames),+ megabits_per_sec: if secs > 0.0 {+ (counters.bytes as f64 * 8.0) / 1_000_000.0 / secs+ } else {+ 0.0+ },+ }+ }+}++impl Report {+ /// Renders the report as aligned, sectioned text for a terminal reader.+ #[must_use]+ pub fn render_text(&self) -> String {+ let mut out = String::new();+ self.render_capture(&mut out);+ self.render_distribution(&mut out);+ self.render_endpoints(&mut out);+ self.render_intel(&mut out);+ self.render_alerts(&mut out);+ self.render_coverage(&mut out);+ out+ }++ fn render_capture(&self, out: &mut String) {+ let c = &self.capture;+ let _ = writeln!(out, "== capture ==");+ let _ = writeln!(out, " source {}", c.source);+ let _ = writeln!(out, " frames {}", c.frames);+ let _ = writeln!(out, " bytes {}", c.bytes);+ let _ = writeln!(out, " tcp segments {}", c.tcp_segments);+ let _ = writeln!(out, " udp datagrams {}", c.udp_datagrams);+ let _ = writeln!(out, " flows {}", c.flows);+ let _ = writeln!(out, " fingerprints {}", c.events);+ let _ = writeln!(out, " capture span {:.3}s", c.duration_secs);+ if c.truncated {+ let _ = writeln!(out, " truncated yes (file ended mid packet)");+ }+ }++ fn render_distribution(&self, out: &mut String) {+ let d = &self.distribution;+ let _ = writeln!(out, "\n== fingerprints by kind ==");+ if d.by_kind.is_empty() {+ let _ = writeln!(out, " none");+ }+ for row in &d.by_kind {+ let _ = writeln!(out, " {:<16} {}", row.kind, row.count);+ }++ let _ = writeln!(out, "\n== top client ja4 ==");+ if d.top_ja4.is_empty() {+ let _ = writeln!(out, " none");+ }+ for row in &d.top_ja4 {+ let _ = writeln!(+ out,+ " {:<40} {:>5} across {} endpoint(s)",+ row.value, row.count, row.endpoints+ );+ }++ if !d.top_sni.is_empty() {+ let _ = writeln!(out, "\n== top server names ==");+ for row in &d.top_sni {+ let _ = writeln!(out, " {:<40} {:>5}", row.name, row.count);+ }+ }+ }++ fn render_endpoints(&self, out: &mut String) {+ let _ = writeln!(out, "\n== endpoints ==");+ if self.endpoints.is_empty() {+ let _ = writeln!(out, " none");+ }+ for endpoint in &self.endpoints {+ let verdict = endpoint.verdict.as_deref().unwrap_or("-");+ let _ = writeln!(+ out,+ " {} ({} event(s), verdict {}, {} alert(s))",+ endpoint.ip, endpoint.events, verdict, endpoint.alerts+ );+ write_list(out, "ja4", &endpoint.ja4);+ write_list(out, "ja4s", &endpoint.ja4s);+ write_list(out, "ja4t", &endpoint.ja4t);+ write_list(out, "ja4h", &endpoint.ja4h);+ write_list(out, "ja4x", &endpoint.ja4x);+ write_list(out, "sni", &endpoint.sni);+ write_list(out, "ua", &endpoint.user_agents);+ }+ }++ fn render_intel(&self, out: &mut String) {+ let _ = writeln!(out, "\n== intelligence ==");+ if self.intel.is_empty() {+ let _ = writeln!(out, " no fingerprints matched the database");+ return;+ }+ for finding in &self.intel {+ let _ = writeln!(+ out,+ " [{}] {} {} (threat {:.2})",+ finding.verdict, finding.kind, finding.value, finding.threat_score+ );+ let _ = writeln!(+ out,+ " {} ({}), {} endpoint(s)",+ finding.label,+ finding.source,+ finding.endpoints.len()+ );+ }+ }++ fn render_alerts(&self, out: &mut String) {+ let _ = writeln!(out, "\n== alerts ==");+ if self.alerts.total == 0 {+ let _ = writeln!(out, " none raised");+ return;+ }+ let _ = writeln!(out, " {} total", self.alerts.total);+ for row in &self.alerts.by_rule {+ let _ = writeln!(out, " {:<14} {}", row.rule, row.count);+ }+ let _ = writeln!(out, " most recent:");+ for alert in &self.alerts.recent {+ let target = alert.ip.as_deref().unwrap_or("-");+ let _ = writeln!(+ out,+ " [{}] {} {} {}",+ alert.severity.as_str(),+ alert.rule.as_str(),+ target,+ alert.title+ );+ }+ }++ fn render_coverage(&self, out: &mut String) {+ let c = &self.coverage;+ let _ = writeln!(out, "\n== coverage ==");+ let _ = writeln!(+ out,+ " tls miss rate {:.1}% ({} read, {} clipped)",+ c.tls_miss_rate * 100.0,+ c.counters.tls_handshakes_fingerprinted,+ c.counters.unfinished_tls_streams+ );+ let _ = writeln!(out, " streams capped {}", c.counters.streams_capped);+ let _ = writeln!(out, " segments dropped {}", c.counters.segments_dropped);+ let _ = writeln!(+ out,+ " quic initials {} ({} decrypted, {:.0}%, {} unsupported version)",+ c.counters.quic_initials,+ c.counters.quic_decrypted,+ c.quic_decrypt_rate * 100.0,+ c.counters.quic_version_unsupported+ );+ let _ = writeln!(+ out,+ " throughput {:.0} fp/s, {:.0} frames/s, {:.1} Mb/s",+ c.events_per_sec, c.frames_per_sec, c.megabits_per_sec+ );+ }+}++/// Writes one labelled line listing a set's values, skipping an empty set.+fn write_list(out: &mut String, label: &str, values: &[String]) {+ if values.is_empty() {+ return;+ }+ let _ = writeln!(out, " {:<5} {}", label, values.join(", "));+}++/// The snake case name a stream event carries, matching its serialised tag.+fn kind_label(event: &StreamEvent) -> &'static str {+ match event {+ StreamEvent::ClientHello { .. } => "client_hello",+ StreamEvent::ServerHello { .. } => "server_hello",+ StreamEvent::Certificate { .. } => "certificate",+ StreamEvent::HttpRequest { .. } => "http_request",+ StreamEvent::TcpSyn { .. } => "tcp_syn",+ StreamEvent::TcpSynAck { .. } => "tcp_syn_ack",+ }+}++/// Ranks the keys of a count map by count descending then key ascending,+/// keeping the top `n` and mapping each through `build`.+fn rank<T>(counts: &HashMap<String, u64>, n: usize, build: impl Fn(&String) -> T) -> Vec<T> {+ let mut keys: Vec<&String> = counts.keys().collect();+ keys.sort_by(|a, b| counts[*b].cmp(&counts[*a]).then_with(|| a.cmp(b)));+ keys.into_iter().take(n).map(build).collect()+}++/// The more alarming of two verdicts, used to fold an endpoint's worst case.+fn worse(current: Option<Verdict>, next: Verdict) -> Verdict {+ let rank = |v: Verdict| match v {+ Verdict::Malicious => 3,+ Verdict::Suspicious => 2,+ Verdict::Unknown => 1,+ Verdict::Benign => 0,+ };+ match current {+ Some(existing) if rank(existing) >= rank(next) => existing,+ _ => next,+ }+}++/// Converts whole nanoseconds to fractional seconds without the precision loss+/// lint, accepting that a capture span beyond `u32::MAX` seconds is unreachable.+#[allow(clippy::cast_precision_loss)]+fn nanos_to_secs(nanos: u64) -> f64 {+ nanos as f64 / 1_000_000_000.0+}++#[cfg(test)]+mod tests {+ use std::time::Duration;++ use tlsfp_core::{Counters, FingerprintEvent, Ja3, Ja4Family, StreamEvent};+ use tlsfp_intel::{Alert, AlertSeverity, FpKind, IntelHit, MatchReport, MatchStrength, Rule};++ use super::ReportBuilder;++ fn client_hello(ip: &str, ja4: &str, sni: &str) -> FingerprintEvent {+ FingerprintEvent {+ ts_nanos: 1_000_000_000,+ src: format!("{ip}:40000").parse().unwrap(),+ dst: "10.0.0.2:443".parse().unwrap(),+ event: StreamEvent::ClientHello {+ ja3: Ja3::from_digest([0u8; 16]),+ ja3_raw: String::new(),+ ja4: Ja4Family::new(ja4.to_owned(), String::new()),+ sni: Some(sni.to_owned()),+ alpn: None,+ },+ }+ }++ #[test]+ fn aggregates_endpoints_and_distribution() {+ let mut builder = ReportBuilder::new("test.pcap");+ builder.observe(+ &client_hello("10.0.0.1", "t13d1516h2_aaaa_bbbb", "a.example"),+ &[],+ &[],+ );+ builder.observe(+ &client_hello("10.0.0.1", "t13d1516h2_aaaa_bbbb", "b.example"),+ &[],+ &[],+ );+ builder.observe(+ &client_hello("10.0.0.9", "t13d1516h2_aaaa_bbbb", "a.example"),+ &[],+ &[],+ );++ let report = builder.finish(Counters::default(), false, Duration::from_millis(10), 15);++ assert_eq!(report.endpoints.len(), 2);+ assert_eq!(report.endpoints[0].ip, "10.0.0.1");+ assert_eq!(report.endpoints[0].events, 2);+ assert_eq!(report.distribution.top_ja4.len(), 1);+ assert_eq!(report.distribution.top_ja4[0].count, 3);+ assert_eq!(report.distribution.top_ja4[0].endpoints, 2);+ assert_eq!(report.distribution.top_sni[0].count, 2);+ }++ #[test]+ fn folds_intel_and_alerts_into_worst_verdict() {+ let mut builder = ReportBuilder::new("test.pcap");+ let event = client_hello("10.0.0.1", "t13d1516h2_aaaa_bbbb", "evil.example");+ let report = MatchReport::from_hits(+ FpKind::Ja4,+ "t13d1516h2_aaaa_bbbb".to_owned(),+ vec![IntelHit {+ kind: FpKind::Ja4,+ value: "t13d1516h2_aaaa_bbbb".to_owned(),+ label: "Cobalt Strike".to_owned(),+ category: tlsfp_intel::Category::Malware,+ source: "test-feed".to_owned(),+ reference: None,+ strength: MatchStrength::Exact,+ }],+ );+ let alert = Alert {+ ts_nanos: 1_000_000_000,+ rule: Rule::KnownBad,+ severity: AlertSeverity::Critical,+ ip: Some("10.0.0.1".to_owned()),+ fp_kind: Some(FpKind::Ja4),+ fp_value: Some("t13d1516h2_aaaa_bbbb".to_owned()),+ title: "known bad fingerprint".to_owned(),+ detail: "matched test-feed".to_owned(),+ score: Some(1.0),+ };+ builder.observe(&event, &[report], &[alert]);++ let built = builder.finish(Counters::default(), false, Duration::from_millis(5), 15);+ assert_eq!(built.endpoints[0].verdict.as_deref(), Some("malicious"));+ assert_eq!(built.endpoints[0].alerts, 1);+ assert_eq!(built.intel.len(), 1);+ assert_eq!(built.intel[0].label, "Cobalt Strike");+ assert_eq!(built.alerts.total, 1);+ assert_eq!(built.alerts.by_rule[0].rule, "known_bad");++ let text = built.render_text();+ assert!(text.contains("== coverage =="));+ assert!(text.contains("Cobalt Strike"));+ }++ #[test]+ fn miss_rate_and_throughput_reach_the_report() {+ let counters = Counters {+ frames: 1000,+ bytes: 1_000_000,+ events: 200,+ tls_handshakes_fingerprinted: 3,+ unfinished_tls_streams: 1,+ ..Counters::default()+ };+ let builder = ReportBuilder::new("test.pcap");+ let report = builder.finish(counters, true, Duration::from_secs(1), 15);+ assert!((report.coverage.tls_miss_rate - 0.25).abs() < 1e-9);+ assert!((report.coverage.events_per_sec - 200.0).abs() < 1e-9);+ assert!(report.capture.truncated);+ assert!(report.render_text().contains("truncated"));+ }+}diff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/tests/report.rs b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/tests/report.rsnew file mode 100644index 00000000..54c33e67--- /dev/null+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/crates/tlsfp/tests/report.rs@@ -0,0 +1,118 @@+// ©AngelaMos | 2026+// report.rs++//! End to end coverage of the forensic report mode.+//!+//! These drive the real binary against a vendored capture the way an analyst+//! would, then assert on what it prints. The capture is read with a database+//! path that does not exist, so the report runs as a pure fingerprint inventory+//! with no intelligence side effects and no dependence on a seeded store, which+//! keeps the test hermetic.++use std::path::PathBuf;+use std::process::Command;++/// The vendored capture used throughout: a browser session with TLS, QUIC, and+/// certificate handshakes, enough to exercise every section of the report.+fn capture() -> PathBuf {+ PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../testdata/pcap/tls-handshake.pcapng")+}++/// A database path under the temp directory that is guaranteed not to exist, so+/// the report stays a pure inventory and never writes a store behind the test.+fn absent_db() -> PathBuf {+ std::env::temp_dir().join(format!(+ "tlsfp-report-test-{}-absent.db",+ std::process::id()+ ))+}++fn run(args: &[&str]) -> std::process::Output {+ Command::new(env!("CARGO_BIN_EXE_tlsfp"))+ .args(args)+ .output()+ .expect("running the tlsfp binary")+}++#[test]+fn text_report_has_every_section() {+ let db = absent_db();+ let output = run(&[+ "pcap",+ capture().to_str().unwrap(),+ "--report",+ "--db",+ db.to_str().unwrap(),+ ]);+ assert!(output.status.success(), "report run failed");+ let text = String::from_utf8(output.stdout).expect("utf8 report");++ for section in [+ "== capture ==",+ "== fingerprints by kind ==",+ "== top client ja4 ==",+ "== endpoints ==",+ "== intelligence ==",+ "== alerts ==",+ "== coverage ==",+ ] {+ assert!(text.contains(section), "missing section {section}");+ }+ assert!(text.contains("t13d1516h2_8daaf6152771_e5627efa2ab1"));+ assert!(text.contains("q13d0310h3_55b375c5d22e_cd85d2d88918"));+ assert!(text.contains("tls miss rate"));+ assert!(text.contains("fp/s"));+ assert!(!db.exists(), "report must not create a database");+}++#[test]+fn json_report_is_well_formed() {+ let db = absent_db();+ let output = run(&[+ "pcap",+ capture().to_str().unwrap(),+ "--report",+ "--json",+ "--db",+ db.to_str().unwrap(),+ ]);+ assert!(output.status.success(), "json report run failed");+ let value: serde_json::Value =+ serde_json::from_slice(&output.stdout).expect("report is valid JSON");++ assert!(value["capture"]["frames"].as_u64().unwrap() > 0);+ assert!(+ value["coverage"]["counters"]["tls_handshakes_fingerprinted"]+ .as_u64()+ .unwrap()+ > 0+ );+ assert!(value["coverage"]["events_per_sec"].as_f64().unwrap() > 0.0);+ assert!(+ !value["distribution"]["top_ja4"]+ .as_array()+ .unwrap()+ .is_empty()+ );+ let endpoints = value["endpoints"].as_array().unwrap();+ assert!(endpoints.iter().any(|e| e["ip"] == "192.168.1.168"));+}++#[test]+fn top_flag_caps_ranked_rows() {+ let db = absent_db();+ let output = run(&[+ "pcap",+ capture().to_str().unwrap(),+ "--report",+ "--json",+ "--top",+ "2",+ "--db",+ db.to_str().unwrap(),+ ]);+ assert!(output.status.success(), "capped report run failed");+ let value: serde_json::Value =+ serde_json::from_slice(&output.stdout).expect("report is valid JSON");+ assert!(value["distribution"]["top_sni"].as_array().unwrap().len() <= 2);+}diff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/index.html b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/index.htmlindex 6f8ff938..24f7bb19 100644--- a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/index.html+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/index.html@@ -28,7 +28,7 @@http-equiv="Content-Security-Policy"content="default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self'; connect-src 'self'; form-action 'self'; worker-src 'self' blob:;"/>- <title>JA3/JA4 TLS Fingerprinting</title>+ <title>MKUtra Valedictorian</title><metaname="description"content="*Cracked*"diff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/android-chrome-192x192.png b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/android-chrome-192x192.pngindex 6a31898f..ef349fa0 100644Binary files a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/android-chrome-192x192.png and b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/android-chrome-192x192.png differdiff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/android-chrome-512x512.png b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/android-chrome-512x512.pngindex e79bc036..21b60186 100644Binary files a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/android-chrome-512x512.png and b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/android-chrome-512x512.png differdiff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/apple-touch-icon.png b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/apple-touch-icon.pngindex be0c040a..f20f47b1 100644Binary files a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/apple-touch-icon.png and b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/apple-touch-icon.png differdiff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon-16x16.png b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon-16x16.pngindex 32c2cf96..19666113 100644Binary files a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon-16x16.png and b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon-16x16.png differdiff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon-32x32.png b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon-32x32.pngindex 87c75f42..6f7aee7a 100644Binary files a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon-32x32.png and b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon-32x32.png differdiff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon.ico b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon.icoindex 6c43eeac..cbdac2dc 100644Binary files a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon.ico and b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/favicon.ico differdiff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/objects/snake.jpg b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/objects/snake.jpgdeleted file mode 100644index c1ac3dd8..00000000Binary files a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/objects/snake.jpg and /dev/null differdiff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/objects/xray-lily.webp b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/objects/xray-lily.webpindex c32f4e22..c1ac3dd8 100644Binary files a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/objects/xray-lily.webp and b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/objects/xray-lily.webp differdiff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/site.webmanifest b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/site.webmanifestindex c77ca2e1..1dd91123 100644--- a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/site.webmanifest+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/public/assets/site.webmanifest@@ -1 +1 @@-{"name":"JA3/JA4 TLS Fingerprinting","short_name":"TLSFP","icons":[{"src":"/assets/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/assets/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#000000","background_color":"#000000","display":"standalone"}+{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"}diff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/src/pages/landing/index.tsx b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/src/pages/landing/index.tsxindex 0b181733..54e74e83 100644--- a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/src/pages/landing/index.tsx+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/frontend/src/pages/landing/index.tsx@@ -32,11 +32,11 @@ export function Component(): React.ReactElement {<header className={styles.head}><span className={styles.kicker}>tls dossier / passive</span>- <span className={styles.stamp}>specimen 001 / handshake</span>+ <span className={styles.stamp}>specimen 006 / handshake</span></header><main className={styles.center}>- <span className={styles.over}>surveillance aesthetics</span>+ <span className={styles.over}>sleep is counter surveillance</span><h1 className={styles.title}>TLSFP</h1><span className={styles.under}>the fingerprint of every client that speaks tlsdiff --git a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/justfile b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/justfileindex 53103bce..89540373 100644--- a/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/justfile+++ b/PROJECTS/intermediate/ja3-ja4-tls-fingerprinting/justfile@@ -59,6 +59,10 @@ run-backend *ARGS:test-backend:cargo test --workspace+[group('backend')]+bench *ARGS:+ cargo bench --bench fingerprint {{ARGS}}+[group('backend')]clippy:cargo clippy --workspace --all-targets -- -D warnings