| name | media-security-report |
| description | Prepare, reproduce, and audit standalone upstream security reports for third-party media libraries Firefox vendors, including FFmpeg/ffvpx, libvpx, libaom, dav1d, the Xiph libraries, libpng, libjpeg-turbo, libsoundtouch, libsrtp, libwebrtc, libyuv, libwebp, nestegg, cubeb, mp4parse-rust, and in-tree components with no upstream. Use when Codex needs to determine the correct private reporting channel, reproduce a suspected vulnerability on a vendored revision, trace its root cause with revision-pinned links, export git-formatted patches, draft a submission without sending it, or audit an existing media-library security report.
|
Media Security Report
Purpose
Produce a self-contained report that the library's own maintainer can reproduce
without any Firefox context, and route it to the private channel that library
actually has. Treat the original bug report as evidence to verify, not as the
root cause.
Only FFmpeg and libjpeg-turbo publish required-contents lists, so the report
body is the same everywhere — report-core.md. What
varies per library is the channel, the confidentiality mechanics, and how the
crash input travels: channel-profiles.md and
library-policies.md.
Follow the $source-permalinks skill for every revision-pinned link.
Inputs
Derive the inputs from the user's request; do not guess a missing path:
--audit <path.md> --library <id> → audit mode. Skip to Step 6.--library <id> → library id or a tree path (media/libdav1d works).--firefox <path> → checkout root. Default: walk up from cwd, since this
skill is symlinked into each worktree's .codex/skills/.--report-dir <path> → where the report and artifacts go.- Remaining token: an existing directory or file → the evidence; otherwise a
freeform claim to verify.
- Anything still unresolved → ask the user directly.
On a fresh run, use update_plan to create one item per workflow step. A report
spans several long builds, so keep the plan current and treat the evidence on
disk as the durable record of completed work.
Guardrails
- Never send, file, email, or submit. Prepare the report and the submission
draft; the user does the rest. This includes never opening a prefilled
tracker URL in a way that creates the item.
- Fail closed on routing. A library with no policy row routes to a
Bugzilla security bug with no external CC. Guessing an upstream security
address is the one mistake that discloses a live vulnerability.
- Crash-input delivery is the channel's decision, not yours. Attaching a
file to a confidential GitLab issue in a public project makes it
world-readable. Follow the profile.
- Verify the issue is real, security-relevant, and reproducible. Do not send
automated false positives, ordinary bugs, non-exploitable undefined behavior,
or leaks to a security address. Several projects ban accounts for this.
- Never invent reviewer or finder identities, CVEs, generators, stack
frames, introducing commits, or exploitability claims. Record
Unknown,
Not available, or Not applicable with a reason, and ask the user directly
when a human attribution is required.
- Never invent a revision either. When the tree does not record one, say so.
- Preserve user changes. Never reset or clean a dirty tree destructively;
use a fresh clone or a separate worktree. Inspect any existing worktree first.
- Keep the vulnerable, latest-upstream, and fixed revisions distinct. A
successful run on latest master does not prove the vendored revision was
affected.
- Delegate research, never verdicts. A subagent gathers stacks, traces and
history; the main agent decides what is verified and where the report goes.
- Record the channel's known unknowns rather than resolving them by assumption.
Inputs and output layout
EVIDENCE_DIR: the supplied bug report, attachments, logs, existing patches.UPSTREAM_WORKTREE: a dedicated clone of the library, used only for this report.REPORT_DIR: the report and its artifacts.
REPORT_DIR/
<library>-security-report.md
submission-draft.md # ready to paste; never sent
01-test-<unique-name>.patch
02-fix-<unique-name>.patch
input-<unique-name>.<ext> # if the channel takes attachments
generate-<unique-name>.<sh|py> # if available
stack-<unique-name>.log # optional, cited by the report
research/ # working notes, never submitted
repro-matrix.md
code-path.md
history.md
audit.md
Never reuse a generic name such as input.bin or crash.log. Preserve the
source extension and give every artifact a report-specific unique name.
Subagent delegation policy
Main-agent context is reserved for synthesis: the security-relevance decision,
the routing decision, separating verified facts from assumptions, and the
report wording.
Delegate with spawn_agent when a task is bounded, voluminous, or parallelisable.
Each subagent writes to its own file under REPORT_DIR/research/ and returns a
short summary plus that path. Once the revision is pinned (Step 2), issue these
as parallel subagent tasks when slots are available:
- Repro runner →
research/repro-matrix.md. Builds and runs the vendored,
latest-upstream and fixed revisions; records compiler, configure flags,
platform, thread count, round count, command line, exit/signal status, and
symbolized stacks.
- Code-path tracer →
research/code-path.md. Reads every function in the
claimed call path at the pinned revision and drafts the numbered trace with
revision-pinned links.
- History archaeologist →
research/history.md. git log -S, git log -G,
git blame, parent comparison; reports what was checked when inconclusive.
Never delegate: which channel the report goes to, whether the issue is
security-relevant, the fix design, or any claim that the issue reproduces.
Workflow
0. Identify the library and route
python3 .codex/skills/media-security-report/scripts/media_lib_facts.py --library <id>
Read the library's row in library-policies.md
and its channel section in
channel-profiles.md, then print a routing
block and confirm it with the user before doing any work:
Library: <id> (paths: <tree paths>)
Revision: <ref> (<kind>) <- <where the tree records it>
Repository: <url> [<forge>]
Bugzilla: <product> :: <component> <- <where that came from>
Channel: <profile> → <intake>
Secondary: <… or none>
Crash input: <attach | inline base64 | encrypted attachment | unverified>
One-shot: <the irreversible step, or none>
Test harness: <framework> — <where its tests live>
Gate: if the library has no upstream (has_upstream: false — libmkv,
openmax_il, mozva, psshparser, gmp-clearkey, wmf-clearkey), stop the upstream
workflow here. The deliverable becomes a Bugzilla security bug with no
external CC, reproduction is a Firefox test, and the code is cited with
revision-pinned searchfox links.
If the tool reports an assumed Bugzilla component, verify it before filing:
./mach file-info bugzilla-component <path>.
1. Intake and evidence inventory
- Read the supplied report and list every claimed manifestation, input, command
or API sequence, build mode, stack, patch, and observed result. Inspect
attachments and logs directly; do not rely on a summary when the
source evidence is available.
- Identify the human reviewer(s) who will stand behind the verification and the
human finder(s) to credit. Ask the user directly; a bot is not a human
reviewer. In the same question, capture whether and where AI was used —
never assume, and never answer it on the user's behalf.
- Separate facts from assumptions. Mark anything still needing a run, source
read, or symbolized stack as pending.
- Decide whether the issue belongs at this library's security channel, against
that library's scope gate where it has one (libjpeg-turbo's is explicit). If
it is an ordinary bug, say so and stop.
2. Pin and prepare the source
-
Clone from the repository URL the routing block printed — not from
origin.url in moz.yaml, which is often just the project homepage.
-
Check out the vendored revision. Confirm the tree and hash before each run:
git -C UPSTREAM_WORKTREE status --short
git -C UPSTREAM_WORKTREE rev-parse HEAD
-
When the tree pins a tag, record both the tag and the hash it resolves to,
and cite the hash in the trace. When it records a short hash (libwebrtc),
say so rather than padding it out.
-
List the library's local Firefox patches; a defect may be Mozilla's, not
upstream's. The facts tool prints them.
-
Cite code with the forge template the facts tool printed, always pinned.
3. Reproduce the issue and the fix
Hand the matrix to the repro-runner subagent when the builds are long, then read
research/repro-matrix.md before making any reproduction claim.
- Start with the smallest command or API sequence that exercises the issue. A
custom harness is fine when it is complete and easy to build. Build/test hints
per library are in library-policies.md.
- Build and run the vendored revision first. Use a normal or debug build before
reaching for ASan, UBSan, or guard pages. Keep compiler, configure flags,
platform, thread count, environment, command line, and exit/signal status.
- Run the same test on latest upstream and with the proposed fix. The matrix
must distinguish vulnerable failure, fixed pass, and latest-upstream status.
Repeat scheduling-sensitive tests enough to justify reliability and record the
number of rounds.
- Capture complete symbolized stacks with file and line numbers, each tied to
one exact revision and build. Preserve the original numbering and every frame
from the first emitted frame (
#0 or #1) through the final #N; never omit
frames in the middle or replace them with an ellipsis. Label and include each
stack separately when the report has faulting-thread, thread-creation, or
multiple-manifestation stacks. The validator rejects a stack that skips,
duplicates, reorders, or elides frames.
- Use a uniquely named input. If a generator exists, run it and confirm it
produces that input; if none can be recovered, say so rather than claiming
reproducibility that was not tested.
Standalone test gate. A CLI reproduction gets the issue triaged; a test in
the project's own harness gets it fixed, and stays as a regression guard
afterwards. If the evidence does not already include one, decide whether you can
write one — do not quietly settle for a command line. The routing block prints
the harness, where its tests live, and how a new one is registered.
Ask the user directly first whether a test already exists and whether they want
one attached; a build cycle is expensive. Then follow the T3 mechanism in
$sherlock (.codex/skills/sherlock/SKILL.md, Third-Party Library
Sub-Workflow) rather than inventing a scheme. Use three branches forked from
the vendored revision so the test, instrumentation, and fix stay separable:
<vendored revision>
└── msr/<library>/test ← the test commit, on its own
├── msr/<library>/debug ← instrumentation on top of the test
└── msr/<library>/fix ← the fix on top of the test
- Read an existing test in that harness and copy its shape.
- On the
test branch, write the smallest test that fails on the vendored
revision, and register it the way that harness requires (a FATE .mak entry
and ref file, a test.mk/CMakeLists.txt line, a meson.build entry, a
#[test] fn, …). Export it with
git format-patch -1 --stdout > 01-test-<desc>.patch.
- On the
debug branch, add temporary logging to prove the traced path is
actually hit (fprintf(stderr, "..."), or a library-specific debug macro,
such as dav1d_log or aom_internal_error). Build and run there, keep the
log as evidence, then switch back to test so the exported patches stay
clean. Instrumentation never ships in an attached patch.
- On the
fix branch, make the change and re-run the test both ways.
- Record both results in the matrix, and confirm the test patch applies and
runs on its own before the fix patch goes on top.
The gate is also a scope check, exactly as the T3 result table in
$sherlock treats it. If the test does not reproduce upstream at the
vendored revision, the defect is probably in Firefox integration or its local
patches, not in the library. Stop and say so instead of sending an upstream
report that the maintainer cannot reproduce. If it reproduces differently,
the scope is split and both halves must be reported.
Three libraries have no usable upstream suite — libsoundtouch (SoundStretch CLI
only), nICEr and widevine-adapter. There, a self-contained main() or a Firefox
gtest is the honest substitute; say which you chose.
If a test genuinely cannot be written, record the concrete blocker: no
upstream suite at all, an input that cannot be redistributed, a failure that
needs a sanitizer the harness does not build with, or timing dependence that
makes it unreliable under the runner. "No test was written" with no reason is
not an acceptable answer, and the validator rejects the report for it.
4. Trace the root cause and identify history
The tracer and archaeologist subagents draft research/code-path.md and
research/history.md. The main agent re-opens the cited lines, decides what is
verified, and writes the trace that ships.
- Read every function in the claimed call path at the pinned revision. For
stateful or frame-threaded codecs, explain worker contexts, reference/frame
state, and how decoding state is handed from one worker or frame to the next.
- Write the Code Path Trace as a numbered 1…N sequence: function name,
arrowed call chain, short explanation, revision-pinned links with line
anchors. Keep READ and WRITE paths separate when they share state but fail in
different functions. Explain non-obvious pointer arithmetic in plain language.
- Find the introducing commit with
git log -S, git log -G, git blame, and
parent comparison. Call it "first affected" only when the evidence supports
it; otherwise say "introducing commit unknown" and state what was checked.
- Create the fix on top of the test commit and export both with
git format-patch. The test patch must apply independently; the fix patch
goes on top. Squash exploratory commits so the test attachment is one complete
patch. Keep debug instrumentation out of both.
- For complicated multithreaded or stateful bugs, add a companion note for a
reader with no codec knowledge, and keep the numbered trace concise.
5. Write the report and the submission draft
5a — core evidence. Write REPORT_DIR/<library>-security-report.md using
the skeleton in report-template.md and the
content rules in report-core.md. Every core item is
either populated or explicitly Unknown/Not available/Not applicable with a
reason.
Name the report for the defect, not the library alone —
vp9-frame-thread-flush-oob.md tells a maintainer what it is before they open
it. Fill every placeholder from evidence; never invent or hardcode a name, an
email address, an employer, a disclosure deadline, or an AI-usage statement —
ask the user directly.
5b — channel packaging. Apply the profile: deliver the crash input the way
the channel requires, add the metadata it wants, and omit the metadata it
forbids (CVSS and CWE are welcome on GitHub and forbidden on Bugzilla). Write
the confidentiality mechanics into the report so the user cannot miss them.
5c — submission draft. Fill the channel's template from
submission-drafts.md into
REPORT_DIR/submission-draft.md. It is a draft. Do not send it.
6. Audit and hand off
-
Run the validator and fix every error; warnings require an explicit decision:
python3 .codex/skills/media-security-report/scripts/validate_media_report.py \
REPORT_DIR/<library>-security-report.md --library <id>
-
Launch an independent audit with spawn_agent, using a subagent that has not
seen this run's reasoning. Give it the report path only, and have it write
research/audit.md: open every source link and confirm the cited file and line still say what the
report claims; confirm every link into the library's repository is pinned to
the vendored revision; confirm the crash input is delivered the way the
channel requires; confirm the fixed/unfixed/latest matrix matches the logs; confirm every
crash stack is complete and consecutively numbered with no omitted middle frames;
flag any downstream detail that leaked.
-
When a proposed fix exists, get a second opinion with the $red-pen skill,
passing the report path and the patch path. The reviewer may argue for a
different fix design — that is in scope; escalate it to the user rather than
quietly keeping the original patch.
-
Report what was not available instead of silently omitting it.
Hand off with this shape, and nothing more:
**Security report — <library>** ([report](<path>) · [draft](<path>))
- Verdict: <security-relevant and reproducible | not security-relevant | unverified>
- Channel: <profile> → <intake> (secondary: <… | none>)
- Revisions: vendored `<ref>` / vulnerable `<ref>` / latest `<ref>` / fixed `<ref|n/a>`
- Crash input: <attached <name> | inline base64 | encrypted attachment>
- Standalone test: <in <harness>, attached as <patch> | not feasible: <blocker>>
- Artifacts: <list>
- Validator: <PASS/FAILED, error and warning counts>
- Do these in order when you file:
1. <one-shot / irreversible step first>
2.
Unresolved: <… | none>
The user files the report. This skill never does.
Resources
- report-template.md: the section skeleton a
finished report follows, derived from an accepted upstream report.
- report-core.md: the universal evidence core,
report order, evidence rules, artifact naming, hygiene.
- channel-profiles.md: the six channels, their
mechanics, traps, and what each one wants or forbids.
- library-policies.md: the routing table,
per-library extras, build/test hints, known unknowns.
- submission-drafts.md: one draft template
per channel.
scripts/media_lib_facts.py: live per-library facts from the checkout.scripts/validate_media_report.py: pre-submission structural checker.scripts/channel_policy.py: the machine-readable policy tables.$sherlock skill: T3 upstream test, debug, and fix branch discipline.$source-permalinks skill: revision-pinned URL patterns per forge.$red-pen skill: independent review of the proposed fix.
