Getting started

Welcome to the Famir documentation.

What is Famir?

Famir (short for Fake Mirrors) is an open-source platform for building mirrors of real websites using reverse proxying.

It is not a ready-to-use product. It is a framework — a set of building blocks, contracts, and runtime services that you assemble into your own mirroring project. You bring the knowledge of the target website; Famir brings the infrastructure to mirror, reshape, and control its traffic.

Think of it as a toolkit for building a custom proxy platform tailored to one or many real websites.

Disclaimer: Famir is intended for security research and educational purposes only. You are responsible for complying with all applicable laws and the terms of service of any website you interact with.

Who is it for?

Security researchers studying how modern websites behave, how they can be mirrored, and how their traffic can be reshaped.

Red teams building controlled mirror environments for simulations.

Engineers working on censorship circumvention, archival access, or resilient content delivery.

The common denominator: you need to mirror a real website, but a plain Nginx proxy_pass is not enough. Real sites have subdomains, streaming, WebSockets, dynamic assets, and auth flows. Famir is built for that reality.

Why not just use a reverse proxy?

Modern websites are messy. A single site typically involves:

  • Many subdomains (www, api, cdn, static, auth, ...).
  • Mixed transports: request/response, streaming, WebSockets, SSE.
  • Complex asset pipelines and signed URLs.
  • Region- and session-dependent responses.

A generic reverse proxy cannot handle this without per-site customization. Famir makes that customization a first-class concept.

Customization happens in two directions:

  1. Presets - YAML files describing how the donor site and the mirror map to each other: subdomains, hostnames, routing rules.
  2. Middleware — backend controllers written in TypeScript that inspect and modify traffic. Famir ships with built-in controllers, and you write custom ones for the specific website you are mirroring.

You do not configure Famir once. You build a project with Famir, and that project describes your mirrors.

Killer features

  • Fully dynamic configuration - change campaigns, routes, and rules at runtime. No restarts.
  • Multi-target reverse proxy - one backend serves hundreds of mirrors at once. Routing is done by the Host header. Scale horizontally by adding more instances.
  • Two mirroring modes:
    • Transparent — an open mirror that behaves like the original site.
    • Landing — a closed mirror reachable only through a secret lure link, personalized per client or group.
  • Outbound traffic through HTTP/SOCKS proxies - control how the mirror talks to the donor.
  • Client tracking via session cookie - stable identity across requests, useful for personalization and analysis.
  • Advanced traffic interception and modification - rewrite headers, bodies, HTML DOM, and inject scripts into the browser.
  • REPL console - manage configuration from a command-line style interface. Two implementations: a standalone app and a TCP server you can reach with telnet or netcat.
  • Caddy as edge server - new mirrors are deployed instantly via the Caddy admin API.
  • Low resource footprint - runs comfortably on a low-cost virtual machine.
  • Clean architecture - services are closed behind contracts with multiple implementations. Extending Famir in any direction is expected, not exceptional.

Stack

  • Runtime: Node.js
  • Language: TypeScript
  • Edge server: Caddy (managed through its admin API)
  • State & messaging: Redis
  • Object storage: any S3-compatible backend (MinIO, AWS S3, ...)
  • Outbound transport: HTTP and SOCKS proxies

The three applications

Famir consists of three cooperating applications:

  1. reverse: Multi-target reverse proxy with dynamic configuration. The data plane. Routes by Host, applies middleware, forwards traffic.
  2. console: Command interface for dynamic configuration management. The control plane. REPL over Redis, also exposed as a TCP server.
  3. actions: Workers for background job processing. Long-running or deferred tasks triggered by the control plane.

You will typically run all three, plus Caddy, Redis, and an S3-compatible store.

What you actually build

Using Famir means writing your own project on top of it. In practice you will:

  1. Write preset YAML files that describe a campaign: the donor site, its subdomains, how the mirror maps to them, and which lure rules apply.
  2. Write middleware controllers in TypeScript for the specific website you are mirroring. Built-in controllers cover common cases; custom ones handle the rest — auth flows, asset rewriting, streaming quirks, WebSocket upgrades, DOM manipulation, script injection.
  3. Compose these into a running project: launch reverse, console, and actions, point them at Redis and your S3 bucket, and register the mirror in Caddy through its admin API.

Famir provides the contracts. Your project provides the knowledge of the website.