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/Ne0nd0g/merlin 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.

WAIT — Stale — last commit 1y ago

• 2 active contributors
• GPL-3.0 licensed
• CI configured
• ⚠ Stale — last commit 1y ago
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 93% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No test directory detected

_{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 Ne0nd0g/merlin repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Ne0nd0g/merlin.

What it runs against: a local clone of Ne0nd0g/merlin — 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 Ne0nd0g/merlin | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 415 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Ne0nd0g/merlin. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Ne0nd0g/merlin.git
#   cd merlin
#
# 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 Ne0nd0g/merlin and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "go.mod" \\
  && ok "go.mod" \\
  || miss "missing critical file: go.mod"
test -f "Makefile" \\
  && ok "Makefile" \\
  || miss "missing critical file: Makefile"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"
test -f "data/modules/templates/base.json" \\
  && ok "data/modules/templates/base.json" \\
  || miss "missing critical file: data/modules/templates/base.json"
test -f ".github/workflows/go_main.yml" \\
  && ok ".github/workflows/go_main.yml" \\
  || miss "missing critical file: .github/workflows/go_main.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 415 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~385d)"
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/Ne0nd0g/merlin"
  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).

Merlin is a cross-platform post-exploitation HTTP/2 Command & Control (C2) server and agent framework written in Go that enables adversary simulation and red team operations. It provides encrypted agent communication over HTTP/1.1, HTTP/2, HTTP/3 (QUIC), and peer-to-peer channels with configurable transforms (AES, JWE, RC4, XOR) and authenticators (OPAQUE PAKE), plus capabilities like in-process .NET assembly execution, shellcode injection (CreateThread/RtlCreateUserThread), and Donut/sRDI integration. Monolithic Go module (github.com/Ne0nd0g/merlin/v2) with a gRPC server interface for multi-user CLI access. Core structure likely contains: agent protocol handlers for HTTP/1.1/2/QUIC, transform/encoding pipelines (AES, JWE, RC4, XOR, gob, Base64, hex), authenticator implementations, and Windows-specific execution methods. Data modules live in data/modules/{darwin,linux,windows}/ organized by OS and script language (bash, python, javascript, objective-c, swift), with individual .json module definitions.

Red teamers, penetration testers, and security researchers who need a modular C2 framework for multi-platform post-exploitation testing with HTTP/2 efficiency and encrypted agent-server communication; also supports Mythic integration for collaborative assessment workflows.

Production-ready and actively maintained. The project has 513KB+ of Go code, comprehensive CI/CD pipelines (GitHub Actions for dev/main/release branches plus CodeQL security scanning), and supports Go 1.23+ with recent toolchain updates (Go 1.24.2). Regular releases and active development indicate stable maturity with ongoing feature additions.

Low-to-moderate risk: the project uses well-vetted dependencies (go-jose for JWE, quic-go for HTTP/3, gopaque for OPAQUE) but has a single primary maintainer (@Ne0nd0g). Breaking changes could occur between major versions (currently v2). Dependency count is reasonable (~10 direct deps) and security scanning is integrated. The GPL v3 license may restrict commercial use without disclosure.

Active development with Go dependency updates (latest go.mod targets Go 1.24.2) and Qodana static analysis integration (.qodana/ directory present). The project maintains parallel workflows for dev and main branches with scheduled release builds, indicating continuous feature development and quality assurance. No specific open PRs visible in file list, but CI/CD setup suggests frequent integration.

Clone the repository: git clone https://github.com/Ne0nd0g/merlin.git && cd merlin. Review the Makefile for build targets (exact commands depend on Makefile content, typically make build or go build ./cmd/server). The README.MD provides feature overview; start with the official documentation for setup and agent configuration.

Daily commands: Check Makefile for exact targets: likely make build to compile the server and agents. The project uses a Dockerfile (suggesting containerized deployment) and data/modules/ suggests module-based configuration. Start the server with the compiled binary and configure agents to beacon via HTTP/2 to the server's listener. Refer to merlin-cli (separate repo) for multi-user CLI access via gRPC.

• go.mod — Defines Go version 1.23+ requirement and core dependencies (merlin-message, quic-go, grpc); every contributor must understand the project's language and external constraints
• Makefile — Build automation and cross-platform compilation entry point; essential for understanding how agents and server binaries are produced
• Dockerfile — Container deployment configuration for the Merlin C2 server; critical for DevOps and deployment workflows
• data/modules/templates/base.json — Base module template defining the schema for all post-exploitation modules; contributors adding new modules must reference this template
• .github/workflows/go_main.yml — Primary CI/CD pipeline for the main branch; ensures all contributions meet build and test standards before release
• .github/workflows/release.yml — Automated release workflow managing cross-platform binary distribution; critical for understanding release process and artifact generation
• data/agents/README.MD — Agent configuration and deployment documentation; contributors need this to understand how agents communicate with the C2 server

Add a new post-exploitation module

1. Review the base module schema by examining data/modules/templates/base.json to understand required fields (name, description, options, author) (data/modules/templates/base.json)
2. Create a new JSON file in the appropriate OS/arch/category directory, e.g., data/modules/windows/x64/powershell/credentials/MyModule.json (data/modules/windows/x64/powershell/credentials/Inveigh.json)
3. Define module metadata, command templates, and parameter options matching the base schema structure (data/modules/templates/base.json)
4. Register the module in the Merlin server module loader (inferred from go.mod and README architecture) (README.MD)

Support a new agent platform (OS/architecture)

1. Add compilation target to the Makefile for the new platform (e.g., GOOS=linux GOARCH=arm64) (Makefile)
2. Create corresponding module directories: data/modules/[os]/[arch]/[language]/[category]/ (data/modules/darwin/x64/swift/enumeration/swiftbelt.json)
3. Add language-specific module template if needed (e.g., data/modules/templates/rust.json) following base.json schema (data/modules/templates/base.json)
4. Update GitHub Actions release workflow (.github/workflows/release.yml) to compile and publish binaries for the new platform (.github/workflows/release.yml)

Implement a new C2 communication protocol variant

1. Review go.mod to understand current protocol stack (HTTP/2, gRPC, protobuf, PAKE via gopaque and go-jose) (go.mod)
2. Add new protocol dependency to go.mod if required (e.g., quic-go for QUIC support is already present) (go.mod)
3. Implement protocol handler in server code following merlin-message contract (interface defined in external merlin-message module) (README.MD)
4. Update agent code to support protocol negotiation and message encryption/PAKE handshake (data/agents/README.MD)

• Go 1.23+ — Cross-platform compilation for Windows, Linux, macOS agents; high performance C2 server; single binary distribution
• HTTP/2 + gRPC — Multiplexed streams reduce C2 detection; gRPC enables multi-user operator CLI with streaming command/result updates
• Protocol Buffers (protobuf) — Efficient message serialization for merlin-message exchange; language-agnostic extensibility for future agents
• PAKE (gopaque + go-jose) — Mutual authentication between agent and server without pre-shared secrets; JOSE for TLS integration
• Kyber/v3 (CRYSTALS-Kyber) — Post-quantum cryptography for forward-secrecy in C2 comms; future-proofing against quantum threats
• JSON Module Definitions — Operator-friendly module configuration without recompilation; platform-specific templating (PowerShell, Bash, C#, Swift, Python)

• Centralized module library (data/modules/) vs. agent-embedded modules

  • Why: Operators can dynamically load/update modules server-side without agent recompilation
  • Consequence: Modules must be streamed to agent over C2 channel; larger network footprint vs. pre-cached agent

• HTTP/2 as primary protocol vs. DNS/HTTPS tunneling

  • Why: Low-latency command dispatch and streaming results; native TLS encryption
  • Consequence: HTTP/2 traffic may be more detectable by proxy/firewall rules than DNS; no covert low-bandwidth exfiltration

• gRPC CLI over network vs. local file-based operator interface

  • Why: Multi-user support; centralized audit log; operator isolation
  • Consequence: Added attack surface (gRPC endpoint); requires network reachability; single server failure affects all operators

• JSON-based modules vs. compiled plugin system

  • Why: Lower barrier to entry for operators; no Go compiler required for module authoring
  • Consequence: Modules limited to scripting languages (PowerShell, Bash) or external binaries; performance overhead vs. native code

• Real-time forensic log deletion or anti-forensics on agent machines (module library includes TimestompReference and ClearShellHistory, but detection evasion is operator responsibility)
• Multi-protocol C2 fallback chains (HTTP/2 primary; QUIC support in go.mod but secondary)
• Blockchain or decentralized C2 infrastructure
• Autonomous agent decision-making or AI-driven exploitation
• DNS-based or out-of-band covert channels

No explicit environment variables or local service dependencies visible in file list. Potential gotchas: (1) HTTP/2 protocol nuances—ensure golang.org/x/net version compatibility for h2c (clear-text HTTP/2) support; (2) JWE encryption uses PBES2_HS512_A256KW with specific RFC parameters, mismatches with agent crypto will cause decryption failures; (3) OPAQUE PAKE implementation requires kyber/v3 elliptic curve library—ensure dependency versions align between server and agent; (4) Windows shellcode execution methods (CreateRemoteThread, RtlCreateUserThread) may fail on hardened systems; (5) P2P communication (SMB, TCP, UDP) requires network connectivity and may be blocked by EDR/firewalls. Start with documented HTTP/2 examples before experimenting with exotic transports.

• HTTP/2 and HTTP/3 (QUIC) Protocol Tunneling — Merlin uses multiplexed HTTP/2 and HTTP/3 for C2 communication to blend in with legitimate traffic and reduce detection—understanding frame multiplexing and QUIC's UDP-based handshake is essential for protocol-level optimization
• Password-Based Encryption Scheme 2 (PBES2) with JWE — Merlin agents use PBES2_HS512_A256KW (RFC 7518) for JWE encryption of agent messages—misunderstanding the HMAC-SHA512 PRF or AES Key Wrap (RFC 3394) will cause key derivation failures
• OPAQUE Password-Authenticated Key Exchange (PAKE) — Merlin supports asymmetric PAKE authentication via gopaque, allowing agents to authenticate without transmitting passwords; critical for zero-knowledge credential validation in hostile networks
• Peer-to-Peer (P2P) Agent Mesh with SMB/TCP/UDP — Agents can relay through each other via named pipes (SMB), TCP sockets, or UDP, enabling lateral movement without direct C2 contact—understanding bind vs reverse modes is essential for network topology design
• Shellcode Injection Techniques (CreateThread, RtlCreateUserThread, QueueUserAPC) — Merlin offers multiple Windows shellcode execution methods with varying ETW/behavioral detection profiles—choosing the right technique depends on target hardening and EDR evasion requirements
• gRPC and Protocol Buffers for Multi-User C2 — Merlin server uses gRPC for the merlin-cli interface, enabling concurrent operators and persistent sessions—understanding protobuf serialization and gRPC streaming is necessary for extending the operator API
• Message Padding for Beaconing Evasion — Configurable padding (mentioned in README) obfuscates fixed message sizes to defeat statistical C2 detection; understanding entropy and padding distribution is key to avoiding re-introduction of predictable patterns

• Ne0nd0g/merlin-agent — Companion agent source code for Merlin—this repo is the server; merlin-agent contains the client that beacons back and executes commands
• Ne0nd0g/merlin-cli — Official gRPC command-line interface to the Merlin server, enabling multi-user operator access and remote team collaboration via CLI over the network
• Binject/go-donut — Integrated dependency (github.com/Binject/go-donut in go.mod) that converts .NET assemblies to shellcode, used by Merlin's invoke-assembly and execute-assembly features
• Ne0nd0g/charm — Companion tool for Merlin; charm is a go-based project for handling encoded/encrypted agent traffic (if maintained by same author)
• MythicMorph/Mythic — Collaborative red team framework that Merlin integrates with for multi-operator C2 management; Merlin agents can register as Mythic payloads

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 Go unit tests for agent module implementations in data/modules

The repo has extensive module definitions (JSON configs for Windows/Linux/Darwin post-exploitation tools like Seatbelt, SharpDump, LinEnum, etc.) but no visible Go test files covering module parsing, validation, and execution logic. Testing module loading from these JSON definitions, parameter marshaling, and platform-specific behavior would catch regressions and improve code quality for this critical C2 component.

• [ ] Create pkg/modules/*_test.go files to test module JSON unmarshaling and validation
• [ ] Add tests verifying platform-specific module filtering (Windows/Linux/Darwin)
• [ ] Test module parameter handling and command template substitution
• [ ] Verify cross-platform module execution paths work correctly

Add HTTP/2 and gRPC protocol integration tests in GitHub Actions

The go.mod shows quic-go, google.golang.org/grpc, and golang.org/x/net dependencies indicating HTTP/2 and gRPC support, but the visible GitHub Actions workflows (go_dev.yml, go_main.yml) likely only run basic build/lint checks. Adding a dedicated integration test workflow would validate the actual C2 agent-to-server communication protocols work end-to-end before release.

• [ ] Create .github/workflows/integration_test.yml workflow
• [ ] Add integration tests in a new cmd/integration_tests/ directory testing HTTP/2 handshakes
• [ ] Test gRPC message serialization with merlin-message proto definitions
• [ ] Validate QUIC protocol functionality mentioned in dependencies

Add comprehensive CLI/agent builder tests and cross-compilation validation

The Makefile and release.yml suggest the project builds agents for multiple platforms (Windows/Linux/Darwin, x64, various architectures) but there are no visible tests validating that built agents actually function correctly across platforms. This is critical for a C2 framework where agent deployment failure is catastrophic.

• [ ] Create cmd/tests/builder_test.go to test agent compilation with different flags/obfuscation
• [ ] Add tests verifying compiled binaries can establish C2 communication (mock server)
• [ ] Test architecture-specific builds: windows/x64, linux/x64, darwin/x64
• [ ] Validate agent configuration injection and TLS certificate handling in builds

• Add end-to-end tests for the JWE transform pipeline (PBES2_HS512_A256KW encryption/decryption) under a new test file—currently no visible test coverage for crypto transforms listed in file structure.
• Extend data/modules/ with Linux x64 Go executable module in data/modules/linux/x64/go/exec/ (parallel to existing bash/python/javascript modules) with a .json manifest for basic go-based command execution, enabling code-based post-exploitation on Go systems.
• Document the gRPC server API by adding .proto file definitions or API reference in docs/ showing how merlin-cli connects and sends commands, reducing onboarding friction for contributors adding new agent capabilities.

• High · Outdated QUIC-Go Dependency — go.mod - github.com/quic-go/quic-go v0.50.1. The project uses quic-go v0.50.1, which may have known vulnerabilities. QUIC-go has had multiple CVEs patched in newer versions. The HTTP/2 C&C server should use the latest stable version to mitigate potential network protocol attacks. Fix: Update quic-go to the latest stable version (v0.46.0+). Run 'go get -u github.com/quic-go/quic-go' and test thoroughly.
• High · Outdated Go Toolchain — go.mod - go 1.23.0 and toolchain go1.24.2. The project specifies Go 1.23.0 with toolchain 1.24.2, but these versions are older. Go 1.24.x and 1.25.x have security patches for cryptographic operations, TLS, and standard library vulnerabilities that affect post-exploitation tools handling sensitive data. Fix: Update to Go 1.24.2 or later (preferably 1.25.x when stable). Update the toolchain directive accordingly and retest all cross-platform builds.
• High · Outdated Cryptographic Dependencies — go.mod - golang.org/x/crypto v0.37.0. golang.org/x/crypto v0.37.0 is specified as an indirect dependency. This version is outdated and may lack fixes for cryptographic vulnerabilities. Given Merlin handles command & control communications, cryptographic strength is critical. Fix: Update to golang.org/x/crypto v0.39.0 or later. Verify all TLS/encryption code paths use the latest crypto primitives.
• Medium · Unencrypted gRPC Communication — Dockerfile - ENTRYPOINT and port 50051. The Dockerfile exposes port 50051 for gRPC communication without explicit TLS enforcement documentation. While gRPC supports TLS, there's no visible configuration enforcing it. Unencrypted gRPC could leak command metadata. Fix: Implement mandatory TLS for gRPC connections. Add -tls flag to the server startup and document certificate setup. Verify with 'grpcurl -plaintext' tests that plaintext connections are rejected.
• Medium · Exposed All Interfaces (0.0.0.0) — Dockerfile - ENTRYPOINT argument '-addr 0.0.0.0:50051'. The Dockerfile starts the Merlin server bound to 0.0.0.0:50051, exposing the gRPC interface on all network interfaces. This is risky in multi-tenant or shared environments. A compromised container can expose the C&C control interface. Fix: Bind to 127.0.0.1:50051 by default or use environment variables for configuration. Document security best practices for network isolation. Use Docker network policies to restrict access.
• Medium · Missing HTTPS Configuration Documentation — Dockerfile comments and data/agents/README.MD. Port 443 is exposed for listeners but no documentation shows how TLS certificates are provisioned or validated. The listener might accept invalid certificates or use self-signed certs without proper validation. Fix: Document certificate provisioning strategy (e.g., Let's Encrypt, self-signed with pinning). Add TLS configuration validation in the codebase. Implement certificate pinning in agents.
• Medium · Outdated Base Image (Merlin-Base v1.5.0) — Dockerfile - FROM ne0nd0g/merlin-base:v1.5.0. The Dockerfile uses 'ne0nd0g/merlin-base:v1.5.0' which may contain outdated system libraries and OS-level vulnerabilities. Base images need regular updates for security patches. Fix: Update to the latest available merlin-base image. Rebuild and scan with tools like Trivy or Snyk. Pin to specific SHAs instead of version tags for reproducibility.
• Medium · No Input Validation Documentation — undefined. Module JSON files reference complex post-exploitation techniques (e.g., SharpDump, Safety 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.