Approval Workflows

// Quick creation with auto-generated APR- prefixed ID
ApprovalRequest request = ApprovalRequest.create(
    "session-abc-123",       // sessionId
    "block_ip_address",      // toolName
    Map.of("ip", "10.0.0.1", "duration", 24),  // parameters
    "Suspicious traffic detected from this IP"   // reason
);
// request.status = PENDING, request.requestedAt = now()

ApprovalRequest request = ApprovalRequest.builder()
    .requestId("APR-custom-001")
    .sessionId("session-abc-123")
    .incidentId("INC-2024-001")
    .toolName("isolate_host")
    .actionDescription("Isolate compromised host from network")
    .toolParameters(Map.of("hostname", "web-server-03", "incidentId", "INC-2024-001"))
    .approvalType(ApprovalType.MULTI)
    .requestedBy("soar-pipeline")
    .requestReason("Host shows signs of lateral movement")
    .potentialImpact("Service disruption for web-server-03")
    .riskAssessment("HIGH - production server with active traffic")
    .timeoutMinutes(30)
    .organizationId("org-456")
    .build();

ApprovalRequestDetails details = new ApprovalRequestDetails(
    "block_ip_address",                          // actionName
    "CONTAINMENT",                               // actionType
    "HIGH",                                      // riskLevel
    "Block IP 10.0.0.1 at the firewall level",   // description
    "{ip: 10.0.0.1, duration: 24}",              // arguments
    Map.of("ip", "10.0.0.1", "durationHours", 24) // parameters
);

String approvalId = approvalService.requestApproval(soarContext, details);

// 1. SOAR pipeline determines a tool requires approval
ApprovalRequestDetails details = new ApprovalRequestDetails(
    "isolate_host", "CONTAINMENT", "CRITICAL",
    "Isolate web-server-03 due to lateral movement detection",
    "{hostname: web-server-03}", Map.of("hostname", "web-server-03")
);

// 2. Request approval through the service
String approvalId = approvalService.requestApproval(soarContext, details);
// SoarContext transitions to WAITING_APPROVAL

// 3. Check status (polling or event-driven)
ApprovalStatus status = approvalService.getApprovalStatus(approvalId);

// 4a. Human approves via dashboard or notification channel
approvalService.handleApprovalResponse(
    approvalId, true, "Confirmed lateral movement in logs", "analyst-jane"
);

// 4b. Or use convenience methods
approvalService.approve(approvalId);   // Quick system approval
approvalService.reject(approvalId);    // Quick system rejection

// 5. Pipeline checks status and proceeds with tool execution
if (approvalService.getApprovalStatus(approvalId) == ApprovalStatus.APPROVED) {
    // Execute the @SoarTool method
}

// Using the builder for full control over the approval request
ApprovalRequest request = ApprovalRequest.builder()
    .sessionId(soarContext.getSessionId())
    .incidentId(soarContext.getIncidentId())
    .toolName("isolate_host")
    .approvalType(ApprovalType.MULTI)
    .requestedBy("soar-pipeline")
    .requestReason("Lateral movement detected from web-server-03")
    .potentialImpact("Web traffic disruption for 200+ active sessions")
    .riskAssessment("CRITICAL - production server under active attack")
    .timeoutMinutes(15)
    .organizationId(soarContext.getOrganizationId())
    .build();

// Submit: saves and notifies in one call
approvalService.submitApprovalRequest(request);

// Or use async API
CompletableFuture<Boolean> future = approvalService.requestApproval(request);
future.thenAccept(approved -> {
    if (approved) {
        // Proceed with tool execution
    }
});