Microsoft Security Integration Guide

Overview

The Microsoft Security integration allows your NINA workflows to seamlessly connect with Microsoft Graph Security API for comprehensive security operations management. This integration enables you to manage security alerts, incidents, threat indicators, and security actions directly from your workflows, providing a unified approach to Microsoft 365 security operations.

Status

We currently support comprehensive operations across Microsoft Security resources:

• Alert Management: Retrieve, update, and manage security alerts with filtering and comments
• Incident Management: Handle security incidents with status updates and tracking
• Threat Intelligence: Create, update, and manage threat indicators for IOC sharing
• Security Actions: Automate security responses and track remediation actions
• Advanced Filtering: Leverage OData queries for precise data retrieval

Some of the main capabilities include:

• Unified Security Operations: Centralized management of Microsoft 365 security events
• Alert Lifecycle Management: Track alerts from detection through resolution
• Incident Response: Coordinate incident response with assignment and status tracking
• Threat Intelligence Integration: Share and manage IOCs across security platforms
• Automated Response: Create and manage security actions for automated remediation
• Rich Filtering: Use OData query syntax for advanced filtering and sorting

Credential Configuration

Before using the Microsoft Security integration in your workflows, you need to configure OAuth2 credentials through Microsoft Azure App Registration. The integration uses OAuth2 authentication to securely connect to Microsoft Graph Security API.

Authentication Method

OAuth2 Authentication

For connecting to Microsoft Graph Security API:

Field	Description	Example
Client ID	Application (client) ID from Azure App Registration	12345678-1234-1234-1234-123456789abc
Client Secret	Client secret value from Azure App Registration	abcd1234-efgh-5678-ijkl-9012mnop3456
Tenant ID	Directory (tenant) ID from Azure App Registration	87654321-4321-4321-4321-fedcba987654
Scope	Required permissions scope	https://graph.microsoft.com/.default

How to create Azure App Registration:

1. Sign in to the Azure portal
2. Navigate to Azure Active Directory > App registrations
3. Click New registration
4. Provide a name (e.g., "NINA Security Integration")
5. Select Accounts in this organizational directory only
6. Click Register
7. Note the Application (client) ID and Directory (tenant) ID
8. Go to Certificates & secrets > Client secrets > New client secret
9. Add a description and expiration, then click Add
10. Copy the Value (this is your client secret)

Required API Permissions:

• SecurityEvents.Read.All
• SecurityEvents.ReadWrite.All
• SecurityAlert.Read.All
• SecurityAlert.ReadWrite.All
• SecurityIncident.Read.All
• SecurityIncident.ReadWrite.All
• ThreatIndicators.ReadWrite.OwnedBy

Creating a Microsoft Security Credential

1. Navigate to the Credentials section in NINA

2. Click Add New Credential

3. Fill in the credential details:

   • Name: A descriptive name (e.g., "Microsoft Security Production")
   • Description: Optional details about the credential's purpose
   • Integration Service: Select "Microsoft Security"
   • Auth Type: Select "OAuth2"
   • Client ID: Enter your Azure App Registration client ID
   • Client Secret: Enter your client secret value
   • Tenant ID: Enter your Azure tenant ID
   • Scope: Enter https://graph.microsoft.com/.default

4. Click Test Connection to verify credentials and complete OAuth flow

5. Click Save to store the credential

Supported Resources and Operations

The Microsoft Security integration supports the following resources and operations:

Alert

Operation	Description
Get All Alerts	Retrieves security alerts with filtering and pagination
Get Alert	Retrieves details of a specific alert by ID
Update Alert	Updates alert status, assignment, classification, and determination
Create Comment	Adds comments to alerts for collaboration
Get Evidence	Retrieves evidence associated with an alert

Incident

Operation	Description
Get All Incidents	Retrieves security incidents with filtering options
Get Incident	Retrieves details of a specific incident by ID
Update Incident	Updates incident status, assignment, and metadata
Create Comment	Adds comments to incidents for tracking

Security Actions

Operation	Description
List Security Actions	Retrieves security actions with filtering
Get Security Action	Retrieves details of a specific security action
Create Security Action	Creates new automated security actions
Cancel Security Action	Cancels in-progress security actions

Threat Indicators

Operation	Description
Get Threat Indicator	Retrieves a specific threat intelligence indicator
List Threat Indicators	Lists threat indicators with filtering
Create Threat Indicator	Creates new IOC indicators
Update Threat Indicator	Updates existing threat indicators
Delete Threat Indicator	Removes threat indicators

Parameter Merging and Templating

The Microsoft Security integration takes full advantage of NINA's parameter merging and templating capabilities:

Parameter Sources (in order of precedence)

1. Node Parameters: Parameters configured directly in the Microsoft Security Integration Node
2. Extracted Parameters: Parameters automatically extracted from the input data
3. Input Data: The complete input data from upstream nodes

When a Microsoft Security Integration Node executes:

• It combines parameters from all sources
• Node parameters take precedence over extracted parameters
• Template variables within parameters are processed (using {{variable_name}} syntax)
• The combined parameters are used to execute the Microsoft Security operation

Example: Managing Security Alerts

Retrieving Security Alerts

Below is an example of retrieving security alerts with filtering:

Node Configuration:

{
  "integration_service": "microsoft-security",
  "resource": "alert",
  "operation": "getAll",
  "parameters": {
    "returnAll": false,
    "limit": 100,
    "filter": {
      "filterString": "severity eq 'high' and status eq 'new'",
      "orderBy": "createdDateTime desc",
      "select": "id,title,severity,status,createdDateTime,assignedTo"
    }
  }
}

Getting Specific Alert Details

Node Configuration:

{
  "integration_service": "microsoft-security",
  "resource": "alert",
  "operation": "get",
  "parameters": {
    "alertId": "{{alert_id}}",
    "additionalFields": {
      "select": "id,title,description,severity,status,evidence,detectionSource"
    }
  }
}

Updating Alert Status

Input Data from Previous Node:

{
  "alert_id": "12345678-1234-5678-9abc-123456789def",
  "analyst": "[email protected]",
  "investigation_status": "completed",
  "verdict": "true_positive"
}

Node Configuration with Template Variables:

{
  "integration_service": "microsoft-security",
  "resource": "alert",
  "operation": "update",
  "parameters": {
    "alertId": "{{alert_id}}",
    "updateFields": {
      "status": "{{#if (eq investigation_status 'completed')}}resolved{{else}}inProgress{{/if}}",
      "assignedTo": "{{analyst}}",
      "classification": "{{#if (eq verdict 'true_positive')}}truePositive{{else}}falsePositive{{/if}}",
      "determination": "{{#if (eq verdict 'true_positive')}}malware{{else}}securityTest{{/if}}"
    }
  }
}

Example: Incident Management

Retrieving Security Incidents

Node Configuration:

{
  "integration_service": "microsoft-security",
  "resource": "incident",
  "operation": "getAll",
  "parameters": {
    "returnAll": false,
    "limit": 50,
    "filter": {
      "filterString": "status eq 'active' and severity eq 'high'",
      "orderBy": "createdDateTime desc"
    }
  }
}

Updating Incident Status

Input Data:

{
  "incident_id": "inc_12345",
  "assigned_analyst": "[email protected]",
  "incident_status": "investigating",
  "priority": "high",
  "tags": ["phishing", "email-attack", "user-reported"]
}

Node Configuration:

{
  "integration_service": "microsoft-security",
  "resource": "incident",
  "operation": "update",
  "parameters": {
    "incidentId": "{{incident_id}}",
    "updateFields": {
      "status": "{{incident_status}}",
      "assignedTo": "{{assigned_analyst}}",
      "severity": "{{priority}}",
      "tags": "{{tags}}"
    }
  }
}

Example: Threat Intelligence Management

Creating Threat Indicators

Node Configuration:

{
  "integration_service": "microsoft-security",
  "resource": "threat-indicators",
  "operation": "create",
  "parameters": {
    "action": "block",
    "description": "Malicious domain identified in APT campaign",
    "expirationDateTime": "2024-12-31T23:59:59Z",
    "targetProduct": "Azure Sentinel",
    "threatType": "Malware",
    "tlpLevel": "amber",
    "confidence": 85,
    "severity": 75,
    "domainName": "malicious-domain.com",
    "tags": ["APT", "command-control", "phishing"],
    "activityGroupNames": ["APT29"],
    "additionalInformation": "Domain used for C2 communication in recent campaign"
  }
}

Creating File Hash Indicators

Input Data:

{
  "malware_analysis": {
    "hash": "5d41402abc4b2a76b9719d911017c592",
    "hash_type": "md5",
    "family": "TrickBot",
    "confidence": 95
  },
  "campaign_info": {
    "name": "TrickBot Campaign 2024",
    "threat_actors": ["TA505"],
    "ttps": ["T1055", "T1082"]
  }
}

Node Configuration:

{
  "integration_service": "microsoft-security",
  "resource": "threat-indicators",
  "operation": "create",
  "parameters": {
    "action": "block",
    "description": "{{campaign_info.name}} - {{malware_analysis.family}} malware hash",
    "expirationDateTime": "2024-12-31T23:59:59Z",
    "targetProduct": "Microsoft Defender ATP",
    "threatType": "Malware",
    "tlpLevel": "amber",
    "confidence": "{{malware_analysis.confidence}}",
    "severity": 90,
    "fileHashType": "{{malware_analysis.hash_type}}",
    "fileHashValue": "{{malware_analysis.hash}}",
    "malwareFamilyNames": ["{{malware_analysis.family}}"],
    "activityGroupNames": "{{campaign_info.threat_actors}}",
    "killChain": "{{campaign_info.ttps}}"
  }
}

Example: Security Actions

Creating Security Actions

Node Configuration:

{
  "integration_service": "microsoft-security",
  "resource": "security-actions",
  "operation": "create",
  "parameters": {
    "name": "Block malicious IP",
    "actionType": "block",
    "vendor": "Microsoft",
    "user": "[email protected]",
    "parameters": {
      "ipAddress": "{{malicious_ip}}",
      "blockDuration": "24h",
      "reason": "IOC detected in threat intelligence feed"
    }
  }
}

Listing Security Actions

Node Configuration:

{
  "integration_service": "microsoft-security",
  "resource": "security-actions",
  "operation": "list",
  "parameters": {
    "returnAll": false,
    "limit": 50,
    "filter": {
      "filterString": "status eq 'InProgress'",
      "orderBy": "createdDateTime desc"
    }
  }
}

Advanced Filtering with OData

Complex Alert Filtering

Node Configuration:

{
  "integration_service": "microsoft-security",
  "resource": "alert",
  "operation": "getAll",
  "parameters": {
    "filter": {
      "filterString": "severity eq 'high' and (category eq 'Malware' or category eq 'SuspiciousActivity') and createdDateTime ge 2024-01-01T00:00:00Z",
      "select": "id,title,severity,category,detectionSource,affectedResources",
      "orderBy": "createdDateTime desc"
    },
    "limit": 200
  }
}

Incident Filtering by Timeline

Input Data:

{
  "time_range": {
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-31T23:59:59Z"
  },
  "severity_levels": ["high", "medium"],
  "status_filter": ["active", "inProgress"]
}

Node Configuration:

{
  "integration_service": "microsoft-security",
  "resource": "incident",
  "operation": "getAll",
  "parameters": {
    "filter": {
      "filterString": "createdDateTime ge {{time_range.start}} and createdDateTime le {{time_range.end}} and severity in ('{{join severity_levels \"','\"}}')",
      "orderBy": "severity desc, createdDateTime desc"
    }
  }
}

Alert and Incident Status Values

Alert Status Options

• new: Newly detected alert requiring attention
• inProgress: Alert is being investigated
• resolved: Alert investigation completed

Alert Classification Options

• unknown: Classification not yet determined
• falsePositive: Alert determined to be false positive
• truePositive: Alert confirmed as genuine security event

Alert Determination Options

• unknown: Determination not yet made
• apt: Advanced Persistent Threat activity
• malware: Malware-related activity
• securityPersonnel: Activity by security personnel
• securityTesting: Security testing or authorized activity
• unwantedSoftware: Unwanted software detection
• other: Other determined cause

Incident Status Options

• active: Incident is active and requires attention
• inProgress: Incident investigation in progress
• resolved: Incident resolved and closed

Threat Indicator Options

Action Types

• unknown: Unknown action
• allow: Allow the indicator
• block: Block the indicator
• alert: Generate alert on indicator match

TLP (Traffic Light Protocol) Levels

• white: No restrictions on sharing
• green: Limited sharing within community
• amber: Limited sharing with named recipients
• red: No sharing beyond immediate recipients

Target Products

• Azure Sentinel: Microsoft Sentinel SIEM
• Microsoft Defender ATP: Microsoft Defender for Endpoint
• Microsoft Cloud App Security: Microsoft Defender for Cloud Apps

File Hash Types

• sha256: SHA-256 hash
• sha1: SHA-1 hash
• md5: MD5 hash

Troubleshooting

Issue	Resolution
OAuth authentication failures	Verify client ID, client secret, and tenant ID are correct. Ensure proper API permissions are granted and admin consent is provided.
"Forbidden" or permission errors	Check that the Azure app has the required Graph API permissions and that admin consent has been granted. Review the specific permissions needed for each operation.
"Not Found" errors for alerts/incidents	Verify the ID exists and the account has access. Some resources may be scoped to specific security products or tenants.
OData filter syntax errors	Use proper OData syntax. Common operators include 'eq', 'ne', 'gt', 'lt', 'and', 'or'. String values must be quoted.
Token expiration issues	The integration automatically handles token refresh. If issues persist, recreate the credential to get fresh tokens.
Rate limiting errors	Microsoft Graph has rate limits. Implement delays between requests or reduce the frequency of API calls.
Date format errors	Use ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ) for all datetime fields.
Threat indicator validation errors	Ensure required fields are provided and values match expected formats (e.g., valid IP addresses, hash formats).

Best Practices

1. Use Proper OAuth Scopes: Request only the minimum required permissions for your use case to follow the principle of least privilege.

2. Implement Efficient Filtering: Use OData filters to reduce API calls and improve performance. Filter at the API level rather than in your workflow.

3. Leverage Template Variables: Use {{variable_name}} syntax to dynamically insert values from upstream nodes for flexible workflows.

4. Handle Rate Limits: Implement proper delays and retry logic to handle Microsoft Graph API rate limits gracefully.

5. Monitor Token Expiration: While the integration handles token refresh automatically, monitor for authentication errors and be prepared to recreate credentials if needed.

6. Use Structured Comments: When adding comments to alerts and incidents, use consistent formatting to improve readability and searchability.

7. Implement Status Workflows: Create systematic workflows for moving alerts and incidents through their lifecycle states.

8. Validate Threat Indicators: Ensure IOC data is properly formatted and validated before creating threat indicators to avoid API errors.

9. Use Appropriate TLP Levels: Apply proper Traffic Light Protocol levels to threat indicators based on your sharing policies.

10. Batch Operations: When possible, use filtering to retrieve multiple items in a single API call rather than making individual requests.

11. Monitor Security Actions: Regularly check the status of security actions to ensure they complete successfully and handle failures appropriately.

12. Implement Error Handling: Build robust error handling for API failures, especially for critical security operations.

13. Use Consistent Naming: Apply consistent naming conventions for security actions and threat indicators to improve organization.

14. Regular Cleanup: Implement processes to remove or update expired threat indicators and completed security actions.

15. Audit and Logging: Maintain logs of security operations performed through the integration for compliance and audit purposes.