Modlishka: an Adversary-in-the-Middle reverse proxy for authorised phishing tests

What Modlishka solves for penetration testers

Modlishka is a reverse proxy written in Go, released under GPL-3.0, whose stated purpose is authorised security testing. The problem it addresses is concrete: a tester who wants to stand between a user's browser and a real target site normally has to either install a certificate on the client or rebuild the target's login page by hand. Modlishka does neither. According to the README, it proxies multi-domain destination traffic, both TLS and non-TLS, over a single domain, and it does so without requiring a certificate to be installed on the client.

The second problem is post-authentication flow. The README states that in 2019 Modlishka was the first publicly released research tool to demonstrate an Adversary-in-the-Middle technique capable of bypassing many common 2FA implementations. That matters because a proxy that only captures a password is useless against an account protected by a one-time code. By sitting in the middle of the live session, the tool sees the code as it is submitted and can keep the session alive. The README lists support for the majority of 2FA authentication schemes out of the box.

The audience is narrow and the README says so twice: the note above the use cases and the closing disclaimer both restrict it to authorised research and professional security testing. If you are not running an engagement with signed scope, this is the wrong project to install.

How the proxy handles TLS and domain translation

The mechanism is a reverse proxy with domain rewriting. You give it a target with -target, and a domain you control with -proxyDomain. Traffic arriving at your domain is forwarded to the target, and links, redirects and resource references pointing at the target are rewritten so the browser keeps talking to you. The README describes this as translating URL domain names to be the proxy domain, and the -disableDynamicSubdomains flag turns that translation off.

Not everything can be rewritten automatically, which is why -targetRes exists: it takes a comma separated list of domains that were not translated automatically, such as static.target.tld. There is a related flag, -staticLocations, for FQDNs in location headers that should be preserved rather than rewritten. Those two flags are the honest admission that automatic rewriting has gaps, and a test that ignores them will show a broken page rather than a working one.

The repository layout backs up the README's claim of a modular design. Alongside main.go there are core/, plugin/, runtime/, templates/ and a config/ directory. Credentials are captured through a regexp with matching groups passed to -credParams, encoded in base64, and the -controlURL flag sets the path where captured credentials and settings can be viewed, defaulting to the string SayHello2Modlishka. That default is documented, which means it is also the first thing an operator should change.

One flag deserves attention on its own. -disableSecurity turns off proxy security features such as anti-SSRF, and the help text says to disable it at your own risk. Anti-SSRF protection is what stops a proxied request from being aimed at internal addresses. Turning it off widens the blast radius of the tool considerably.

Installing Modlishka and running a first proxy

There are two documented installation routes. The first uses the Go toolchain directly. The module path is github.com/drk1wi/Modlishka, and the README gives this command:

go install github.com/drk1wi/Modlishka@latest

The second route builds from source. The Makefile defines a dist directory and a binary named proxy, and the default goal runs the tests before the build, so a plain make will fail early if the test step fails:

git clone https://github.com/drk1wi/Modlishka.git
cd Modlishka
make

After either route you should have a proxy binary. Running it with -h prints the full flag list reproduced in the README. A minimal invocation needs at least a target, a proxy domain, and somewhere to listen:

./dist/proxy -target target.tld -proxyDomain proxy.tld \
  -listeningAddress 127.0.0.1 -listeningPortHTTP 80 -listeningPortHTTPS 443

The README states that certificates can be supplied as base64 encoded values through -cert and -certKey, with -certPool for a certification authority certificate. It also lists an automatic TLS certificate generation plugin that requires a self-signed CA. The README does not document the exact steps for that CA setup, so plan to read the plugin directory rather than the README for it.

For repeatable runs the README recommends a JSON configuration file instead of long command lines, passed with -config. The repository has a config/ directory, but the README does not reproduce a full example file, so the field names have to be taken from the source. That is a real gap for a first-time user.

Where Modlishka breaks or is the wrong choice

The tool is stateless by design, which the README presents as an advantage for scaling behind a DNS load balancer. It is also a limitation: session state that the proxy would otherwise hold has to live somewhere, and the README does not describe how credentials and sessions are shared across multiple instances. If your test needs several proxy nodes behind a balancer, that question is unanswered in the documentation.

The credential panel is labelled beta in the README. Treat it as a convenience for a single operator during a short engagement, not as a case-management system for a long one. The README does not describe retention, storage format or access control beyond the -controlCreds flag, which takes a user:pass pair to protect the credentials page.

Domain translation will fail on sites that build URLs in JavaScript at runtime, use certificate pinning, or serve resources from domains you have not listed in -targetRes. The README's own wording, that translation handles most cases automatically, implies the rest are manual. There is no rollback mechanism described for a half-rewritten page; you either fix the rule list or the page stays broken.

Finally, the licensing and the law are separate constraints. GPLv3 governs what you may do with the code. It says nothing about whether proxying a particular login page is permitted where you operate. The README's disclaimer puts responsibility for actions taken by users on the users themselves, and that is the accurate description of the situation.

Modlishka compared with Evilginx

The obvious alternative is Evilginx, another AitM phishing proxy, and the difference in approach is worth stating plainly. Evilginx is built around phishlets: per-site configuration files that describe which cookies and credentials to capture and how to rewrite that specific service. Adopting a new target means writing or finding a phishlet for it.

Modlishka inverts that. The README states that no website templates are required and that handling is automatic in most cases. Instead of a per-site definition, you supply a target domain and a proxy domain and let the rewriting engine work. That is less upfront work per target and more dependence on the rewriter getting it right. When automatic translation misses a resource, you are debugging rules such as -rules, -targetRes and -staticLocations rather than editing a declarative phishlet.

The practical consequence: Evilginx suits an operator who wants a reviewed, versioned definition per service and is willing to maintain it. Modlishka suits an operator who wants to point the proxy at an unfamiliar target and see what happens, then patch the gaps. Both are GPL-family tools aimed at the same authorised-testing audience, and neither is a general purpose reverse proxy for production traffic.

Maintenance, licence and upgrade cost

The repository is not archived. The most recent push recorded is 2026-08-14, which is recent enough that the project is not dormant, but the release history tells a different story about cadence. v1.1.0 is dated 2019-05-21 and v1.0.0 is dated 2019-01-02. v1.1.1, described as bug fixes and improvements from community contributions, is dated 2025-05-18. That is roughly six years between the second and third releases. Activity between releases appears to live in the master branch rather than in tagged versions, so pinning to a release means pinning to code that is years old.

The build requirements have moved with the toolchain. go.mod declares go 1.25.0, while the README badge advertises Go 1.24 or later. Those two statements disagree, and in practice the go directive in go.mod is the one the compiler enforces. Check your toolchain before you clone.

The dependency set is small and mostly indirect: buntdb for embedded storage, miekg/dns, golang.org/x/net, and a few tidwall and compression packages. A short dependency list keeps the upgrade surface manageable.

On licence: Modlishka is GPL-3.0. The README states that commercial use is permitted under the terms of the GPLv3 and invites contact about support or commercial arrangements. GPLv3 is a copyleft licence, so if you redistribute a modified binary you take on source distribution obligations. Internal use during a client engagement is a different question from shipping a product built on this code, and the README does not resolve it. That is a question for your own counsel, not for this article.

Editorial conclusion

Adopt Modlishka if you run authorised red-team engagements and need a transparent proxy that keeps a target's own pages, cookies and login flow intact while you observe the session; the JSON config and the plugin directory make it scriptable, and the GPLv3 licence is workable for internal testing. Do not adopt it for production traffic, for wrapping a public website you do not own, or for any test where you cannot put the scope in writing first. Before you run it, verify three things: that your Go toolchain satisfies the go 1.25.0 directive in go.mod, that your DNS and certificate plan matches the proxyDomain and target values you intend to set, and that the credential capture path you configure with credParams and controlURL is one your engagement letter covers.

Frequently asked questions

Official sources

1. drk1wi/Modlishka on GitHub
2. Issues
3. License: GPL-3.0
4. README
5. Releases