Documentation
¶
Overview ¶
Package dastrun turns a governed DAST verification probe from a synchronous request-thread execution into a durable, lease-executed job. The API Submits a run (persist + enqueue atomically) and returns immediately; a worker claims the job and runs the SAME approval-gated, evidence-sealing probe the in-process path ran, then records the verdict on the durable run. The approval's single-use consume and its evidence seal are unchanged: they still happen exactly once, inside the probe, now on the worker.
Index ¶
- Constants
- type Prober
- type Service
- func (s *Service) FailStrandedJob(ctx context.Context, payload []byte, cause error) error
- func (s *Service) GetRun(ctx context.Context, tenantID, runID shared.ID) (ddast.Run, error)
- func (s *Service) RunJob(ctx context.Context, payload []byte) error
- func (s *Service) Submit(ctx context.Context, engagementID, actionID shared.ID, actor string, ...) (ddast.Run, error)
Constants ¶
const JobKind = "dast_run"
JobKind is the durable job kind for a DAST verification run.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Prober ¶
type Prober interface {
Run(ctx context.Context, actor string, engagementID, actionID shared.ID, probe dastrunner.Probe) (dastrunner.Result, error)
}
Prober runs one governed DAST probe against a consumed approval. *dastworkflow.Service satisfies it.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service submits and reads DAST runs (API) and executes them (worker).
func NewService ¶
func NewService(runs ports.DASTRunStore, prober Prober, audit ports.AuditLogger, clock ports.Clock, ids ports.IDGenerator) (*Service, error)
NewService validates dependencies. prober may be nil for a submit/read-only (API) service; it is required to execute jobs on the worker.
func (*Service) FailStrandedJob ¶
FailStrandedJob records a run as failed when its job is dead-lettered, so a stranded run does not sit in a non-terminal state forever. It writes through SaveDASTRun rather than the FinishRun CAS on purpose: a dead-lettered run may be either queued (never started) or running (started by this same worker), and FinishRun can only terminalize from running, so it would orphan a queued stranded run. The blind write is safe because the worker calls OnDeadLetter only AFTER its fenced queue.Deadletter succeeds, which proves this worker still holds the claim at the current fence; no other worker owns the job, so no live run of another worker can be clobbered. SaveDASTRun's terminal-immutability still guards the case where a terminal outcome was recorded between the Terminal() check and the write.
func (*Service) RunJob ¶
RunJob is the worker handler. It loads the run and drives it to a terminal state exactly once, then completes the job. The run's own status is the redelivery marker:
- terminal: a prior delivery already finished it. No-op.
- running: a prior delivery started the probe and died before recording the outcome. The probe may have already consumed the single-use approval and moved the judgment score, so it is NEVER re-executed (re-running would double-probe, and re-admitting a consumed approval returns forbidden and would overwrite a real success with a false failure). The run is terminalized "interrupted" via the FinishRun compare-and-set; the operator re-submits, and the approval, if it was never consumed, is still valid.
- queued: this delivery owns execution. With no prober (this worker has no live scoped egress) the run is failed "egress_unavailable" so it is operator-visible instead of orphaned in the queue. With a prober, the run is marked running (the redelivery marker above) and the probe executes.
A probe-level error terminalizes the run rather than returning it for retry: the run is running, so the queue cannot safely retry it, and a transient pre-consume error is indistinguishable from a post-consume one without re-admitting a possibly-consumed approval. The operator re-submits. Only a store or tenant error is returned to the queue.
func (*Service) Submit ¶
func (s *Service) Submit(ctx context.Context, engagementID, actionID shared.ID, actor string, probe dastrunner.Probe) (ddast.Run, error)
Submit persists a queued run and its durable job atomically, then returns the run. The probe is not executed here; the worker does, and the worker is where the approval is enforced: prober.Run admits through the safety gate, requires the approval decision to be approved, binds the probe to it by digest, and consumes it once before probing. Submit does not re-check the approval, so a run for a missing or unapproved action enqueues and then fails on the worker rather than at the edge.
Source Files