PacketFlowAI v5 - Verifiable Assurance

PacketFlowAI is a verifiable-assurance cyber-defence prototype. It separates threat confidence from evidence integrity, inclusion, sequence continuity, expected-source coverage, reproducibility, and unknown omission risk. Live capture and PCAP replay use the same flow, detection, fusion, policy, evidence, campaign, and assurance pipeline.

Features

• Deterministic HDC encoding with checkpoint integrity validation
• Bidirectional IPv4/IPv6 TCP/UDP flow tracking with temporal and host features
• Temporal HDC, prototype similarity, OOD detection, anomaly scoring, and calibration
• Dataset-native label normalization without explanation leakage
• Named dataset adapters and machine-readable security benchmark reports
• Optional NIM disabled/shadow/influence modes with evidence sanitization
• Deterministic fusion, ATT&CK provenance, alert-only defaults, and TTL containment gates
• SQLite evidence, analyst-adjudicated feedback, drift checks, and active learning
• Candidate/active/previous model registry with promotion and rollback
• Read-only API, Prometheus metrics, structured logs, and operations dashboard
• Persistent campaign graph connecting flows, hosts, accounts, services, alerts, ATT&CK techniques, and cases
• Next-move prediction with uncertainty, evidence references, and time horizons
• Counterfactual response simulation and digital-twin blast-radius analysis
• Evidence time reconstruction, hash-chain sealing, Merkle verification, and explicit action authority
• Multi-sensor adapters, threat memory, guarded continual prototypes, federated consensus, and bounded playbooks
• Portable .pfcase evidence bundles and the independent packetflow-verifier package
• OCSF, STIX 2.1, TAXII, Sigma, SIEM, OpenTelemetry, and case-management interoperability
• Causal reasoning, intervention optimisation, adversarial assurance, adaptive sensing, and Linux fast paths
• Signed/versioned Evidence Contracts, producer sequences, epoch counts, heartbeats, dark-period detection, and ingest receipts
• Witness reconciliation, multi-service checkpoints, omission/redaction ledgers, lifecycle provenance, and trust-root history
• PFCASE 1.0 formal claims, inclusion proofs, decision capsules/autopsy, challenge mode, and local-only browser verification
• Assurance-aware authority, observation-plane modeling, sensor-suppression signals, and an interactive Assurance War Room

Installation

1. Clone the repository.

git clone https://github.com/Arkay92/PacketFlowAI.git

2. Install dependencies.

cd PacketFlowAI
pip install -e .

Usage

List available commands:

python -m packetflowai --help

Train against a dataset containing authoritative labels:

python -m packetflowai train --dataset rdpahalavan/packet-tag-explanation --split train --epochs 10

List interfaces and start live capture:

python -m packetflowai interfaces
python -m packetflowai capture --interface <interface_name>

Replay a PCAP through the same flow pipeline:

python -m packetflowai replay traffic.pcap
python -m packetflowai replay traffic.pcap --realtime --speed 10 --output artifacts/replay.json

Benchmark, model lifecycle, API/dashboard, and load testing:

python -m packetflowai benchmark run --dataset cicids2017 --input test.csv \
  --predictions predictions.json --model candidate-v2 --output artifacts/benchmarks/report.json
python -m packetflowai model list
python -m packetflowai model promote packet-hv-mlp:2.3.0
python -m packetflowai api --host 127.0.0.1 --port 8080
python -m packetflowai loadtest --flows 10000 --packets-per-flow 4

The API command starts the Signal Room at http://127.0.0.1:8080. The live dashboard visualizes flow activity, threat pressure, classifications, alerts, evidence channels, model state, and runtime telemetry. It refreshes every four seconds and exposes a pause control for incident review.

The Forensics view isolates orange and red packet conversations for deeper analysis. Select cases from the threat constellation or case strip, use the arrow keys to move between incidents, and inspect route identity, packet statistics, directional volume, model evidence, protocol metadata, policy provenance, and the correlated read-only record.

The Command view is the v3 predictive-defence cell. Navigate the temporal threat graph, inspect campaign and next-move assessments, compare counterfactual responses, rewind the evidence timeline, verify the sealed forensic chain, and inspect exactly where autonomous authority ends.

The v5 Assurance view is a separate evidence war room. It exposes the assurance vector, proof path, source heatmap, recording-path loss, formal claims, re-derivation boundary, known blind spots, assurance debt, authority degradation, Evidence Contract, and witness state. Imperfect numbers are intentional: integrity is not completeness.

Verify a portable case without importing or trusting the PacketFlowAI application package:

packetflow-verifier verify case.pfcase
packetflow-verifier replay-decision case.pfcase --decision PF-1234
packetflow-verifier decision-autopsy case.pfcase --decision PF-1234
packetflow-verifier inclusion-proof case.pfcase --file evidence/events.jsonl
packetflow-verifier challenge case.pfcase
packetflow-verifier audit-resource case.pfcase evidence-contract

PFCASE 1.0 is documented in the open format specification, with the formal claim dictionary, JSON schema, and verification vectors. The standalone assets under packetflow_verifier/web/ verify a dropped bundle locally in a browser; no evidence is uploaded and PacketFlowAI does not need to be running.

Create the guided Signal Room presentation video with Playwright:

pip install -e ".[presentation]"
playwright install chromium
python scripts/create_ui_video.py

The recorder uses isolated presentation data and writes artifacts/presentation/packetflowai-signal-room-tour.webm. Each explanatory card and dashboard view is held for at least six seconds.

Record the interactive Forensic War Room analyst journey with:

python scripts/create_forensics_video.py

This walkthrough uses a visible guided cursor, real clicks, smooth scrolling, case navigation, and the same UI-styled explanatory cards. It writes artifacts/presentation/packetflowai-forensics-war-room-tour.webm.

Record the complete v3 journey with:

python scripts/create_v3_video.py

The v3 walkthrough uses real navigation, graph selection, response comparisons, timeline controls, Forensic War Room movement, and UI-styled cards held for at least five seconds. It writes artifacts/presentation/packetflowai-v3-predictive-defence-tour.webm.

Record the v4 provable collective-defence walkthrough with:

python scripts/create_v4_video.py

The v4 tour adds the Assurance Deck, independent-verification story, collective-defence matrix, and new interoperability, learning, robustness, and runtime capabilities. It writes artifacts/presentation/packetflowai-v4-collective-defence-tour.webm.

Record the v5 Verifiable Assurance walkthrough with:

python scripts/create_v5_video.py

The v5 tour interactively follows the assurance vector, proof path, dark-period heatmap, observation graph, formal claims, re-derivation boundary, authority degradation, evidence challenge lab, signed contract, witnesses, and Forensics journey. It writes artifacts/presentation/packetflowai-v5-verifiable-assurance-tour.webm.

python main.py ... remains available as a compatibility launcher. Live capture requires appropriate packet-capture permissions and Npcap on Windows.

Configuration

Configuration is defined in packetflowai/config.py. Common runtime overrides are available through environment variables:

• PACKETFLOWAI_ARTIFACT_DIR
• PACKETFLOWAI_HV_DIMENSION
• PACKETFLOWAI_NUM_LEVELS
• PACKETFLOWAI_ENCODER_SEED
• PACKETFLOWAI_QUEUE_SIZE
• PACKETFLOWAI_RISK_HALF_LIFE
• PACKETFLOWAI_NIM_MODE (disabled, shadow, or influence)
• NIM_BASE_URL
• NIM_MODEL
• NVIDIA_API_KEY (environment/secret manager only)

NIM is disabled by default. Its self-reported reasoning strength is not a calibrated probability, it cannot invoke enforcement, and its assessments cannot become training labels. Generated checkpoints, registry state, databases, reports, and logs live under artifacts/ and are excluded from Git. Legacy state-dict-only checkpoints intentionally fail manifest validation.

See architecture, v5 architecture, threat model, and benchmark methodology.

Contributing

Run the test suite with:

python -m unittest discover -v

License

This project is licensed under the MIT License. See LICENSE.