Skip to content

feat: Add SOAR MCP Case Management Tools #234

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jshlbrd wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Add SOAR MCP Case Management Tools #234

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 123 additions & 0 deletions docs/servers/secops_soar_mcp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,6 +123,27 @@ The server supports two authentication methods:

These tools are always available.

- **`create_case(name, priority=None, description=None, environment=None)`**
- **Description:** Creates a new manual case in the SOAR platform for tracking a security incident or investigation.
- **Parameters:**
- `name` (required): The name or title of the case.
- `priority` (optional): The priority level (e.g., "PriorityInfo", "PriorityLow", "PriorityMedium", "PriorityHigh", "PriorityCritical").
- `description` (optional): A description providing context about the security incident.
- `environment` (optional): The environment for the case.
- **Returns:** The newly created case details including its assigned ID.
- **Return Example:**
```json
{
"id": 12350,
"identifier": "SEC-12350",
"name": "Suspicious Login Attempts from External IP",
"description": "Multiple failed login attempts detected from IP 203.0.113.50",
"priority": "PriorityHigh",
"status": "New",
"creationTime": "2023-09-15T16:00:00Z"
}
```

- **`list_cases()`**
- **Description:** Lists available cases in the SOAR platform.
- **Returns:** A list of cases with basic information like ID, name, status, and priority.
Expand Down Expand Up @@ -270,6 +291,108 @@ These tools are always available.
}
```

- **`update_case_description(case_id, description)`**
- **Description:** Updates the description of a specific case. This replaces the existing description entirely.
- **Parameters:**
- `case_id` (required): The ID of the case.
- `description` (required): The new description text for the case.
- **Returns:** Confirmation of the description update.
- **Return Example:**
```json
{
"success": true,
"case_id": 12345,
"description": "Confirmed phishing campaign targeting finance department. Three users clicked malicious links.",
"timestamp": "2023-09-15T15:45:30Z"
}
```

- **`close_case(case_id, root_cause, comment, reason, tags=None)`**
- **Description:** Closes a specific case by setting its root cause, close reason, and a closing comment. Marks the end of the investigation lifecycle.
- **Parameters:**
- `case_id` (required): The ID of the case.
- `root_cause` (required): The determined root cause of the incident.
- `comment` (required): A comment explaining the closure decision.
- `reason` (required): The close reason category. Must be one of: "Malicious", "NotMalicious", "Maintenance", "Inconclusive".
- `tags` (optional): Comma-separated tags to apply to the case when closing.
- **Returns:** Confirmation of the case closure.
- **Return Example:**
```json
{
"success": true,
"case_id": 12345,
"status": "Closed",
"reason": "Malicious",
"root_cause": "Phishing email with credential harvester",
"timestamp": "2023-09-15T16:00:00Z"
}
```

- **`assign_case(case_id, user)`**
- **Description:** Assigns a specific analyst or responder to a specific case, establishing ownership for the investigation.
- **Parameters:**
- `case_id` (required): The ID of the case.
- `user` (required): The username or email of the user to assign.
- **Returns:** Confirmation of the assignment.
- **Return Example:**
```json
{
"success": true,
"case_id": 12345,
"assigned_user": "john.analyst@example.com",
"timestamp": "2023-09-15T14:35:00Z"
}
```

- **`change_case_stage(case_id, stage)`**
- **Description:** Updates the workflow stage of a specific case to reflect its current position in the incident response lifecycle. Stages are configurable per SOAR deployment.
- **Parameters:**
- `case_id` (required): The ID of the case.
- `stage` (required): The new stage name (e.g., "Triage", "Investigation", "Containment", "Remediation").
- **Returns:** Confirmation of the stage change.
- **Return Example:**
```json
{
"success": true,
"case_id": 12345,
"stage": "Investigation",
"timestamp": "2023-09-15T14:40:00Z"
}
```

- **`add_case_tag(case_id, tag)`**
- **Description:** Adds a descriptive tag to a specific case for categorization, filtering, and reporting purposes.
- **Parameters:**
- `case_id` (required): The ID of the case.
- `tag` (required): The tag to add (e.g., "phishing", "ransomware").
- **Returns:** Confirmation of the tag addition.
- **Return Example:**
```json
{
"success": true,
"case_id": 12345,
"tag": "phishing",
"timestamp": "2023-09-15T14:45:00Z"
}
```

- **`remove_case_tag(case_id, tag)`**
- **Description:** Removes a previously applied tag from a specific case.
- **Parameters:**
- `case_id` (required): The ID of the case.
- `tag` (required): The tag to remove.
- **Returns:** Confirmation of the tag removal.
- **Return Example:**
```json
{
"success": true,
"case_id": 12345,
"tag": "false-positive",
"removed": true,
"timestamp": "2023-09-15T14:50:00Z"
}
```

- **`get_entities_by_alert_group_identifiers(case_id, alert_group_identifiers)`**
- **Description:** Retrieves entities (like IPs, users, hosts) involved in one or more alert groups within a case. Can also be used to get target entities for manual actions.
- **Parameters:**
Expand Down
6 changes: 5 additions & 1 deletion extensions/google-secops/TOOL_MAPPING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,11 @@ When executing a skill, the agent should first check which tools are available i
| | Get Case Details | `get_case` | `get_case_full_details` | Local `get_case_full_details` aggregates alerts/comments. Remote `get_case` fetches the case object; use `expand='tasks,tags,products'` or call `list_case_alerts`/`list_case_comments` for full context. |
| | Comment on Case | `create_case_comment` | `post_case_comment` | |
| | Update Case | `update_case` | `change_case_priority` | Remote tool is general (priority, status, assignee). Local tool is specific to priority. |
| | Close Case | `execute_bulk_close_case` | *(No local tool)* | Only remote tool can close cases. |
| | Close Case | `execute_bulk_close_case` | `close_case` | Remote uses bulk endpoint; local closes a single case. |
| | Assign Case | *(No direct equivalent)* | `assign_case` | Local tool assigns a user to a case. |
| | Change Case Stage | *(No direct equivalent)* | `change_case_stage` | Local tool updates the workflow stage of a case. |
| | Add Case Tag | *(No direct equivalent)* | `add_case_tag` | Local tool adds a tag to a case. |
| | Remove Case Tag | *(No direct equivalent)* | `remove_case_tag` | Local tool removes a tag from a case. |
| **Alerts (SOAR)** | List Alerts for Case | `list_case_alerts` | `list_alerts_by_case` | |
| | List Events for Alert | `list_connector_events` | `list_events_by_alert` | Remote tool lists "connector events". |
| | List Alert Groups | *(No direct equivalent)* | `list_alert_group_identifiers_by_case` | Remote `list_case_alerts` returns alert objects which may contain grouping info. |
Expand Down
Loading