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

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 Hackmode's canonical native module model: descriptors, metadata, family taxonomy, registry/discovery, implementation binding, versioning, applicability and lifecycle.

The result should feel familiar to operators coming from Metasploit-style module catalogs while remaining native to Hackmode.

Core model

A module descriptor should carry typed metadata equivalent to:

stable module ID + version;
family/category;
human title + description;
authorship/provenance/reference metadata;
supported target/service/environment predicates;
required input option schema;
required Hackmode capabilities;
authority/effect requirements;
expected result/evidence schema;
optional check/preflight contract;
cleanup/finalization contract where relevant;
implementation binding;
lifecycle/deprecation state.

Metadata is descriptive and does not itself grant authority.

Initial families

Support extensible families such as:

recon/discovery;
auxiliary/scanner;
detection/corroboration;
active verification / exploit-oriented;
protocol/service interaction;
session/operation follow-up;
evidence collection;
reporting/artifact generation;
external-framework adapter.

Do not encode family names as separate execution engines.

Registry + discovery

Provide typed APIs for:

register/unregister during system composition;
enumerate modules;
lookup exact module ID/version;
search by family, tags, service/protocol, applicability, capability requirement and text metadata;
inspect complete module metadata;
detect duplicate/conflicting IDs;
expose deprecated/superseded state;
deterministic ordering for equivalent search results.

Prefer declarative module definitions that can be loaded from Common Lisp systems/packages and composed through the flake without a second plugin database.

Instantiation

Selecting/using a module creates a run-local module instance/configuration. Global descriptor metadata remains immutable.

Instances should reference:

operation id
module id/version
authority mode snapshot
option/config layer
run id
implementation binding

Hackpert / Prolog-RLM integration

Hackpert and Prolog-RLM may query catalog metadata and propose/select module IDs as typed candidates. They do not receive direct implementation closures or bypass Hackmode admission.

Module applicability should be projectable as symbolic facts/rules later without making the registry depend on Prolog.

Acceptance

canonical module descriptor exists;
registry detects duplicate IDs/versions;
module families are extensible data, not hard-coded dispatch branches;
search/info APIs are deterministic and typed;
module descriptors can declare applicability and capability requirements;
selecting a module creates a run-local instance without mutating descriptor state;
deprecated/superseded modules remain inspectable;
registry works with Prolog-RLM absent;
deterministic fixtures cover registration, search, exact lookup, duplicate rejection and instantiation;
LISH and #191 artifact generation can consume the same public descriptor schema.

Non-goals

No Ruby/MSF API/file-layout compatibility.
No module-local operation database.
No authority grant from family, tag or registration.
No arbitrary executable source loaded from model output.

First slice

Create a minimal descriptor + registry and three harmless synthetic module fixtures from different families. Prove search/info/instantiate behavior before wiring effectful execution.

Parent: #192 ## Mission Define Hackmode's canonical **native module model**: descriptors, metadata, family taxonomy, registry/discovery, implementation binding, versioning, applicability and lifecycle. The result should feel familiar to operators coming from Metasploit-style module catalogs while remaining native to Hackmode. ## Core model A module descriptor should carry typed metadata equivalent to: - stable module ID + version; - family/category; - human title + description; - authorship/provenance/reference metadata; - supported target/service/environment predicates; - required input option schema; - required Hackmode capabilities; - authority/effect requirements; - expected result/evidence schema; - optional check/preflight contract; - cleanup/finalization contract where relevant; - implementation binding; - lifecycle/deprecation state. Metadata is descriptive and does not itself grant authority. ## Initial families Support extensible families such as: - recon/discovery; - auxiliary/scanner; - detection/corroboration; - active verification / exploit-oriented; - protocol/service interaction; - session/operation follow-up; - evidence collection; - reporting/artifact generation; - external-framework adapter. Do not encode family names as separate execution engines. ## Registry + discovery Provide typed APIs for: - register/unregister during system composition; - enumerate modules; - lookup exact module ID/version; - search by family, tags, service/protocol, applicability, capability requirement and text metadata; - inspect complete module metadata; - detect duplicate/conflicting IDs; - expose deprecated/superseded state; - deterministic ordering for equivalent search results. Prefer declarative module definitions that can be loaded from Common Lisp systems/packages and composed through the flake without a second plugin database. ## Instantiation Selecting/using a module creates a **run-local module instance/configuration**. Global descriptor metadata remains immutable. Instances should reference: ```text operation id module id/version authority mode snapshot option/config layer run id implementation binding ``` ## Hackpert / Prolog-RLM integration Hackpert and Prolog-RLM may query catalog metadata and propose/select module IDs as typed candidates. They do not receive direct implementation closures or bypass Hackmode admission. Module applicability should be projectable as symbolic facts/rules later without making the registry depend on Prolog. ## Acceptance - [ ] canonical module descriptor exists; - [ ] registry detects duplicate IDs/versions; - [ ] module families are extensible data, not hard-coded dispatch branches; - [ ] search/info APIs are deterministic and typed; - [ ] module descriptors can declare applicability and capability requirements; - [ ] selecting a module creates a run-local instance without mutating descriptor state; - [ ] deprecated/superseded modules remain inspectable; - [ ] registry works with Prolog-RLM absent; - [ ] deterministic fixtures cover registration, search, exact lookup, duplicate rejection and instantiation; - [ ] LISH and #191 artifact generation can consume the same public descriptor schema. ## Non-goals - No Ruby/MSF API/file-layout compatibility. - No module-local operation database. - No authority grant from family, tag or registration. - No arbitrary executable source loaded from model output. ## First slice Create a minimal descriptor + registry and three harmless synthetic module fixtures from different families. Prove search/info/instantiate behavior before wiring effectful execution.

nsaspy referenced this issue

2026-09-05 08:18:47 +00:00

[EPIC][module-framework] Native Hackmode security module framework with Metasploit-inspired concepts #197