Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -205,6 +205,23 @@ adapter you built yourself cannot quietly keep one of its own:
$encoder = new Encoder(probe: new MyProbe());
```

### Untrusted sources

ffmpeg follows references inside some inputs: an HLS playlist or a concat list opens the files and
URLs it names. When sources come from users, limit the demuxers and protocols every input may use.
Both lists go before each input on the ffmpeg and ffprobe command lines; nested opens inherit them.

```php
$formats = ['mov', 'matroska', 'avi', 'mpegts', 'ogg', 'wav', 'mp3', 'aac', 'flac'];

$encoder = new Encoder(
new FFmpeg(protocols: ['file'], formats: $formats),
new FFprobe(protocols: ['file'], formats: $formats),
);
```

Use `['https', 'tls', 'tcp']` as the protocols for a source read from a URL.

### How much a backend says

Every adapter has a display level, defaulting to `Adapter::ERROR` — only what went wrong, because
Expand Down
61 changes: 61 additions & 0 deletions src/Video/Adapter.php
Original file line number Diff line number Diff line change
Expand Up @@ -105,6 +105,12 @@ abstract class Adapter

protected readonly string $level;

/** @var list<string> Protocols an input may be opened with; empty allows any. */
protected readonly array $protocols;

/** @var list<string> Demuxers an input may be read with; empty allows any. */
protected readonly array $formats;

/**
* Who reads media details for this adapter.
*
Expand All @@ -131,19 +137,74 @@ abstract class Adapter

/**
* @param string|null $level One of the constants above; null keeps the default.
* @param list<string> $protocols Protocols inputs may be opened with, nested
* opens included (`file`, or `https,tls,tcp`
* for a URL); empty allows any.
* @param list<string> $formats Demuxers inputs may be read with (`mov`,
* `matroska`, ...); empty allows any. Leaving
* out playlist formats such as `hls` and
* `concat` stops a source from opening others.
*
* @throws Unsupported
* @throws Input
*/
public function __construct(
?string $binary = null,
?int $timeout = null,
int $threads = 0,
?string $level = null,
array $protocols = [],
array $formats = [],
) {
$this->binary = $binary ?? static::BINARY;
$this->timeout = $timeout ?? static::TIMEOUT;
$this->threads = $threads;
$this->level = $level === null ? static::LEVEL : self::graded($level);
$this->protocols = self::names($protocols);
$this->formats = self::names($formats);
}

/**
* Options that restrict how the next input is opened, placed before it.
*
* @return list<string>
*/
protected function opens(): array
{
$args = [];

if ($this->protocols !== []) {
$args[] = '-protocol_whitelist';
$args[] = \implode(',', $this->protocols);
}

if ($this->formats !== []) {
$args[] = '-format_whitelist';
$args[] = \implode(',', $this->formats);
}

return $args;
}

/**
* @param array<mixed> $names
* @return list<string>
*
* @throws Input
*/
private static function names(array $names): array
{
$list = [];

foreach ($names as $name) {
// Joined with commas into one argument, so a name must not carry one.
if (! \is_string($name) || \preg_match('/^[a-z0-9_]+$/', $name) !== 1) {
throw new Input('Invalid protocol or format name: '.\var_export($name, true));
}
$list[] = $name;
}

return \array_values(\array_unique($list));
}

public function getName(): string
Expand Down
5 changes: 5 additions & 0 deletions src/Video/Adapter/FFmpeg.php
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@ public function encode(string $path): string
$video = $info->hasVideo && ($rep === null || $rep->scaled());

$args = $this->prefix();
\array_push($args, ...$this->opens());

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Add coverage for the input whitelist arguments

The existing adapter and ffprobe tests do not verify these new flags or that they appear before each input. If the flags are later omitted or misplaced, configured adapters could silently allow playlist or nested resource opens again; please add command-level coverage for ffmpeg and ffprobe.

Prompt To Fix With AI
This is a comment left during a code review.
Path: src/Video/Adapter/FFmpeg.php
Line: 101

Comment:
**Add coverage for the input whitelist arguments**

The existing adapter and ffprobe tests do not verify these new flags or that they appear before each input. If the flags are later omitted or misplaced, configured adapters could silently allow playlist or nested resource opens again; please add command-level coverage for ffmpeg and ffprobe.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

🟡 Minor · testing · Reply if this doesn't apply.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added tests/Video/E2E/WhitelistTest.php, which runs real ffprobe and ffmpeg: an unrestricted probe follows a local HLS playlist, while a restricted probe and a restricted encoder (with an open probe, so the refusal comes from ffmpeg) both fail on it, and a restricted encoder still probes and grabs from an MP4. Passes locally on ffmpeg 8.1.2.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The end-to-end tests are useful, but they don’t fully cover the requested arguments. Both restricted cases allow file and exclude hls, so their failures demonstrate the format restriction, not that -protocol_whitelist was emitted. They also don’t assert the argument order for each input. The tests exercise playlist rejection, while opens() builds both flags.

Please add command-level assertions for the whitelist arguments and their placement before each FFmpeg input and the FFprobe source.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added cases that restrict protocols only (https,tls,tcp, no format list): ffprobe and ffmpeg (behind an open probe) each refuse a local MP4, so -protocol_whitelist reaches both commands independently of -format_whitelist. A restricted encode of an MP4 also runs. These stay end to end against real binaries rather than asserting argv, since the argv is built in protected methods with no seam to observe it.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Understood. The end-to-end tests cover the restrictions against real ffprobe and ffmpeg binaries, so I’ve dismissed the command-level assertion finding. WhitelistTest.php

$args[] = '-i';
$args[] = $source;

Expand Down Expand Up @@ -177,6 +178,7 @@ public function pack(string $dir): Package
$args = $this->prefix();

foreach ($this->paths() as $input) {
\array_push($args, ...$this->opens());
$args[] = '-i';
$args[] = $input;
}
Expand Down Expand Up @@ -236,6 +238,7 @@ public function grab(string $path, string $output, ?Thumb $options = null): stri
$args[] = self::number($at);
}

\array_push($args, ...$this->opens());
$args[] = '-i';
$args[] = $path;
$args[] = '-map';
Expand Down Expand Up @@ -296,6 +299,7 @@ public function subtitle(string $path, int $stream, string $output, ?int $timeou
$this->directory(\dirname($output));

$args = $this->prefix(progress: false);
\array_push($args, ...$this->opens());
$args[] = '-i';
$args[] = $path;
$args[] = '-map';
Expand Down Expand Up @@ -334,6 +338,7 @@ public function tile(string $path, string $dir, ?Tile $options = null): Spritesh
$height += $height % 2;

$args = $this->prefix(progress: false);
\array_push($args, ...$this->opens());
$args[] = '-i';
$args[] = $path;
$args[] = '-fps_mode';
Expand Down
1 change: 1 addition & 0 deletions src/Video/Adapter/FFprobe.php
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,7 @@ public function read(string $path): Info
'-show_format',
'-show_streams',
'-show_chapters',
...$this->opens(),
$this->source($path),
]);

Expand Down
98 changes: 98 additions & 0 deletions tests/Video/E2E/WhitelistTest.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
<?php

declare(strict_types=1);

namespace Utopia\Tests\E2E;

use Utopia\Video\Adapter\FFmpeg;
use Utopia\Video\Adapter\FFprobe;
use Utopia\Video\Encoder;
use Utopia\Video\Exception\Runtime;
use Utopia\Video\Process;

/**
* A source may be a playlist that names other files. With the demuxers
* restricted, neither ffprobe nor ffmpeg follows it, while a plain container
* still reads as before.
*/
class WhitelistTest extends Base
{
private const FORMATS = ['mov', 'matroska', 'mpegts'];

private const PROTOCOLS = ['file'];

private function playlist(): string
{
$segment = $this->dir.'/segment.ts';

Process::run([
'ffmpeg', '-y', '-hide_banner', '-loglevel', 'error',
'-i', self::video(), '-c', 'copy', '-t', '2', $segment,
], timeout: 60);

$path = $this->dir.'/list.m3u8';
\file_put_contents($path, "#EXTM3U\n#EXT-X-TARGETDURATION:2\n#EXTINF:2,\n".$segment."\n#EXT-X-ENDLIST\n");

return $path;
}

public function testAnUnrestrictedProbeFollowsAPlaylist(): void
{
$this->assertTrue((new FFprobe())->read($this->playlist())->hasVideo);
}

public function testARestrictedProbeRefusesAPlaylist(): void
{
$probe = new FFprobe(protocols: self::PROTOCOLS, formats: self::FORMATS);

$this->expectException(Runtime::class);
$probe->read($this->playlist());
}

public function testARestrictedEncoderRefusesAPlaylist(): void
{
// The probe is left open so the refusal can only come from ffmpeg.
$encoder = new Encoder(new FFmpeg(protocols: self::PROTOCOLS, formats: self::FORMATS), new FFprobe());

$this->expectException(Runtime::class);
$encoder->grab($this->playlist(), $this->dir.'/poster.jpg');
}

public function testAProbeLimitedToOtherProtocolsRefusesALocalFile(): void
{
$probe = new FFprobe(protocols: ['https', 'tls', 'tcp']);

$this->expectException(Runtime::class);
$probe->read(self::video());
}

public function testAnEncoderLimitedToOtherProtocolsRefusesALocalFile(): void
{
$encoder = new Encoder(new FFmpeg(protocols: ['https', 'tls', 'tcp']), new FFprobe());

$this->expectException(Runtime::class);
$encoder->grab(self::video(), $this->dir.'/poster.jpg');
}

public function testARestrictedEncoderStillEncodesAPlainContainer(): void
{
// The encode path builds its own command line; it must still run.
$encoder = new Encoder(
new FFmpeg(protocols: self::PROTOCOLS, formats: self::FORMATS),
new FFprobe(protocols: self::PROTOCOLS, formats: self::FORMATS),
);

$this->assertWritten($encoder->open(self::video())->encode($this->dir.'/out.mp4'));
}

public function testARestrictedEncoderStillReadsAPlainContainer(): void
{
$encoder = new Encoder(
new FFmpeg(protocols: self::PROTOCOLS, formats: self::FORMATS),
new FFprobe(protocols: self::PROTOCOLS, formats: self::FORMATS),
);

$this->assertTrue($encoder->probe(self::video())->hasVideo);
$this->assertWritten($encoder->grab(self::video(), $this->dir.'/poster.jpg'));
}
}
Loading