nsaspy/hackmode

Fork 0

Integrate Hackpert as a Prolog expert layer over canonical Hackmode state #201

New issue

Open

opened 2026-09-15 14:53:09 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-15 14:53:09 +00:00

Owner

Outcome

Fold Hackpert into the canonical Hackmode monorepo as a SWI-Prolog expert/orchestration layer with two explicit engine modes: passive and active.

Hackpert must not become a second operation database or parallel source of truth. Hackmode/Tek9 remains canonical for operations, typed assets, graph persistence, KB lifecycle, and StarIntel synchronization. However, Hackpert does orchestrate tool runs, and in active mode it may intentionally drive canonical state changes through Hackmode's normal mutation APIs.

Source inspiration: https://github.com/lost-rob0t/hackpert

Engine modes

Passive mode

Passive Hackpert observes canonical Hackmode state, typed tool calls/results, and passive evidence such as IPX traffic.

Passive mode may:

classify, correlate, constrain, rank, infer, and recommend;
build derived reasoning/graph output;
propose plans, KB promotions, or next actions;
analyze already-produced tool output and traffic evidence.

Passive mode must not:

dispatch tools;
alter operation state;
persist new canonical assets/findings/KB entries by itself;
replay or actively probe targets.

Active mode

Active Hackpert is an orchestrating expert engine. It is required for fuzzing, SQLi, OOB, XSS/blind-XSS, and other experts whose reasoning loop must take an action, inspect the result, update knowledge, and continue.

Active mode may:

choose and dispatch registered Hackmode capabilities/providers;
create/update canonical graph state through typed Hackmode APIs;
persist discovered assets/findings and execution evidence;
mutate the operational KB as part of the reasoning loop;
advance attack/recon plans and playbook state;
request long-term KB promotion candidates when supported.

Active mode does not get arbitrary mutation authority. Prolog emits typed actions/state deltas; the Common Lisp active-engine wrapper validates them and executes them through canonical Hackmode interfaces. No direct Prolog writes into Tek9 and no arbitrary shell primitive.

                     +----------------------+
                     | canonical Hackmode   |
                     | state + graph + KB   |
                     +----------+-----------+
                                |
                                v
                     deterministic snapshot
                                |
                                v
                          SWI-Prolog
                          Hackpert engine
                          /             \
                         /               \
                  passive mode        active mode
                      |                   |
               graph/advice       typed actions +
                                  graph/state delta
                                          |
                                          v
                                Common Lisp active
                                  engine boundary
                                          |
                       +------------------+------------------+
                       |                  |                  |
                       v                  v                  v
                 provider dispatch   Tek9/KB writes    discover/findings

Tool orchestration

Hackpert already conceptually runs/orchestrates tools; the Hackmode adaptation must preserve that capability instead of reducing Hackpert to a recommendation service.

All active execution still uses Hackmode's registered provider/capability runtime so:

provider typing remains authoritative;
execution is observable in the tool-call/result graph;
failures and retries become reasoning evidence;
provider lifecycle/concurrency controls remain intact;
arbitrary Prolog shell execution is unnecessary.

The active loop is roughly:

reason -> select typed capability -> dispatch -> observe result
      -> persist execution/result graph -> update operational KB
      -> reason again

Graph model

Hackpert consumes canonical operation state plus typed tool calls/results. Its durable reasoning output/state transition is graph-shaped.

The graph covers:

expert/engine mode;
plans/playbooks and steps;
capability/tool calls;
inputs and outputs;
discovered assets and findings;
success/failure/negative evidence;
hypotheses and constraints;
KB provenance/promotion links;
passive IPX observations.

Passive mode returns graph/advice deltas only. Active mode may return graph + typed action/state deltas for Common Lisp to accept and apply.

Knowledge-base model

Hackmode should have three explicit KB scopes:

Operational KB — per-operation working knowledge: current hypotheses, failed paths, observations, temporary fuzz/word candidates, active plans/playbooks, and recent execution graph context. Active Hackpert may mutate this through the canonical wrapper.
Long-term KB — reusable learned knowledge: validated working paths, useful payload/fuzz/wordlist knowledge, stable constraints, reusable plan fragments, and repeated failure conditions. Promotion should be evidence/provenance carrying.
Global KB / looting — optional explicit export of selected long-term knowledge for reuse across operations. Global export is never implicit.

Hackpert may propose promotions/exports. Common Lisp validates and persists them. Active mode may mutate operational state directly through the wrapper; long-term/global promotion remains an explicit lifecycle operation.

Learning requirements

wordlists/fuzz lists can be imported as provenance-carrying KB data;
working attacks/recon paths can be promoted into long-term KB candidates;
failed attack paths remain graph evidence so orchestration can avoid blind repetition;
useful operation-local knowledge can be explicitly exported/"looted" to global KBs;
all promotion/export paths preserve evidence/provenance and rule/expert version.

Expert families / goals

Shared graph + KB substrate should support specialized experts rather than separate state silos:

recon expert;
expert-level web fuzzing;
SQL injection expert;
out-of-band testing expert;
XSS expert;
blind-XSS expert.

Attack plans and playbooks are first-class graph structures with prerequisites, candidate capabilities, expected evidence, success/failure branches, and stop conditions.

SQLi/fuzzing-class experts are expected to run in active mode because they require iterative action -> evidence -> state mutation -> next action loops.

Possible Prolog-RLM integration comes later once stable and must reuse Hackmode's graph/KB/active-engine boundary.

LISH integration

Hackpert needs first-class LISH integration rather than a separate Hackpert REPL.

LISH should be able to:

inspect current Hackpert mode/status;
switch/select passive vs active mode where policy allows;
ask the expert for reasoning/recommendations;
start/stop/inspect active expert runs;
inspect plans/playbooks and tool-call/result graph nodes;
inspect operational/long-term KB state and promotion candidates;
inspect IPX-derived passive evidence;
surface provider/tool execution initiated by active Hackpert.

Authority boundary

Hackmode/Tek9 owns canonical persisted state.
capability-provider registry + provider actors own executable tools/capabilities.
Passive Hackpert has no mutation/dispatch authority.
Active Hackpert may orchestrate tools and request canonical mutations through a typed Common Lisp active-engine interface.
Common Lisp validates active-engine actions/deltas before execution/persistence.
Prolog does not directly write Tek9 or receive an unrestricted shell primitive.
no targets.txt, inscope.txt, outscope.txt, expert-state.prolog, or environment-variable operation authority.

First slice in PR #25

optional hackmode-expert bridge using SWI-Prolog when installed
deterministic projection of current operation/assets/providers into temporary Prolog facts
target classification: URL/domain/IPv4/IPv6/unknown
capability recommendation from target/asset type + registered provider metadata
fixed-goal query boundary; user data is serialized as facts, never concatenated into executable Prolog source
structured Common Lisp results
tests for target classification, recommendation ordering, missing swipl, quoting/injection safety, and no canonical-state mutation in the passive foundation
architecture records graph/KB direction and IPX passive evidence path

PR #25 implemented the passive foundation only. Its "no mutation" property is not the final Hackpert architecture; active mode is the next major execution layer.

Next implementation slices

typed execution graph for tool calls/results, persisted by Common Lisp/Tek9
explicit Hackpert engine mode model (:passive / :active)
active-engine typed action/state-delta protocol
active provider orchestration loop using Hackmode capabilities
operational KB storage + active mutation API
long-term KB storage and promotion lifecycle
explicit global-KB export/looting API
graph + KB snapshot facts into Prolog and typed graph/state deltas back
attack-plan/playbook graph primitives
LISH Hackpert mode/run/graph/KB integration
recon expert on shared substrate
wordlist/fuzz-list KB import with provenance
success/failure promotion candidates from execution evidence
specialized fuzzing/SQLi/OOB/XSS/blind-XSS experts incrementally in active mode
Emacs graph/plan/KB inspection
evaluate Prolog-RLM integration after the direct boundary is stable

Invariants

local-first operation still works with Prolog absent;
expert failure cannot corrupt canonical Hackmode state;
passive mode causes zero tool dispatches and zero canonical mutations;
active mode mutations are explicit, typed, validated, graph-recorded, and auditable;
active tool execution goes through the provider runtime;
no duplicate target/operation authority;
same canonical input + same rule/KB version produces deterministic reasoning output where practical;
global KB mutation/export is explicit and auditable.

Acceptance proof for active mode

select an operation and start Hackpert in active mode;
Hackpert receives canonical graph/KB/provider facts;
Prolog emits a typed capability action rather than shell code;
Common Lisp validates and dispatches it through the normal provider actor path;
tool call + result are persisted as execution graph nodes/edges;
discovered assets/findings are persisted through canonical Hackmode APIs;
operational KB state may be updated by the active loop;
the next reasoning iteration sees those mutations and can choose a different action;
switching to passive mode makes the same expert unable to dispatch or mutate;
LISH can inspect mode, run state, plan, graph, and resulting KB changes.

## Outcome Fold Hackpert into the canonical Hackmode monorepo as a SWI-Prolog expert/orchestration layer with **two explicit engine modes**: passive and active. Hackpert must not become a second operation database or parallel source of truth. Hackmode/Tek9 remains canonical for operations, typed assets, graph persistence, KB lifecycle, and StarIntel synchronization. However, Hackpert **does orchestrate tool runs**, and in active mode it may intentionally drive canonical state changes through Hackmode's normal mutation APIs. Source inspiration: https://github.com/lost-rob0t/hackpert ## Engine modes ### Passive mode Passive Hackpert observes canonical Hackmode state, typed tool calls/results, and passive evidence such as IPX traffic. Passive mode may: - classify, correlate, constrain, rank, infer, and recommend; - build derived reasoning/graph output; - propose plans, KB promotions, or next actions; - analyze already-produced tool output and traffic evidence. Passive mode must **not**: - dispatch tools; - alter operation state; - persist new canonical assets/findings/KB entries by itself; - replay or actively probe targets. ### Active mode Active Hackpert is an orchestrating expert engine. It is required for fuzzing, SQLi, OOB, XSS/blind-XSS, and other experts whose reasoning loop must take an action, inspect the result, update knowledge, and continue. Active mode may: - choose and dispatch registered Hackmode capabilities/providers; - create/update canonical graph state through typed Hackmode APIs; - persist discovered assets/findings and execution evidence; - mutate the **operational KB** as part of the reasoning loop; - advance attack/recon plans and playbook state; - request long-term KB promotion candidates when supported. Active mode does **not** get arbitrary mutation authority. Prolog emits typed actions/state deltas; the Common Lisp active-engine wrapper validates them and executes them through canonical Hackmode interfaces. No direct Prolog writes into Tek9 and no arbitrary shell primitive. ```text +----------------------+ | canonical Hackmode | | state + graph + KB | +----------+-----------+ | v deterministic snapshot | v SWI-Prolog Hackpert engine / \ / \ passive mode active mode | | graph/advice typed actions + graph/state delta | v Common Lisp active engine boundary | +------------------+------------------+ | | | v v v provider dispatch Tek9/KB writes discover/findings ``` ## Tool orchestration Hackpert already conceptually runs/orchestrates tools; the Hackmode adaptation must preserve that capability instead of reducing Hackpert to a recommendation service. All active execution still uses Hackmode's registered provider/capability runtime so: - provider typing remains authoritative; - execution is observable in the tool-call/result graph; - failures and retries become reasoning evidence; - provider lifecycle/concurrency controls remain intact; - arbitrary Prolog shell execution is unnecessary. The active loop is roughly: ```text reason -> select typed capability -> dispatch -> observe result -> persist execution/result graph -> update operational KB -> reason again ``` ## Graph model Hackpert consumes canonical operation state plus typed tool calls/results. Its durable reasoning output/state transition is graph-shaped. The graph covers: - expert/engine mode; - plans/playbooks and steps; - capability/tool calls; - inputs and outputs; - discovered assets and findings; - success/failure/negative evidence; - hypotheses and constraints; - KB provenance/promotion links; - passive IPX observations. Passive mode returns graph/advice deltas only. Active mode may return graph + typed action/state deltas for Common Lisp to accept and apply. ## Knowledge-base model Hackmode should have three explicit KB scopes: 1. **Operational KB** — per-operation working knowledge: current hypotheses, failed paths, observations, temporary fuzz/word candidates, active plans/playbooks, and recent execution graph context. Active Hackpert may mutate this through the canonical wrapper. 2. **Long-term KB** — reusable learned knowledge: validated working paths, useful payload/fuzz/wordlist knowledge, stable constraints, reusable plan fragments, and repeated failure conditions. Promotion should be evidence/provenance carrying. 3. **Global KB / looting** — optional explicit export of selected long-term knowledge for reuse across operations. Global export is never implicit. Hackpert may propose promotions/exports. Common Lisp validates and persists them. Active mode may mutate operational state directly through the wrapper; long-term/global promotion remains an explicit lifecycle operation. ## Learning requirements - wordlists/fuzz lists can be imported as provenance-carrying KB data; - working attacks/recon paths can be promoted into long-term KB candidates; - failed attack paths remain graph evidence so orchestration can avoid blind repetition; - useful operation-local knowledge can be explicitly exported/"looted" to global KBs; - all promotion/export paths preserve evidence/provenance and rule/expert version. ## Expert families / goals Shared graph + KB substrate should support specialized experts rather than separate state silos: - recon expert; - expert-level web fuzzing; - SQL injection expert; - out-of-band testing expert; - XSS expert; - blind-XSS expert. Attack plans and playbooks are first-class graph structures with prerequisites, candidate capabilities, expected evidence, success/failure branches, and stop conditions. SQLi/fuzzing-class experts are expected to run in **active mode** because they require iterative action -> evidence -> state mutation -> next action loops. Possible Prolog-RLM integration comes later once stable and must reuse Hackmode's graph/KB/active-engine boundary. ## LISH integration Hackpert needs first-class LISH integration rather than a separate Hackpert REPL. LISH should be able to: - inspect current Hackpert mode/status; - switch/select passive vs active mode where policy allows; - ask the expert for reasoning/recommendations; - start/stop/inspect active expert runs; - inspect plans/playbooks and tool-call/result graph nodes; - inspect operational/long-term KB state and promotion candidates; - inspect IPX-derived passive evidence; - surface provider/tool execution initiated by active Hackpert. ## Authority boundary - Hackmode/Tek9 owns canonical persisted state. - capability-provider registry + provider actors own executable tools/capabilities. - Passive Hackpert has no mutation/dispatch authority. - Active Hackpert may orchestrate tools and request canonical mutations through a typed Common Lisp active-engine interface. - Common Lisp validates active-engine actions/deltas before execution/persistence. - Prolog does not directly write Tek9 or receive an unrestricted shell primitive. - no `targets.txt`, `inscope.txt`, `outscope.txt`, `expert-state.prolog`, or environment-variable operation authority. ## First slice in PR #25 - [x] optional `hackmode-expert` bridge using SWI-Prolog when installed - [x] deterministic projection of current operation/assets/providers into temporary Prolog facts - [x] target classification: URL/domain/IPv4/IPv6/unknown - [x] capability recommendation from target/asset type + registered provider metadata - [x] fixed-goal query boundary; user data is serialized as facts, never concatenated into executable Prolog source - [x] structured Common Lisp results - [x] tests for target classification, recommendation ordering, missing `swipl`, quoting/injection safety, and no canonical-state mutation in the passive foundation - [x] architecture records graph/KB direction and IPX passive evidence path PR #25 implemented the **passive foundation only**. Its "no mutation" property is not the final Hackpert architecture; active mode is the next major execution layer. ## Next implementation slices - [ ] typed execution graph for tool calls/results, persisted by Common Lisp/Tek9 - [ ] explicit Hackpert engine mode model (`:passive` / `:active`) - [ ] active-engine typed action/state-delta protocol - [ ] active provider orchestration loop using Hackmode capabilities - [ ] operational KB storage + active mutation API - [ ] long-term KB storage and promotion lifecycle - [ ] explicit global-KB export/looting API - [ ] graph + KB snapshot facts into Prolog and typed graph/state deltas back - [ ] attack-plan/playbook graph primitives - [ ] LISH Hackpert mode/run/graph/KB integration - [ ] recon expert on shared substrate - [ ] wordlist/fuzz-list KB import with provenance - [ ] success/failure promotion candidates from execution evidence - [ ] specialized fuzzing/SQLi/OOB/XSS/blind-XSS experts incrementally in active mode - [ ] Emacs graph/plan/KB inspection - [ ] evaluate Prolog-RLM integration after the direct boundary is stable ## Invariants - local-first operation still works with Prolog absent; - expert failure cannot corrupt canonical Hackmode state; - passive mode causes zero tool dispatches and zero canonical mutations; - active mode mutations are explicit, typed, validated, graph-recorded, and auditable; - active tool execution goes through the provider runtime; - no duplicate target/operation authority; - same canonical input + same rule/KB version produces deterministic reasoning output where practical; - global KB mutation/export is explicit and auditable. ## Acceptance proof for active mode 1. select an operation and start Hackpert in active mode; 2. Hackpert receives canonical graph/KB/provider facts; 3. Prolog emits a typed capability action rather than shell code; 4. Common Lisp validates and dispatches it through the normal provider actor path; 5. tool call + result are persisted as execution graph nodes/edges; 6. discovered assets/findings are persisted through canonical Hackmode APIs; 7. operational KB state may be updated by the active loop; 8. the next reasoning iteration sees those mutations and can choose a different action; 9. switching to passive mode makes the same expert unable to dispatch or mutate; 10. LISH can inspect mode, run state, plan, graph, and resulting KB changes.

nsaspy referenced this issue

2026-09-17 03:04:05 +00:00

feat: receive StarIntel targets in Hackmode actors #204