dBA

Audio metadata firewall for ASR and multimodal LLM pipelines.

dBA operates at the ingestion boundary of artificial intelligence systems. It inspects audio file metadata and structure, calculates a deterministic risk score, decides disposition (allow / quarantine / reject), and returns a fully sanitized, metadata-free audio file paired with a forensic JSON report.

Supported formats: WAV, MP3, FLAC, Ogg, AAC, m4a
(Note: Image/EXIF embedded streams are actively stripped; analysis of EXIF data is not supported.)

---

The Threat Landscape

Audio metadata (ID3 tags, RIFF INFO/LIST chunks, embedded streams) consists of attacker-controlled, free-form text. When these files are processed by ASR (Automated Speech Recognition) systems or downstream multimodal LLMs, the metadata becomes an unmonitored attack vector.

dBA prevents:

• Prompt Injection: Malicious instructions hidden in album or artist tags.
• Log Injection / Poisoning: Payloads designed to corrupt downstream SIEMs or logging mechanisms.
• PII Leakage & Secret Exfiltration: Unintentional exposure of keys or user data.
• Structural Attacks: Polyglot files, trailing malicious data, or unexpected executable streams.

---

Architecture & Pipeline

dBA enforces a strict, fail-closed zero-trust pipeline before any file reaches your core infrastructure.

flowchart LR
    A[Ingest] -->|UUID temp file| B(Extract)
    B -->|ffprobe JSON| C(Analyze)
    C -->|Pattern & Structure| D{Score}
    D -->|Weighted Risk| E[Decide]
    
    E -->|Allow / Quarantine| F(Sanitize)
    E -->|Reject| G((Drop))
    
    F -->|-map_metadata -1| H[Respond]
    G -.->|HTTP 422| H
    
    style A fill:#1a1a1a,stroke:#333
    style D fill:#4d4d4d,stroke:#333
    style G fill:#961490,stroke:#fff,color:#fff
    style H fill:#1a1a1a,stroke:#333

Loading

1. Ingest: Original filename is immediately discarded. File is saved to a UUID-named temp file.
2. Extract: Interrogates file structure and metadata via ffprobe (JSON + on-disk size).
3. Analyze: Executes regex pattern matching and structural integrity checks.
4. Score: Calculates weighted risk (Low: +10 | Med: +25 | High: +40, capped at 100).
5. Decide: Routes based on active policy mode.
6. Sanitize: Uses strict ffmpeg flags (-fflags +bitexact -map_metadata -1 -map 0:a -c copy) to rebuild the audio track and dump all external streams.
7. Respond: Yields the clean file and a forensic indicator report.

---

Quick Start

Docker (Recommended)

The safest and fastest way to deploy the firewall.

docker build -t dba .
docker run --rm -p 8000:8000 dba

Local Development

Requires ffmpeg and ffprobe accessible on your system $PATH.

pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000

Example Usage

curl -s -X POST "http://localhost:8000/analyze-and-sanitize-audio?mode=strict" \
  -F "file=@payload_test.wav" | jq

---

API Reference

Method	Path	Description
POST	/analyze-and-sanitize-audio?mode=...	Full pipeline: Analysis + Risk Scoring + Disposition + Sanitization
POST	/sanitize-audio	Bypass analysis: Strip metadata only (lightweight fallback)
GET	/healthz	Liveness and readiness probe

Operating Modes

Pass the mode query parameter to control the strictness of the disposition engine.

Mode	Allow if	Quarantine if	Reject	Notes
strict	< 10	< 40	≥ 40	+10 to score if any indicator is present.
default	< 20	< 60	≥ 60	Standard baseline.
lenient	< 30	< 80	≥ 80	−10 to score. Use for high-noise environments.
audit	always	—	—	Dry-run. Calculates score + indicators, never blocks.

Note: A reject disposition triggers an HTTP 422 Unprocessable Entity, returning the full forensic report but no sanitized file (fail-closed).

---

Telemetry & Indicators

dBA generates stable indicator IDs designed for direct SIEM/SOAR ingestion. Raw tag values are heavily truncated and never logged or returned in full to prevent secondary poisoning of your logging infrastructure.

Content Indicators

• TAG_VIPER
• TAG_SEIZURE_MARKER
• TAG_OPERATION_ID
• TAG_DEBUG_FLAG
• TAG_POTENTIAL_SHELL
• TAG_CMD_SUBSTITUTION
• TAG_HTML_SCRIPT
• TAG_GENERIC_URL
• TAG_EMAIL_PII
• TAG_AWS_KEY
• TAG_PRIVATE_KEY

Payload schema: id, severity, key, pattern, value_snippet (≤ 80 chars).

Structural Indicators

• UNUSUAL_DURATION — Discrepancy between very short duration and large disk size.
• TRAILING_DATA — On-disk size significantly exceeds stream bitrate × duration.
• UNEXPECTED_CODEC — Deviations from allowed format constraints.
• MULTIPLE_AUDIO_STREAMS — Potential data hiding in secondary tracks.
• EMBEDDED_NONAUDIO_STREAM — Presence of cover art, video, or data streams.

---

Security Guarantees

• Zero-Trust Filenames: The original filename is never utilized in paths, subprocess calls, or logs.
• Safe Subprocessing: All ffmpeg/ffprobe executions use strict argument lists (shell=False).
• Resource Constraints: Enforced hard limits on upload sizes (default 200 MiB) and strict subprocess timeouts.
• Strict Muxing: The output muxer is explicitly selected from an allowlist based on the detected codec format.
• Stream Isolation: -map 0:a explicitly discards all non-audio streams.
• Deterministic Output: -bitexact prevents ffmpeg from embedding its own encoder tags into the final file.
• Ephemeral Storage: The original metadata-bearing file is securely unlinked immediately after processing.

---

Configuration

Control the firewall behavior via environment variables:

Env Var	Default	Description
MD_TEMP_DIR	(System temp)	Working directory for ephemeral processing
MD_MAX_UPLOAD_BYTES	209715200	Maximum upload size in bytes (200 MiB)
MD_FFPROBE_TIMEOUT	30	Maximum execution time for ffprobe (sec)
MD_FFMPEG_TIMEOUT	120	Maximum execution time for ffmpeg (sec)

---

Extending the Ruleset

dBA is designed to be easily extensible. Modify the core arrays to fit your specific threat model:

Goal	Location
Add suspicious patterns	SUSPICIOUS_PATTERNS
Whitelist specific tags	ALLOWED_TAG_KEYS
Add structural detectors	_structural_indicators
Adjust risk posture	SEVERITY_WEIGHT + thresholds in _decide_disposition

---

Testing

pip install -r requirements-dev.txt
pytest

• tests/test_policy.py: Validates pure analysis and scoring logic (runs independently of ffmpeg).
• tests/test_endpoints.py: Tests the full FastAPI application and ffmpeg integration (automatically skipped if ffmpeg is not found on $PATH).

---

License

Released under the MIT License.