Skip to content

v2.5.0

Choose a tag to compare

View all tags
@Indspl0it Indspl0it released this 11 Apr 09:45
· 74 commits to main since this release
v2.5.0
9dce78c

[2.5.0] - 2026-04-11

Summary

Blue-Tap 2.5.0 is the Standardized Framework release. Every module now produces structured RunEnvelope output with typed ExecutionRecord entries, evidence blocks, and artifact references. The report pipeline has been rewritten around module-owned ReportAdapter classes. The CLI emits structured lifecycle events throughout all operations. Session logging validates envelope shape. This release lays the groundwork for the upcoming modular framework architecture (Metasploit-style module families, registry, and plugin system).

Added — Standardized Result Schema

Core Framework Contracts

  • RunEnvelope schema (core/result_schema.py) — canonical output container for every module invocation with required fields: schema, schema_version, module, run_id, target, adapter, started_at/completed_at, operator_context, summary, executions, artifacts, module_data
  • ExecutionRecord model — normalized unit of work within a run with two-layer status taxonomy: execution_status (lifecycle: completed/failed/error/skipped/timeout) and module_outcome (semantic: confirmed/inconclusive/recovered/observed/etc.)
  • EvidenceRecord model — structured observation container with summary, confidence, observations, packets, state_changes, module_evidence, and capability_limitations
  • ArtifactRef model — typed pointer to saved files (pcap, log, HTML, JSON) with artifact_id, kind, label, path, execution_id
  • validate_run_envelope() — schema shape validator for envelope integrity
  • looks_like_run_envelope() — fast heuristic check for session logging
  • Envelope helper functions — build_run_envelope(), make_execution(), make_evidence(), make_artifact(), envelope_executions(), envelope_module_data()

Structured CLI Event System

  • emit_cli_event() (core/cli_events.py) — structured event emitter with required fields: event_type, module, run_id, target, adapter, timestamp, message, details
  • 13 defined event types — run_started, phase_started, execution_started, execution_result, execution_skipped, pairing_required, recovery_wait_started, recovery_wait_progress, recovery_wait_finished, artifact_saved, run_completed, run_aborted, run_error
  • Every CLI command now emits lifecycle events — operators always know what started, what's running, and when it's done

Report Adapter Architecture

  • ReportAdapter ABC (core/report_contract.py) — module-owned report interface with accepts(), ingest(), build_sections(), build_json_section()
  • SectionModel/SectionBlock data models — typed report section containers replacing raw HTML string generation
  • 12 report adapters — one per module type:
    • DiscoveryReportAdapter — scan result tables with device properties, risk indicators
    • VulnscanReportAdapter — CVE/non-CVE finding cards with evidence, execution logs
    • AttackReportAdapter — attack outcome cards with phase tracking, evidence
    • AutoReportAdapter — 9-phase pentest summary with per-phase execution records
    • DataReportAdapter — PBAP/MAP/OPP/AT extraction summaries with artifact links
    • AudioReportAdapter — HFP/A2DP/AVRCP session summaries with capture artifacts
    • DosReportAdapter — DoS check results with recovery probe outcomes
    • FirmwareReportAdapter — DarkFirmware operations with KNOB detection cards
    • FuzzReportAdapter — per-protocol campaign runs with crash details and corpus stats
    • LmpCaptureReportAdapter — LMP sniff session summaries
    • ReconReportAdapter — reconnaissance campaign results with correlation analysis
    • SpoofReportAdapter — spoof operations with before/after MAC evidence
  • Block renderer system (report/renderers/) — BlockRendererRegistry with typed block renderers for tables, paragraphs, text, and custom block types
  • render_sections() — converts SectionModel lists into HTML via block renderers

Report Generator Refactor

  • Adapter-driven report generation — generator.py now orchestrates via REPORT_ADAPTERS registry: dispatches envelopes to matching adapters, collects SectionModel output, renders HTML/JSON through shared renderers
  • Generator no longer contains module-specific logic — all CVE interpretation, evidence formatting, and finding classification moved to adapters
  • Unified ingestion pipeline — both HTML and JSON reports consume the same adapter output, preventing report format divergence

Added — Module Envelope Builders

Each module family has a dedicated envelope builder in core/:

  • attack_framework.py — build_attack_result() for exploitation modules (BIAS, KNOB, BLUFFS, hijack, SSP/encryption downgrade, CTKD)
  • audio_framework.py — build_audio_result() for HFP/A2DP/AVRCP sessions
  • auto_framework.py — build_auto_result() with build_auto_phase_execution() for 9-phase auto pentest
  • data_framework.py — build_data_result() for PBAP/MAP/OPP/AT data extraction
  • firmware_framework.py — build_firmware_status_result(), build_firmware_dump_result(), build_connection_inspect_result(), build_firmware_operation_result() for DarkFirmware operations
  • fuzz_framework.py — build_fuzz_result() for fuzzing campaign runs
  • recon_framework.py — build_recon_result() for reconnaissance operations
  • scan_framework.py — build_scan_result() for discovery scans
  • spoof_framework.py — build_spoof_result() with MAC before/after evidence, method verification

Added — Module Standardization

Discovery & Scan

  • Scan commands produce RunEnvelope — scan classic, scan ble, scan combined, scan all, scan inquiry, scan watch all log full envelopes to session
  • Campaign correlation output wrapped in scan envelopes with correlation evidence
  • Fleet scan logs actual scan envelope instead of raw device list

Reconnaissance

  • All 13 recon commands produce envelopes via build_recon_result() — auto, sdp, gatt, fingerprint, ssp, rfcomm, l2cap, capture, capture-analyze, pairing-mode, ble-sniff, lmp-capture, lmp-intercept, combined-sniff, crackle, extract-keys, wireshark-keys
  • Recon CLI helpers — _recon_cli_context(), _recon_emit(), _recon_start(), _recon_result(), _recon_skip() for consistent event emission
  • Capture analysis wrapped in recon correlation envelopes
  • HCI capture — improved parser, stale PID detection, capture analysis integration

Vulnerability Assessment

  • Vulnscan produces structured envelope (blue_tap.vulnscan.result) with scanner metadata, per-check execution logs, finding summaries, and evidence
  • CVE check execution tracking — each check records execution_status + module_outcome + evidence
  • Fleet assessment builds reports from standardized scan and vuln envelopes

Exploitation

  • BIAS — per-phase ExecutionRecord entries (spoof, connect, inject, verify) with structured evidence
  • KNOB — probe and brute-force phases produce typed execution records with key-size evidence
  • BLUFFS — per-variant (A1 LSC downgrade, A3 SC→LSC) execution records with DarkFirmware capability reporting
  • SSP downgrade — execution tracking across SSP probe, legacy force, PIN brute phases with lockout evidence
  • Hijack — 4-phase tracking (spoof, connect, monitor, exploit) with per-phase success/failure evidence
  • CTKD — probe result standardization with MAC normalization and cross-transport key evidence
  • Encryption downgrade — 3 method variants (disable, toggle, SC-reject) produce execution records with LMP evidence
  • DoS — all checks wrapped in RunEnvelope with recovery probe outcomes, timing evidence, and severity

Post-Exploitation

  • PBAP/MAP — structured data envelopes with extraction counts, artifact refs, parsed entry metadata
  • HFP — all 8 subcommands (call, answer, hangup, volume, dtmf, sco, codec, diagnostics) log audio envelopes
  • A2DP — capture/record/eavesdrop/play/stream/loopback produce audio envelopes with duration, codec, sample rate evidence
  • AVRCP — all 10 subcommands (play, pause, next, prev, volume, info, shuffle, repeat, monitor, flood) log structured envelopes
  • AT commands — extraction responses parsed into structured device artifacts with field-level evidence
  • OPP — transfer diagnostics across dbus and raw fallback paths with artifact tracking
  • Bluesnarfer — extraction operations produce data envelopes

Fuzzing

  • Per-protocol RunEnvelope — each protocol fuzz run produces its own envelope with crash/corpus/timing evidence
  • Run IDs — every fuzz campaign gets a stable run_id carried through all events and artifacts
  • Crash lifecycle events — execution_result emitted for each crash with severity and reproduction steps
  • Utility commands (list-crashes, replay, import-pcap) emit structured events
  • Legacy fuzz commands removed — all fuzzing routes through the standardized engine

Adapter & Firmware

  • Adapter commands (up, down, reset, set-name, set-class) log general envelopes to session
  • Firmware status/install/init/dump emit lifecycle events and log envelopes
  • Connection inspect builds envelope with per-slot KNOB detection findings
  • Spoof commands produce spoof envelopes with before/after MAC proof and method verification

Auto Pentest

  • 9-phase RunEnvelope with per-phase ExecutionRecord entries (discover, fingerprint, recon, vulnscan, pair, exploit, fuzz, dos, report)
  • Phase skip tracking — skipped phases produce execution records with skip reason evidence
  • Summary counters — per-phase success/fail/skip counts in envelope summary

Playbook / Run Mode

  • Playbook execution produces RunEnvelope with per-step execution records
  • Lifecycle events emitted per playbook step (run_started, execution_started, execution_result, run_completed)

Added — Shared OBEX Client

  • core/obex_client.py — unified dbus-fast OBEX client for PBAP, MAP, and OPP with shared session management, error handling, and transfer tracking
  • PBAPSession — PBAP phonebook access with folder navigation, vCard pull, property filtering
  • MAPSession — MAP message access with folder listing, message pull, notification registration
  • OPPSession — OPP file push with progress tracking and transfer validation
  • Shared OBEX error hierarchy — ObexError, transport-level vs protocol-level error distinction

Added — DoS Expansion

  • Modular CVE-backed DoS probes for BLE, AVRCP, and AVDTP paths
  • Recovery probe validation — real ATT request validation instead of simple ping
  • DoS guide (docs/dos-guide.md) — workflow documentation
  • DoS CVE matrix (docs/dos-cve-matrix.md) — coverage mapping
  • Structured DoS metadata in report generation

Added — Profile Environment Doctor

  • env-doctor command — prerequisite checker for BlueZ, OBEX, PulseAudio, and audio subsystem readiness
  • OBEX capability detection — validates dbus-fast OBEX transport availability
  • Audio prerequisites — PulseAudio module availability, Bluetooth source/sink detection

Added — Framework Architecture Plan

  • Modular framework architecture plan (thoughts/plans/2026-04-11-blue-tap-framework-architecture-plan.md) — 13-phase migration plan to Metasploit-style module families with registry, contracts, and plugin system
  • Framework architecture rules (.claude/rules/blue-tap-architecture.md) — enforced development rules for all agents: import paths, family classification, registry requirements, schema rules, migration protocol

Added — Testing

  • 36 new envelope tests across 3 test files:
    • test_spoof_envelope.py (11 tests) — envelope shape, validation, success/failure/restore outcomes, MAC evidence, adapter round-trip
    • test_firmware_envelope.py (17 tests) — status/dump/inspect/operation builders, KNOB detection, partial hooks, artifact refs
    • test_auto_envelope.py (8 tests) — per-phase executions, skip/fail evidence, summary counters, validation
  • Fuzz envelope tests — l2cap-sig transport map, transport overrides, raw frame format, connect failure finalization
  • Report adapter regression tests — standardized rendering validation
  • Attack envelope regression tests — BIAS/KNOB/BLUFFS/hijack/SSP/CTKD/encryption downgrade envelope validation
  • Discovery regression tests — scan envelope shape validation
  • Media/data regression tests — HFP/A2DP/AVRCP/PBAP/MAP envelope validation
  • PBAP/MAP/media regression fixtures — structured test data

Changed

  • Report generator completely refactored — adapter-driven architecture replaces monolithic parsing; generator orchestrates layout and dispatch only
  • Session logging now validates envelope shape — non-envelope data logged at debug level for audit traceability
  • clone_device_identity() return type changed from bool to dict with success, method, original_mac, target_mac, verified, error fields
  • spoof_address()/bdaddr()/spooftooph()/btmgmt()/rtl8761b() return types changed from bool to structured dicts with per-operation evidence
  • restore_original_mac() return type changed from bool to dict with restored_mac and method
  • Adapter input validation — device_class hex format/range validation (0x000000-0xFFFFFF), device_name length validation (max 248 bytes UTF-8)
  • DarkFirmware detection — failures logged instead of silenced; adapter power recovery when stuck DOWN after SSP toggle
  • DarkFirmware CLI bootstrap — smart skip for non-hardware commands (scan/report/session); partial hook status downgraded from info to warning
  • Fuzz engine — transport_overrides parameter for per-protocol channel/hci_dev override; extracted _finalize_single_run() for consistent envelope construction on error paths
  • Crash replay — removed _StubTransport fallback, added RawACLTransport support
  • L2CAP-sig fuzzing — rewired to raw ACL via DarkFirmware instead of standard L2CAP socket
  • AT deep fuzzing — context-aware injection corpus with RFCOMM surface autodiscovery, batch runner across hfp/phonebook/sms/injection channels
  • Transport hardening — DarkFirmware presence check in LMP and RawACL connect() returns False instead of crashing
  • DoS probe timeouts — hardened timeout handling for unresponsive targets
  • Attack cleanup — improved cleanup paths in attack modules and recon transport retries
  • Fleet reports — built from standardized scan and vuln envelopes instead of ad hoc data
  • Demo report data — standardized around run envelopes

Fixed

  • clone_device_identity callers — bias.py and hijack.py used if not clone_device_identity(...) which always evaluated False after the bool→dict migration (non-empty dicts are truthy); fixed to check result.get("success", False)
  • Recon capture-stop — HCICapture.stop() returns a string path, not a dict; two stray copy-paste blocks called result.get("success") on the string, raising AttributeError
  • Recon lmp-sniff — artifacts variable referenced in build_recon_result() but never initialized, causing NameError on every execution
  • Recon nrf-sniff — same NameError — artifacts undefined before build_recon_result()
  • RAM BDADDR patching — corrected controller spoofing memory write for RTL8761B
  • HFP reconnect socket leak — fixed socket resource leak in HFP reconnection path
  • DoS result/report normalization — aligned DoS result keys with report adapter expectations
  • Report merge conflict marker — removed leftover <<<<<<< HEAD marker from generator.py
  • btmgmt public-addr errors — btmgmt public-addr call errors now handled safely instead of crashing

Removed

  • Legacy fuzz commands — all standalone fuzz protocol commands removed; all fuzzing routes through the unified engine
  • _StubTransport fallback in crash replay — replaced with proper transport selection
Assets 2
Loading