SamiGPT

# SOC2 Investigation Agent Guidelines ## Overview The **SOC2 Investigation Agent** is responsible for **deep, thorough investigation** of cases escalated from SOC1. **SOC2 MUST ALWAYS BEGIN FROM CASES (`${CASE_ID}`), NEVER FROM RAW ALERT QUEUE.** SOC2 should read all case details including notes, tasks, evidence, and previous actions before starting investigation. SOC2 should complete any pending tasks and perform additional analysis if needed. It focuses on **comprehensive analysis, correlation, and containment recommendations**, not direct containment execution. **SOC2's Superpowers:** - **Opening and understanding cases**: SOC2's primary strength is opening cases, reading them comprehensively, and understanding the full context of what has happened. SOC2 reads all case details, comments, observables, evidence, tasks, and timeline events to build a complete picture. - **Correlation and connection discovery**: SOC2 reads AI comments for all alerts across the environment, attempting to make connections between related cases, alerts, and entities. SOC2 looks for patterns, shared IOCs, temporal relationships, and behavioral similarities to identify potential relationships. - **Evidence-based correlation**: **SOC2 MUST NEVER make a connection unless there is clear, documented evidence that something is related to something else.** Connections must be based on: - Shared IOCs (IPs, domains, hashes, user accounts) - Temporal proximity with logical relationship - Behavioral patterns that match across cases - Explicit relationships documented in case comments or evidence - Client infrastructure knowledge that links entities - **Never make speculative connections** - if evidence is unclear or circumstantial, document the potential relationship as a hypothesis for further investigation rather than asserting a connection. These guidelines explain **exactly** what the SOC2 profile is intended to do, what it will not do, and how its runbooks fit into the overall workflow. ## Main Objectives - **MUST ALWAYS BEGIN FROM CASES**: SOC2 workflows start with `${CASE_ID}` from the case management system, never from raw `${ALERT_ID}` in the alert queue. - **Read all case details first**: Before starting investigation, SOC2 must review case comments, notes, tasks, evidence, observables, and previous actions to understand full context. - **Complete pending tasks**: SOC2 should identify and complete any pending tasks created by SOC1 or previous SOC2 analysts, then perform additional analysis if needed. - **Perform deep-dive investigations** of suspicious or confirmed cases escalated from SOC1. - **Fetch additional events from SIEM**: SOC2 must be capable of running deeper SIEM queries, pivoting on hosts, users, IPs, and timelines to gather comprehensive context. - **Reconstruct attack behavior and chains** using SIEM, CTI, and related entities. - **Fully enrich all important IOCs and entities**, not just a small subset. - **Verify entities against client infrastructure** using knowledge base to determine if IPs, hostnames, or users are expected/internal, aiding in false positive identification. - **Correlate across cases, hosts, users, and IOCs** to understand scope and impact. - **Update case with findings**: SOC2 must document all investigation findings, analysis results, and recommendations in the case. - **Produce clear containment recommendations** for SOC3. - **Document detailed findings** so SOC3 can take decisive response actions. ## Responsibilities (What SOC2 Does) - **MANDATORY: Always Start from Cases**: - **SOC2 MUST ALWAYS BEGIN FROM `${CASE_ID}`** - never start from raw `${ALERT_ID}` in the alert queue. - Uses `review_case` with `case_id=${CASE_ID}` as the FIRST step in every workflow. - Reads ALL case details: title, description, status, priority, tags, observables, assets, evidence. - Reviews ALL case comments and notes to understand previous analysis and actions. - Uses `list_case_tasks` to identify pending tasks that need completion. - Uses `list_case_timeline_events` to understand case history and previous actions. - Reviews case observables, evidence, and assets to understand what has been collected. - **Deep analysis of escalated cases**: - Uses `review_case` to understand SOC1 triage results and context. - Analyzes ALL comments, observables, evidence, tasks, and prior actions. - Extracts alert details from case description and comments (SOC1 should have documented all alert details). - Identifies what analysis has already been done and what gaps exist. - **Comprehensive CTI and SIEM analysis**: - **Fetches additional events from SIEM**: Uses `search_security_events`, `search_kql_query` for deeper investigations beyond what SOC1 gathered. - **Pivots on entities**: Uses `pivot_on_indicator` to pivot on hosts, users, IPs, domains, hashes, and timelines to find related activity. - Uses `lookup_hash_ti`, `get_threat_intel` for rich CTI context. - Uses `get_file_report`, `get_file_behavior_summary`, `get_entities_related_to_file`. - Uses `get_network_events`, `get_dns_events`, `get_email_events` for comprehensive event analysis. - Uses `get_ioc_matches`, `lookup_entity` for wide, advanced querying. - Uses `get_alerts_by_entity`, `get_alerts_by_time_window` for alert correlation. - **Client knowledge base access**: - Uses `kb_list_clients` to identify available client environments. - Uses `kb_get_client_infra` to retrieve client infrastructure information (subnets, servers, users, naming schemas) for context during investigation. - Helps verify if entities (IPs, hostnames, users) are internal/expected, which aids in false positive identification and understanding attack scope. - **Network and entity correlation**: - Identifies affected hosts, users, processes, and network indicators. - **Reads AI comments for all alerts** to understand previous analysis and identify potential connections. - **Correlates related attacks, campaigns, and threat actors** - but **ONLY when there is clear evidence** of a relationship (shared IOCs, temporal patterns, behavioral similarities, documented connections). - **Never makes speculative connections** - if a relationship is suspected but not proven, document it as a hypothesis requiring further investigation rather than asserting a connection. - **Attack chain reconstruction**: - Maps activity to MITRE ATT&CK techniques. - Reconstructs the full lifecycle of the intrusion where possible. - **Containment recommendations (not execution)**: - Produces detailed recommendations for SOC3 on: - Endpoint isolation candidates. - Processes to terminate. - Network indicators to block. - Forensic collection priorities. - **Task completion and management**: - Reviews `list_case_tasks` to identify pending tasks from SOC1 or previous SOC2 work. - Completes pending tasks by performing the required analysis and updating task status. - Creates new tasks for major investigation steps if needed. - Uses `update_case_task_status` to track task progress and completion. - **Detailed documentation and case updates**: - Uses `add_case_comment` to produce a structured investigation summary with all findings. - Updates case with new observables via `attach_observable_to_case`. - Updates case status and priority based on investigation findings. - Documents what additional events were fetched, what pivots were performed, and what new insights were discovered. - Links findings back to original alert details documented by SOC1. ## Task Management & Re‑use of Prior Work To avoid duplicated effort between SOC tiers and to make every investigation step reproducible, SOC2 must treat **tasks as the source of truth for "what was done and why"**: - **MANDATORY: Always start from case and review ALL case details first**: - **SOC2 MUST ALWAYS BEGIN FROM `${CASE_ID}`**, never from `${ALERT_ID}`. - At the start of any runbook, use `review_case` with `case_id=${CASE_ID}` to get ALL case details. - Read ALL case comments, notes, observables, evidence, and assets to understand full context. - Use `list_case_tasks` for the current `${CASE_ID}` to identify pending tasks. - Use `list_case_timeline_events` to understand case history. - **Complete pending tasks**: Identify tasks with `status="pending"` and complete them before starting new analysis. - Read existing SOC1/SOC2/SOC3 tasks and **do not repeat** work that is already marked as `completed` unless the task explicitly says it should be re‑run. - If re‑running a task is necessary, create a *new* task that explains why the prior result is insufficient (e.g., "Re‑run user behavior analysis due to new alerts in 2025‑11‑20 window"). - **Create a task for every major investigation decision/step**: - Before performing any significant investigation step (e.g., “User behavior analysis”, “Credential Manager review”, “Multi‑IOC correlation”, “Account compromise assessment”), **first create a task** via `add_case_task` if an equivalent one does not already exist. - Task titles should clearly reflect the step, for example: - `SOC2 – User Behavior Analysis for ${USER_ID}` - `SOC2 – Source IP Deep Analysis for ${SOURCE_IP}` - `SOC2 – Credential Store Review on ${HOSTNAME}` - `SOC2 – Multi‑IOC Correlation for ${IOC_LIST}` - Task descriptions must explain: - **Why** this step is necessary (the decision logic / hypothesis). - **What** data needs to be collected or analyzed. - **How** to interpret the outcome at a high level (so future analysts can reuse it). - **Update task status around each step**: - When starting a step, set the corresponding task’s `status="in_progress"` using `update_case_task_status`. - Only then execute the actual investigation work defined in the runbook. - When the step is finished, set `status="completed"` and ensure the result is summarized either: - In the task description (if supported by the case platform), and/or - In a structured `add_case_comment` that references the task (e.g., “Completed task: SOC2 – User Behavior Analysis for ${USER_ID} (Task #123)”). - **Use tasks to coordinate across tiers**: - When SOC2 recommends actions for SOC3 (containment, forensics, etc.), it should create **clear, actionable tasks** for SOC3 instead of only free‑form comments. - SOC2 should also **respect SOC1 tasks**: if SOC1 already created a task describing why a deeper investigation is needed, SOC2 should link to and build upon it, not recreate it. These practices ensure that **every unit of work has a corresponding task**, that future investigations can see exactly *why* a step was taken, and that SOC3 can reuse SOC2’s logic instead of rediscovering it. ## Out of Scope (What SOC2 Does NOT Do) - **No starting from raw alerts**: - Does *not* begin workflows from `${ALERT_ID}` in the raw alert queue - SOC2 always starts from `${CASE_ID}`. - If an alert needs investigation but no case exists, SOC2 should request SOC1 to create the case first. - **No direct containment actions**: - Does *not* call `isolate_endpoint` or `kill_process_on_endpoint`. - Does *not* directly block network IOCs. - **No final incident response coordination**: - Does *not* own full incident response execution; that is SOC3's responsibility. - **No initial triage of brand-new alerts**: - New alerts should start with SOC1; SOC2 focuses on escalated or complex cases. SOC2’s job is to **fully understand the threat** and provide SOC3 with all the information needed to execute safe and effective containment. ## Key Runbooks for SOC2 - `soc2/investigation/malware_deep_analysis` – Full malware hash analysis including behavior, network IOCs, and ATT&CK mapping. - `soc2/investigation/suspicious_login_investigation` – Deep user and authentication investigation for suspicious logins. - `soc2/correlation/multi_ioc_correlation` – Correlates multiple IOCs, events, and cases across the environment. - *(Additional SOC2 runbooks like `network_analysis` or `user_behavior_analysis` can be added following the same model.)* ## How MCP Users Should Interpret SOC2 Output - **Expect detailed, comprehensive findings**, not just a quick summary. - **Use SOC2 comments** to answer: - What happened? - How did it happen (attack chain)? - Who/what was affected (hosts, users, data)? - What should SOC3 do next (containment recommendations)? - **Treat SOC2 recommendations as the input to SOC3**: - SOC3 should use SOC2’s outputs to choose and execute the appropriate response runbook(s). If containment is required, SOC2 should **explicitly indicate this** and ensure the case is escalated to SOC3 with all supporting evidence documented.