安全调查工具

pip install -r requirements.txt # Without hash verification

Prerequisites

1. Install Dependencies

Verify prerequisites:

python --version   # Requires 3.8+
node --version     # Requires 18+ (needed for KQL Search MCP)
az --version       # Azure CLI (needed for Azure MCP Server, ingestion report skill)
pwsh --version     # Requires 7.0+ (needed for sentinel-ingestion-report skill)

If Node.js is missing: Download or run winget install OpenJS.NodeJS.LTS (Windows) / brew install node (macOS). If Azure CLI is missing: Install, then az login --tenant <tenant_id> and az account set --subscription <subscription_id>. If the log-analytics extension is missing: az extension add --name log-analytics (required for sentinel-ingestion-report skill).

Set up Python environment:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Dependencies

pip install -r requirements.txt

Core packages: requests (HTTP client for enrichment APIs), python-dateutil (date parsing for KQL time ranges).

---

🚀 Setup

4. Build MCP Apps (Optional — Visualization Skills)

PowerShell (Windows):

cd mcp-apps/sentinel-geomap-server; npm install; npm run build; cd ../..
cd mcp-apps/sentinel-heatmap-server; npm install; npm run build; cd ../..
cd mcp-apps/sentinel-incident-comment; npm install; npm run build; cd ../..

Bash (macOS/Linux):

cd mcp-apps/sentinel-geomap-server && npm install && npm run build && cd ../..
cd mcp-apps/sentinel-heatmap-server && npm install && npm run build && cd ../..
cd mcp-apps/sentinel-incident-comment && npm install && npm run build && cd ../..

The sentinel-incident-comment MCP App requires an Azure Logic App backend. See mcp-apps/sentinel-incident-comment/README.md for setup. Based on stefanpems/mcp-add-comment-to-sentinel-incident.

---

🔌 MCP Server Setup

The system uses several Model Context Protocol (MCP) servers. All are pre-configured in .vscode/mcp.json.template — copy it to .vscode/mcp.json to get started (see Step 3 above). The sections below document permissions, tools, and installation guides for each server.

1. Install the Entra Beta PowerShell module (v1.0.13+)

Install-Module Microsoft.Entra.Beta -Force -AllowClobber

Verify Setup

Open Copilot Chat (Ctrl+Shift+I) in Agent mode and try these prompts:

If any server fails, check the MCP Servers panel in VS Code (click the {} icon in the bottom status bar) to verify each server shows a green connected status.

---

Quick Start (TL;DR)

```powershell

2. Set up Python environment

python -m venv .venv .venv\Scripts\Activate.ps1 # Windows

source .venv/bin/activate # macOS/Linux

pip install --require-hashes -r requirements.lock # Hash-verified (recommended)

3. Configure environment

copy config.json.template config.json

Edit config.json → add your Sentinel workspace ID, tenant ID

copy .env.template .env

Edit .env → add your API tokens (ipinfo, AbuseIPDB, vpnapi, Shodan)

4. Configure MCP servers

copy .vscode\mcp.json.template .vscode\mcp.json

All platform servers are pre-configured — just needs a GitHub PAT on first use

2. Configure Environment

Copy config.json.template to config.json and fill in your workspace details:

{
  "sentinel_workspace_id": "YOUR_WORKSPACE_ID_HERE",
  "tenant_id": "YOUR_TENANT_ID_HERE",
  "subscription_id": "YOUR_SUBSCRIPTION_ID_HERE",
  "azure_mcp": {
    "resource_group": "YOUR_LOG_ANALYTICS_RESOURCE_GROUP",
    "workspace_name": "YOUR_LOG_ANALYTICS_WORKSPACE_NAME",
    "tenant": "YOUR_TENANT_ID_HERE",
    "subscription": "YOUR_SUBSCRIPTION_ID_HERE"
  },
  "output_dir": "reports"
}

API Tokens (.env file)

API tokens for IP enrichment are stored in a .env file (gitignored) rather than config.json for security. Copy the template and add your keys:

```powershell copy .env.template .env

Edit .env with your token values

These are auto-loaded by enrich_ips.py via python-dotenv — no manual sourcing needed.

3. Configure MCP Servers

Copy the MCP server template (all platform servers + 3 optional MCP Apps are pre-configured):

copy .vscode/mcp.json.template .vscode/mcp.json

The template includes inline documentation for each server. On first use, VS Code will prompt for: - Entra ID login — browser-based auth for Sentinel Data Lake, Graph, Triage, and Sentinel Graph servers - GitHub PAT — for KQL Search MCP (schema intelligence and query discovery). Needs public_repo scope.

See MCP Server Setup below for per-server permissions and installation guides.

⚙️ Configuration Details

🧠 (Optional) Persistent Tenant Context

GitHub Copilot Chat in VS Code provides agents with a memory tool — a built-in filesystem (/memories/) for persisting notes across conversations. Copilot already uses this internally; you can extend it with tenant-specific context (known infrastructure IPs, validated personnel, false-positive patterns, lab automation signatures) so investigations don't repeatedly mis-classify documented activity as 🔴 critical.

Two memory tiers are relevant:

The memory tool is an internal agent capability — VS Code does not publish a dedicated docs page for it. Closest related concepts are custom instructions and Agent Skills, which serve different purposes (always-applied conventions and specialized workflows, respectively).

This workspace ships with:

• Templates in notes/memory/examples/ — copy and adapt for your tenant (one user-tier example, two repo-tier examples)
• Sync script scripts/sync-repo-memory.ps1 — backs up workspace-scoped (repo) memory from VS Code AppData into the workspace folder, surviving VS Code reinstall and workspace rename. Any cloud sync attached to your workspace (OneDrive, Dropbox, iCloud, etc.) then mirrors the backup across machines. Defaults to one-way export (ToBackup); restore mode (FromBackup) requires -Force because it writes into Copilot's trusted memory store.
• Setup guide notes/memory/README.md — full walkthrough, sync usage, security model, and the trigger-rule pattern that makes Copilot actually consult repo memory

Quickstart: Open a template from notes/memory/examples/, then ask Copilot in chat to "create this as a memory file at /memories/..., replacing placeholders with my tenant values." Copilot uses its memory tool to write it directly — no AppData path navigation needed.

⚠️ Memory = trusted input. Anything in notes/memory/repo/ becomes authoritative instructions for Copilot in every future chat (with MCP tool access to Sentinel, Graph, Azure). Review diffs from forks/PRs before restoring, never paste secrets, and if your workspace is cloud-synced, confirm the destination is acceptable for security context. See notes/memory/README.md for the full threat model.

---

API Rate Limits (IP Enrichment)

Token priority: If ipinfo_token is a paid plan, VPN detection is included and vpnapi_token is optional. Shodan uses the full API when a paid key is available; on 403/429 it automatically falls back to the free InternetDB.

IP enrichment happens during report generation (not data collection), so you can re-generate reports without re-querying Sentinel/Graph.

Threat Intelligence APIs

• ipinfo.io — IP geolocation, ISP/ASN identification, hosting provider detection
• vpnapi.io — VPN, proxy, Tor exit node, and relay detection
• AbuseIPDB — Community-sourced IP abuse scoring and recent attack reports
• Shodan — Open port enumeration, service/banner detection, CVE identification, infrastructure tagging

1. Clone and open in VS Code

git clone https://github.com/SCStelz/security-investigator.git code security-investigator

3. Register the MCP Server and grant permissions to VS Code

Grant-EntraBetaMCPServerPermission -ApplicationName VisualStudioCode ```

This only needs to be done once per tenant. After provisioning, all users in the tenant can use the Graph MCP server by signing in with their own account.

Permissions (delegated, per-user): - User.Read.All — user profiles and authentication methods - UserAuthenticationMethod.Read.All — MFA methods - Device.Read.All — device compliance and enrollment - IdentityRiskEvent.Read.All — Identity Protection risk detections

🛠️ Troubleshooting