[EPIC][module-interop] External-framework interoperability and Metasploit adapter boundary #192

New issue

Open

opened 2026-09-05 08:07:21 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-05 08:07:21 +00:00

Owner

Parent: #192

Mission

Define a safe, typed interoperability boundary so Hackmode can consume useful metadata/results from external security frameworks such as Metasploit without adopting their runtime, datastore, session authority, or target-scope model as canonical Hackmode state.

Design principle

External frameworks are providers/adapters, not peers in authority.

Hackmode module instance
   -> typed adapter capability
   -> external framework/tool
   -> normalized typed result/evidence
   -> Hackmode graph/state APIs

The adapter must preserve Hackmode's operation scope, authority, capability admission, cancellation, result normalization and provenance.

Interoperability surfaces

Support architecture for:

module metadata/catalog import or projection;
mapping external module metadata to Hackmode descriptors where representable;
typed option translation with validation;
invocation through a registered provider/adapter;
normalized status/result/evidence;
external background-run correlation;
external session/result handles represented as constrained Hackmode handles rather than raw ambient authority;
version/capability detection;
structured unsupported/incompatible outcomes.

Metasploit-specific mapping

Where practical, map concepts such as:

MSF module metadata -> Hackmode module descriptor projection
MSF datastore/options -> typed Hackmode option translation
MSF workspace -> selected Hackmode operation (never imported as authority)
MSF job -> external run correlated to Hackmode run/job
MSF session -> constrained external-session reference under Hackmode policy
MSF result/output -> normalized Hackmode evidence/artifact

Do not require exact command/API parity.

Generated artifacts

#191 may generate Metasploit-family artifacts. This epic owns how those artifacts can be handed to an external Metasploit adapter for validation/use while keeping the Hackmode run/evidence boundary intact.

Native Hackmode modules should remain usable with no Metasploit installation.

Acceptance

adapter interface is generic enough for more than one external framework;
external catalog metadata can be normalized without becoming executable authority;
option translation rejects invalid/unrepresentable values cleanly;
external invocation occurs only through a registered Hackmode provider/capability;
Hackmode operation scope is checked independently of external framework configuration;
external jobs/results correlate to stable Hackmode run IDs;
external sessions are represented by constrained/stale-safe handles;
normalized result/evidence includes adapter/framework/version provenance;
cancellation/timeout/adapter failure become structured Hackmode run states;
native module framework remains functional with adapter disabled/uninstalled;
synthetic adapter fixtures prove metadata -> configure -> invoke -> normalize without requiring a real target.

Non-goals

No importing an external framework's workspace as Hackmode target authority.
No raw external shell/session handle exposed as ambient capability.
No assumption that every external module can be safely/faithfully represented.
No requirement to reimplement Metasploit.

First slice

Build a deterministic fake external-framework adapter implementing metadata projection, option translation and one read-only invocation. Use it to lock the generic contract before adding any real Metasploit integration.

Parent: #192 ## Mission Define a safe, typed interoperability boundary so Hackmode can consume useful metadata/results from external security frameworks such as Metasploit without adopting their runtime, datastore, session authority, or target-scope model as canonical Hackmode state. ## Design principle External frameworks are **providers/adapters**, not peers in authority. ```text Hackmode module instance -> typed adapter capability -> external framework/tool -> normalized typed result/evidence -> Hackmode graph/state APIs ``` The adapter must preserve Hackmode's operation scope, authority, capability admission, cancellation, result normalization and provenance. ## Interoperability surfaces Support architecture for: - module metadata/catalog import or projection; - mapping external module metadata to Hackmode descriptors where representable; - typed option translation with validation; - invocation through a registered provider/adapter; - normalized status/result/evidence; - external background-run correlation; - external session/result handles represented as constrained Hackmode handles rather than raw ambient authority; - version/capability detection; - structured unsupported/incompatible outcomes. ## Metasploit-specific mapping Where practical, map concepts such as: ```text MSF module metadata -> Hackmode module descriptor projection MSF datastore/options -> typed Hackmode option translation MSF workspace -> selected Hackmode operation (never imported as authority) MSF job -> external run correlated to Hackmode run/job MSF session -> constrained external-session reference under Hackmode policy MSF result/output -> normalized Hackmode evidence/artifact ``` Do not require exact command/API parity. ## Generated artifacts `#191` may generate Metasploit-family artifacts. This epic owns how those artifacts can be handed to an external Metasploit adapter for validation/use while keeping the Hackmode run/evidence boundary intact. Native Hackmode modules should remain usable with no Metasploit installation. ## Acceptance - [ ] adapter interface is generic enough for more than one external framework; - [ ] external catalog metadata can be normalized without becoming executable authority; - [ ] option translation rejects invalid/unrepresentable values cleanly; - [ ] external invocation occurs only through a registered Hackmode provider/capability; - [ ] Hackmode operation scope is checked independently of external framework configuration; - [ ] external jobs/results correlate to stable Hackmode run IDs; - [ ] external sessions are represented by constrained/stale-safe handles; - [ ] normalized result/evidence includes adapter/framework/version provenance; - [ ] cancellation/timeout/adapter failure become structured Hackmode run states; - [ ] native module framework remains functional with adapter disabled/uninstalled; - [ ] synthetic adapter fixtures prove metadata -> configure -> invoke -> normalize without requiring a real target. ## Non-goals - No importing an external framework's workspace as Hackmode target authority. - No raw external shell/session handle exposed as ambient capability. - No assumption that every external module can be safely/faithfully represented. - No requirement to reimplement Metasploit. ## First slice Build a deterministic fake external-framework adapter implementing metadata projection, option translation and one read-only invocation. Use it to lock the generic contract before adding any real Metasploit integration.

nsaspy referenced this issue

2026-09-05 08:07:21 +00:00

[EPIC][module-lish] Native LISH module console: search, use, info, options, run, jobs, and sessions #193

nsaspy referenced this issue

2026-09-05 08:07:21 +00:00

[EPIC][module-runtime] Supervised module runs, jobs, cancellation, evidence, and typed session handles #194

nsaspy referenced this issue

2026-09-05 08:07:21 +00:00

[EPIC][module-options] Typed module options, datastore-style layering, validation, and operation scoping #195

nsaspy referenced this issue

2026-09-05 08:07:21 +00:00

[EPIC][modules] Native module contract, families, registry, discovery, and lifecycle #196