mirror of
https://github.com/mukul975/Anthropic-Cybersecurity-Skills.git
synced 2026-08-28 12:19:41 +03:00
feat: add 5 new cybersecurity skills - secrets scanning CI/CD, Bluetooth assessment, DNS exfil Zeek, SOAR phishing, AD ACL abuse
This commit is contained in:
mukul975
@@ -0,0 +1,8 @@
|
||||
MIT License
|
||||
Copyright (c) 2025 Mahipal
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
||||
@@ -0,0 +1,68 @@
|
||||
---
|
||||
name: implementing-soar-playbook-for-phishing
|
||||
description: Automate phishing incident response using Splunk SOAR REST API to create containers, add artifacts, and trigger playbooks
|
||||
domain: cybersecurity
|
||||
subdomain: security-operations
|
||||
tags: [soar, splunk-phantom, phishing, incident-response]
|
||||
version: "1.0"
|
||||
author: mahipal
|
||||
license: Apache-2.0
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This skill implements a phishing incident response workflow using the Splunk SOAR (formerly Phantom) REST API. When a suspected phishing email is reported, the agent parses email headers and body, creates a SOAR container representing the incident, attaches artifacts containing indicators of compromise (sender address, URLs, IP addresses, file hashes), triggers an automated investigation playbook, and polls for action results.
|
||||
|
||||
Splunk SOAR orchestrates and automates security operations through playbooks that chain together investigative and response actions. The REST API at `/rest/container`, `/rest/artifact`, and `/rest/playbook_run` enables programmatic incident creation and automation triggering from external tools, email gateways, and SIEM alerts.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.9 or later with `requests` and `email` modules
|
||||
- Splunk SOAR instance (Cloud or On-Premises) with REST API access
|
||||
- SOAR API token with permissions to create containers and trigger playbooks
|
||||
- Network connectivity to SOAR instance on port 443
|
||||
- A configured phishing investigation playbook in SOAR
|
||||
|
||||
## Steps
|
||||
|
||||
1. **Parse the phishing email**: Read the email file (.eml format) and extract headers including From, To, Subject, Reply-To, Return-Path, Received, Message-ID, X-Mailer, and authentication results (SPF, DKIM, DMARC). Extract URLs and IP addresses from the email body.
|
||||
|
||||
2. **Authenticate to SOAR REST API**: Use the API token in the `ph-auth-token` header to authenticate all REST API requests to the SOAR instance.
|
||||
|
||||
3. **Create a container**: POST to `/rest/container` with the incident label, name, description, severity, and status. The container represents the phishing incident and receives a container ID in the response.
|
||||
|
||||
4. **Add email header artifacts**: POST to `/rest/artifact` with `container_id` and CEF (Common Event Format) fields containing sender address (`fromAddress`), recipient (`toAddress`), subject, originating IP (`sourceAddress`), and Message-ID. Set `run_automation` to False for all but the last artifact.
|
||||
|
||||
5. **Add URL artifacts**: For each URL extracted from the email body, create an artifact with CEF field `requestURL` and type `url`. These artifacts feed into URL reputation checks in the playbook.
|
||||
|
||||
6. **Trigger the playbook**: POST to `/rest/playbook_run` with the playbook ID or name and the container ID. This initiates the automated investigation workflow.
|
||||
|
||||
7. **Poll action results**: GET `/rest/action_run` filtered by container ID to monitor playbook progress. Poll until all actions reach a terminal state (success, failed, or cancelled).
|
||||
|
||||
8. **Compile response report**: Aggregate playbook action results into a summary report with verdicts from URL reputation, domain reputation, IP geolocation, and email header analysis.
|
||||
|
||||
## Expected Output
|
||||
|
||||
```json
|
||||
{
|
||||
"incident": {
|
||||
"container_id": 1542,
|
||||
"status": "new",
|
||||
"severity": "high",
|
||||
"artifacts_created": 5
|
||||
},
|
||||
"playbook": {
|
||||
"name": "phishing_investigate",
|
||||
"run_id": 892,
|
||||
"status": "success",
|
||||
"actions_completed": 8
|
||||
},
|
||||
"verdict": "malicious",
|
||||
"indicators": {
|
||||
"sender_domain_reputation": "malicious",
|
||||
"urls_flagged": 2,
|
||||
"spf_result": "fail",
|
||||
"dkim_result": "fail"
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,122 @@
|
||||
# SOAR Phishing Playbook API Reference
|
||||
|
||||
## Splunk SOAR REST API
|
||||
|
||||
### Authentication
|
||||
All requests require the `ph-auth-token` header:
|
||||
```
|
||||
ph-auth-token: <your-api-token>
|
||||
```
|
||||
|
||||
### Create Container (Incident)
|
||||
```
|
||||
POST /rest/container
|
||||
```
|
||||
```json
|
||||
{
|
||||
"name": "Phishing: Suspicious invoice email",
|
||||
"description": "User reported phishing email",
|
||||
"label": "phishing",
|
||||
"severity": "high",
|
||||
"status": "new",
|
||||
"sensitivity": "amber",
|
||||
"owner_id": 1,
|
||||
"tags": ["phishing", "email"]
|
||||
}
|
||||
```
|
||||
Response: `{"success": true, "id": 1542}`
|
||||
|
||||
### Create Artifact
|
||||
```
|
||||
POST /rest/artifact
|
||||
```
|
||||
```json
|
||||
{
|
||||
"container_id": 1542,
|
||||
"name": "Sender Email",
|
||||
"label": "email",
|
||||
"type": "email",
|
||||
"severity": "high",
|
||||
"cef": {
|
||||
"fromAddress": "attacker@evil.com",
|
||||
"toAddress": "victim@company.com",
|
||||
"emailSubject": "Urgent Invoice #9921",
|
||||
"sourceAddress": "198.51.100.23",
|
||||
"requestURL": "https://evil-phish.com/login"
|
||||
},
|
||||
"run_automation": true
|
||||
}
|
||||
```
|
||||
Response: `{"success": true, "id": 8834}`
|
||||
|
||||
### Trigger Playbook
|
||||
```
|
||||
POST /rest/playbook_run
|
||||
```
|
||||
```json
|
||||
{
|
||||
"container_id": 1542,
|
||||
"playbook_id": "local/phishing_investigate",
|
||||
"scope": "new",
|
||||
"run": true
|
||||
}
|
||||
```
|
||||
|
||||
### List Action Runs
|
||||
```
|
||||
GET /rest/action_run?_filter_container=1542&page_size=100
|
||||
```
|
||||
|
||||
### Get Container Details
|
||||
```
|
||||
GET /rest/container/{container_id}
|
||||
GET /rest/container/{container_id}/artifacts
|
||||
GET /rest/container/{container_id}/actions
|
||||
```
|
||||
|
||||
### Update Container Status
|
||||
```
|
||||
POST /rest/container/{container_id}
|
||||
```
|
||||
```json
|
||||
{"status": "closed", "close_reason": "resolved"}
|
||||
```
|
||||
|
||||
## XSOAR (Cortex XSOAR) API Comparison
|
||||
|
||||
### Create Incident
|
||||
```
|
||||
POST /incident
|
||||
```
|
||||
```json
|
||||
{
|
||||
"name": "Phishing Report",
|
||||
"type": "Phishing",
|
||||
"severity": 3,
|
||||
"labels": [
|
||||
{"type": "Email/from", "value": "attacker@evil.com"},
|
||||
{"type": "Email/subject", "value": "Urgent Invoice"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Run Playbook on Incident
|
||||
```
|
||||
POST /incident/investigate
|
||||
```
|
||||
```json
|
||||
{"id": "1542", "playbookId": "phishing_investigation"}
|
||||
```
|
||||
|
||||
## Common Phishing Playbook Actions
|
||||
|
||||
| Action | App | Description |
|
||||
|--------|-----|-------------|
|
||||
| `url reputation` | VirusTotal | Check URL against VT database |
|
||||
| `domain reputation` | VirusTotal | Check sender domain reputation |
|
||||
| `ip reputation` | AbuseIPDB | Check originating IP reputation |
|
||||
| `whois domain` | WHOIS | Domain registration lookup |
|
||||
| `detonate url` | URLScan.io | Sandbox URL detonation |
|
||||
| `get email headers` | IMAP | Retrieve full email headers |
|
||||
| `block sender` | Exchange | Block sender at email gateway |
|
||||
| `quarantine email` | O365 | Remove email from all mailboxes |
|
||||
@@ -0,0 +1,245 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Splunk SOAR phishing playbook automation via REST API."""
|
||||
|
||||
import argparse
|
||||
import email
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
import time
|
||||
|
||||
import requests
|
||||
from email import policy
|
||||
from email.parser import BytesParser
|
||||
|
||||
|
||||
URL_PATTERN = re.compile(r'https?://[^\s<>"\']+', re.IGNORECASE)
|
||||
IP_PATTERN = re.compile(r'\b(?:\d{1,3}\.){3}\d{1,3}\b')
|
||||
|
||||
|
||||
class SOARClient:
|
||||
def __init__(self, base_url: str, token: str, verify_ssl: bool = True):
|
||||
self.base_url = base_url.rstrip("/")
|
||||
self.session = requests.Session()
|
||||
self.session.headers.update({
|
||||
"ph-auth-token": token,
|
||||
"Content-Type": "application/json",
|
||||
})
|
||||
self.session.verify = verify_ssl
|
||||
|
||||
def create_container(self, name: str, description: str, severity: str,
|
||||
label: str = "events") -> dict:
|
||||
payload = {
|
||||
"name": name,
|
||||
"description": description,
|
||||
"severity": severity,
|
||||
"label": label,
|
||||
"status": "new",
|
||||
"sensitivity": "amber",
|
||||
}
|
||||
resp = self.session.post(f"{self.base_url}/rest/container", json=payload)
|
||||
resp.raise_for_status()
|
||||
data = resp.json()
|
||||
return {"container_id": data.get("id"), "success": data.get("success", False)}
|
||||
|
||||
def add_artifact(self, container_id: int, name: str, cef: dict,
|
||||
label: str = "event", severity: str = "medium",
|
||||
artifact_type: str = "network", run_automation: bool = False) -> dict:
|
||||
payload = {
|
||||
"container_id": container_id,
|
||||
"name": name,
|
||||
"label": label,
|
||||
"severity": severity,
|
||||
"type": artifact_type,
|
||||
"cef": cef,
|
||||
"run_automation": run_automation,
|
||||
}
|
||||
resp = self.session.post(f"{self.base_url}/rest/artifact", json=payload)
|
||||
resp.raise_for_status()
|
||||
data = resp.json()
|
||||
return {"artifact_id": data.get("id"), "success": data.get("success", False)}
|
||||
|
||||
def trigger_playbook(self, playbook_name: str, container_id: int,
|
||||
scope: str = "new") -> dict:
|
||||
payload = {
|
||||
"container_id": container_id,
|
||||
"playbook_id": playbook_name,
|
||||
"scope": scope,
|
||||
"run": True,
|
||||
}
|
||||
resp = self.session.post(f"{self.base_url}/rest/playbook_run", json=payload)
|
||||
resp.raise_for_status()
|
||||
return resp.json()
|
||||
|
||||
def get_action_runs(self, container_id: int) -> list:
|
||||
resp = self.session.get(
|
||||
f"{self.base_url}/rest/action_run",
|
||||
params={"_filter_container": container_id, "page_size": 100}
|
||||
)
|
||||
resp.raise_for_status()
|
||||
return resp.json().get("data", [])
|
||||
|
||||
def poll_playbook(self, container_id: int, timeout: int = 300,
|
||||
interval: int = 10) -> list:
|
||||
terminal_states = {"success", "failed", "cancelled"}
|
||||
elapsed = 0
|
||||
while elapsed < timeout:
|
||||
runs = self.get_action_runs(container_id)
|
||||
if runs and all(r.get("status") in terminal_states for r in runs):
|
||||
return runs
|
||||
time.sleep(interval)
|
||||
elapsed += interval
|
||||
return self.get_action_runs(container_id)
|
||||
|
||||
|
||||
def parse_email_file(email_path: str) -> dict:
|
||||
with open(email_path, "rb") as f:
|
||||
msg = BytesParser(policy=policy.default).parse(f)
|
||||
|
||||
headers = {
|
||||
"from": msg.get("From", ""),
|
||||
"to": msg.get("To", ""),
|
||||
"subject": msg.get("Subject", ""),
|
||||
"reply_to": msg.get("Reply-To", ""),
|
||||
"return_path": msg.get("Return-Path", ""),
|
||||
"message_id": msg.get("Message-ID", ""),
|
||||
"date": msg.get("Date", ""),
|
||||
"x_mailer": msg.get("X-Mailer", ""),
|
||||
}
|
||||
|
||||
received_headers = msg.get_all("Received", [])
|
||||
auth_results = msg.get("Authentication-Results", "")
|
||||
spf_result = "none"
|
||||
dkim_result = "none"
|
||||
dmarc_result = "none"
|
||||
if "spf=pass" in auth_results.lower():
|
||||
spf_result = "pass"
|
||||
elif "spf=fail" in auth_results.lower():
|
||||
spf_result = "fail"
|
||||
if "dkim=pass" in auth_results.lower():
|
||||
dkim_result = "pass"
|
||||
elif "dkim=fail" in auth_results.lower():
|
||||
dkim_result = "fail"
|
||||
if "dmarc=pass" in auth_results.lower():
|
||||
dmarc_result = "pass"
|
||||
elif "dmarc=fail" in auth_results.lower():
|
||||
dmarc_result = "fail"
|
||||
|
||||
body_text = ""
|
||||
if msg.is_multipart():
|
||||
for part in msg.walk():
|
||||
if part.get_content_type() == "text/plain":
|
||||
body_text += part.get_content()
|
||||
elif part.get_content_type() == "text/html":
|
||||
body_text += part.get_content()
|
||||
else:
|
||||
body_text = msg.get_content()
|
||||
|
||||
urls = list(set(URL_PATTERN.findall(body_text)))
|
||||
originating_ips = []
|
||||
for recv in received_headers:
|
||||
originating_ips.extend(IP_PATTERN.findall(recv))
|
||||
originating_ips = list(set(originating_ips))
|
||||
|
||||
return {
|
||||
"headers": headers,
|
||||
"received_count": len(received_headers),
|
||||
"auth": {"spf": spf_result, "dkim": dkim_result, "dmarc": dmarc_result},
|
||||
"urls": urls,
|
||||
"originating_ips": originating_ips,
|
||||
}
|
||||
|
||||
|
||||
def run_phishing_workflow(args) -> dict:
|
||||
email_data = parse_email_file(args.email_file)
|
||||
client = SOARClient(args.soar_url, args.token, verify_ssl=not args.no_verify)
|
||||
|
||||
sender = email_data["headers"]["from"]
|
||||
subject = email_data["headers"]["subject"]
|
||||
severity = "high" if email_data["auth"]["spf"] == "fail" else "medium"
|
||||
|
||||
container = client.create_container(
|
||||
name=f"Phishing Report: {subject[:80]}",
|
||||
description=f"Reported phishing email from {sender}",
|
||||
severity=severity,
|
||||
label="phishing",
|
||||
)
|
||||
cid = container["container_id"]
|
||||
|
||||
artifacts_created = 0
|
||||
client.add_artifact(cid, "Email Headers", {
|
||||
"fromAddress": sender,
|
||||
"toAddress": email_data["headers"]["to"],
|
||||
"emailSubject": subject,
|
||||
"emailMessageId": email_data["headers"]["message_id"],
|
||||
"emailReplyTo": email_data["headers"]["reply_to"],
|
||||
"emailReturnPath": email_data["headers"]["return_path"],
|
||||
}, label="email", artifact_type="email", severity=severity)
|
||||
artifacts_created += 1
|
||||
|
||||
for ip in email_data["originating_ips"]:
|
||||
client.add_artifact(cid, f"Originating IP: {ip}", {
|
||||
"sourceAddress": ip,
|
||||
}, label="email", artifact_type="ip", severity="medium")
|
||||
artifacts_created += 1
|
||||
|
||||
url_list = email_data["urls"]
|
||||
for i, url in enumerate(url_list):
|
||||
is_last = (i == len(url_list) - 1) and not args.playbook
|
||||
client.add_artifact(cid, f"Embedded URL: {url[:60]}", {
|
||||
"requestURL": url,
|
||||
}, label="email", artifact_type="url", severity="high",
|
||||
run_automation=is_last)
|
||||
artifacts_created += 1
|
||||
|
||||
playbook_result = None
|
||||
if args.playbook:
|
||||
playbook_result = client.trigger_playbook(args.playbook, cid)
|
||||
action_runs = client.poll_playbook(cid, timeout=args.poll_timeout)
|
||||
playbook_result["action_runs"] = len(action_runs)
|
||||
playbook_result["actions_completed"] = sum(
|
||||
1 for r in action_runs if r.get("status") == "success"
|
||||
)
|
||||
|
||||
return {
|
||||
"incident": {
|
||||
"container_id": cid,
|
||||
"status": "new",
|
||||
"severity": severity,
|
||||
"artifacts_created": artifacts_created,
|
||||
},
|
||||
"email_analysis": {
|
||||
"sender": sender,
|
||||
"subject": subject,
|
||||
"urls_found": len(url_list),
|
||||
"originating_ips": email_data["originating_ips"],
|
||||
"auth": email_data["auth"],
|
||||
},
|
||||
"playbook": playbook_result,
|
||||
}
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="SOAR Phishing Playbook Automation")
|
||||
parser.add_argument("--soar-url", required=True, help="Splunk SOAR base URL")
|
||||
parser.add_argument("--token", required=True, help="SOAR API auth token")
|
||||
parser.add_argument("--email-file", required=True, help="Path to .eml phishing email file")
|
||||
parser.add_argument("--playbook", default=None,
|
||||
help="Playbook name or ID to trigger")
|
||||
parser.add_argument("--poll-timeout", type=int, default=300,
|
||||
help="Max seconds to poll for playbook completion")
|
||||
parser.add_argument("--no-verify", action="store_true",
|
||||
help="Disable SSL certificate verification")
|
||||
parser.add_argument("--output", default=None, help="Output JSON file path")
|
||||
args = parser.parse_args()
|
||||
|
||||
result = run_phishing_workflow(args)
|
||||
report = json.dumps(result, indent=2)
|
||||
if args.output:
|
||||
with open(args.output, "w") as f:
|
||||
f.write(report)
|
||||
print(report)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user