docs: add deployment assumptions, security model, and build troubleshooting steps

README.md

@@ -10,6 +10,7 @@
 ## Table of Contents
 
 - [Overview](#overview)
+  - [Deployment Security Model](#deployment-security-model)
 - [Notices](#notices)
 - [Features](#features)
 - [Building](#building)
@@ -56,6 +57,21 @@ dvledtx reads a video source file (e.g., MP4), decodes it using FFmpeg, and tran
 | **Memory** | Hugepages configured (typically 2GB+) |
 | **Kernel** | IOMMU and VFIO support enabled |
 
+### Deployment Security Model
+
+dvledtx is intended for deployment on a physically secured, network-isolated media segment: the
+TX host, a dedicated L2 switch and the receivers all sit inside a locked cabinet, with all NICs
+on the TX host used for transmission onto that switch.
+
+The transport (SMPTE ST 2110-20) and its PTP timing provide no authentication, encryption or
+integrity protection — security is delegated to MTL/ST 2110 and to physical and Layer 2
+isolation. Integrators must therefore verify the deployment assumptions before relying on this
+model.
+
+See **[Deployment Assumptions and Security Model](docs/assumptions.md)** for the trust boundary,
+the required deployment assumptions, the security properties the toolkit does not provide, and
+the residual risk and mitigations.
+
 ## Notices
 
 ### FFmpeg
@@ -106,10 +122,7 @@ FFmpeg is an open source project licensed under LGPL and GPL. See https://www.ff
     ```
     If this prints nothing, FFmpeg needs to be reconfigured/rebuilt after installing the packages above — screen capture will otherwise fail at runtime with `x11grab input format not found`.
   - **`x11grab` only works against an X11 (Xorg) display, not Wayland** — see [Ensuring an X11 session](#ensuring-an-x11-session-required-for-screen-capture) below if you're capturing from a machine's own physical desktop session.
-  - **Headless machines (no physical monitor)** additionally need a virtual display to capture from — see [Screen capture on a headless machine](#screen-capture-on-a-headless-machine-no-physical-monitor) below, which requires:
-    ```bash
-    sudo apt-get install -y xserver-xorg-video-dummy ubuntu-desktop
-    ```
+  - **Headless machines (no physical monitor)** additionally need a virtual display to capture from. This is an optional, environment-specific setup — not a dependency of dvledtx — so it is documented as an example in [Screen capture on a headless machine](#screen-capture-on-a-headless-machine-no-physical-monitor) below.
   - The stock `mtl_st20p` muxer only exposes `p_port`/`r_port` (2 physical NIC ports). To use more than 2 NICs with the default (non-`ENABLE_MTL_TX`) build, the plugin's `libavdevice/mtl_common.h` must be patched to add `p2_port`..`p7_port` (and matching `p2_sip`..`p7_sip`) AVOptions mapped to `devArgs.port[MTL_PORT_2..MTL_PORT_7]` / `devArgs.sip[...]`, then FFmpeg rebuilt and reinstalled. Without this patch, `nic_count` is effectively capped at 2 for the FFmpeg TX path (the `ENABLE_MTL_TX` direct-pipeline build already supports up to 8 NICs without any patch).
 
 ### Build Steps
@@ -250,7 +263,12 @@ To capture from a machine's own physical display, make sure that desktop session
 
 `x11grab` needs a real X11 display to attach to — it does not work against a raw framebuffer or DRM device. On a machine with no monitor connected, create a virtual display using Xorg with the `dummy` video driver and run a desktop session on it so there's actual content to capture. Unlike Xvfb, a real Xorg server claims physical input devices — your keyboard and mouse work directly on the virtual display.
 
-1. **Install prerequisites** (once): see [Software Requirements](#software-requirements) for the `xserver-xorg-video-dummy`/`ubuntu-desktop` packages and the `x11grab`-enabled FFmpeg build.
+> The packages below are **not dvledtx dependencies** — they are only needed to construct a virtual display on a headless host. The following is an example of one way to set this up on Ubuntu; adapt it to your environment as needed.
+
+1. **Install the virtual-display packages** (once), along with the `x11grab`-enabled FFmpeg build. As an example, on Ubuntu:
+   ```bash
+   sudo apt-get install -y xserver-xorg-video-dummy ubuntu-desktop
+   ```
 
 2. **Create an Xorg config** for the dummy driver:
    ```bash
@@ -680,6 +698,19 @@ sudo pkill -9 -f dvledtx
      # Group should be 'vfio' with rw permissions
      ```
 
+6. **`pip install` fails with `externally-managed-environment`**
+   - On newer systems (Ubuntu 24.04+, PEP 668) `pip` refuses to install packages system-wide, which breaks installing the Python build tools (`meson`, `ninja`, `pyelftools`) required by DPDK/MTL. Re-run the install with `--break-system-packages`:
+     ```bash
+     pip install --break-system-packages meson ninja pyelftools
+     ```
+
+7. **FFmpeg `./configure` fails with `nasm/yasm not found or too old`**
+   - Building FFmpeg (and DPDK) requires the NASM assembler. If configuring FFmpeg errors out looking for `nasm`, install it:
+     ```bash
+     sudo apt install -y nasm
+     ```
+   - Then re-run FFmpeg's `./configure`.
+
 ## Contributing
 
 Contributions are welcome. Please open an issue or submit a pull request on [GitHub](https://github.com/OpenVisualCloud/directview-led-software-toolkit).

Security.md

@@ -1,6 +1,23 @@
 # Security Policy
 Intel is committed to rapidly addressing security vulnerabilities affecting our customers and providing clear guidance on the solution, impact, severity and mitigation. 
 
+## Security Model
+
+dvledtx is designed for deployment on a physically secured, network-isolated media segment. The
+transport (SMPTE ST 2110-20) and its PTP timing provide no authentication, encryption or
+integrity protection; security is delegated to MTL/ST 2110 and to the physical and Layer 2
+isolation of that segment.
+
+**In scope:** the dvledtx transmitter application, its JSON configuration parsing, and its use
+of FFmpeg and the Media Transport Library.
+
+**Out of scope:** the receivers (customer-designed, typically FPGA-based, and not delivered with
+this toolkit), the LED panels, and the physical and network controls of the installation site.
+
+The trust boundary, the deployment assumptions this model depends on, and the residual risk if
+those assumptions are broken are documented in
+[Deployment Assumptions and Security Model](docs/assumptions.md).
+
 ## Reporting a Vulnerability
 Please report any security vulnerabilities in this project [utilizing the guidelines here](https://www.intel.com/content/www/us/en/security-center/vulnerability-handling-guidelines.html).
 

docs/assumptions.md

@@ -0,0 +1,94 @@
+# Deployment Assumptions and Security Model
+
+dvledtx transmits uncompressed video using the SMPTE ST 2110-20 standard. That transport, and
+the PTP timing it depends on, carry no authentication, encryption or integrity protection. The
+security of a deployment therefore rests on the **physical and Layer 2 isolation of the media
+segment**, not on controls inside this application.
+
+This document records that trust boundary, the assumptions it depends on, and the risk that
+remains if those assumptions are broken.
+
+## Table of Contents
+
+- [Trust Boundary and Topology](#trust-boundary-and-topology)
+- [Deployment Assumptions](#deployment-assumptions)
+- [Security Properties Not Provided by This Toolkit](#security-properties-not-provided-by-this-toolkit)
+- [Residual Risk and Defence in Depth](#residual-risk-and-defence-in-depth)
+
+## Trust Boundary and Topology
+
+```
+            ┌───────────────────── locked cabinet ──────────────────────┐
+            │                                                           │
+            │    TX host             Dedicated          Receivers       │
+            │    (dvledtx)    ──▶    L2 switch   ──▶    (FPGA)     ──▶ LED wall
+            │    all NICs = TX       media + PTP        customer-        │
+            │                        VLAN only          designed         │
+            └───────────────────────────────────────────────────────────┘
+                                     ▲
+                                     └── isolation boundary:
+                                         no uplink to any other network
+```
+
+| Element | Role | Position relative to the boundary |
+|---------|------|-----------------------------------|
+| **TX host** (dvledtx) | Decodes, crops and transmits ST 2110-20 streams | Inside the locked cabinet |
+| **Dedicated L2 switch** | Carries media (ST 2110-20) and PTP traffic only | The isolation boundary itself — no uplink to a corporate or building network |
+| **Receivers** | Receive streams and drive the LED panels | Inside the cabinet; **customer-designed (typically FPGA-based) and out of scope for this toolkit** |
+| **Administrator** | Configures and operates the TX host | Enters through the physical cabinet lock |
+
+**All NICs on the TX host are used for transmission.** `interfaces[]` may declare up to 8 NICs,
+and every one of them is consumed by ST 2110-20 TX onto the dedicated switch. The TX host does
+not bridge the media segment to any other network.
+
+## Deployment Assumptions
+
+The model above is only valid while all of the following hold. They are the responsibility of
+the integrator, and should be verified at installation and after any change to the
+installation:
+
+| # | Assumption | Why it matters |
+|---|------------|----------------|
+| 1 | The TX host, switch and receivers are installed in a **physically locked cabinet**, with keyed access restricted to authorised administrators | Physical access to the equipment is equivalent to full control over what is displayed on the wall |
+| 2 | The switch is **dedicated to the media segment** and has **no uplink** to a corporate, building or guest network | An uplink extends the trust boundary to every network it reaches |
+| 3 | **All unused switch ports are administratively disabled** | A live port reachable outside the cabinet — for example a patched wall socket believed to be disconnected — places an attacker directly inside the boundary |
+| 4 | Media and PTP traffic run on a **dedicated VLAN**, with no DHCP server and no general-purpose hosts attached to it | Prevents an attached device from being addressed onto the media network, and keeps unrelated traffic off the transmission path |
+
+## Security Properties Not Provided by This Toolkit
+
+Transmission is delegated to the
+[Media Transport Library (MTL)](https://github.com/OpenVisualCloud/Media-Transport-Library) and
+follows the SMPTE ST 2110 standards. dvledtx hands decoded frames to MTL and does not add
+security controls above it — the security of the wire is offloaded to physical and Layer 2
+isolation.
+
+State the following explicitly when assessing a deployment:
+
+- **No authentication** of ST 2110-20 senders or receivers.
+- **No encryption** of the video payload on the wire.
+- **No integrity or replay protection** on the media path.
+- **No authentication on the PTP path** — PTP is a broadcast protocol with no grandmaster
+  validation.
+
+## Residual Risk and Defence in Depth
+
+Physical isolation reduces exposure but does not eliminate it. If an adversary obtains Layer 2
+access to the media VLAN — for example by connecting to an overlooked live switch port — the
+following become feasible and are **not** mitigated in software:
+
+| Risk | Effect | Mitigation |
+|------|--------|------------|
+| Injection of a rogue ST 2110-20 stream | Unauthorised or offensive content displayed on the LED wall | Physically block access to the L2 media VLAN (locked cabinet, disabled unused ports, switch port security / 802.1X); operator visual detection of anomalous wall output |
+| Rogue PTP grandmaster | TX pacing skew and stream disruption | Keep PTP on the isolated VLAN; leave PTP disabled (default TSC pacing) unless a trusted grandmaster is present |
+| Traffic flooding on the media VLAN | Frame loss and visible artefacts on the wall | Dedicated switch with no other traffic; IGMP snooping |
+| Passive capture of video | Loss of content confidentiality | Physical isolation only — no encryption is available on the ST 2110-20 path |
+
+**Detection and response are physical and visual.** There is no in-band alerting: an operator
+observes anomalous output on the LED wall, and an administrator unlocks the cabinet to inspect,
+disconnect or power-cycle the affected equipment.
+
+> **Known accepted risk.** Because all authentication and encryption are absent by design of the
+> transport, an adversary who defeats the physical and L2 isolation has no further software
+> barrier. This is accepted for the current deployment profile and is pending validation by an
+> adversarial-testing exercise. This document will be revisited if authentication or encryption
+> become available in the underlying transport.