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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
Fix a real filter-graph injection via colour flags (#107)
Shogo Kajiyama4f53de0ef967
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 setFound and fixed while auditing the tools added across 0.13.0-0.15.0:diff --git a/docs/contract.md b/docs/contract.mdindex 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 theToolSpec 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.jsonindex 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.pyindex bb5d9cb..da96359 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -9,6 +9,7 @@ from __future__ import annotationsimport jsonimport osimport platform+import reimport shutilimport subprocessimport 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.pyindex 512d459..0bfdd76 100644--- a/scripts/background.py+++ b/scripts/background.py@@ -14,7 +14,7 @@ import argparseimport mathimport 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_argsdef 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.outputdiff --git a/scripts/export.py b/scripts/export.pyindex 9cd3a40..e2ca5f7 100755--- a/scripts/export.py+++ b/scripts/export.py@@ -26,7 +26,7 @@ import sysfrom pathlib import Pathfrom 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_colorPRESETS: 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 0if 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.pyindex 046c429..1e63540 100755--- a/scripts/fit.py+++ b/scripts/fit.py@@ -37,7 +37,7 @@ import sysfrom fractions import Fractionfrom 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_argsASPECT_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.pyindex a2ffd0e..89eb321 100755--- a/scripts/join.py+++ b/scripts/join.py@@ -23,7 +23,7 @@ import argparseimport sysfrom 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_colorTRANSITIONS = ["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.pyindex 22a0b57..e262cda 100755--- a/scripts/overlay.py+++ b/scripts/overlay.py@@ -24,7 +24,7 @@ import argparseimport sysfrom 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_argsPOS = {"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.pyindex 2d4e536..28c648b 100644--- a/scripts/pad.py+++ b/scripts/pad.py@@ -16,7 +16,7 @@ Examples:import argparseimport 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_argsdef 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.pyindex 6eb5835..164b559 100644--- a/scripts/straighten.py+++ b/scripts/straighten.py@@ -22,7 +22,7 @@ import argparseimport mathimport 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_argsdef 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.pyindex 72ace0a..c65e92e 100644--- a/scripts/waveform.py+++ b/scripts/waveform.py@@ -22,7 +22,7 @@ Examples:import argparseimport 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_colorWAVEFORM_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.pyindex 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