Skip to content

Commit 574f772

Browse files
JosperdoJosperdo
committed
Add sentinel intergration
1 parent a0cfe56 commit 574f772

18 files changed

Lines changed: 1773 additions & 16 deletions

‎README.md‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -251,17 +251,26 @@ Pre-built dashboards are located in **dashboards/**:
251251

252252
---
253253

254-
## Future Enhancements
254+
## Azure Sentinel Integration
255255

256-
SOC Lab Docker is actively maintained with regular feature additions. The vision includes:
256+
Deploy the lab's detection library to Microsoft Sentinel — the leading enterprise cloud SIEM — using Terraform and ARM templates.
257257

258-
- **Enhanced Detection Library:** Expanded Sigma rules, multi-source correlation queries, advanced baselines
259-
- **Cloud Integration:** Deployment support for Azure Sentinel, AWS SecurityHub, GCP Security Command Center
260-
- **Alerting Framework:** Alert rule definitions, notification backends, response automation
261-
- **Advanced Scenarios:** APT-inspired campaigns, persistence mechanisms, ransomware simulation
262-
- **Team Training Mode:** Multi-tenant support for security team training exercises
258+
**What's included (`terraform/sentinel/`):**
263259

264-
See [docs/roadmap.md](docs/roadmap.md) for the capabilities roadmap and planned features.
260+
- **Terraform IaC** — Log Analytics Workspace + Sentinel onboarding, fully parameterized
261+
- **8 analytics rules** — All lab detections as `azurerm_sentinel_alert_rule_scheduled` resources with MITRE tactics, entity mappings, and tunable frequency/lookback
262+
- **3 SOAR playbooks** — ARM Logic App templates for Slack notification, ticket creation (ServiceNow/JIRA pattern), and host isolation
263+
- **Data connector guide** — Forward lab events via Filebeat → Azure Monitor for end-to-end pipeline experience
264+
265+
```bash
266+
cd terraform/sentinel
267+
terraform init
268+
terraform apply -var-file="terraform.tfvars"
269+
```
270+
271+
No live Azure subscription required to study or customize the templates. See [docs/SENTINEL_INTEGRATION.md](docs/SENTINEL_INTEGRATION.md) for the full deployment walkthrough.
272+
273+
See [docs/roadmap.md](docs/roadmap.md) for the full capabilities roadmap.
265274

266275
---
267276

‎docs/SENTINEL_INTEGRATION.md‎

Lines changed: 293 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,293 @@
1+
# Azure Sentinel Integration
2+
3+
This guide covers deploying SOC Lab Docker's detection library to Microsoft Sentinel — converting the lab's KQL queries into production-grade analytics rules, automating response with Logic App playbooks, and forwarding lab events for an end-to-end pipeline experience.
4+
5+
No live Azure subscription is required to study or customize the templates. A free Azure account is sufficient to deploy the full stack.
6+
7+
---
8+
9+
## Architecture
10+
11+
```
12+
┌─────────────────────────────────────────────────────────────────┐
13+
│ SOC Lab Docker (Local) │
14+
│ │
15+
│ ┌───────────────┐ ┌──────────────┐ ┌──────────────────┐ │
16+
│ │ Mock Log │───►│ Filebeat │───►│ Elasticsearch │ │
17+
│ │ Generator │ │ │ │ (localhost:9200) │ │
18+
│ └───────────────┘ └──────┬───────┘ └──────────────────┘ │
19+
│ │ │
20+
└──────────────────────────────┼──────────────────────────────────┘
21+
│ Azure Monitor Data Collector API
22+
│ (HTTPS, HMAC-SHA256 signed)
23+
▼
24+
┌─────────────────────────────────────────────────────────────────┐
25+
│ Microsoft Azure │
26+
│ │
27+
│ ┌─────────────────────────────────────────────────────────┐ │
28+
│ │ Log Analytics Workspace (soc_lab_CL) │ │
29+
│ └───────────────────────────┬─────────────────────────────┘ │
30+
│ │ │
31+
│ ┌───────────────────────────▼─────────────────────────────┐ │
32+
│ │ Microsoft Sentinel │ │
33+
│ │ │ │
34+
│ │ ┌─────────────────┐ ┌──────────────────────────────┐ │ │
35+
│ │ │ Analytics Rules │──►│ Incidents / Alerts │ │ │
36+
│ │ │ (8 lab rules) │ └──────────────┬───────────────┘ │ │
37+
│ │ └─────────────────┘ │ │ │
38+
│ │ │ Automation Rule │ │
39+
│ │ ┌────────────────────────────────────▼───────────────┐ │ │
40+
│ │ │ SOAR Playbooks (Logic Apps) │ │ │
41+
│ │ │ notify_slack │ create_ticket │ isolate_host │ │ │
42+
│ │ └────────────────────────────────────────────────────┘ │ │
43+
│ └─────────────────────────────────────────────────────────┘ │
44+
└─────────────────────────────────────────────────────────────────┘
45+
```
46+
47+
**Data flow:** Lab events → Filebeat → Azure Monitor Data Collector API → `soc_lab_CL` table → Sentinel analytics rules evaluate every 5–15 minutes → alerts fire → Logic App playbooks automate response actions.
48+
49+
---
50+
51+
## Prerequisites
52+
53+
### Tools
54+
55+
| Tool | Version | Install |
56+
|---|---|---|
57+
| Terraform CLI | >= 1.3.0 | https://developer.hashicorp.com/terraform/install |
58+
| Azure CLI | Latest | https://learn.microsoft.com/en-us/cli/azure/install-azure-cli |
59+
| Docker & Docker Compose | v20+ | (already installed for the lab) |
60+
61+
### Azure Account
62+
63+
A free Azure account includes:
64+
- 5 GB/day Log Analytics ingestion (free for 31 days, then billable — lab generates ~1 MB/day)
65+
- Microsoft Sentinel (first 10 GB/day free)
66+
- Logic Apps (pay-per-execution — idle playbooks cost nothing)
67+
68+
Create a free account at: https://azure.microsoft.com/free/
69+
70+
---
71+
72+
## Deployment Walkthrough
73+
74+
### Step 1 – Clone and enter the Terraform directory
75+
76+
```bash
77+
git clone https://github.com/Josperdo/soc-lab-docker.git
78+
cd soc-lab-docker/terraform/sentinel
79+
```
80+
81+
### Step 2 – Authenticate to Azure
82+
83+
```bash
84+
az login
85+
# Follow the browser prompt to complete authentication
86+
```
87+
88+
Verify the correct subscription is selected:
89+
90+
```bash
91+
az account show --query "{name:name, id:id}" -o table
92+
```
93+
94+
To switch subscriptions:
95+
96+
```bash
97+
az account set --subscription "YOUR-SUBSCRIPTION-ID"
98+
```
99+
100+
### Step 3 – Create terraform.tfvars
101+
102+
```bash
103+
cat > terraform.tfvars << 'EOF'
104+
subscription_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
105+
resource_group_name = "soc-lab-sentinel-rg"
106+
location = "eastus"
107+
workspace_name = "soc-lab-sentinel-workspace"
108+
retention_in_days = 90
109+
EOF
110+
```
111+
112+
Replace `subscription_id` with your actual subscription ID from `az account show`.
113+
114+
### Step 4 – Initialize Terraform
115+
116+
```bash
117+
terraform init
118+
```
119+
120+
Expected output:
121+
```
122+
Initializing the backend...
123+
Initializing provider plugins...
124+
- Finding hashicorp/azurerm versions matching "~> 3.0"...
125+
- Installing hashicorp/azurerm v3.x.x...
126+
Terraform has been successfully initialized!
127+
```
128+
129+
### Step 5 – Review the plan
130+
131+
```bash
132+
terraform plan -var-file="terraform.tfvars"
133+
```
134+
135+
The plan will show:
136+
- 1 resource group
137+
- 1 Log Analytics Workspace
138+
- 1 Sentinel onboarding
139+
- 8 scheduled analytics rules
140+
141+
### Step 6 – Apply
142+
143+
```bash
144+
terraform apply -var-file="terraform.tfvars"
145+
```
146+
147+
Type `yes` when prompted. Provisioning takes 2–5 minutes.
148+
149+
### Step 7 – Note the outputs
150+
151+
```bash
152+
terraform output workspace_customer_id # Workspace ID for data connector
153+
terraform output -raw primary_shared_key # Primary key for data connector
154+
```
155+
156+
Store these securely — you need them in the next step.
157+
158+
---
159+
160+
## Navigating Analytics Rules in the Sentinel UI
161+
162+
After `terraform apply` completes:
163+
164+
1. Open the [Azure portal](https://portal.azure.com)
165+
2. Search for **Microsoft Sentinel** and open it
166+
3. Select your workspace (`soc-lab-sentinel-workspace`)
167+
4. Navigate to **Configuration** → **Analytics**
168+
169+
You should see all 8 rules listed as "Active":
170+
171+
```
172+
┌──────────────────────────────────────────────────────────────────┐
173+
│ Analytics rules Active: 8│
174+
├──────────────────────────────────────────────────────────────────┤
175+
│ ✓ SOC Lab – Brute Force SSH Authentication High 5m/1h │
176+
│ ✓ SOC Lab – Account Lockout Spike Medium 15m/1h │
177+
│ ✓ SOC Lab – RDP Lateral Movement High 5m/1h │
178+
│ ✓ SOC Lab – PsExec Remote Execution Detected High 5m/1h │
179+
│ ✓ SOC Lab – WMI Remote Code Execution High 5m/1h │
180+
│ ✓ SOC Lab – Local Privilege Escalation to SYSTEM High 5m/1h │
181+
│ ✓ SOC Lab – Scheduled Task / Cron Persistence Medium 15m/24h │
182+
│ ✓ SOC Lab – Suspicious Outbound Data Transfer High 15m/1h │
183+
└──────────────────────────────────────────────────────────────────┘
184+
```
185+
186+
Click any rule to view its query, entity mappings, and MITRE technique tags.
187+
188+
---
189+
190+
## Enabling and Linking Playbooks to Analytics Rules
191+
192+
### Step 1 – Deploy a playbook
193+
194+
```bash
195+
az deployment group create \
196+
--resource-group soc-lab-sentinel-rg \
197+
--template-file playbooks/notify_slack/azuredeploy.json \
198+
--parameters @playbooks/notify_slack/parameters.json
199+
```
200+
201+
Edit `playbooks/notify_slack/parameters.json` first to substitute your Slack webhook URL.
202+
203+
### Step 2 – Create an automation rule
204+
205+
1. In Sentinel → **Automation** → **Automation rules** → **Create**
206+
2. **Name:** `Alert - Notify Slack`
207+
3. **Trigger:** When alert is created
208+
4. **Conditions:** (optional) Filter by rule name or severity
209+
5. **Actions:** Run playbook → select `soc-lab-notify-slack`
210+
6. **Save**
211+
212+
The playbook now fires automatically for every new Sentinel alert.
213+
214+
See [playbooks/README.md](../terraform/sentinel/playbooks/README.md) for deployment instructions for all three playbooks.
215+
216+
---
217+
218+
## Data Connector Setup (Event Forwarding)
219+
220+
To forward live lab events to Sentinel, configure the Filebeat → Azure Monitor output.
221+
222+
See [terraform/sentinel/data_connector/README.md](../terraform/sentinel/data_connector/README.md) for the full setup guide including field mapping notes and Logstash vs. direct HTTP options.
223+
224+
Quick summary:
225+
226+
```bash
227+
# Get credentials from Terraform outputs
228+
WORKSPACE_ID=$(terraform output -raw workspace_customer_id)
229+
PRIMARY_KEY=$(terraform output -raw primary_shared_key)
230+
231+
# Substitute into filebeat-azure-monitor.yml and restart Filebeat
232+
# See data_connector/README.md for signing details
233+
```
234+
235+
Verify in Sentinel → **Logs**:
236+
237+
```kql
238+
soc_lab_CL
239+
| take 10
240+
```
241+
242+
---
243+
244+
## Cost Guidance
245+
246+
| Resource | Free Tier | Lab Usage | Expected Cost |
247+
|---|---|---|---|
248+
| Log Analytics ingestion | 5 GB/day free (30 days) | ~1 MB/day | $0 |
249+
| Microsoft Sentinel | 10 GB/day free | <1 MB/day | $0 |
250+
| Logic Apps | ~4,000 runs/month free | Idle/low | $0 |
251+
| Storage (workspace) | Included | Minimal | $0 |
252+
253+
The lab generates approximately 1 MB of log data per day under normal operation. This is well within the free tier limits for both Log Analytics and Sentinel.
254+
255+
After the 31-day free trial, Log Analytics ingestion is billed at approximately $2.76/GB. At 1 MB/day, monthly cost remains under $0.10.
256+
257+
---
258+
259+
## Cleanup
260+
261+
To remove all Sentinel resources:
262+
263+
```bash
264+
terraform destroy -var-file="terraform.tfvars"
265+
```
266+
267+
Type `yes` when prompted. This deletes the resource group, workspace, Sentinel instance, and all analytics rules.
268+
269+
To also remove playbook Logic Apps (deployed separately via `az deployment group create`):
270+
271+
```bash
272+
az logicapp delete \
273+
--resource-group soc-lab-sentinel-rg \
274+
--name soc-lab-notify-slack
275+
276+
az logicapp delete \
277+
--resource-group soc-lab-sentinel-rg \
278+
--name soc-lab-create-ticket
279+
280+
az logicapp delete \
281+
--resource-group soc-lab-sentinel-rg \
282+
--name soc-lab-isolate-host
283+
```
284+
285+
---
286+
287+
## Further Reading
288+
289+
- [Microsoft Sentinel documentation](https://learn.microsoft.com/en-us/azure/sentinel/)
290+
- [AzureRM Sentinel provider](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/sentinel_alert_rule_scheduled)
291+
- [Azure Monitor Data Collector API](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/data-collector-api)
292+
- [Logic Apps documentation](https://learn.microsoft.com/en-us/azure/logic-apps/)
293+
- [MITRE ATT&CK](https://attack.mitre.org/)

‎docs/roadmap.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -115,17 +115,19 @@ The features described here represent the direction of development and community
115115

116116
---
117117

118-
### Cloud Deployment Support
118+
### Azure Sentinel Integration
119119

120-
**Description:** Easy deployment to major cloud platforms with feature parity to local Docker.
120+
**Description:** Reference Terraform templates and ARM playbook examples for deploying the lab's detection logic to Azure Sentinel — the leading enterprise cloud SIEM.
121121

122-
**Planned targets:**
122+
**Delivered (`terraform/sentinel/`):**
123123

124-
- **Azure:** Bicep/ARM templates, Azure Sentinel integration
125-
- **AWS:** CloudFormation, ECS/EKS support
126-
- **GCP:** Deployment Manager, GKE support
124+
- **Terraform IaC:** Log Analytics Workspace and Sentinel onboarding, fully parameterized — deploy with `terraform apply` against your own subscription
125+
- **8 analytics rules:** All lab detections converted to `azurerm_sentinel_alert_rule_scheduled` resources with MITRE tactics, entity mappings, and tunable frequency/lookback settings
126+
- **3 SOAR playbook templates:** ARM Logic App templates for Slack notification, ticket creation (ServiceNow/JIRA pattern), and host isolation — parameterized and deployable via `az deployment group create`
127+
- **Data connector guide:** How to forward lab events (Filebeat → Azure Monitor) for an end-to-end pipeline experience (`data_connector/`)
128+
- **Full documentation:** `docs/SENTINEL_INTEGRATION.md` — prerequisites, deployment walkthrough, Sentinel UI navigation, cost guidance, and cleanup
127129

128-
**Why it matters:** Learning cloud-native security, scalable environments for team training, cost optimization
130+
**Why it matters:** Azure Sentinel dominates enterprise cloud SIEM deployments. Writing detection-as-code in Terraform, structuring KQL analytics rules with entity mappings and MITRE techniques, and automating response with Logic Apps are high-signal skills for SOC and detection engineering roles. All templates are reference implementations — no live Azure subscription required to study or customize them.
129131

130132
---
131133

@@ -304,5 +306,5 @@ The team prioritizes features based on:
304306

305307
---
306308

307-
**Last Updated:** February 26, 2026
309+
**Last Updated:** February 27, 2026
308310
**Next Review:** Quarterly (community feedback incorporated)

0 commit comments

Comments
 (0)