Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

Fix a real filter-graph injection via colour flags (#107)

Shogo Kajiyama4f53de0ef967
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2f0de66..a6bdaad 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,39 @@
(nothing yet)
+## 0.15.2 — fix a real filter-graph injection via colour flags
+
+Found by adversarial testing: every flag that string-formats a colour straight
+into an ffmpeg filter graph accepted the value verbatim, with no validation.
+Since ffmpeg filter options are comma/colon-delimited, a value like
+`black,drawtext=text=INJECTED` doesn't just set an odd colour -- the comma
+ends the colour filter early and starts an entirely new one. Confirmed this is
+a real, working injection, not a theoretical one: rendered a frame with
+`pad.py --color 'black,drawtext=text=INJECTED:fontcolor=white'` and the
+injected text was actually burnt into the output picture.
+
+Added `validate_color()` to `_common.py` (refuses anything that isn't a named
+colour, `0xRRGGBB[AA]`, or `#RRGGBB[AA]`, optionally with an `@alpha` suffix)
+and applied it to every colour-like flag that reaches a filter graph
+unescaped:
+
+- `pad.py --color`, `straighten.py --fill-color`, `waveform.py --background`
+ and `--color` (new tools, this release cycle)
+- `background.py --color`/`--gradient`, `fit.py --pad-color`,
+ `export.py --pad-color`, `join.py --pad-color`, `overlay.py --chromakey`/
+ `--font-color`/`--border-color`/`--box-color` (pre-existing tools -- this
+ gap predates the recent tool additions)
+
+`caption.py`'s colour flags were already safe (routed through the existing
+`color_hex()`/`ass_color()` strict RRGGBB validators) and needed no change.
+
+This is the same "no filter graph accepted from the caller" invariant every
+other typed flag in this codebase already holds to -- colour flags were the
+one place a free-form string still reached a filter graph unescaped. New
+regression test proves the exploit across all 9 fixed call sites and that
+real colour values still work; full suite (183 tests) and the contract suite
+(67 tests) both pass.
+
## 0.15.1 — bug-check pass on the 39-tool set
Found and fixed while auditing the tools added across 0.13.0-0.15.0:
diff --git a/docs/contract.md b/docs/contract.md
index 96b2125..e634c96 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
| Field | Meaning | Changes when |
|---|---|---|
| `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`0.15.1`) | any release |
+| `skill.version` | the npm / package.json version (`0.15.2`) | any release |
A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -39,7 +39,7 @@ drifting silently.
```json
{
"contract_version": "1.0",
- "skill": {"id": "ffmpeg-skill", "version": "0.15.1", "execution_mode": "local", "kind": "execution",
+ "skill": {"id": "ffmpeg-skill", "version": "0.15.2", "execution_mode": "local", "kind": "execution",
"entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
"not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
"requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
diff --git a/package.json b/package.json
index 8c9118f..e6874e9 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "0.15.1",
+ "version": "0.15.2",
"description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 39 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
"keywords": [
"ffmpeg",
diff --git a/scripts/_common.py b/scripts/_common.py
index bb5d9cb..da96359 100755
--- a/scripts/_common.py
+++ b/scripts/_common.py
@@ -9,6 +9,7 @@ from __future__ import annotations
import json
import os
import platform
+import re
import shutil
import subprocess
import sys
@@ -815,6 +816,23 @@ def color_hex(value: str) -> str:
return v.upper()
+_COLOR_TOKEN_RE = re.compile(r"^(0[xX][0-9A-Fa-f]{6,8}|#[0-9A-Fa-f]{6,8}|[A-Za-z][A-Za-z0-9]*)(@[0-9.]+)?$")
+
+
+def validate_color(value: str, flag: str = "--color") -> str:
+ """Refuse a colour argument that isn't a plain ffmpeg colour token (named colour, 0xRRGGBB[AA],
+ #RRGGBB[AA], optionally with an @alpha suffix). Every caller that string-formats a colour flag
+ straight into a filter graph (color=c=..., tpad=...:color=..., rotate=...:fillcolor=...) must
+ validate it first -- ffmpeg filter options are comma/colon-delimited, so an unvalidated value
+ containing those characters lets a caller splice in an entirely different filter (a real,
+ demonstrated filter-graph injection: --color "black,drawtext=text=..." renders arbitrary burnt-in
+ text), not just an odd colour. This is the same "no filter graph accepted from the caller"
+ invariant every other typed flag in this codebase already holds to."""
+ if not _COLOR_TOKEN_RE.match(value):
+ die(f"{flag} must be a plain colour (a name, 0xRRGGBB[AA], or #RRGGBB[AA], optionally @alpha), got '{value}'")
+ return value
+
+
def print_json(obj: Any) -> None:
sys.stdout.write(json.dumps(obj, indent=2, ensure_ascii=False) + "\n")
diff --git a/scripts/background.py b/scripts/background.py
index 512d459..0bfdd76 100644
--- a/scripts/background.py
+++ b/scripts/background.py
@@ -14,7 +14,7 @@ import argparse
import math
import sys
-from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args
+from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, validate_color, video_args
def main() -> int:
@@ -49,11 +49,14 @@ def main() -> int:
c0, c1 = args.gradient.split(":")
except ValueError:
die(f"--gradient needs two colours as C1:C2, got '{args.gradient}'")
+ validate_color(c0, "--gradient")
+ validate_color(c1, "--gradient")
rad = math.radians(args.angle)
x1 = round(args.width * math.cos(rad))
y1 = round(args.width * math.sin(rad))
src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}"
else:
+ validate_color(args.color, "--color")
src_filter = f"color=c={args.color}:size={args.width}x{args.height}:rate={args.fps:g}"
output = args.output
diff --git a/scripts/export.py b/scripts/export.py
index 9cd3a40..e2ca5f7 100755
--- a/scripts/export.py
+++ b/scripts/export.py
@@ -26,7 +26,7 @@ import sys
from pathlib import Path
from typing import Dict, List
-from _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run
+from _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color
PRESETS: Dict[str, Dict] = {
"youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},
@@ -63,6 +63,7 @@ def main() -> int:
return 0
if not args.input or not args.preset:
die("input and --preset are required (or use --list)")
+ validate_color(args.pad_color, "--pad-color")
p = PRESETS[args.preset]
meta = probe(args.input)
diff --git a/scripts/fit.py b/scripts/fit.py
index 046c429..1e63540 100755
--- a/scripts/fit.py
+++ b/scripts/fit.py
@@ -37,7 +37,7 @@ import sys
from fractions import Fraction
from typing import List
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, x264_args
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args
ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
@@ -114,6 +114,7 @@ def main() -> int:
die(f"--crop-x must be 0..1, got {args.crop_x}")
if not 0.0 <= args.crop_y <= 1.0:
die(f"--crop-y must be 0..1, got {args.crop_y}")
+ validate_color(args.pad_color, "--pad-color")
meta = probe(args.input)
if not meta.get("video"):
diff --git a/scripts/join.py b/scripts/join.py
index a2ffd0e..89eb321 100755
--- a/scripts/join.py
+++ b/scripts/join.py
@@ -23,7 +23,7 @@ import argparse
import sys
from typing import List
-from _common import STATE, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run
+from _common import STATE, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, validate_color
TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
"circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
@@ -104,6 +104,7 @@ def main() -> int:
if len(args.inputs) < 2:
die("give at least two clips")
+ validate_color(args.pad_color, "--pad-color")
metas = [probe(p) for p in args.inputs]
if all(not m.get("video") for m in metas):
for p, m in zip(args.inputs, metas):
diff --git a/scripts/overlay.py b/scripts/overlay.py
index 22a0b57..e262cda 100755
--- a/scripts/overlay.py
+++ b/scripts/overlay.py
@@ -24,7 +24,7 @@ import argparse
import sys
from typing import List, Optional
-from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, x264_args
+from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args
POS = {
"top-left": ("{m}", "{m}"),
@@ -163,6 +163,11 @@ def main() -> int:
die("--opacity must be within 0..1")
if args.chromakey and not args.video:
die("--chromakey needs --video")
+ if args.chromakey:
+ validate_color(args.chromakey, "--chromakey")
+ validate_color(args.font_color, "--font-color")
+ validate_color(args.border_color, "--border-color")
+ validate_color(args.box_color, "--box-color")
if not 0 < args.chromakey_similarity <= 1:
die("--chromakey-similarity must be within (0, 1]")
if not 0 <= args.chromakey_blend <= 1:
diff --git a/scripts/pad.py b/scripts/pad.py
index 2d4e536..28c648b 100644
--- a/scripts/pad.py
+++ b/scripts/pad.py
@@ -16,7 +16,7 @@ Examples:
import argparse
import sys
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args
def main() -> int:
@@ -36,6 +36,7 @@ def main() -> int:
die(f"--start/--end must be >= 0, got start={args.start:g} end={args.end:g}")
if args.start == 0 and args.end == 0:
die("--start and/or --end must be > 0 (nothing to pad)")
+ validate_color(args.color, "--color")
meta = probe(args.input)
if not meta.get("video"):
diff --git a/scripts/straighten.py b/scripts/straighten.py
index 6eb5835..164b559 100644
--- a/scripts/straighten.py
+++ b/scripts/straighten.py
@@ -22,7 +22,7 @@ import argparse
import math
import sys
-from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, validate_color, video_args
def main() -> int:
@@ -46,6 +46,7 @@ def main() -> int:
die(f"--degrees must be -45..45, got {args.degrees:g}")
if args.degrees == 0:
die("--degrees must be nonzero (nothing to straighten)")
+ validate_color(args.fill_color, "--fill-color")
meta = probe(args.input)
if not meta.get("video"):
diff --git a/scripts/waveform.py b/scripts/waveform.py
index 72ace0a..c65e92e 100644
--- a/scripts/waveform.py
+++ b/scripts/waveform.py
@@ -22,7 +22,7 @@ Examples:
import argparse
import sys
-from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run
+from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, validate_color
WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
@@ -51,6 +51,9 @@ def main() -> int:
die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
if args.width % 2 or args.height % 2:
die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")
+ for token in args.color.split("|"):
+ validate_color(token, "--color")
+ validate_color(args.background, "--background")
if args.fps <= 0:
die(f"--fps must be > 0, got {args.fps:g}")
diff --git a/tests/test_all.py b/tests/test_all.py
index 32893b0..31e97d9 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -1557,6 +1557,43 @@ class FFmpegSkillTests(unittest.TestCase):
self.assertIn("-preset veryfast", proc.stderr, "--fast overrides the preset")
self.assertClose(probe(str(out))["duration"], 6.0, 0.2)
+ # ---------------------------------------------------------------- colour-flag filter-graph injection (adversarial)
+ def test_color_like_flags_refuse_filter_graph_injection(self):
+ """Every flag that string-formats a colour straight into a filter graph (color=c=...,
+ tpad=...:color=..., rotate=...:fillcolor=..., drawtext=...:fontcolor=..., pad=...:color=...)
+ used to accept any string verbatim. Since ffmpeg filter options are comma/colon-delimited,
+ a value like "black,drawtext=text=INJECTED" doesn't just set an odd colour -- the comma ends
+ the colour filter early and starts an entirely new one, so the payload actually gets burnt
+ into the frame (confirmed by rendering it and inspecting the pixels before this fix existed).
+ This is a real filter-graph injection, not just a cosmetic validation gap -- every colour-like
+ flag across the codebase must refuse anything that isn't a plain colour token."""
+ payload = "black,drawtext=text=INJECTED"
+ cases = [
+ ("pad.py", [self.src, "--start", "1", "--color", payload]),
+ ("straighten.py", [self.src, "--degrees", "5", "--fit", "pad", "--fill-color", payload]),
+ ("waveform.py", [self.src, "--background", payload]),
+ ("waveform.py", [self.src, "--color", payload]),
+ ("background.py", ["--duration", "1", "--width", "640", "--height", "360", "--color", payload, "-o", OUT / "bg_inject.mp4"]),
+ ("background.py", ["--duration", "1", "--width", "640", "--height", "360", "--gradient", f"{payload}:0x0057ff", "-o", OUT / "bg_inject2.mp4"]),
+ ("fit.py", [self.src, "--aspect", "1:1", "--fit", "pad", "--pad-color", payload]),
+ ("export.py", [self.src, "--preset", "reels", "--pad-color", payload]),
+ ("join.py", [self.src, self.src, "--pad-color", payload]),
+ ("overlay.py", [self.src, "--text", "hi", "--font-color", payload]),
+ ("overlay.py", [self.src, "--text", "hi", "--border-color", payload]),
+ ("overlay.py", [self.src, "--text", "hi", "--box-color", payload]),
+ ("overlay.py", [self.src, "--video", self.src, "--chromakey", payload]),
+ ]
+ for name, argv in cases:
+ proc = script(name, *argv, expect_fail=True)
+ self.assertIn("colour", proc.stderr, f"{name} {argv}: expected a colour-validation refusal")
+
+ def test_color_like_flags_still_accept_real_colors(self):
+ script("pad.py", self.src, "--start", "0.5", "--color", "0x101010", "-o", OUT / "colorok1.mp4")
+ script("straighten.py", self.src, "--degrees", "5", "--fit", "pad", "--fill-color", "black", "-o", OUT / "colorok2.mp4")
+ script("waveform.py", self.src, "--background", "0x101010", "--color", "cyan|magenta", "-o", OUT / "colorok3.mp4")
+ script("background.py", "--duration", "1", "--width", "640", "--height", "360", "--gradient", "0xff6a00:0x0057ff", "-o", OUT / "colorok4.mp4")
+ script("overlay.py", self.src, "--text", "hi", "--box-color", "[email protected]", "-o", OUT / "colorok5.mp4")
+
# ---------------------------------------------------------------- real iPhone regressions (Dolby Vision 8.4 / HLG, VFR, extra tracks)
def test_hdr_source_stays_hdr_through_reencodes(self):
# HLG 10-bit HEVC with audio AND a timecode data track, like an iPhone .mov