SocialFish v3.0: a phishing simulation toolkit that clones real login pages with Playwright

What SocialFish v3.0 is for, and who should not touch it

SocialFish is a phishing simulation toolkit. The README describes it as a "Modern Dynamic Phishing Toolkit" and states that it is for educational purposes only, with consent required and only for systems you own or have explicit written permission to test. The stated use case is a red team or a security awareness exercise: you stand up a clone of a login page, hand a lure URL to a defined group, and watch what they submit.

The v3.0 release notes point at a specific gap in older tools of this kind. Modern login pages are JavaScript-heavy: React, Vue and Angular single-page apps submit credentials through fetch or XHR rather than a plain form POST, and many of them split authentication across two or three steps. A tool that only scrapes the HTML form captures nothing on those pages. SocialFish v3.0 answers that with a Playwright browser automation recorder, which the README lists as the default browser engine, with Selenium as an optional fallback.

The audience is narrow on purpose. If you do not have written authorization, the tool is the wrong instrument, and the README says so twice, in the security section and in the disclaimer. The repository also carries an ADVANCED_ATTACKS_GUIDE.md at the top level, which is worth reading before you decide how much of the feature set you actually want on your network.

How the Playwright recorder, cookie inspector and OTP panel fit together

The architecture is a Flask application with Socket.IO for the real-time parts. SocialFish.py is the main app, and core/ holds the working modules: recorder_playwright.py for browser automation, cookie_inspector.py for cookie analysis, tunnel_manager.py for tunneling, and db_migration.py for the database schema. The admin UI lives under templates/admin/ as templates.html, otp_panel.html and sessions.html.

The data flow the README describes is: you create a template from a target URL, and the recorder drives a real browser through that page so the clone reproduces the JavaScript behaviour instead of just the markup. When a victim submits, the capture mode decides what is stored. The README names three clone modes, both for credentials plus cookies, login for credentials only, and cookies for session only, and says templates can be saved and reused across multiple targets.

Cookie capture is more than a string dump. The README says the cookie jar records domain, path, secure, httponly, samesite and expiry, and that cookie_inspector.py detects auth tokens and analyses security attributes. The OTP panel is the part that needs a live operator: it runs over WebSocket, shows the victim session, waits for a 2FA code either manually or automatically, and can inject that code back into the victim's browser so the flow continues. Multi-step detection is heuristic, and the README names Office365, Gmail and GitHub as examples of flows it handles.

The tunnel manager wraps ngrok or cloudflared and the README says it auto-installs them, which is what makes a lure URL reachable from outside your machine. Webhook notifications fire on credential submit, OTP received and session created, with JSON, form-encoded or XML payloads to Slack, Discord or a custom API.

Installing SocialFish: interactive setup and manual setup

The README gives two paths. The interactive setup runs a wizard that installs dependencies, sets up Playwright browsers, initializes the database and optionally configures tunneling. The wizard checks for Python 3.8 or newer and installs the pinned dependency list from setup.py, which includes flask==2.3.3, playwright>=1.40.0, pyngrok>=7.0.0 and eventlet>=0.33.3.

python setup.py

Expect a banner and a progress log naming each package as it installs, then a Playwright browser download that setup.py itself warns may take a few minutes.

The manual path is three commands. Note that the app takes the admin username and password as command-line arguments rather than reading them from a prompt.

pip install -r requirements.txt
playwright install chromium
python SocialFish.py admin password

The README says the admin interface is then at http://localhost:5000/neptune. If you prefer containers, the repository has a Dockerfile and a docker-compose.yml that publishes port 5000 and starts the app with the credentials user and password.

docker compose up

Those credentials are written into the compose file as comments and as the command argument, so change them before the container is reachable from anywhere but your own machine. One inconsistency worth knowing: setup.py pins flask==2.3.3 while requirements.txt pins Flask==3.1.3, so the two install paths do not resolve to the same Flask version.

Your first template and lure URL

Once the app is running, the workflow in the README is four steps. Create a template from a target URL under /templates, optionally set up a tunnel, generate a lure URL, and monitor sessions. The template form asks for the target URL and a clone mode, and the modes are both, login and cookies.

The README also documents a small HTTP API, which is useful if you want to drive template creation from a script rather than the browser UI. Listing templates is a plain GET, and generating a lure URL is a POST with the template id as form data.

curl http://localhost:5000/templates

curl -X POST http://localhost:5000/lure/generate \
  -d "template_id=1"

The response to the second call contains the unguessable lure URL that you distribute. After that, /sessions shows captured credentials, cookies and OTP codes, and /admin/otp_panel.html is where you sit when a flow reaches a 2FA prompt. If you want the tunnel from the command line instead of the UI, the README lists the tunnel manager directly.

python core/tunnel_manager.py setup
python core/tunnel_manager.py start --type ngrok

Run database migrations with python core/db_migration.py if you are upgrading an existing installation rather than starting fresh.

Where SocialFish v3.0 breaks down

The largest constraint is operational, not technical: the OTP panel needs a human watching it. If a target's login flow asks for a one-time code and no operator is at the panel, the session stalls, and the README's own framing of the panel as "live" and "real-time" confirms that this is an attended workflow rather than a fire-and-forget campaign.

Heuristic multi-step detection is the second soft spot. The README calls it automatic heuristics and also mentions manual breakpoints for user interaction, which tells you the automation has a fallback path for flows it cannot parse. Any site that changes its login markup, adds a CAPTCHA, or fingerprints the browser will move you onto that fallback. Playwright reduces the problem for JavaScript-rendered pages but does not remove it.

The third issue is dependency weight. A Playwright browser download, ngrok or cloudflared, Selenium and webdriver-manager, and a Flask app with Socket.IO is a lot of surface for a tool you may only run during an exercise. The Dockerfile builds on python:3.9.16-alpine3.17 and switches the Alpine repositories to edge, which is a rolling target: a rebuild months later can pull different package versions than the last one did.

Finally, the repository is not archived, but the last push was on 2026-05-20, and the release history is uneven: v3.0.0 landed in 2019 and v3.0.1 in 2026. Treat the v3.0.1 tag as the current state rather than assuming a steady release cadence.

SocialFish against GoPhish and other simulation platforms

The obvious comparison is GoPhish, the widely used open source phishing simulation framework. The difference is where the work happens. GoPhish is campaign-oriented: you import an email template and a landing page, define a target group, schedule a send, and the platform reports on who clicked and who submitted. The landing page is something you supply or import, and capturing a session cookie or relaying a 2FA code is not part of that model.

SocialFish inverts the emphasis. The clone is generated from a live target URL by a browser recorder, the capture modes are about credentials and cookies, and the OTP panel exists to keep a multi-step login moving in real time. That makes it closer to an interception tool with a campaign front end than to a mail-and-reporting platform. If your exercise is about measuring click-through across a large list, GoPhish's model fits better. If your exercise is about what a modern SPA login leaks when it is cloned, and you have an operator available, SocialFish v3.0 is built for exactly that.

A second reference point is the project's own SocialFishMobile repository, which the README points to for a mobile controller. That is a companion rather than an alternative, but it matters if you expect to drive sessions from a phone.

Licence, maintenance and upgrade cost

SocialFish is BSD-3-Clause. The licence text quoted in the README disclaims liability for any direct, indirect, incidental or consequential damages, and the disclaimer adds that use is the complete responsibility of the end user. In practice that means the licence gives you the usual permissive freedoms to use and modify the code, and places the operational risk on whoever runs it. That is a general description of the licence, not legal advice; if you are deploying this inside an organization, have the deployment reviewed against your own policy and local privacy law, which the README also asks you to do under its GDPR note.

Upgrade cost is driven by the dependency pinning. There are two dependency definitions in the repository, setup.py and requirements.txt, and they disagree on Flask. The Dockerfile installs packages individually through pipenv rather than from requirements.txt, so the container, the wizard and the manual pip path can each end up with a different set of versions. Before upgrading, run python core/db_migration.py, since the schema is versioned separately from the application code.

On maintenance: the repository is not archived, and the last push was on 2026-05-20. The gap between v3.0.0 in 2019 and v3.0.1 in 2026 is the honest picture of the release rhythm, so plan to read the diff between tags rather than assuming small patch releases.

Editorial conclusion

SocialFish v3.0 fits red teams and security trainers who run phishing simulations against systems they own or have written permission to test, and who need modern SPA logins, cookie evidence and 2FA flows rather than a static HTML copy. It does not fit anyone without that authorization, and it is a poor choice for a quick demo because the Playwright browser download and the tunnel setup are the slowest parts of the first run. Before you adopt it, verify that Playwright Chromium installs on your host, confirm the credentials you pass on the command line, and check whether the docker-compose.yml default of user and password is acceptable on the network where port 5000 will be reachable.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-3-Clause
3. README
4. Releases
5. UndeadSec/SocialFish on GitHub