ShellForge

A Metasploit Payload Generation Tool for Ethical Lab Use

Author: zenyy (lahirurashmika3434@gmail.com)

ShellForge is a Python-based tool for generating and managing Metasploit payloads in controlled, isolated lab environments. Version 3.0 is the latest release, featuring an enhanced payload catalog, plugin extensibility, and robust safety mechanisms. It is designed for ethical security researchers and penetration testers with explicit permission to operate in a lab or virtual machine (VM).

---

ShellForge v3 (Latest Release)

Overview

ShellForge v3 is the most advanced iteration, offering an interactive CLI for payload generation, listener management, and plugin-based extensibility. It supports a wide range of payloads (binary, script, web) and emphasizes safety by logging encoder-enabled commands for manual or plugin-based execution.

Key Features

• Expanded Payload Catalog: Supports binary (Windows, Linux, Android, macOS), script (Python, PowerShell, PHP, Ruby, Perl, Bash, Node.js), and web (JSP, ASP, PHP) payloads in payload_catalog.json.
• Interactive CLI: Browse or search payloads by OS/keyword, with manual entry support.
• Injection Support: Inject payloads into Android APKs for advanced testing.
• Encoder Selection: Choose encoders (e.g., x86/shikata_ga_nai) with iteration control, logged as dry-runs.
• Embedded Listener: Launch msfconsole handlers using pexpect for interactive sessions.
• Configuration Persistence: Save LHOST, LPORT, and last payload in shellforge_config.json.
• Plugin System: Extend functionality with plugins (e.g., plugins/lab_builder.py) for safe encoder execution.
• Safety Mechanisms:
  • Encoder-enabled commands logged to logs/dryrun_commands.log, not auto-executed.
  • Non-encoder commands require user confirmation.
  • Dependency checks without auto-installation.
• Robust Logging: Dry-run and listener logs saved to logs/.
• Improved Format Detection: Maps payloads to msfvenom formats (e.g., py, ps1, exe, raw).

Files

• shellforgev3.py: Main script for payload generation and listener management.
• plugins/lab_builder.py: Plugin which I built run_build_with_encoder.
• payload_catalog.json: Defines supported payloads.
• shellforge_config.json: Stores user preferences (generated at runtime).
• output/: Generated payloads (created at runtime).
• logs/: Dry-run and listener logs (created at runtime).

Requirements

• Python 3.6+
• Metasploit Framework: msfvenom and msfconsole required.
• Optional Tools (Android injection): apktool, zipalign, jarsigner.
• Python Packages:
  • colorama (optional, colored output): pip install colorama
  • pexpect (optional, embedded listener): pip install pexpect
• Environment: Isolated lab/VM with UTF-8 locale (export LC_ALL=en_US.UTF-8).

Installation

1. Clone the repository:

   git clone https://github.com/zenyyxz/ShellForge.git
   cd ShellForge

2. Install dependencies:
   • Metasploit Framework: Official instructions.
   • Python packages:

     pip install colorama pexpect

   • Android injection: Install apktool, zipalign, jarsigner.
3. Verify directory structure:

   ShellForge/
   ├── shellforgev3.py
   ├── plugins/
   │   └── lab_builder.py
   ├── payload_catalog.json
   ├── output/              # Created at runtime
   ├── logs/                # Created at runtime
   └── shellforge_config.json # Created at runtime
   

Usage

1. Run the script:

   python3 shellforgev3.py

2. Main menu options:
   • 1) Build payload (menu): Select payload, configure LHOST/LPORT, choose injection/encoder.
   • 2) Build payload (manual): Enter custom msfvenom command.
   • 3) Start embedded listener: Launch handler for a payload, LHOST, LPORT.
   • 4) Show dry-run log: View last 20 commands from logs/dryrun_commands.log.
   • 5) Exit: Quit the tool.
3. Example:
   • Choose option 1, select python/meterpreter/reverse_tcp.
   • Set LHOST (e.g., 192.168.8.150), LPORT (e.g., 4444), output name (e.g., payload1).
   • Select encoder or confirm execution for non-encoder commands.
   • Start embedded listener to catch connections.

Previous Versions

ShellForge has evolved through multiple versions. Older versions are preserved in the archive/ directory for reference. Use v3 for the latest features.

• ShellForge v2 (archive/ShellForge_v2.py):

  • Features: Basic payload generation, manual msfvenom commands, simple catalog.
  • Limitations: No plugins, limited payload types (binary only), no listener.
  • README: archive/README_v2.md (if available).

• ShellForge v1 (archive/ShellForge.py):

  • Features: Initial proof-of-concept with manual payload selection.
  • Limitations: No catalog, encoders, or injection support.
  • README: archive/README.md (if available).

Access previous versions in the archive/ directory or browse the commit history.

---

Safety and Ethics

• Lab Use Only: ShellForge is for ethical use in controlled lab environments. Unauthorized use on systems or networks is prohibited.
• Encoder Safety: Encoder-enabled commands are logged to logs/dryrun_commands.log and require manual execution or a private plugin.
• No Auto-Install: Dependencies must be installed manually for security.
• Responsible Use: Misuse of this tool to harm systems is illegal and strictly prohibited.

---

Troubleshooting

• Dependency Errors: Ensure msfvenom, msfconsole, and optional tools are in PATH.
• Listener Issues: Verify pexpect (pip install pexpect) and check logs/msfconsole_<timestamp>.log.
• Encoder Commands: Use plugins or manual execution for encoder-enabled commands.
• Payload Errors: Verify payloads with msfvenom --list payloads and update payload_catalog.json.

---

Contributing

Contributions are welcome for lab-use enhancements. To contribute:

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/your-feature.
3. Commit changes: git commit -m "Add feature".
4. Push: git push origin feature/your-feature.
5. Open a pull request with a clear description.

Note: Exclude private plugins (e.g., lab_builder.py) from public contributions.

---

GitHub Release

ShellForge v3 is available as a GitHub release with:

• shellforgev3.py
• plugins/sample_plugin.py
• payload_catalog.json

Download the release for the latest features.

---https://github.com/zenyyxz/ShellForge.git

License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Disclaimer

ShellForge is provided for educational and ethical purposes only. The author is not responsible for misuse or illegal activities. Always obtain explicit permission before testing systems or networks.