Documentation
¶
Overview ¶
Package exploitation is the evidence-gated lifecycle for AI/exploitation findings. An AI finding is a CLAIM until an independent adversarial verifier proves it. Two operations:
Propose creates the finding at EvidenceScore 0 (KindExploitation). Until proven it can be neither confirmed (CanPromote == false) nor included in a report. Confirm applies an adversarial-verifier verdict. It SEALS the verdict into the evidence chain FIRST (fail-closed), then raises the score – so a raised score ALWAYS has a sealed, hash-chained "try to refute" record behind it. The proposing agent has no path to raise its own score: Confirm is not an agent-callable tool (the catalog exposes no write/verdict tool), and there is no other evidence-score setter in the use cases.
Index ¶
- Constants
- type FindingStore
- type Service
- func (s *Service) Confirm(ctx context.Context, verifier string, engagementID, findingID shared.ID, ...) (finding.Finding, error)
- func (s *Service) Propose(ctx context.Context, proposer string, engagementID shared.ID, ...) (finding.Finding, error)
- func (s *Service) ProposeHypothesis(ctx context.Context, proposer string, engagementID shared.ID, ...) (finding.Finding, error)
Constants ¶
const VerdictEvidenceKind = "exploitation_verdict"
VerdictEvidenceKind is the evidence-chain kind under which a sealed adversarial verdict is recorded (the provenance behind any raised score).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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 Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service runs the evidence-gated exploitation-finding lifecycle.
func NewService ¶
func NewService(findings FindingStore, ev evidenceSealer, audit ports.AuditLogger, clock ports.Clock, ids ports.IDGenerator) (*Service, error)
NewService validates its dependencies (all required; the evidence sealer is mandatory because a verdict that cannot be sealed must never move a score).
func (*Service) Confirm ¶
func (s *Service) Confirm(ctx context.Context, verifier string, engagementID, findingID shared.ID, score int, rationale string, expectedVersion int) (finding.Finding, error)
Confirm applies an adversarial-verifier verdict to a proposed finding. It seals the verdict as evidence FIRST (fail-closed: an unrecorded verdict never moves a score), then sets the finding's EvidenceScore under optimistic concurrency (expectedVersion guards a racing update). A passing score (>= EvidenceThreshold) makes the finding promotable/reportable; a refuting (low) score leaves it gated. Returns the updated finding.
Provenance is one-directional by design: a moved score ALWAYS has a sealed verdict behind it, but the converse does not strictly hold – because the seal precedes the version-guarded write, a Confirm that LOSES a concurrency race (ErrConflict) can leave an orphan sealed verdict in the append-only chain with no score move. That is acceptable: the verdict is a real adversarial assessment that happened; it simply did not win the race.
func (*Service) Propose ¶
func (s *Service) Propose(ctx context.Context, proposer string, engagementID shared.ID, in finding.ExploitationInput) (finding.Finding, error)
Propose creates an AI/exploitation finding at EvidenceScore 0. proposer is the actor that proposed it (an agent session – attribution only; it confers no power to confirm).
func (*Service) ProposeHypothesis ¶
func (s *Service) ProposeHypothesis(ctx context.Context, proposer string, engagementID shared.ID, in finding.HypothesisInput) (finding.Finding, error)
ProposeHypothesis creates an AI attack-chain hypothesis finding (Kind=hypothesis) at EvidenceScore 0, linking the named constituent findings. proposer is the agent session (attribution only – the finding is gated and confers no power to verify; a DISTINCT human raises the score via Confirm). Mirrors Propose; NewHypothesis validates (>= 2 constituents, title+description, etc.) and stamps the gating ProposedBy.
Source Files