AI SOC Analyst Agent

AI-assisted threat hunting platform built with Python, Azure Log Analytics, Microsoft Defender for Endpoint (MDE), and OpenAI.

This project demonstrates how Large Language Models (LLMs) can assist Security Operations Center (SOC) analysts by analyzing security telemetry, identifying suspicious activity, mapping findings to MITRE ATT&CK, and generating structured threat-hunting reports.

This project originated from an AI-assisted threat hunting exercise completed during a cybersecurity training program. The baseline implementation was subsequently refactored, documented, sanitized for public release, and enhanced with additional security guardrails, configuration controls, and operational safety improvements. All tenant information, infrastructure identifiers, credentials, IP addresses, and sensitive telemetry have been sanitized or redacted.

---

Project Overview

Security analysts often need to investigate large volumes of telemetry across multiple systems and data sources.

This project explores how an AI-powered SOC analyst can assist with:

• Interpreting natural-language investigation requests
• Selecting relevant telemetry sources
• Retrieving data from Azure Log Analytics
• Performing AI-assisted threat hunting
• Mapping findings to MITRE ATT&CK
• Generating structured investigation reports
• Supporting optional analyst-approved response actions

The goal is not to replace human analysts, but to accelerate investigations while maintaining human oversight and decision-making.

---

Architecture

High-Level Workflow

SOC Analyst Request
        │
        ▼
Determine Investigation Scope
        │
        ▼
Apply Security Guardrails
        │
        ▼
Query Azure Log Analytics
        │
        ▼
Collect Security Telemetry
        │
        ▼
Redact Sensitive Data
        │
        ▼
OpenAI Threat Analysis
        │
        ▼
MITRE ATT&CK Mapping
        │
        ▼
Threat Findings
        │
        ▼
Optional Human-Approved Remediation

Additional architecture and workflow diagrams can be found in the docs/ directory.

---

Features

AI-Assisted Threat Hunting

The agent can:

• Interpret analyst requests
• Select appropriate telemetry sources
• Retrieve Azure Log Analytics data
• Analyze logs using OpenAI
• Identify suspicious activity
• Extract indicators of compromise (IOCs)
• Map findings to MITRE ATT&CK
• Generate investigation recommendations

---

Supported Telemetry Sources

• DeviceLogonEvents
• DeviceProcessEvents
• DeviceNetworkEvents
• DeviceFileEvents
• AzureActivity
• SigninLogs
• AzureNetworkAnalytics_CL

---

Human-in-the-Loop Response Actions

Potential response actions require analyst approval before execution.

Examples include:

• Endpoint isolation
• Investigation pivoting
• Incident escalation recommendations

No remediation action occurs automatically.

---

🛡️ Security Enhancements & Refactoring

The original training implementation provided a working proof-of-concept.

This portfolio version was refactored to improve security, maintainability, configuration management, and operational safety.

Configuration Improvements

Original Implementation

• Direct credential references
• Limited GitHub publication safeguards

Portfolio Version

• Environment-variable support
• .env.example template
• Secret-safe repository structure
• Improved configuration hygiene

---

Additional Security Guardrails

Table Allowlists

Only approved telemetry sources may be queried.

Field Allowlists

Only approved fields may be returned from each telemetry source.

Model Allowlists

Only approved OpenAI models may be used.

Time Window Restrictions

Maximum lookback periods are enforced per telemetry source.

Examples:

Source	Maximum Lookback
DeviceProcessEvents	24 Hours
DeviceNetworkEvents	24 Hours
DeviceLogonEvents	96 Hours
AzureActivity	168 Hours
SigninLogs	168 Hours

Row Limiting

Large query results are automatically truncated before submission to the LLM.

Current limit:

500 rows

Benefits:

• Controls token consumption
• Improves response performance
• Reduces operational cost
• Prevents oversized prompts

Sensitive Data Redaction

Sensitive information is sanitized before logs are submitted to the LLM.

Current redaction includes:

• IP addresses
• Email addresses
• Azure GUIDs

Guardrail Reporting

The platform displays active security controls applied during each investigation, including:

• Time-window enforcement
• Row truncation status
• PII redaction status

Human Approval Requirements

Potential remediation actions require explicit analyst confirmation before execution.

---

🚨 Screenshots

Investigation Initialization

Shows investigation scope selection, telemetry source selection, and Azure Log Analytics query execution.

Model Validation & Cost Estimation

Demonstrates model selection, token estimation, and validation controls.

Threat Hunting Results

Threat #1 – Credential Stuffing Activity

Threat #2 – Suspicious Root Logins

Threat #3 – Service Account Credential Probing

Threat #4 – SSH Enumeration Activity

Optional Endpoint Isolation

Illustrates analyst-approved endpoint containment.

---

Repository Structure

ai-soc-analyst-agent/
│
├── data/
│   └── sample_device_logon_events.csv
│
├── docs/
│   ├── baseline_agent_workflow.jpg
│   ├── defining_guardrails.md
│   ├── network_guardrails.jpg
│   └── prompt_engineering_diagram.jpg
│
├── output/
│   └── .gitkeep
│
├── screenshots/
│
├── src/
│   ├── executor.py
│   ├── guardrails.py
│   ├── keys.py
│   ├── main.py
│   ├── model_management.py
│   ├── prompt_management.py
│   └── utilities.py
│
├── .env.example
├── .gitignore
├── README.md
└── requirements.txt

---

Additional Documentation

The /docs folder contains supporting material used during development and refactoring:

Document	Description
Defining Guardrails	Security controls, validation mechanisms, and AI safety considerations
Prompt Engineering Diagram	Prompt construction and workflow visualization
Network Guardrails	High-level overview of the network environment
Baseline Agent Workflow	Original workflow used as the foundation for the project

---

Configuration

Create a local .env file based on .env.example.

Example:

OPENAI_API_KEY=your_openai_api_key_here

AZURE_WORKSPACE_ID=your_workspace_id_here

AZURE_TENANT_ID=your_tenant_id_here

AZURE_CLIENT_ID=your_client_id_here

AZURE_CLIENT_SECRET=your_client_secret_here

The .env file is excluded from source control and should never be committed to Git.

---

Technologies Used

• Python
• Azure Log Analytics
• Microsoft Defender for Endpoint (MDE)
• Azure Identity
• Kusto Query Language (KQL)
• OpenAI API
• MITRE ATT&CK Framework

---

🎓 Lessons Learned

This project provided practical experience with:

• Threat hunting workflows
• Azure security telemetry
• KQL query development
• Prompt engineering
• AI security guardrails
• Security automation
• MITRE ATT&CK mapping
• Human-in-the-loop response workflows

One of the key lessons learned was that AI-assisted security tooling requires strong guardrails, validation controls, and analyst oversight to remain effective and trustworthy.

---

Future Enhancements

Potential future improvements include:

• Threat intelligence enrichment
• IOC reputation lookups
• Investigation timeline reconstruction
• Multi-agent orchestration

---

⚠️ Disclaimer

This project is intended for educational and portfolio purposes.

Screenshots were captured from a controlled cybersecurity training environment. All tenant information, infrastructure identifiers, credentials, IP addresses, and sensitive telemetry have been sanitized or redacted.

No production systems were accessed during development.

---

📬 Contact

My Blog post: Happy Bytes

Feel free to connect on LinkedIn or review my other security projects.

Feedback and discussion are welcome. Thank you for reviewing this project.