validation

type AgentCapability ¶

type AgentCapability interface {
	AvailableExecutorKinds(ctx context.Context, tenantID shared.ID) ([]ExecutorKind, error)
}

AgentCapability lets the service ask "which ExecutorKinds are currently available for this tenant?" before selecting. A real implementation looks at agent registrations; the test stub returns a static slice.

type AttackerProfile ¶

type AttackerProfile struct {
	ID           shared.ID
	Name         string
	Capabilities []string // "external-unauth" | "credentialed" | "network-pivot" | ...
}

AttackerProfile is the narrow subset of the full profile that the API-side selection / gating logic needs. It never travels to the agent — the agent receives the already-approved executor kind and technique.

type CoverageThresholds ¶

type CoverageThresholds struct {
	P0 float64
	P1 float64
	P2 float64
	P3 float64
}

CoverageThresholds define the SLO targets per priority class. Exported so tenants can override later (per-tenant-config).

type DefaultSelector ¶

type DefaultSelector struct{}

DefaultSelector applies a conservative mapping:

• safe-check is preferred when available — cheapest + legally safest
• nuclei is next for web-reachable targets
• atomic-red-team / caldera require a non-empty profile capability set (waiver + adversary emulation opt-in)

func (DefaultSelector) Select(
	tid TechniqueID,
	profile *AttackerProfile,
	available []ExecutorKind,
) (ExecutorKind, error)

type Evidence ¶

type Evidence struct {
	// ExecutorKind identifies which agent-side tool produced this
	// evidence. Enforced by the ingest handler against the
	// ExecutorKind declared on the job.
	ExecutorKind string
	Technique    TechniqueID
	Target       Target
	StartedAt    time.Time
	EndedAt      time.Time
	Outcome      Outcome
	Summary      string
	Artifacts    []string // attachment IDs (screenshots, PCAPs)
	RawMeta      map[string]any
}

Evidence is everything a reviewer needs to judge whether the technique was executed and what it produced. Produced by the agent and POSTed back through the validation-ingest endpoint.

func (e Evidence) Executor() string

type EvidenceRepository ¶

type EvidenceRepository interface {
	Create(ctx context.Context, ev StoredEvidence) error
	ListByFinding(ctx context.Context, tenantID, findingID shared.ID) ([]StoredEvidence, error)
}

EvidenceRepository persists StoredEvidence. Implemented by a postgres-backed type; tests use an in-memory fake.

type EvidenceStore ¶

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

EvidenceStore is the app-layer facade. Calls redact → persist → returns the stored record so callers can surface it.

func NewEvidenceStore(repo EvidenceRepository) *EvidenceStore

func (s *EvidenceStore) ListForFinding(
	ctx context.Context,
	tenantID, findingID shared.ID,
) ([]StoredEvidence, error)

func (s *EvidenceStore) Record(
	ctx context.Context,
	tenantID, findingID shared.ID,
	simulationRunID *shared.ID,
	ev Evidence,
) (StoredEvidence, error)

type ExecutorKind ¶

type ExecutorKind string

ExecutorKind enumerates the validation tool the AGENT will run. The API uses this string to route jobs to agents that declare they support it. The API does not import or call the tool itself.

const (
	KindSafeCheck     ExecutorKind = "safe-check"
	KindAtomicRedTeam ExecutorKind = "atomic-red-team"
	KindCaldera       ExecutorKind = "caldera"
	KindNuclei        ExecutorKind = "nuclei"
)

type FindingMutator ¶

type FindingMutator interface {
	Get(ctx context.Context, tenantID, findingID shared.ID) (*vulnerability.Finding, error)
	Update(ctx context.Context, f *vulnerability.Finding) error
}

FindingMutator is the narrow contract for loading + saving a finding during the transition.

type Outcome ¶

type Outcome string

Outcome is the exit status of an execution.

const (
	OutcomeDetected     Outcome = "detected"
	OutcomeNotDetected  Outcome = "not_detected"
	OutcomeInconclusive Outcome = "inconclusive"
	OutcomeError        Outcome = "error"
	OutcomeSkipped      Outcome = "skipped"
)

type ProofOfFixService ¶

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

ProofOfFixService orchestrates the retest.

func NewProofOfFixService(
	dispatcher ValidationDispatcher,
	capability AgentCapability,
	evStore *EvidenceStore,
	findingRepo FindingMutator,
	notifier RetestNotifier,
) *ProofOfFixService

func (s *ProofOfFixService) Retest(
	ctx context.Context,
	tenantID, findingID shared.ID,
	tid TechniqueID,
	target Target,
	priorKind ExecutorKind,
	profile *AttackerProfile,
) (Evidence, bool, error)

type Redactor ¶

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

Redactor scrubs common secret patterns from the evidence before it is persisted.

func NewRedactor() *Redactor

func (r *Redactor) AddPattern(re string)

func (r *Redactor) Redact(ev Evidence) Evidence

type RetestNotifier ¶

type RetestNotifier interface {
	NotifyFixRejected(ctx context.Context, tenantID, findingID shared.ID, reason string) error
}

RetestNotifier posts a message to the assignee when the retest refutes the fix. Nil notifier is acceptable — the status revert still happens.

type Selector ¶

type Selector interface {
	Select(tid TechniqueID, profile *AttackerProfile, available []ExecutorKind) (ExecutorKind, error)
}

Selector owns the API-side policy: given a technique + attacker profile + a list of executor kinds the agent fleet supports, pick the appropriate kind.

type StoredEvidence ¶

type StoredEvidence struct {
	ID              shared.ID
	TenantID        shared.ID
	FindingID       shared.ID  // the finding this execution validated
	SimulationRunID *shared.ID // optional; populated when evidence is part of a scheduled simulation
	Evidence        Evidence
	CreatedAt       time.Time
}

StoredEvidence is the persistence shape. Adds tenant_id + finding linkage to the in-memory Evidence struct. Persisted into the simulation_evidence table (migration lives in a companion PR).

type Target ¶

type Target struct {
	AssetID  shared.ID
	Type     string // "host" | "web_url" | "api_endpoint" | "cloud_resource"
	Address  string // host:port, URL, ARN, etc.
	Metadata map[string]any
}

Target identifies what we are validating against. The executor kind determines which fields it uses.

type TechniqueID ¶

type TechniqueID string

TechniqueID is the MITRE ATT&CK technique identifier. The API does not interpret it — it is passed to the agent unchanged.

type ValidationCoverage ¶

type ValidationCoverage struct {
	P0Total        int
	P0WithEvidence int
	P1Total        int
	P1WithEvidence int
	P2Total        int
	P2WithEvidence int
	P3Total        int
	P3WithEvidence int
}

ValidationCoverage aggregates per-priority coverage for a tenant or cycle window.

func (c ValidationCoverage) Pct(class string) float64

type ValidationDispatcher ¶

type ValidationDispatcher interface {
	Submit(ctx context.Context, job ValidationJob) (Evidence, error)
}

ValidationDispatcher submits a job for an agent and returns the resulting Evidence when the agent has reported back. Concrete implementations plug into the platform-job queue (Redis / Postgres).

Submit is expected to BLOCK until the agent finishes OR the context deadline fires — callers choose the deadline. In practice the implementation is queue + subscribe, not a synchronous call.

type ValidationJob ¶

type ValidationJob struct {
	JobID          shared.ID
	TenantID       shared.ID
	FindingID      shared.ID
	ExecutorKind   ExecutorKind
	Technique      TechniqueID
	Target         Target
	ProfileID      shared.ID
	TimeoutSeconds int
}

ValidationJob is the payload the API queues for an agent. Agents long-poll for jobs that match their advertised ExecutorKinds. Result is delivered via POST /api/v1/validation/evidence.