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/Hackplayers/evil-winrm 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 — Mixed signals — read the receipts

• Last commit 2mo ago
• 8 active contributors
• LGPL-3.0 licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 58% of recent commits
• ⚠ LGPL-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 Hackplayers/evil-winrm repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Hackplayers/evil-winrm.

What it runs against: a local clone of Hackplayers/evil-winrm — 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 Hackplayers/evil-winrm | Confirms the artifact applies here, not a fork | | 2 | License is still LGPL-3.0 | 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 ≤ 91 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(LGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"LGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is LGPL-3.0" \\
  || miss "license drift — was LGPL-3.0 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 "bin/evil-winrm" \\
  && ok "bin/evil-winrm" \\
  || miss "missing critical file: bin/evil-winrm"
test -f "evil-winrm.rb" \\
  && ok "evil-winrm.rb" \\
  || miss "missing critical file: evil-winrm.rb"
test -f "evil-winrm.gemspec" \\
  && ok "evil-winrm.gemspec" \\
  || miss "missing critical file: evil-winrm.gemspec"
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f "Dockerfile" \\
  && ok "Dockerfile" \\
  || miss "missing critical file: Dockerfile"

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

Evil-WinRM is a Ruby-based remote shell client that exploits WinRM (Windows Remote Management) and PSRP (PowerShell Remoting Protocol) to gain interactive command execution on Windows servers during post-exploitation. It specializes in offensive security features like in-memory code execution (DLLs, C# assemblies, PowerShell scripts), AMSI bypass, pass-the-hash authentication, and Kerberos support—all from a Linux attacker machine. Monolithic single-file Ruby application (evil-winrm.rb is the core) with a CLI entry point (bin/evil-winrm), a Gemfile for dependency management, and a resources/ folder for assets. The project uses a traditional gem structure with evil-winrm.gemspec defining the package, and GitHub Actions workflows (in .github/workflows/) handle CI/CD for both dev and master branches.

Penetration testers and red teamers who have obtained valid credentials or hashes for a Windows target and need a user-friendly shell alternative to vanilla WinRM. System administrators may also use it for legitimate remote management, but the feature set (AMSI bypass, AV evasion, donut payloads) is clearly optimized for offensive security workflows.

Actively maintained but moderately mature: the project has CI/CD via GitHub Actions (dev.yml and master.yml workflows), proper gem packaging (evil-winrm.gemspec in RubyGems), and responsive issue/PR handling visible from the CHANGELOG and CONTRIBUTING guidelines. However, it is a specialist tool without widespread enterprise adoption, and the single primary maintainer (Hackplayers org) presents some continuity risk.

Low-to-moderate dependency risk: as a ~158KB Ruby codebase, it likely has a manageable dependency graph (see Gemfile), but the project's focus on offensive security means it could be targeted by security researchers or become a legal/liability concern in some jurisdictions. The reliance on external WinRM libraries (now using PSRP protocol internals) means upstream breaking changes could impact functionality. No obvious signs of abandonment, but commit recency data is not provided.

Based on the file structure, the project maintains two main branches (dev.yml and master.yml workflows suggest active CI/CD), has coding standards enforced via .rubocop.yml, and follows a pull request template (.github/pull_request_template.md). A CHANGELOG.md indicates version tracking, though specific recent commits or open PRs are not visible in the provided data.

Clone the repo and install via bundler: git clone https://github.com/Hackplayers/evil-winrm.git && cd evil-winrm && bundle install. Then run: bundle exec ruby evil-winrm.rb -i <target_ip> -u <user> -p <password> or use the prebuilt gem: gem install evil-winrm && evil-winrm -i <target_ip> -u <user> -p <password>.

Daily commands: Local development: bundle install && bundle exec ruby evil-winrm.rb -i <IP> -u <USER> -p <PASS>. Alternatively, build and run the Docker image: docker build -t evil-winrm . && docker run -it evil-winrm -i <IP> -u <USER> -p <PASS>. The bin/evil-winrm executable is the standard entry point.

• bin/evil-winrm — Entry point executable that bootstraps the WinRM shell application.
• evil-winrm.rb — Core main module containing the primary WinRM shell logic and command handling.
• evil-winrm.gemspec — Gem specification defining dependencies, version, and package metadata required for distribution.
• Gemfile — Ruby dependency lock file that specifies all required libraries and versions for reproducible builds.
• Dockerfile — Container image definition for packaging evil-winrm in isolated environments with all dependencies.
• README.md — Primary documentation describing purpose, usage, installation, and feature overview for all users.
• .github/workflows/master.yml — CI/CD pipeline for automated testing and release validation on the master branch.

• CLI Entry Point (bin/evil-winrm) (Ruby, OptionParser) — Parse command-line arguments, validate inputs, instantiate shell with credentials
  • Failure mode: Invalid arguments or missing credentials cause immediate exit with usage message
• WinRM Shell Engine (evil-winrm.rb) (Ruby, WinRM client library, OpenSSL) — Core REPL loop handling user commands, WinRM protocol communication, output formatting, session state
  • Failure mode: Connection drops or authentication loss terminates interactive shell; command execution errors displayed to user
• WinRM Authenticator (WinRM protocol, SOAP/XML, HTTPS) — Establish SOAP session with target, handle Basic/Kerberos/NTLM authentication, maintain session tokens
  • Failure mode: Failed credentials prevent shell initialization; SSL errors occur with untrusted certificates
• Command Executor (PowerShell, WinRM protocol, Base64 encoding) — Wrap PowerShell commands in WinRM payload format, send to target, stream and parse output
  • Failure mode: Malformed PowerShell causes remote errors; large output streams may timeout or truncate
• Container Runtime (Dockerfile) (Docker, Alpine/Debian Linux, Ruby) — Provide isolated Linux environment with Ruby and evil-winrm pre-installed for consistent deployment
  • Failure mode: Container networking issues prevent WinRM connection to target; missing dependencies cause runtime errors

Add a New WinRM Command Handler

1. Define the command handler logic in the main shell module (evil-winrm.rb)
2. Register the command in the command dispatcher/router within the main module (evil-winrm.rb)
3. Document the new command in the README feature list (README.md)
4. Add entry to changelog with version and description (CHANGELOG.md)

Add a New Ruby Dependency

1. Add the gem to the gemspec with version constraint (evil-winrm.gemspec)
2. Run bundle install to resolve and lock the dependency (Gemfile)
3. Import and initialize the dependency in the main module (evil-winrm.rb)
4. Update README with new capability or feature enabled by dependency (README.md)

Update Docker Image for New Ruby Version

1. Update the base Ruby image version in Dockerfile (Dockerfile)
2. Verify evil-winrm.gemspec compatibility constraints (evil-winrm.gemspec)
3. Test the container build locally (Dockerfile)
4. Document Ruby version update in CHANGELOG (CHANGELOG.md)

Enforce New Code Style Rule

1. Add the linting rule to rubocop configuration (.rubocop.yml)
2. Run rubocop against entire codebase to identify violations (evil-winrm.rb)
3. Fix violations in main module and other Ruby files (evil-winrm.rb)
4. Document the style change in CONTRIBUTING guide (CONTRIBUTING.md)

• Ruby — Rapid prototyping and scripting language ideal for penetration testing tools with minimal dependencies
• WinRM (WS-Management Protocol) — Native Windows remote management protocol available on all modern Microsoft Windows systems, no additional software required
• Docker — Provides isolated, reproducible execution environment across different Linux hosts for consistent pentesting campaigns
• GitHub Actions — Native CI/CD platform for automated testing and release management integrated with repository
• RuboCop — Static analysis tool ensures code consistency and catches common Ruby anti-patterns early

• Ruby instead of compiled language (Go, Rust)

  • Why: Faster development cycle and easier prototyping for security tools
  • Consequence: Slightly slower execution and requires Ruby runtime on attacker machine; easier to reverse-engineer

• Interactive shell vs batch command executor

  • Why: Mimics legitimate Windows RDP/PowerShell sessions for stealthy post-exploitation
  • Consequence: More complex state management; harder to parallelize or script large operations

• SOAP-based WinRM vs WinRS direct API

  • Why: WinRM is standard Microsoft protocol available by default without additional services
  • Consequence: Requires SOAP XML parsing overhead; less flexibility than direct API but more universally available

• Does not provide initial exploitation or credential acquisition—assumes valid credentials already obtained
• Does not support non-Windows targets—WinRM is Windows-exclusive protocol
• Does not implement defense evasion features like UAC bypass—focuses on command execution after access gained
• Does not provide multi-session management or command queuing—single-session interactive shell model
• Does not implement logging or evidence cleanup—pentester responsible for operational security

Key non-obvious gotchas: (1) WinRM requires port 5985 (HTTP) or 5986 (HTTPS) to be open on the target; (2) the target must have WinRM enabled, which is not default on all Windows versions; (3) authentication methods (pass-the-hash, Kerberos, certificates) require specific setup (e.g., krbi/ccache files for Kerberos); (4) AMSI bypass and ETW bypass features may trigger security alerts or fail on fully patched/hardened systems; (5) the gem depends on the WinRM library which uses PSRP internally, so breakage can occur if Microsoft changes the protocol format; (6) no built-in logging of credentials, so manual OPSEC is required. No obvious environment variable gotchas, but SSL certificate handling (--key, --certificate) requires proper file paths.

• PSRP (PowerShell Remoting Protocol) — Evil-winrm uses PSRP (not raw WinRM SOAP) to initialize runspace pools and execute commands; understanding this protocol is essential for debugging remote execution failures and grasping why certain commands succeed or fail
• AMSI (Antimalware Scan Interface) — Evil-winrm includes dynamic AMSI bypass to evade Windows Defender and other AV engines; this is a core offensive feature and understanding AMSI hooks is critical for troubleshooting detection avoidance
• Pass-the-Hash (PTH) Authentication — Evil-winrm supports NTLM hash-based authentication (-H flag) without plaintext passwords; this is a fundamental post-exploitation technique and requires understanding NTLM protocol internals
• Kerberos Authentication & ccache/kirbi Files — Evil-winrm can authenticate using Kerberos tickets (ccache from mimikatz or raw kirbi files); this enables lateral movement in Active Directory environments and requires knowledge of Kerberos ticket structure
• ETW (Event Tracing for Windows) Bypass — Evil-winrm includes ETW bypass to prevent logging of executed commands; understanding ETW providers and how they track PowerShell execution is necessary for OPSEC and defensive evasion
• In-Memory Code Execution (Donut Payloads & DLL Injection) — Evil-winrm can load and execute C# assemblies, DLLs, and donut-generated shellcode without writing to disk; understanding this prevents AV detection and is a key evasion mechanism in the tool
• WS-Management Protocol (WS-Man) — WinRM is built on WS-Man SOAP protocol; while evil-winrm abstracts this via the WinRM library, understanding the underlying SOAP communication helps debug network issues and SSL/certificate problems

• rapid7/metasploit-framework — Industry-standard exploitation framework with WinRM modules; evil-winrm is often chained with Metasploit for post-exploitation
• Alamot/code-snippets — Collection of offensive PowerShell and C# snippets frequently used as payloads with evil-winrm for in-memory execution
• PowerShellEmpire/Empire — Post-exploitation agent framework that can be delivered via evil-winrm; complementary tool for persistence and lateral movement
• BC-SECURITY/Invoke-PSImage — Steganographic PowerShell delivery mechanism compatible with evil-winrm's script loading features
• SecureHats/WinRM-Session-Manager — Alternative WinRM management tool; differs from evil-winrm by focusing on legitimate sysadmin workflows rather than offensive evasion

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 comprehensive RSpec test suite for evil-winrm.rb core functionality

The repo lacks a spec/ directory with unit tests. Given this is a security tool with complex WinRM protocol handling, adding tests for core modules (authentication, command execution, session management) in evil-winrm.rb would improve reliability and prevent regressions. This is critical for a pentesting tool where correctness is paramount.

• [ ] Create spec/ directory structure with appropriate subdirectories
• [ ] Add spec_helper.rb with RSpec configuration and test fixtures
• [ ] Write unit tests for authentication methods in evil-winrm.rb (credentials handling, SSL/TLS negotiation)
• [ ] Write integration tests for command execution and output parsing
• [ ] Add spec tests to .rubocop.yml and dev.yml GitHub Action workflow
• [ ] Update CONTRIBUTING.md with testing guidelines for PRs

Implement automated Dockerfile builds and image testing in CI/CD pipeline

The repo contains a Dockerfile but has no CI workflow (dev.yml and master.yml are referenced but content missing) validating that Docker builds succeed or testing the image. Adding a GitHub Action to build and test the Docker image on each PR would catch Dockerfile issues early and ensure the published oscarakaelvis/evil-winrm Docker image remains functional.

• [ ] Review existing .github/workflows/dev.yml and master.yml configurations
• [ ] Add Docker build step to dev.yml workflow that builds image with dev tag
• [ ] Add Docker image tests verifying: binary runs (evil-winrm --help), dependencies load, entrypoint works
• [ ] Configure Docker image to push to registry only on master branch merges
• [ ] Document Docker development workflow in CONTRIBUTING.md

Create security policy documentation and add SECURITY.md for vulnerability reporting

A pentesting tool handling credentials and remote code execution needs clear vulnerability disclosure procedures. The repo has CODE_OF_CONDUCT.md and CONTRIBUTING.md but lacks SECURITY.md. This PR should define how contributors should responsibly report security issues without public disclosure, critical for maintaining trust in a hacking tool.

• [ ] Create SECURITY.md following GitHub security policy template
• [ ] Define responsible disclosure process (private reporting channel/email)
• [ ] Specify security issue response timeline expectations
• [ ] Add reference to SECURITY.md in README.md's security section
• [ ] Update .github/security.yml to enable private vulnerability reporting if using GitHub Advanced Security

• Add comprehensive unit tests for evil-winrm.rb covering session initialization, command execution, and error handling—currently no test/ or spec/ directory is visible, which is a significant gap for a security tool.
• Document the PSRP protocol flow and WinRM session lifecycle in a design guide (e.g., docs/protocol.md) to help new contributors understand how commands are marshaled and executed remotely.
• Create example payloads and scripts in resources/ (e.g., sample AMSI bypass, donut payload integration demo, C# assembly loader example) with inline comments for new contributors to learn the code patterns.

The Evil-WinRM project shows moderate security concerns. Critical issues include an incomplete Dockerfile build process and the complexity of a remote shell tool that requires careful input validation and secure credential handling. High-risk areas involve command injection prevention, TLS enforcement, and secure credential management. The codebase lacks visible evidence of automated security testing, dependency vulnerability scanning, and security policy documentation. Immediate recommendations include completing and validating the Dockerfile, implementing strict input validation for command handling, enforcing TLS, and establishing a security vulnerability disclosure process. The project would benefit significantly from implementing CI/CD security scanning and maintaining up-to-date dependency management.

• High · Incomplete Dockerfile - Build Stage Vulnerability — Dockerfile. The Dockerfile snippet is incomplete and appears to be cut off during the ruby-install download. The incomplete wget command (ending with 'v0.8') suggests the file may be corrupted or the build process may fail. This could lead to unexpected behavior or installation of unverified components. Fix: Complete the Dockerfile with the full ruby-install URL and verify the checksum of downloaded artifacts. Use multi-stage builds properly and ensure all downloads are complete and verified.
• High · Use of Alpine Linux Base Image with Known CVEs — Dockerfile. The Dockerfile uses Alpine 3.20.3 as the base image. While Alpine is lightweight, the specific version may contain unpatched security vulnerabilities. The Dockerfile also installs multiple development tools (clang, gcc, etc.) that increase the attack surface in a production container. Fix: Regularly update the Alpine base image to the latest stable version. Use a minimal final stage without build dependencies. Consider using a vulnerability scanner (e.g., Trivy) in CI/CD pipeline to detect known CVEs.
• Medium · Hardcoded URL for Ruby Installation — Dockerfile. The Dockerfile contains a hardcoded GitHub URL for ruby-install (https://github.com/postmodern/ruby-install/archive/v0.8). If this repository becomes unavailable or compromised, builds could fail or pull malicious code. Fix: Pin to specific release tags with checksums. Implement checksum verification after download. Consider mirroring dependencies internally or using a package manager with signature verification.
• Medium · Missing Security Headers and TLS Configuration — evil-winrm.rb, bin/evil-winrm. As a WinRM shell tool, the codebase likely handles remote connections. No evidence of enforced TLS/SSL configuration, certificate pinning, or secure credential handling is visible in the provided snippets. Fix: Implement mandatory TLS 1.2+ for all remote connections. Add certificate validation and pinning. Ensure credentials are not logged or stored in plaintext. Use secure credential management libraries.
• Medium · Insufficient Input Validation Indicators — evil-winrm.rb, bin/evil-winrm. A WinRM shell application that accepts remote commands has high risk for command injection attacks. No visible input sanitization or validation patterns in the file structure provided. Fix: Implement strict input validation and sanitization for all user-supplied commands. Use allowlists for permitted operations. Escape/quote all parameters passed to shell execution. Implement command whitelisting where possible.
• Low · Missing Security Configuration Files — Repository root. No evidence of security-related configuration files such as SECURITY.md, security policy documentation, or dependency vulnerability scanning configuration (e.g., Dependabot, snyk config). Fix: Add a SECURITY.md file with vulnerability disclosure policy. Enable GitHub Dependabot for automated vulnerability detection. Implement automated security scanning in CI/CD pipeline (.github/workflows).
• Low · Missing SBOM and Dependency Tracking — Gemfile, Gemfile.lock. No Software Bill of Materials (SBOM) or detailed dependency lockfile content was provided. This makes it difficult to track and manage security vulnerabilities in dependencies. Fix: Maintain an up-to-date Gemfile.lock with all transitive dependencies. Generate and maintain an SBOM. Use tools like bundler-audit to check for known vulnerable gems regularly.

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.