SOAR Tools

The SOAR tool module provides five tools for playbook execution, human approval, case management, and report generation. Located in aurorasoc/tools/soar/.

Tool Inventory

Tool	Action Type	Approval Required
ExecutePlaybook	Automated response	Depends on playbook steps
RequestHumanApproval	Human gate	N/A (creates approval)
CreateCase	Case creation	No
UpdateCase	Case modification	No
GenerateReport	Report creation	No

ExecutePlaybook

Triggers a SOAR playbook execution:

class ExecutePlaybook(AuroraTool):
    name = "execute_playbook"
    description = "Execute an automated response playbook"
    
    input_schema = {
        "properties": {
            "playbook_id": {"type": "string"},
            "alert_id": {"type": "string"},
            "parameters": {"type": "object"},
            "dry_run": {"type": "boolean", "default": False}
        },
        "required": ["playbook_id", "alert_id"]
    }
    
    async def _execute(self, playbook_id, alert_id, parameters=None, dry_run=False):
        engine = PlaybookEngine()
        result = await engine.execute(
            playbook_id=playbook_id,
            alert_id=alert_id,
            parameters=parameters or {},
            dry_run=dry_run
        )
        return {
            "execution_id": result.id,
            "status": result.status,
            "steps_completed": result.steps_completed,
            "total_steps": result.total_steps,
            "dry_run": dry_run
        }

RequestHumanApproval

Creates a human approval request and polls for response:

class RequestHumanApproval(AuroraTool):
    name = "request_human_approval"
    description = "Request human authorization for a high-impact action"
    
    input_schema = {
        "properties": {
            "action": {"type": "string", "description": "Action requiring approval"},
            "justification": {"type": "string", "description": "Why this action is needed"},
            "case_id": {"type": "string"},
            "ttl_hours": {"type": "number", "default": 4}
        },
        "required": ["action", "justification"]
    }
    
    async def _execute(self, action, justification, case_id=None, ttl_hours=4):
        # Create approval record
        approval = await create_approval(
            action=action,
            justification=justification,
            case_id=case_id,
            ttl_hours=ttl_hours
        )
        
        # Poll for decision (with timeout)
        MAX_POLLS = 10  # 5 minutes at 30s intervals
        for _ in range(MAX_POLLS):
            await asyncio.sleep(30)
            status = await check_approval_status(approval.id)
            if status != "pending":
                return {
                    "approval_id": approval.id,
                    "status": status,
                    "decided_by": approval.decided_by
                }
        
        return {
            "approval_id": approval.id,
            "status": "timeout",
            "message": "Approval not received within polling window"
        }

CreateCase / UpdateCase

class CreateCase(AuroraTool):
    name = "create_case"
    description = "Create a new investigation case from alerts"
    
    async def _execute(self, title, severity, alert_ids, description=None):
        case = await db.create_case(
            title=title, severity=severity,
            alert_ids=alert_ids, description=description
        )
        return {"case_id": case.id, "status": "open"}

class UpdateCase(AuroraTool):
    name = "update_case"
    description = "Update an existing case status or details"
    
    async def _execute(self, case_id, status=None, notes=None, severity=None):
        case = await db.update_case(case_id, status=status, notes=notes, severity=severity)
        return {"case_id": case.id, "status": case.status}

GenerateReport

class GenerateReport(AuroraTool):
    name = "generate_report"
    description = "Generate a formatted investigation or executive report"
    
    async def _execute(self, report_type, case_id=None, format="markdown"):
        report = await report_generator.generate(
            report_type=report_type,  # "investigation", "executive", "compliance"
            case_id=case_id,
            format=format
        )
        return {"report_id": report.id, "content": report.content}

SOAR Tool Flow