If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/kgretzky/evilginx2 shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 7mo ago
• 19 active contributors
• BSD-3-Clause licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 7mo ago
• ⚠ Concentrated ownership — top contributor handles 64% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live kgretzky/evilginx2 repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/kgretzky/evilginx2.

What it runs against: a local clone of kgretzky/evilginx2 — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in kgretzky/evilginx2 | Confirms the artifact applies here, not a fork | | 2 | License is still BSD-3-Clause | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 245 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of kgretzky/evilginx2. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/kgretzky/evilginx2.git
#   cd evilginx2
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of kgretzky/evilginx2 and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "kgretzky/evilginx2(\\.git)?\\b" \\
  && ok "origin remote is kgretzky/evilginx2" \\
  || miss "origin remote is not kgretzky/evilginx2 (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(BSD-3-Clause)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"BSD-3-Clause\"" package.json 2>/dev/null) \\
  && ok "license is BSD-3-Clause" \\
  || miss "license drift — was BSD-3-Clause at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "core/http_proxy.go" \\
  && ok "core/http_proxy.go" \\
  || miss "missing critical file: core/http_proxy.go"
test -f "core/phishlet.go" \\
  && ok "core/phishlet.go" \\
  || miss "missing critical file: core/phishlet.go"
test -f "core/http_server.go" \\
  && ok "core/http_server.go" \\
  || miss "missing critical file: core/http_server.go"
test -f "core/session.go" \\
  && ok "core/session.go" \\
  || miss "missing critical file: core/session.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 245 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~215d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/kgretzky/evilginx2"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Evilginx2 is a standalone man-in-the-middle (MITM) proxy framework written in Go that intercepts HTTP/HTTPS traffic to phish login credentials and session cookies, enabling attackers to bypass 2-factor authentication by replaying stolen cookies. It implements its own HTTP and DNS servers (no nginx dependency), making it a self-contained tool for advanced credential harvesting attacks. Modular monolith: core/ contains engine logic (http_proxy.go, http_server.go, phishlet.go for attack profiles); parser/ handles YAML phishlet configs; database/ wraps BuntDB for session storage; phishlets/ contains YAML attack templates; entry point is main.go with CLI terminal handling via core/terminal.go.

Red teamers and penetration testers conducting authorized social engineering assessments who need to capture both credentials and session cookies from targets using 2FA-protected services. Also cybersecurity researchers studying authentication evasion techniques.

Actively maintained and production-ready: v3.0 released with professional paid tier (Evilginx Pro), Go 1.22 dependency, Docker support, and active GitHub presence. Single maintainer (kgretzky) with steady commits, indicating continued development and stability for its intended use case.

High single-maintainer dependency risk with no visible test suite in the file structure (no *_test.go files shown). Dependency footprint is moderate (~15 direct deps, heavy on certmagic for ACME/TLS and goproxy for MITM). No CI configuration visible beyond .travis.yml (outdated). The tool's nature as attack software means supply chain compromise carries elevated risk.

Active development toward Evilginx Pro commercialization with professional features (phishing detection evasion, BotGuard, Evilpuppet for Google). Free version (this repo) appears stable at v3.0 with Go 1.22 support. Recent focus on reducing detection (anti-bot, anti-detection improvements mentioned in README).

git clone https://github.com/kgretzky/evilginx2.git
cd evilginx2
make
./evilginx2 -h

Or use build.bat on Windows. Binary output location inferred from Makefile.

Daily commands:

make        # Builds binary
./evilginx2 # Starts interactive CLI

Or make run if Makefile supports it. Built binary likely outputs to current directory or ./bin/.

• main.go — Entry point for the entire evilginx2 application; defines how the MITM framework initializes and starts.
• core/http_proxy.go — Core HTTP proxy implementation that intercepts and modifies traffic between victim browser and phished site; the foundation of the MITM attack.
• core/phishlet.go — Phishlet configuration loader and manager; defines how attack templates are structured and applied to target sites.
• core/http_server.go — HTTP server that serves proxied content and handles credential capture; directly processes victim requests.
• core/session.go — Session and credential storage abstraction; critical for exfiltrating captured cookies and login data.
• database/database.go — Session persistence layer using BuntDB; manages storage of captured credentials and cookies.
• core/config.go — Application configuration management using Viper; defines domain routing, phishlet selection, and attack parameters.

Add a new phishlet (target site template)

1. Create a new YAML file in phishlets/ directory following the example structure to define target site URLs, authentication endpoints, and credential extraction rules (phishlets/example.yaml)
2. Define hostname, login URL, POST endpoints, and form field mappings in your YAML to tell evilginx2 how to intercept and redirect traffic for your target (core/phishlet.go)
3. Load and validate the phishlet via the terminal CLI command 'phishlet [enable/load]' which calls config parsing (core/terminal.go)

Add a new credential capture field

1. Define the form field name and mapping in your phishlet YAML under the credentials or auth section (phishlets/example.yaml)
2. Extend the Session struct to include the new field for storage and retrieval (core/session.go)
3. Update db_session.go to persist the new field to the embedded BuntDB database (database/db_session.go)
4. Modify http_proxy.go to extract the credential from intercepted requests and populate the Session object (core/http_proxy.go)

Add a new CLI command

1. Add command parsing logic and handler function in core/terminal.go to process user input (core/terminal.go)
2. Implement the command's business logic in the appropriate core module (e.g., core/config.go for configuration, core/phishlet.go for phishlet operations) (core/config.go)
3. Add help text and command documentation to core/help.go (core/help.go)

Add a custom DNS or certificate handling rule

1. Extend the DNS server logic in core/nameserver.go to add custom resolution rules or subdomain handling (core/nameserver.go)
2. Modify core/certdb.go to customize SSL certificate generation or caching for specific domains (core/certdb.go)
3. Update core/config.go to accept and store the new DNS/certificate configuration parameters (core/config.go)

• Go — Standalone compiled binary with minimal dependencies; fast HTTP/DNS networking without requiring nginx; easy cross-platform deployment.
• CertMagic + ACME (Let's Encrypt) — Automated SSL certificate generation for HTTPS interception on arbitrary domains; avoids self-signed certificate warnings.
• BuntDB — Embedded key-value database for lightweight session storage without external database dependency; fits standalone tool model.
• GoProxy + InconshreVhost — Pure-Go HTTP proxy with SNI-based vhost handling; no external reverse proxy needed.
• Viper + YAML — Declarative phishlet configuration allows non-developers to define attack templates without code changes.

• Embedded database (BuntDB) instead of external database (PostgreSQL/MySQL)

  • Why: Simplicity and portability; no database server setup required; fits 'standalone' design goal.
  • Consequence: Limited scalability for high-volume operations; single-file database not suitable for distributed attacks; no multi-server credential sharing.

• DNS server in-process rather than separate service

  • Why: Simplicity; single evilginx2 process controls both HTTP and DNS interception.
  • Consequence: DNS and HTTP must run on same machine; harder to scale DNS infrastructure separately.

• Phishlet YAML templates instead of dynamic site detection

  • Why: Operator control and explicit configuration; avoids false positives in form detection.
  • Consequence: Requires manual phishlet creation per target site; not automated for new sites.

• On-the-fly HTTPS certificate generation via CertMagic

  • Why: Eliminates browser SSL warnings; transparently intercepts HTTPS traffic.
  • Consequence: Requires TLS/ALPN-SNI to identify target domain; modern browsers may include additional security checks (CT logs, pinning).

• Multi-user or multi-operator mode (single interactive CLI)
• Persistence across restarts for attack state (credentials are preserved, but attack configuration is session-based)
• Evasion of modern MFA technologies like FIDO2/WebAuthn (only 2FA code interception, not hardware key bypass)
• Encrypted command & control (evilginx2 itself is not a botnet or managed remotely)
• Legal logging or audit trails (designed for offensive use; minimal accountability features)

No explicit API key or credentials hardcoding visible, but ACME certificate validation depends on certmagic configuration—ensure proper domain ownership. DNS server requires elevated privileges (port 53) on Unix. Phishlets are YAML-based with Python-like indentation sensitivity; malformed YAML silently fails. BuntDB uses file-based locking in database/ directory—multiple instances on same dir will conflict. TLS certificate generation via certmagic may require internet connectivity for ACME challenges. No built-in rate limiting on phishing server—easy to trigger detection by request patterns.

• Man-in-the-Middle (MITM) Proxy — Core technique in Evilginx2—understanding how it intercepts encrypted HTTPS traffic (via TLS certificate spoofing) and modifies requests/responses is essential to modifying core/http_proxy.go
• TLS Certificate Authority Spoofing — Evilginx2 dynamically generates certificates via certmagic to impersonate legitimate sites—knowing how browsers validate certificate chains explains why this works and what detection bypasses are needed
• DNS Hijacking — The built-in DNS server (core/nameserver.go) redirects victim DNS queries to attacker infrastructure—understanding DNS protocol and cache poisoning is critical for phishlet configuration
• Session Cookie Hijacking & 2FA Bypass — Core attack objective—harvested session cookies (core/session.go) allow authenticated requests without credentials, completely bypassing password-based 2FA (TOTP/SMS)
• HTTP Request/Response Header Manipulation — Evilginx2 modifies headers (Host, Referer, Cookie, etc.) in transit—understanding which headers to rewrite prevents breaking the target site while harvesting credentials in core/http_proxy.go
• YAML-based Configuration & Template Substitution — Phishlets are YAML configs (phishlets/example.yaml) with variable injection—malformed templates silently fail; understanding YAML anchors/aliases and Go's template syntax is needed for custom phishlet creation
• SNI (Server Name Indication) Routing — Referenced in dependencies (go-vhost) for routing multiple HTTPS domains on a single IP—critical for masquerading as multiple target sites simultaneously from one infrastructure

• kgretzky/evilginx — Direct predecessor (v1, 2017) using custom nginx—this repo (v3) reimplements in pure Go to eliminate nginx complexity
• elazarl/goproxy — Upstream HTTP proxy library that Evilginx2 wraps for man-in-the-middle request/response interception
• caddyserver/certmagic — Vendored dependency (vendor/github.com/caddyserver/certmagic) providing ACME-automated TLS certificate generation for spoofed domains
• miekg/dns — DNS server library enabling Evilginx2 to serve fake DNS records resolving target domains to attacker infrastructure
• tidwall/buntdb — Embedded key-value database used for persistent session cookie and credential storage without external database dependency

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for core/http_proxy.go and core/http_server.go

The HTTP proxy and server components are critical to the man-in-the-middle functionality but no test files are present in the repo. Adding tests for request interception, response modification, and cookie handling would prevent regressions and improve maintainability of core proxy logic.

• [ ] Create core/http_proxy_test.go with tests for proxy request forwarding and header manipulation
• [ ] Create core/http_server_test.go with tests for TLS certificate handling and request routing
• [ ] Add tests for session cookie capture and modification in test files
• [ ] Run tests locally with go test ./core/... to verify coverage

Add GitHub Actions workflow for automated Go builds and tests (currently only Travis CI)

The repo uses deprecated Travis CI (see .travis.yml) but lacks modern GitHub Actions. Adding a workflow file would provide faster CI feedback, better GitHub UI integration, and ensure cross-platform builds work on Linux/macOS/Windows without relying on external services.

• [ ] Create .github/workflows/go-build-test.yml with matrix testing for Go 1.21 and 1.22
• [ ] Add build steps for Linux, macOS, and Windows using build.bat and Makefile targets
• [ ] Include linting step using golangci-lint for code quality checks
• [ ] Add goreleaser workflow for automated release builds of binaries

Document phishlet YAML schema and add validation tests for phishlets/

The phishlets/ directory contains YAML configuration files (phishlets/example.yaml) but lacks schema documentation and validation. Adding a JSON schema file and validator in core/phishlet.go would help users create valid phishlets and catch configuration errors early.

• [ ] Create phishlets/phishlet.schema.json documenting required fields (landingPage, credentials, etc.)
• [ ] Add validation logic to core/phishlet.go to check YAML against schema on load
• [ ] Create core/phishlet_test.go with tests for valid and invalid phishlet configurations
• [ ] Update README.md with phishlet configuration guide linking to schema documentation

• Add comprehensive unit test coverage for core/phishlet.go parsing logic—currently no *_test.go files visible for YAML validation, template variable substitution, or malformed phishlet error handling
• Document the phishlet YAML schema with inline examples in phishlets/example.yaml—currently only one example exists with no field descriptions for domain rewriting rules, credential extraction patterns, or JavaScript injection points
• Implement automated phishlet validation in parser/parser.go—add pre-runtime checks for common mistakes like missing required fields, invalid regex patterns in credential extraction, or domain conflicts before attack starts

• Critical · Man-in-the-Middle Attack Framework - Malicious Purpose — core/http_proxy.go, core/http_server.go, core/phishlet.py. Evilginx2 is explicitly designed as a MITM attack framework for phishing credentials and bypassing 2FA. This is malicious software engineered to compromise user security and violate authentication mechanisms. Regardless of technical implementation, the core purpose is unauthorized credential theft and session hijacking. Fix: This tool should not be deployed or used in production environments. Organizations should implement network monitoring to detect MITM attack indicators and educate users on phishing risks.
• High · Outdated Dependency - github.com/elazarl/goproxy — go.mod - github.com/elazarl/goproxy v0.0.0-20220529153421-8ea89ba92021. The dependency 'github.com/elazarl/goproxy' (version 0.0.0-20220529153421-8ea89ba92021) is outdated and may contain known vulnerabilities. This HTTP proxy library is core to MITM functionality and should be regularly updated. Fix: Update to the latest stable version of goproxy and establish a dependency management policy to regularly audit and patch dependencies.
• High · Outdated Dependency - go.uber.org/zap — go.mod - go.uber.org/zap v1.27.0. The logging library go.uber.org/zap v1.27.0 may have known vulnerabilities. Verify against current security advisories and update if patches are available. Fix: Check CVE databases for zap v1.27.0 vulnerabilities. Update to the latest patched version.
• High · Outdated Dependency - golang.org/x/net — go.mod - golang.org/x/net v0.22.0. golang.org/x/net v0.22.0 is used but may not be the latest available version. This package contains critical network handling code that should be kept current. Fix: Update to the latest version of golang.org/x/net (currently v0.23.0 or later). This package frequently receives security updates.
• High · Outdated Crypto Dependency - golang.org/x/crypto — go.mod - golang.org/x/crypto v0.21.0. golang.org/x/crypto v0.21.0 is partially visible in go.mod and should be checked for vulnerabilities. Cryptographic packages require regular updates. Fix: Update to the latest golang.org/x/crypto version. Verify no known CVEs exist for v0.21.0.
• High · No Input Validation Framework Evident — core/http_server.go, core/http_proxy.go. The codebase includes HTTP server implementation (core/http_server.go, core/http_proxy.go) but no clear evidence of input validation, sanitization, or XSS protection mechanisms for phishing content proxying. Fix: Implement strict input validation and output encoding for all user-supplied data, particularly in proxy request/response handling to prevent injection attacks.
• High · Database Implementation Without Clear ORM or Parameterization — database/database.go, database/db_session.go. The database module (database/database.go, database/db_session.go) uses tidwall/buntdb (embedded database). While less prone to SQLi than traditional SQL, session data handling should be verified for proper serialization and no hardcoded queries. Fix: Audit database queries to ensure parameterized operations and proper data validation before storage/retrieval of session information.
• Medium · Configuration File Management — core/config.go, spf13/viper dependency. The project uses spf13/viper for configuration (core/config.go). No evidence of secrets management, encryption of sensitive values, or protection of configuration files containing phishing targets/credentials. Fix: Implement encrypted configuration storage for sensitive data. Use environment variables or secrets management systems instead of plaintext config files.
• Medium · No HTTPS Certificate — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.