Persistent Browser-In-The-Middle

P-BitM is a containerized platform for controlled browser-in-the-middle security assessments. It combines an administrative dashboard, isolated campaign services, dedicated browser containers, live session viewing, and bounded evidence collection.

Caution

Use P-BitM only on systems you own or where you have explicit written authorization. Read the authorized-use policy.

Important

P-BitM is under active development. Its modular architecture is designed to grow with community feedback and contributions, especially new ideas for client-side modules and Firefox extensions used in authorized assessments.

Highlights

• Red Team Operator Dashboard
• Campaign and victim containers lifecycle management
• Target, email, SMTP, landing-page, plugin, and module libraries
• Immediate and scheduled campaigns
• VNC and Selkies browser-session modes
• Role-based administrative access
• Restricted Docker socket proxies and isolated campaign networks
• Campaign and per-session exports

Product demos

The short recordings below show P-BitM in a controlled, authorized environment. Open the linked documentation pages for context and the complete video catalog.

Watch the campaign creation demo

Watch the file interception demo

Quick start

Requirements: Python 3.9+, Docker Engine 23.0+, Docker Buildx and Compose plugins, Git, and OpenSSL. The standalone docker-compose command is not supported. On Linux, the current user should normally have direct access to Docker; P-BitM automatically aligns its unprivileged containers with the selected host UID/GID when bind-mounted storage is used.

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 p-bitm.py setup
python3 p-bitm.py doctor
python3 p-bitm.py up

The dashboard defaults to https://127.0.0.1:8443/. Review config.yaml before setup, especially the environment and production DNS challenge.

Architecture and codebase

P-BitM separates the trusted administrative control plane from the campaign-facing services and browser sessions. The dashboard talks to the admin backend, which stores persistent state and provisions isolated workloads through a restricted Docker socket proxy. Public campaign traffic is routed by Traefik to a per-campaign service, which validates the victim session and connects it to its assigned browser container.

Operator browser
  -> Frontend nginx
  -> Admin backend
     -> SQLite and storage
     -> Restricted Docker proxy
        -> Per-campaign services
        -> Per-session VNC or Selkies browser containers

Victim browser
  -> Traefik
  -> Per-campaign service
  -> Assigned browser session

The source tree is organized around those boundaries:

.
├── bitm-images/
│   ├── common/              # Shared browser-runtime files
│   ├── selkies/             # Selkies browser runtime
│   └── vnc/                 # VNC/noVNC browser runtime
├── assets/                  # Project and README visual assets
├── cli/                     # CLI implementation
├── docs/                    # Credits, use policy, and docs link
├── modules/                 # Built-in modules
├── server/
│   ├── backend/             # Administrative control plane
│   ├── backend-phishing/    # Per-campaign service
│   ├── egress-proxy/        # Controlled campaign egress
│   ├── frontend/            # Administrative dashboard
│   └── traefik/             # Public routing and TLS
└── tests/                   # Shared regression tests

The main codebase boundaries are:

Path	Responsibility
p-bitm.py, cli/	CLI entry point, configuration, setup, diagnostics, and lifecycle operations
server/frontend/	Vue administrative dashboard and its nginx entry point
server/backend/	Trusted FastAPI control plane, persistence, authentication, and container orchestration
server/backend-phishing/app/	Per-campaign FastAPI service, public routes, tracking, and session admission
server/traefik/	Public routing and TLS configuration
server/egress-proxy/	Controlled outbound proxy used by campaign workloads
bitm-images/common/	Files shared by the browser runtimes, including policies, extensions, and keylogging support
bitm-images/vnc/	VNC/noVNC browser runtime
bitm-images/selkies/	Selkies browser runtime using H.264 over WebSockets
modules/	Built-in modules that can be seeded into the application
tests/	CLI and shared regression tests; service-specific tests live beside their services
assets/	Project and README visual assets
docs/	Credits, authorized-use policy, and link to published docs

For a deeper walkthrough, read the architecture, request flow, and service reference. Contributors should start with the development setup.

Documentation

The complete, current documentation is published at P-BitM Docs.

• Installation
• Quick start
• Video demos
• Architecture
• Deployment
• CLI reference
• Security model
• Authorized-use policy

Development

python3 -m pip install pytest
python3 -m pytest tests
PYTHONPATH=server/backend python3 -m pytest server/backend/tests
PYTHONPATH=server/backend-phishing/app python3 -m pytest server/backend-phishing/tests
(cd server/frontend && npm ci && npm run lint && npm test && npm run build)
python3 scripts/release_checks.py

See the development guide. Contributions are welcome; read CONTRIBUTING.md before opening a pull request.

Security

Read SECURITY.md before reporting a vulnerability. Do not include real credentials, collected data, tracking identifiers, or personal information in public reports.

License

P-BitM's original code is distributed under the GNU General Public License version 3 only (GPL-3.0-only). Third-party components remain subject to their respective licenses; see Third-Party Notices and Credits and acknowledgements.