exploitation

type ChainRegistry ¶ added in v0.1.8

type ChainRegistry struct {
	// contains filtered or unexported fields
}

ChainRegistry tracks the exploitation chains currently running IN THIS PROCESS, so the offensive kill switch (issue #418, follow-up on #420) can reach them.

The work-order layer of the kill switch cancels queued and claimed offensive work orders. A chain already executing in memory is not a work order, so without this registry a running chain would be the one thing an operator's halt could not stop. The registry closes that gap: a Machine registers itself while it runs and the kill switch halts every registered chain for the tenant.

Scope honesty. This registry covers the process it lives in. In the current single-process deployment that is the whole estate's control plane. Under horizontal scale (P5) a chain runs on one node and a fleet-wide halt must fan out to every node's registry — a P5 concern this type does not pretend to solve. It never claims to reach a chain running in another process.

It implements offensivepolicyuc.ChainHalter. The interface is defined in the offensivepolicy package (the consumer) and implemented here; the dependency points from exploitation to offensivepolicy, the same direction admission already uses, so there is no import cycle.

func NewChainRegistry() *ChainRegistry

func (r *ChainRegistry) HaltChains(ctx context.Context, tenantID shared.ID, actor, reason string) (offensivepolicyuc.ChainHaltSummary, error)

func (r *ChainRegistry) Register(m *Machine)

func (r *ChainRegistry) RunTracked(ctx context.Context, m *Machine) (dexploit.ChainState, error)

func (r *ChainRegistry) Unregister(tenant, chainID shared.ID)

type ChainStore ¶ added in v0.1.8

type ChainStore interface {
	SaveChain(ctx context.Context, chain *dexploit.Chain) error
}

ChainStore persists a chain's state as it advances, so a halt or a crash cannot lose track of which steps still hold a cleanup obligation.

type CleanupRunner ¶ added in v0.1.8

type CleanupRunner interface {
	Cleanup(ctx context.Context, chain *dexploit.Chain, step dexploit.Step) error
}

CleanupRunner undoes a state-changing step. It runs on halt and on failure, in reverse order of execution, for every completed state-changing step.

type CreatedFindingProjector ¶ added in v0.2.0

type CreatedFindingProjector interface {
	ProjectCreatedFinding(context.Context, shared.ID, finding.Finding, string) error
}

type FindingStore ¶

type FindingStore interface {
	Upsert(ctx context.Context, findings []finding.Finding) error
	ListByEngagement(ctx context.Context, engagementID shared.ID) ([]finding.Finding, error)
	SetEvidenceScore(ctx context.Context, engagementID, findingID shared.ID, score, expectedVersion int) (finding.Finding, error)
}

FindingStore is the narrow slice of the finding repository this use case needs. The evidence-score setter is intentionally NOT on the broad ports.FindingRepository – it lives only on the concrete repos and is reached only here, so a read-only consumer (the agent tool catalog) cannot move a score. The concrete repos satisfy this consumer interface.

type Machine ¶ added in v0.1.8

type Machine struct {
	// contains filtered or unexported fields
}

Machine orchestrates one chain. It is a Go state machine over the pure domain chain: it admits, executes, seals, verifies and advances, and it runs cleanup on any halt or failure. No agent tool is registered that reaches Run or Halt, so a model can propose a chain but never drives one.

func NewMachine(chain *dexploit.Chain, admit StepAdmitter, exec StepExecutor, v StepVerifier, cleanup CleanupRunner, sealer stepSealer, store ChainStore, audit ports.AuditLogger, clock ports.Clock) (*Machine, error)

func (m *Machine) Chain() *dexploit.Chain

func (m *Machine) Halt(ctx context.Context, actor, reason string) (dexploit.ChainState, error)

func (m *Machine) Run(ctx context.Context) (dexploit.ChainState, error)

func (m *Machine) State() dexploit.ChainState

type PolicyStepAdmitter ¶ added in v0.1.8

type PolicyStepAdmitter struct {
	// contains filtered or unexported fields
}

PolicyStepAdmitter admits each chain step through the #418 offensive governance policy, individually, carrying the engagement's rules of engagement and the recorded approvals for that step.

It satisfies StepAdmitter. Every step is a fresh Authorize call evaluated at the current time — a chain never inherits permission from its first step, so a window that closes mid-chain, or a step whose technique is not in the register, halts the chain at exactly that step.

func NewPolicyStepAdmitter(gov governanceAuthorizer, roe offensivepolicyuc.RulesOfEngagement, approvals StepApprovals, now func() time.Time) *PolicyStepAdmitter

func (a *PolicyStepAdmitter) AdmitStep(ctx context.Context, chain *dexploit.Chain, step dexploit.Step) error

type Service ¶

type Service struct {
	// contains filtered or unexported fields
}

Service runs the evidence-gated exploitation-finding lifecycle.

func NewService(findings FindingStore, ev evidenceSealer, audit ports.AuditLogger, clock ports.Clock, ids ports.IDGenerator) (*Service, error)

func (s *Service) Confirm(ctx context.Context, verifier string, engagementID, findingID shared.ID, score int, rationale string, expectedVersion int) (finding.Finding, error)

func (s *Service) Propose(ctx context.Context, proposer string, engagementID shared.ID, in finding.ExploitationInput) (finding.Finding, error)

func (s *Service) ProposeHypothesis(ctx context.Context, proposer string, engagementID shared.ID, in finding.HypothesisInput) (finding.Finding, error)

func (s *Service) SetAttributor(a ports.FindingAttributor)

func (s *Service) SetLifecycleShadow(tx ports.TenantTransactionRunner, projector CreatedFindingProjector, enabled func(string) bool, engagements ports.EngagementTenantResolver) error

type SimulationCleanupRunner ¶ added in v0.2.0

type SimulationCleanupRunner struct{}

SimulationCleanupRunner discharges a step's cleanup obligation without touching a host, since the simulation changed nothing. It keeps the chain-of-custody consistent (every state-changing step's cleanup is recorded as run) without performing real teardown.

func (SimulationCleanupRunner) Cleanup(_ context.Context, _ *dexploit.Chain, _ dexploit.Step) error

type SimulationExecutor ¶ added in v0.2.0

type SimulationExecutor struct{}

SimulationExecutor is a StepExecutor that EXECUTES NOTHING on any host. It exists so the full governed offensive flow — admission through the #418 policy, single-step blast-radius enforcement, distinct-verifier sealing, and cleanup — can be wired and exercised end-to-end WITHOUT crossing the execution-safety boundary. It mirrors responseuc.SimulationExecutor and is shared by adversary emulation and exploitation chains.

It echoes the step's declared blast radius as the observed radius, so a benign, in-radius step records as cleanly executed and the Machine's radiusExceeded guard sees no escalation. It never performs I/O.

A REAL host executor is DELIBERATELY not provided. Running a technique argv on a live endpoint is a hard-to-reverse outward action: it must go through the same argv-only sandbox as every other tool, and wiring it requires a distinct execution-safety review plus explicit operator authorization. Until then the simulation executor keeps the governed chain-of-custody honest and testable without ever touching a host, which is the platform's stated differentiator (proof under a defensible chain of custody).

func (SimulationExecutor) Execute(_ context.Context, _ *dexploit.Chain, step dexploit.Step) (StepOutcome, error)

type SimulationStepVerifier ¶ added in v0.2.0

type SimulationStepVerifier struct{}

SimulationStepVerifier confirms a SIMULATED step. It attests that the rehearsal ran within the step's declared blast radius, NOT that a real exploit succeeded: the executor touched no host, the sealed evidence and the run are labeled simulation, and the verdict rationale says so. It exists so the governed Machine (admission, sealed evidence, distinct verification, cleanup) can run end to end as a rehearsal. A real, independent verifier is the deliberate extension point that a live host executor requires.

func (SimulationStepVerifier) Verify(_ context.Context, _ *dexploit.Chain, _ dexploit.Step, outcome StepOutcome) (verdict.Verdict, error)

type StepAdmitter ¶ added in v0.1.8

type StepAdmitter interface {
	AdmitStep(ctx context.Context, chain *dexploit.Chain, step dexploit.Step) error
}

StepAdmitter admits one step through the offensive governance policy and the execution guard before it runs. It returns an error (ErrForbidden) when the step's technique is not permitted for the target, the window has closed, or approval is missing. Each step is admitted INDIVIDUALLY — a chain never inherits permission from its first step.

type StepApprovals ¶ added in v0.1.8

type StepApprovals func(step dexploit.Step) []offensivepolicyuc.Approval

StepApprovals resolves the recorded human approvals for one step. It is a function so the caller can source approvals from wherever they live without this package depending on that store.

type StepExecutor ¶ added in v0.1.8

type StepExecutor interface {
	Execute(ctx context.Context, chain *dexploit.Chain, step dexploit.Step) (StepOutcome, error)
}

StepExecutor runs one step argv-only inside the sandbox with egress scoped to the authorised target. The Machine never shells out or opens a socket itself; everything a step does goes through here.

type StepOutcome ¶ added in v0.1.8

type StepOutcome struct {
	Succeeded      bool
	ObservedRadius offensivepolicy.Radius
	Proof          []byte // raw; the Machine bounds and redacts it before sealing
	Observation    string // the specific observation that proves success/failure, for the evidence record
}

StepOutcome is what the sandboxed executor reports back. ObservedRadius is the effect that ACTUALLY occurred, which the Machine checks against the step's declared radius: a step that changed state while declaring read_only is a policy violation, not a success.

type StepVerifier ¶ added in v0.1.8

type StepVerifier interface {
	Verify(ctx context.Context, chain *dexploit.Chain, step dexploit.Step, outcome StepOutcome) (verdict.Verdict, error)
}

StepVerifier produces a DISTINCT verifier's sealed verdict for a step's outcome. Its verdict's Verifier must differ from the step's proposer; the Machine enforces that and refuses otherwise, so a model cannot talk itself through a chain by verifying its own step.