Vulnenv week1 by Nayeraneru · Pull Request #1 · Nayeraneru/metasploit-framework

Nayeraneru · 2026-06-29T03:08:43Z

Refering to #20506
GSoC 2026 — Week 1 deliverables for the Automated Vulnerable Environment Provisioning project.

Architecture docs:

architecture/01-command-dispatcher.md
architecture/02-module-metadata.md
architecture/03-database-schema.md
architecture/04-environment-schema.md
architecture/05-runtime-adapter.md

Additional files:

reference_modules.md — ActiveMQ (from PR Activemq jolokia exploit (CVE-2026-34197) rapid7/metasploit-framework#21497), Jenkins, Drupal
workflow.md — target user scenarios & error handling spec
ci_workflow.md — GitHub Actions + resource script
docs/test_env/README.md — master index
plugins/test_env.rb — loads successfully in msfconsole
data/vuln_envs/jenkins.yml — reference environment definition

Open question:
In 02-module-metadata.md — is it better to encapsulate mod.send(:module_info)['VulnEnv'] in a helper method, or keep the direct send call?

h00die

Overall I think this looks reasonable. I added a few comments and notes

h00die · 2026-07-03T23:33:53Z

+| `list` | `cmd_test_env_list(args)` | Show all tracked environments |
+| `stop <ID>` | `cmd_test_env_stop(args)` | Stop a running container |
+| `start <ID>` | `cmd_test_env_start(args)` | Restart a stopped container |
+| `remove <ID>` | `cmd_test_env_remove(args)` | Tear down a container |


for many commands we allow a range as well. See sessions and the -k command for an example: -k, --kill <id> Terminate sessions by session ID and/or range.

I think this will apply for stop start remove. I'm not sure exec would be a good idea though.

h00die · 2026-07-03T23:42:52Z

+  if words.length == 2
+    case words[0]
+    when 'stop', 'start', 'remove', 'exec'
+      # TODO: Return IDs from registry (Week 6)


good idea marking which week in the comment

h00die · 2026-07-03T23:46:24Z

+
+## Alternative: Encapsulate in Helper Method (Is it better to do or not?)
+
+If It's not preferable not to use `send` directly everywhere:


I think @zeroSteiner is better to answer this, its too deep in the framework weeds for my preference.

Yeah it looks like the established pattern would be to have #vulnerable_environment method and return the key from the private module_info attribute.

https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/module/module_info.rb#L49-L60

The module class is large. I'd have a preference towards verbosity and clarity over abbreviations so #vulnerable_environment would probably have less of a chance of conflicting with anything pre-existing than say #vuln_env. In either case we should do a quick grep to make sure.

That'd make it

def vulnerable_environment self.module_info['VulnerableEnvironment']

https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/module/module_info.rb also has normalizations that are applied with the various #merge_* methods. These patterns are old... because framework is old. I would suggest we sort of adopt them and do some normalization, but use a Struct object to encapsulate all the info. We should also do validation on the keys and types so we know that required attributes are set, things are the correct type etc.

h00die · 2026-07-03T23:54:15Z

+```ruby
+'VulnEnv' => {
+  'definition'      => String,   # e.g., 'jenkins' → data/vuln_envs/jenkins.yml
+  'default_version' => String,   # e.g., '2.361'


Keep an eye on rapid7#21583 . I'm not sure if it would necessarily help or not, but that may give the ability to run different versions on the fly if theyre in that range, or allow for checking that the docker version is in that range kind of thing. No change needed, specially since thats just an Issue/idea and not implemented yet, but figured i'd bring it up to see if you had any ideas of how that could be useful here or not.

For now though, since it's not implemented yet , no structural changes needed, but it's a future enhancement. however, my current design is already compatible —the EnvironmentResolver would just gain an additional validation/filtering step

i think thats reasonable

Oh I see this is doing the validation I had noted in my previous comment 👍

h00die · 2026-07-03T23:59:49Z

+
+```bash
+docker run -d \
+  --label "msf.vulnenv.instance_id=msf-$(hostname)-$$" \


i dont know much about docker labels and how you may want to pull them later, but would it potentially be easier to do like a base64 encoded json dump of the variables? Just a thought

yes a base64 json blob is cleaner, however, we need individual labels for managed_by and module because Docker's --filter only does string matching on label values, we can't query inside a json blob. I'll adopt a hybrid: individual labels for the filterable identity fields, and a base64 JSON payload label for the full datastore, credentials, and exploit command. this gives us native docker ps --filter performance for discovery, plus the atomicity and schema flexibility you suggested

Is it necessary to store the full datastore, credentials and exploit command in the label? If framework is running and you can associate an instance with the module, the module already has that information in the vulnerable_environment hash definition right?

yup, I'll store only the truly dynamic data in container labels,everything else is reconstructible at runtime

h00die · 2026-07-04T00:52:00Z

+
+| Label | Value | Purpose |
+|-------|-------|---------|
+| `msf.vulnenv.instance_id` | `msf-{hostname}-{pid}` | Isolate msfconsole instances |


pid may be enough, i'm not sure if hostname adds any value

although PID is unique among running processes on a machine. I kept hostname for three defensive reasons:
1- CI integration: multiple GitHub Actions runners may share a Docker daemon
2- PID reuse after msfconsole crash/restart
3- debugging — docker inspect shows which machine created the container
for pure single-machine use, PID alone is sufficient. If you prefer minimalism, I could switch to a random startup token instead: msf-{token}-{pid}. Would you prefer that or shall I keep hostname for the CI safety margin?

keep it as it is

h00die · 2026-07-04T00:58:30Z

+    branches: [ main ]
+  pull_request:
+    branches: [ main ]


spinning up an env and exploiting it is a time consuming event. Likely it'll only be run before a weekly build or something similar.

okay, got it
I'll change the trigger from push/pull_request to a hybrid model: weekly scheduled runs to catch bit-rot, label-triggered runs for PRs that need validation (vuln-env-test label), and workflow_dispatch for manual runs

h00die · 2026-07-04T01:09:27Z

@@ -0,0 +1,194 @@
+# CI Workflow: Automated Exploit Verification


looks to be a duplicate of docs/architecture/ci_workflow.md

h00die · 2026-07-04T01:09:39Z

@@ -0,0 +1,48 @@
+# Reference Modules for test_env


looks to be a duplicate of docs/architecture/reference_modules.md

h00die · 2026-07-04T01:09:51Z

@@ -0,0 +1,280 @@
+# test_env User Workflow (Design Specification)


looks to be a duplicate of docs/architecture/workflow.md

smcintyre-r7 · 2026-07-08T13:46:06Z

+From `lib/msf/ui/console/command_dispatcher/jobs.rb`, I saw:
+- One dispatcher can handle multiple commands via `commands` hash
+- `cmd_jobs(*args)` uses `args.shift` to get the subcommand
+- `cmd_rename_job_tabs` provides tab completion


I'm pretty sure it should be cmd_jobs_tabs for a command named jobs.

smcintyre-r7 · 2026-07-08T21:26:49Z

+# Test: Can we add a custom key?
+puts "=== Adding custom key ==="
+info['VulnEnv'] = {
+  'definition' => 'jenkins',
+  'default_version' => '2.361',
+  'port_mapping' => { 8080 => 'RPORT' }
+}


Adding metadata to the module is perfectly fine but we'd want to do it in the #initialize method where the other module metadata exists. Otherwise, the shape looks correct. The port_mapping looked odd at first but I'm guessing the intention is to iterate over the keys and assign datastore options. With that being the case either one for the key should be fine since they should both be unique.

okay I will clarify

smcintyre-r7 · 2026-07-08T21:38:48Z

+
+## Alternative: Encapsulate in Helper Method (Is it better to do or not?)
+
+If It's not preferable not to use `send` directly everywhere:


Yeah it looks like the established pattern would be to have #vulnerable_environment method and return the key from the private module_info attribute.

https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/module/module_info.rb#L49-L60

The module class is large. I'd have a preference towards verbosity and clarity over abbreviations so #vulnerable_environment would probably have less of a chance of conflicting with anything pre-existing than say #vuln_env. In either case we should do a quick grep to make sure.

That'd make it

def vulnerable_environment self.module_info['VulnerableEnvironment']

https://github.com/rapid7/metasploit-framework/blob/master/lib/msf/core/module/module_info.rb also has normalizations that are applied with the various #merge_* methods. These patterns are old... because framework is old. I would suggest we sort of adopt them and do some normalization, but use a Struct object to encapsulate all the info. We should also do validation on the keys and types so we know that required attributes are set, things are the correct type etc.

smcintyre-r7 · 2026-07-08T21:39:44Z

+```ruby
+'VulnEnv' => {
+  'definition'      => String,   # e.g., 'jenkins' → data/vuln_envs/jenkins.yml
+  'default_version' => String,   # e.g., '2.361'


Oh I see this is doing the validation I had noted in my previous comment 👍

smcintyre-r7 · 2026-07-08T21:43:31Z

+
+```bash
+docker run -d \
+  --label "msf.vulnenv.instance_id=msf-$(hostname)-$$" \


Is it necessary to store the full datastore, credentials and exploit command in the label? If framework is running and you can associate an instance with the module, the module already has that information in the vulnerable_environment hash definition right?

smcintyre-r7 · 2026-07-08T21:53:50Z

+    image: vulnhub/jenkins:2.361
+    build_args:
+      JENKINS_VERSION: "2.361"
+  "2.375":


It might be a bit more flexible to refer to these as "variants" instead of versions. I could see scenarios where we have an app with one version configured two different ways such as with SQLite or postgresql but it's the same version.

In that case treating this as a list and moving the version number to either a name field or if you truly need the version, a version field.

variants: - name: "v2.361" image: vulnhub/jenkins:2.361 build_args: JENKINS_VERSION: "2.361" ...

…'s review

Make the NODE_ID optional

…e-option Fix WinRM PowerShell session resource leaks and race conditions

Nayeraneru · 2026-09-02T18:30:12Z

Closed as already in vulnenv branch

h00die mentioned this pull request Jul 4, 2026

Vulnenv week1 rapid7/metasploit-framework#21625

Closed

h00die suggested changes Jul 4, 2026

View reviewed changes

Nayeraneru and others added 10 commits July 4, 2026 17:18

complete runtime adapter with dynamic port allocation

8e1c633

Update formatting

017ee09

reference modules and workflow drafts

251376f

Week 1 tasks Complete: test_env plugin skeleton and architecture

0d435c9

plugin skeleton

1cf782b

Update links in README

f43d97a

command dispatcher arch design

82c9418

verify module metadata access

bb41989

design in-memory registry with phase 2 database plan

1666a99

add jenkins environment definition and schema docs

d64786e

Nayeraneru force-pushed the vulnenv-week1 branch from e138718 to f43d97a Compare July 4, 2026 14:49

Nayeraneru and others added 6 commits July 4, 2026 18:30

Enhance command dispatcher with range support

28c5af5

revise container labels and add payload helpers

ebf1f37

Enhance environment schema with multi profiles

f75cdc8

Enhance CI workflow

edda996

Remove unnecessary codes

6d82b63

Remove duplicate docs

1c06970

smcintyre-r7 reviewed Jul 8, 2026

View reviewed changes

Nayeraneru and others added 10 commits July 9, 2026 04:56

fixing typo

70d9555

Enhance doc for VulnerableEnvironment integration based on the mentor…

45f0278

…'s review

Adjust database schema for labels

f987e48

adjust 'versions' section to 'variants'

247123a

Change default_version to default_variant in metadata

389a2e1

Update doc for consistency

b0ac0db

minor fix

72976c3

minor note

3c5c75c

Refactor variants section and update validation rules

77452aa

fixes

f031093

Add output for 'variants' in environment schema (jenkins.yml week3 file)

3b4be6d

Nayeraneru closed this Jul 20, 2026

Nayeraneru reopened this Jul 25, 2026

Nayeraneru closed this Jul 25, 2026

Nayeraneru pushed a commit that referenced this pull request Aug 1, 2026

Merge pull request #1 from smcintyre-r7/pr/collab/21681

e6ab9ae

Make the NODE_ID optional

Nayeraneru pushed a commit that referenced this pull request Sep 2, 2026

Merge pull request #1 from bwatters-r7/collab/winrm-login-session-typ…

657735e

…e-option Fix WinRM PowerShell session resource leaks and race conditions

Nayeraneru reopened this Sep 2, 2026

Nayeraneru closed this Sep 2, 2026


		## Alternative: Encapsulate in Helper Method (Is it better to do or not?)

		If It's not preferable not to use `send` directly everywhere:

		@@ -0,0 +1,194 @@
		# CI Workflow: Automated Exploit Verification

		@@ -0,0 +1,280 @@
		# test_env User Workflow (Design Specification)

Conversation

Nayeraneru commented Jun 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

h00die left a comment

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!

Nayeraneru Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

Nayeraneru Jul 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

Nayeraneru commented Sep 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Nayeraneru commented Jun 29, 2026 •

edited

Loading

Nayeraneru Jul 4, 2026 •

edited

Loading

Nayeraneru Jul 4, 2026 •

edited

Loading