microsoft-security-skills-plugin

Skill by ara.so — Security Skills collection.

What this project does

The Microsoft Security Skills Plugin is a curated collection of 56 security expertise modules that teach AI coding agents how to provide accurate, opinionated Microsoft Security guidance. Instead of generic security advice, agents gain decision trees, workflows, and guardrails grounded in Microsoft Learn documentation across:

• Threat protection & SecOps: Defender XDR, Sentinel, Security Copilot, unified SecOps platform
• Identity & access: Entra ID, Conditional Access, PIM, ID Protection, Permissions Management
• Compliance & data protection: Purview DLP, eDiscovery, audit, data classification, Priva
• Endpoint & device: Intune device management, app protection, BitLocker, PAW design
• Cloud platform security: Azure Policy, Key Vault, network security, App Service, API security

Each skill packages Microsoft Learn knowledge into actionable guidance that compatible agents (GitHub Copilot, Claude Code, Cursor, Codex CLI, Gemini CLI) can apply during conversations.

Installation

Prerequisites

Verify you have Git and Node.js 18+ installed:

git --version
npx --version

APM (recommended - all hosts at once)

Install across GitHub Copilot, Claude Code, Cursor, OpenCode, Codex, and Gemini with one command:

apm install vinayaklatthe/microsoft-security-skills

Universal install (manual clone)

Clone the repository and configure your agent to read from the skills/ directory:

git clone https://github.com/vinayaklatthe/microsoft-security-skills.git
cd microsoft-security-skills

Then point your agent configuration to the skills/ directory.

Host-specific install with npx skills

Install globally for a specific agent host:

# GitHub Copilot (VS Code, Copilot CLI)
npx skills add https://github.com/vinayaklatthe/microsoft-security-skills/tree/main/skills -a github-copilot -g -y

# Claude Code
npx skills add https://github.com/vinayaklatthe/microsoft-security-skills/tree/main/skills -a claude -g -y

# Cursor
npx skills add https://github.com/vinayaklatthe/microsoft-security-skills/tree/main/skills -a cursor -g -y

# Codex CLI
npx skills add https://github.com/vinayaklatthe/microsoft-security-skills/tree/main/skills -a codex -g -y

Gemini CLI

gemini extensions install https://github.com/vinayaklatthe/microsoft-security-skills

Verifying installation

After installation, test the agent's access to skills with three quick prompts:

1. Test security skills

What Microsoft Defender controls should I prioritise for a new Microsoft 365 tenant?

Expected: Structured, product-specific guidance with Microsoft Learn references.

2. Test identity skills

How do I design a Conditional Access policy baseline for a mid-size organisation?

Expected: Policy framework with named Conditional Access templates and guardrails.

3. Test compliance skills

What Purview DLP policies should I configure to protect sensitive data in Microsoft 365?

Expected: Scoped DLP guidance with workload-specific recommendations.

How to use skills in conversations

Once installed, the agent automatically scans skill front matter (name, description, WHEN: triggers) during conversations. Simply ask natural questions:

Design a Sentinel workspace for my SOC

Help me build a Conditional Access policy for contractors

What Defender for Cloud hardening steps should I take first?

Review my Intune device compliance policy for security gaps

The agent loads the most relevant skill (e.g., sentinel.md, conditional-access-mfa.md, defender-for-cloud-hardening.md, intune-device-mgmt.md) and follows its decision trees and guardrails.

Skill selection reference

Use this table to choose the right skill before asking:

Repository structure

microsoft-security-skills/
├── skills/                     # 56 skill definitions
│   ├── defender-xdr/
│   │   └── SKILL.md
│   ├── sentinel/
│   │   └── SKILL.md
│   ├── entra-id/
│   │   └── SKILL.md
│   ├── conditional-access-mfa/
│   │   └── SKILL.md
│   ├── purview-dlp-policy/
│   │   └── SKILL.md
│   ├── intune-device-mgmt/
│   │   └── SKILL.md
│   └── ...
├── plugin.json                 # Plugin metadata
├── validation/                 # Validation harness
└── README.md

Example: Using a skill in code generation

Scenario: Generate a Conditional Access policy in JavaScript

Ask your agent:

Generate a Conditional Access policy JSON for blocking legacy authentication across all cloud apps

The agent loads conditional-access-mfa skill and produces:

// Conditional Access policy: Block legacy authentication
// Reference: https://learn.microsoft.com/entra/identity/conditional-access/

const blockLegacyAuthPolicy = {
  displayName: "Block Legacy Authentication - All Cloud Apps",
  state: "enabledForReportingButNotEnforced", // Start in report-only mode
  conditions: {
    users: {
      includeUsers: ["All"]
    },
    applications: {
      includeApplications: ["All"]
    },
    clientAppTypes: [
      "exchangeActiveSync",
      "other" // Covers POP, IMAP, SMTP AUTH, older Office clients
    ]
  },
  grantControls: {
    operator: "OR",
    builtInControls: ["block"]
  }
};

// Deploy with Microsoft Graph API
const deployPolicy = async (accessToken) => {
  const response = await fetch(
    "https://graph.microsoft.com/v1.0/identity/conditionalAccess/policies",
    {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${accessToken}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(blockLegacyAuthPolicy)
    }
  );
  
  if (!response.ok) {
    throw new Error(`Policy deployment failed: ${response.statusText}`);
  }
  
  return await response.json();
};

// Usage
// 1. Start in report-only mode (state: "enabledForReportingButNotEnforced")
// 2. Monitor sign-in logs for 2-4 weeks
// 3. Remediate users still using legacy protocols
// 4. Change state to "enabled" after validation

Scenario: Query Sentinel with KQL for identity threats

Ask your agent:

Write a KQL query to detect potential Entra ID token theft from Sentinel logs

The agent loads sentinel skill and produces:

// Sentinel KQL: Detect potential Entra ID token theft
// Trigger: Multiple sign-ins from different geolocations within 15 minutes
// Reference: https://learn.microsoft.com/azure/sentinel/

const tokenTheftQuery = `
SigninLogs
| where TimeGenerated > ago(24h)
| where ResultType == "0" // Successful sign-ins only
| extend GeoLocation = strcat(Location.city, ", ", Location.countryOrRegion)
| summarize 
    Locations = make_set(GeoLocation),
    LocationCount = dcount(GeoLocation),
    IPAddresses = make_set(IPAddress)
  by UserPrincipalName, bin(TimeGenerated, 15m)
| where LocationCount > 1 // Multiple locations in same 15-min window
| project 
    TimeGenerated, 
    UserPrincipalName, 
    LocationCount, 
    Locations, 
    IPAddresses
| order by TimeGenerated desc
`;

// Export as Sentinel analytic rule (JavaScript SDK example)
const { SecretClient } = require("@azure/keyvault-secrets");
const { DefaultAzureCredential } = require("@azure/identity");

const deployAnalyticRule = async () => {
  const credential = new DefaultAzureCredential();
  const subscriptionId = process.env.AZURE_SUBSCRIPTION_ID;
  const resourceGroup = process.env.AZURE_RESOURCE_GROUP;
  const workspaceName = process.env.SENTINEL_WORKSPACE_NAME;
  
  const rule = {
    displayName: "Potential Entra ID Token Theft - Impossible Travel",
    description: "Detects successful sign-ins from multiple geolocations within 15 minutes, indicating potential token theft or session hijacking",
    severity: "High",
    enabled: true,
    query: tokenTheftQuery,
    queryFrequency: "PT1H", // Run every hour
    queryPeriod: "P1D", // Look back 1 day
    triggerOperator: "GreaterThan",
    triggerThreshold: 0,
    suppressionDuration: "PT1H",
    suppressionEnabled: false,
    tactics: ["CredentialAccess", "InitialAccess"],
    techniques: ["T1528", "T1539"] // MITRE ATT&CK
  };
  
  const url = `https://management.azure.com/subscriptions/${subscriptionId}/resourceGroups/${resourceGroup}/providers/Microsoft.OperationalInsights/workspaces/${workspaceName}/providers/Microsoft.SecurityInsights/alertRules/token-theft-rule-001?api-version=2023-02-01`;
  
  const accessToken = await credential.getToken("https://management.azure.com/.default");
  
  const response = await fetch(url, {
    method: "PUT",
    headers: {
      "Authorization": `Bearer ${accessToken.token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      kind: "Scheduled",
      properties: rule
    })
  });
  
  if (!response.ok) {
    throw new Error(`Rule deployment failed: ${response.statusText}`);
  }
  
  return await response.json();
};

// Deploy the rule
deployAnalyticRule().catch(console.error);

Configuration

Multi-host compatibility

The plugin works across:

• GitHub Copilot (VS Code, Copilot CLI)
• Claude Code
• Cursor
• Codex CLI
• Gemini CLI
• OpenCode

No per-host configuration required after installation.

Custom skill directories

If you clone the repo, point your agent to the skills/ directory:

# Example: VS Code settings.json for GitHub Copilot
{
  "github.copilot.advanced": {
    "customSkillsPath": "/path/to/microsoft-security-skills/skills"
  }
}

Environment variables for examples

When running code examples that interact with Microsoft APIs:

export AZURE_TENANT_ID="your-tenant-id"
export AZURE_CLIENT_ID="your-client-id"
export AZURE_CLIENT_SECRET="your-client-secret"
export AZURE_SUBSCRIPTION_ID="your-subscription-id"
export AZURE_RESOURCE_GROUP="your-resource-group"
export SENTINEL_WORKSPACE_NAME="your-sentinel-workspace"

Use Azure Key Vault for production secrets:

const { SecretClient } = require("@azure/keyvault-secrets");
const { DefaultAzureCredential } = require("@azure/identity");

const credential = new DefaultAzureCredential();
const vaultUrl = `https://${process.env.KEY_VAULT_NAME}.vault.azure.net`;
const client = new SecretClient(vaultUrl, credential);

const secret = await client.getSecret("client-secret");

Common patterns

Pattern 1: Skill-guided policy creation

// 1. Ask agent: "Design a Purview DLP policy for financial data"
// 2. Agent loads purview-dlp-policy skill
// 3. Agent returns policy JSON with guardrails

const dlpPolicy = {
  name: "Block External Sharing - Financial Data",
  locations: [
    { location: "ExchangeOnline" },
    { location: "SharePointOnline" },
    { location: "OneDriveForBusiness" },
    { location: "TeamsChat" }
  ],
  rules: [
    {
      name: "Detect Financial Information",
      conditions: {
        contentContainsSensitiveInformation: [
          { name: "Credit Card Number", minCount: 1 },
          { name: "U.S. Bank Account Number", minCount: 1 },
          { name: "International Banking Account Number (IBAN)", minCount: 1 }
        ]
      },
      actions: {
        blockAccess: true,
        notifyUser: true,
        incidentReport: true
      }
    }
  ]
};

// Deploy with Purview API or PowerShell

Pattern 2: Security assessment automation

// Ask: "What Defender for Cloud recommendations should I prioritize?"
// Agent loads defender-for-cloud-hardening skill

const assessSecureScore = async (credential, subscriptionId) => {
  const url = `https://management.azure.com/subscriptions/${subscriptionId}/providers/Microsoft.Security/secureScores/ascScore?api-version=2020-01-01`;
  
  const token = await credential.getToken("https://management.azure.com/.default");
  const response = await fetch(url, {
    headers: { "Authorization": `Bearer ${token.token}` }
  });
  
  const data = await response.json();
  
  // Prioritize by score impact
  const recommendations = data.properties.recommendations
    .filter(r => r.weight > 0)
    .sort((a, b) => b.weight - a.weight)
    .slice(0, 10);
  
  return recommendations.map(r => ({
    name: r.displayName,
    severity: r.severity,
    scoreImpact: r.weight,
    remediationSteps: r.remediationDescription
  }));
};

Pattern 3: Incident investigation workflow

// Ask: "Help me investigate a Defender XDR incident"
// Agent loads defender-xdr skill

const investigateIncident = async (incidentId, accessToken) => {
  // 1. Get incident details
  const incident = await fetch(
    `https://graph.microsoft.com/v1.0/security/incidents/${incidentId}`,
    { headers: { "Authorization": `Bearer ${accessToken}` } }
  ).then(r => r.json());
  
  // 2. Get alerts
  const alerts = incident.alerts.map(a => ({
    title: a.title,
    severity: a.severity,
    category: a.category,
    affectedAssets: a.assets
  }));
  
  // 3. Pivot to related entities
  const users = [...new Set(alerts.flatMap(a => 
    a.affectedAssets.filter(asset => asset.type === 'User')
      .map(asset => asset.identifier)
  ))];
  
  const devices = [...new Set(alerts.flatMap(a => 
    a.affectedAssets.filter(asset => asset.type === 'Device')
      .map(asset => asset.identifier)
  ))];
  
  return {
    incident: {
      id: incident.id,
      severity: incident.severity,
      status: incident.status
    },
    alerts,
    affectedUsers: users,
    affectedDevices: devices,
    nextSteps: [
      "Review alert timelines in Defender portal",
      "Check for lateral movement indicators",
      "Validate user sign-in logs in Entra ID",
      "Isolate affected devices if needed"
    ]
  };
};

Troubleshooting

Skills not loading in agent

Symptom: Agent gives generic advice instead of Microsoft-specific guidance.

Fix:

1. Verify installation: ls skills/ should show skill directories
2. Restart your agent/IDE
3. Test with explicit skill invocation: "Use the defender-xdr skill to help me..."

APM install fails

Symptom: apm install returns error.

Fix:

# Install APM first
npm install -g @microsoft/apm

# Verify APM is in PATH
apm --version

# Retry install
apm install vinayaklatthe/microsoft-security-skills

Skill outputs outdated recommendations

Symptom: Agent references deprecated Microsoft Learn pages.

Fix:

# Update the plugin
cd microsoft-security-skills
git pull origin main

# Or reinstall with APM
apm update vinayaklatthe/microsoft-security-skills

Code examples fail with authentication errors

Symptom: Unauthorized or Forbidden when running generated code.

Fix:

1. Verify Azure credentials:

   az login
   az account show
   

2. Verify app registration permissions in Azure portal:

   • Microsoft Graph API: Policy.Read.All, SecurityEvents.Read.All, etc.
   • Grant admin consent for tenant-wide permissions

3. Use Managed Identity for Azure-hosted code:

   const { DefaultAzureCredential } = require("@azure/identity");
   const credential = new DefaultAzureCredential();
   

Which skill to use for overlapping scenarios

Symptom: Uncertain which skill to invoke (e.g., SOC spans SIEM + XDR).

Strategy:

1. Start with the most specific skill (e.g., sentinel for KQL queries)
2. Follow cross-references in skill body (e.g., "See also: defender-xdr")
3. Ask agent: "Which security skill should I use for [scenario]?"

Validation

The plugin includes a zero-dependency validation harness in validation/ that measures the lift each skill adds over an unaided model. Validated across:

• GPT-4 Turbo (OpenAI)
• Claude 3.5 Sonnet (Anthropic)

Run validation:

cd validation
node validate.js

References

• Microsoft Learn Security: https://learn.microsoft.com/security/
• APM (Agent Plugin Manager): https://github.com/microsoft/apm
• Plugin repository: https://github.com/vinayaklatthe/microsoft-security-skills
• License: MIT