[EPIC][module-conformance] Native module SDK, fixtures, conformance matrix, packaging, and framework docs #191

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

Make the native Hackmode module framework practical to extend and safe to evolve by defining a developer-facing module SDK surface, deterministic conformance fixtures, packaging/discovery rules, compatibility guarantees, and architecture/operator documentation.

SDK / authoring surface

Document and stabilize the minimum Common Lisp interfaces for authors to define:

module descriptor/metadata;
option schema;
applicability/preflight/check behavior;
implementation binding to canonical capabilities/providers;
typed result/evidence schema;
cleanup/finalization hooks;
optional background/session behavior through #195;
tests/fixtures.

Module authors should not need to know Tek9 persistence internals or LISH parsing internals.

Conformance matrix

Every module family should be testable against a shared matrix covering at least:

registration + duplicate rejection
search/info projection
option defaults + override validation
operation/scope binding
passive/active admission behavior
foreground run
background run + cancellation where supported
provider failure normalization
result/evidence typing
cleanup/finalization
replay/trace identity
LISH inspection

Family-specific rows may extend the matrix.

Deterministic fixtures

Maintain harmless local/synthetic fixture modules representing several families so framework CI never requires an Internet target or privileged host access.

Fixtures should exercise success, denial, validation failure, provider error, cancellation and stale-handle behavior.

Packaging / discovery

Define how native modules are composed into the Hackmode flake/Common Lisp system:

core/built-in modules;
optional module packages;
external/local development module sets;
deterministic load order;
version/conflict handling;
reproducible discovery in nix flake check.

Do not require mutable global plugin directories as the canonical packaging mechanism.

Compatibility

Version public contracts for descriptors/options/results so modules can declare compatibility and fail clearly when the host is too old/new.

Deprecation should be explicit and inspectable rather than silently changing module semantics.

Documentation

Provide architecture and operator docs including:

mapping of familiar Metasploit concepts to Hackmode-native concepts;
module authoring walkthrough using harmless fixture;
option/datastore layering;
jobs/session model;
scope/authority/effect boundaries;
LISH workflow;
external adapter model;
artifact-generator relationship with #191;
Hackpert/Prolog-RLM relationship;
troubleshooting and conformance commands.

Acceptance

module SDK/public authoring contract is documented;
at least three synthetic fixture modules cover distinct families;
shared conformance matrix runs deterministically with no Internet target;
passive/active admission is regression-tested;
cancellation/provider failure/stale-handle paths are regression-tested where applicable;
optional module packages compose reproducibly through Nix/Common Lisp system definitions;
duplicate/version/conflict behavior is deterministic;
public descriptor/result schema versions are inspectable;
documentation maps Metasploit-style concepts to Hackmode without claiming implementation/API compatibility;
#191-generated native module artifacts have a documented validation/conformance path before eligibility;
Agent Zero workers can pick a module-family slice and know exactly which tests/docs define done.

Non-goals

No real-world target dependency in core conformance tests.
No module installation mechanism that bypasses Nix/package trust and runtime admission.
No generated source becomes trusted merely by passing syntax checks.

First slice

Add a hello/read-only-observation style fixture module plus a shared conformance helper that proves descriptor registration, option validation, foreground execution through a fake provider and typed evidence output. Use that fixture as the SDK documentation baseline.

Parent: #192 ## Mission Make the native Hackmode module framework practical to extend and safe to evolve by defining a developer-facing module SDK surface, deterministic conformance fixtures, packaging/discovery rules, compatibility guarantees, and architecture/operator documentation. ## SDK / authoring surface Document and stabilize the minimum Common Lisp interfaces for authors to define: - module descriptor/metadata; - option schema; - applicability/preflight/check behavior; - implementation binding to canonical capabilities/providers; - typed result/evidence schema; - cleanup/finalization hooks; - optional background/session behavior through #195; - tests/fixtures. Module authors should not need to know Tek9 persistence internals or LISH parsing internals. ## Conformance matrix Every module family should be testable against a shared matrix covering at least: ```text registration + duplicate rejection search/info projection option defaults + override validation operation/scope binding passive/active admission behavior foreground run background run + cancellation where supported provider failure normalization result/evidence typing cleanup/finalization replay/trace identity LISH inspection ``` Family-specific rows may extend the matrix. ## Deterministic fixtures Maintain harmless local/synthetic fixture modules representing several families so framework CI never requires an Internet target or privileged host access. Fixtures should exercise success, denial, validation failure, provider error, cancellation and stale-handle behavior. ## Packaging / discovery Define how native modules are composed into the Hackmode flake/Common Lisp system: - core/built-in modules; - optional module packages; - external/local development module sets; - deterministic load order; - version/conflict handling; - reproducible discovery in `nix flake check`. Do not require mutable global plugin directories as the canonical packaging mechanism. ## Compatibility Version public contracts for descriptors/options/results so modules can declare compatibility and fail clearly when the host is too old/new. Deprecation should be explicit and inspectable rather than silently changing module semantics. ## Documentation Provide architecture and operator docs including: - mapping of familiar Metasploit concepts to Hackmode-native concepts; - module authoring walkthrough using harmless fixture; - option/datastore layering; - jobs/session model; - scope/authority/effect boundaries; - LISH workflow; - external adapter model; - artifact-generator relationship with #191; - Hackpert/Prolog-RLM relationship; - troubleshooting and conformance commands. ## Acceptance - [ ] module SDK/public authoring contract is documented; - [ ] at least three synthetic fixture modules cover distinct families; - [ ] shared conformance matrix runs deterministically with no Internet target; - [ ] passive/active admission is regression-tested; - [ ] cancellation/provider failure/stale-handle paths are regression-tested where applicable; - [ ] optional module packages compose reproducibly through Nix/Common Lisp system definitions; - [ ] duplicate/version/conflict behavior is deterministic; - [ ] public descriptor/result schema versions are inspectable; - [ ] documentation maps Metasploit-style concepts to Hackmode without claiming implementation/API compatibility; - [ ] #191-generated native module artifacts have a documented validation/conformance path before eligibility; - [ ] Agent Zero workers can pick a module-family slice and know exactly which tests/docs define done. ## Non-goals - No real-world target dependency in core conformance tests. - No module installation mechanism that bypasses Nix/package trust and runtime admission. - No generated source becomes trusted merely by passing syntax checks. ## First slice Add a `hello/read-only-observation` style fixture module plus a shared conformance helper that proves descriptor registration, option validation, foreground execution through a fake provider and typed evidence output. Use that fixture as the SDK documentation baseline.

nsaspy referenced this issue

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

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

nsaspy referenced this issue

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

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

nsaspy referenced this issue

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

[EPIC][zeroforge-artifacts] Public symbolic exploit + detection artifact generation #198

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