faceswap - Moses Yebei

The Problem

Developers need a ready‑to‑run pipeline for face‑swap, enhancement, and related video/audio processing. Existing scripts are scattered across many modules, making it hard to trace execution, manage dependencies, and ensure security.

What This Does

facefusion/ implements the full stack: UI components (facefusion/uis/*), processing modules (facefusion/processors/modules/*), and job orchestration (facefusion/jobs/*). The top‑level script facefusion.py simply forwards CLI arguments to the core entry point in facefusion/core.py. Core functions such as create_job, run, render, and pre_check drive the workflow, while helper modules (common_helper.py, filesystem.py, state_manager.py) provide cross‑cutting utilities.

How It Is Wired

Entry point	File & line	Reach
cli	`facefusion/core.py:33`	401 functions
run	`facefusion/benchmarker.py:34`	399 functions
start	`facefusion/process_manager.py:36`	67 functions

The CLI (cli) parses arguments and calls run (the benchmark runner) which in turn:

Calls pre_check → create_static_model_set → resolve_relative_path (172 calls) and resolve_download_url (168 calls).
Uses get_item (called from 117 locations) to fetch UI components, job definitions, and model files.
Invokes ffmpeg.run_ffmpeg (via facefusion/ffmpeg.py) which spawns a subprocess (subprocess.Popen).
Generates a hash with hashlib.sha1().hexdigest in suggest_output_path (cryptographic operation).

The hub module facefusion/__init__.py is imported by 91 other modules, making it the highest‑impact change point. State is stored in facefusion/state_manager.py (7 functions, referenced by 67 files) and persisted via facefusion/filesystem.py (27 functions, 35 callers). Job lifecycle (create_job, submit_job, run_job) lives in facefusion/jobs/job_manager.py (27 functions, 15 callers).

External effects:

Subprocess execution (ffmpeg.run_ffmpeg, subprocess.call) – 42 functions.
File I/O – 4 functions (open_stream, open_ffmpeg, etc.).
Cryptographic hash – 1 function (suggest_output_path).

No circular imports were detected; the import graph is a clean DAG of 167 modules and 712 edges.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/faceswap.git
cd faceswap

# Install Python dependencies (no lockfile, so use a virtualenv)
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

The primary command line is documented in the README:

python facefusion.py run          # normal run
python facefusion.py headless-run  # headless mode
python facefusion.py benchmark   # benchmark suite

Configuration files such as facefusion.ini and facefusion.ico are read by facefusion/config.py. No additional environment variables are required for a basic run.

Real‑World Use

A media‑production pipeline can invoke the CLI from a CI step to generate a swapped‑face video:

- name: Generate swap
  run: |
    source .venv/bin/activate
    python facefusion.py run --input source.mp4 --output out.mp4 --job face_swapper

The job manager records the job in the internal state store, and ffmpeg streams the processed frames to out.mp4.

Code Health & Issues

Critical – gradio==5.42.0 and onnx==1.19.0 have known CVEs (CVE‑2026‑27167, CVE‑2026‑28500). Upgrade to fixed versions and add a lockfile.
High – GitHub Actions reference tags (AnimMouse/setup-ffmpeg@v1). Pin to commit SHA to prevent supply‑chain drift.
Medium – No explicit permissions for GITHUB_TOKEN; add permissions: contents: read.
Medium – No Dependabot/Renovate config; add .github/dependabot.yml.
Medium – No dependency‑vulnerability scan in CI; integrate dependency-review-action or osv-scanner.
Medium – actions/checkout leaves the token persisted; set persist-credentials: false.
Low – Workflow jobs lack timeout-minutes; define reasonable limits.

Additional static findings (selected):

Hub module (facefusion/__init__.py) is imported by 91 modules – high change impact.
Resource safety – facefusion/uis/core.py opens files without a context manager.
Deep nesting – up to 6 levels in facefusion/download.py, facefusion/face_analyser.py, facefusion/program_helper.py.
Duplicated code – 137 six‑line blocks repeated across 44 files (e.g., benchmark UI and core logic).

The Bottom Line

The repository provides a complete, test‑covered face‑manipulation pipeline but suffers from a few high‑impact security and maintainability risks: outdated pinned dependencies, unpinned CI actions, and a large central module that should be stabilized. It is suitable for teams comfortable with Python and willing to address the critical advisories and refactor the hub module before production deployment.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

180 files

Python167
YAML2
Markdown2
CSS1

Express

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["facefusion<br/>125 modules"] g1["tests<br/>40 modules"] g2["(root)<br/>2 modules"] g0 -->|82| g2 g1 -->|72| g0 g1 -->|8| g2

Module dependencies

The 10 most depended-upon modules of 167, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_facefusion["facefusion"] n1_facefusion_types["types"] n2_facefusion_filesystem["filesystem"] n3_facefusion_common_helper["common_helper"] n4_facefusion_download["download"] n5_facefusion_uis_core["core"] n6_facefusion_jobs_job_manager["job_manager"] n7_facefusion_vision["vision"] n8_facefusion_choices["choices"] n9_facefusion_processors_types["types"] n8_facefusion_choices --> n3_facefusion_common_helper n8_facefusion_choices --> n1_facefusion_types n4_facefusion_download --> n8_facefusion_choices n4_facefusion_download --> n0_facefusion n4_facefusion_download --> n2_facefusion_filesystem n4_facefusion_download --> n1_facefusion_types n2_facefusion_filesystem --> n8_facefusion_choices n6_facefusion_jobs_job_manager --> n8_facefusion_choices n6_facefusion_jobs_job_manager --> n2_facefusion_filesystem n6_facefusion_jobs_job_manager --> n1_facefusion_types n9_facefusion_processors_types --> n1_facefusion_types n5_facefusion_uis_core --> n0_facefusion n5_facefusion_uis_core --> n2_facefusion_filesystem n7_facefusion_vision --> n3_facefusion_common_helper n7_facefusion_vision --> n2_facefusion_filesystem n7_facefusion_vision --> n1_facefusion_types

Dependencies

2 of 9 declared dependencies are a major version behind. Resolved 9 of 9 against the registry.

Package	Declared	Latest	Behind
`gradio`	==5.42.0	6.24.0	1 major
`opencv-python`	==4.12.0.88	5.0.0.93	1 major

Findings

LowDependencies declared without a lockfile - non-reproducible builds requirements.txt

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

critical1

high1

medium4

low1

Upgrade the pinned dependency carrying a critical advisorycritical28 occurrences

gradio@5.42.0 CVE-2026-27167 (critical) +12 more; onnx@1.19.0 CVE-2026-28500 (critical) +14 more

The manifest pins the exact version the advisory covers, so this is not a warning about drift: the vulnerable code is what installs, and a critical rating means it is reachable over the network without credentials or user interaction.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Pin third-party GitHub Actions to a commit SHAhigh2 occurrences

.github/workflows

AnimMouse/setup-ffmpeg@v1, FedericoCarboni/setup-ffmpeg@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium

.github/workflows/ci.yml

1 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/ci.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow

.github/workflows/ci.yml

1 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.