Sentinel greenfield starter files.

# Sentinel Greenfield IaC -- Master Plan

## Purpose

Build a practical, reusable Microsoft Sentinel greenfield baseline
without prematurely building a full MSSP deployment platform.

## Starting Model

1.  **Bicep** --- desired Azure/Sentinel baseline.
2.  **GitHub** --- source control, review, and releases.
3.  **PowerShell** --- discovery, validation, testing, and helper
    automation.
4.  **Confluence** --- operational and architecture documentation.
5.  **Claude** --- pair programmer, reviewer, researcher, and
    documentation assistant.

## Recommended Order

-   Step 1 --- tooling
-   Step 2 --- repository
-   Step 3 --- architecture decisions
-   Step 4 --- first Bicep baseline
-   Step 5 --- PowerShell validation
-   Step 6 --- Confluence documentation
-   Step 7 --- Claude skills
-   Step 8 --- CI validation
-   Step 9 --- customer handoff
-   Step 10 --- Sentinel content-as-code
-   Step 11 --- snapshots/drift
-   Step 12 --- multi-customer delivery

## First Definition of Done

A repository can deploy a Log Analytics workspace, onboard Sentinel,
apply documented baseline settings, accept parameters, build/lint,
validate the result, and produce useful documentation.

## Do Not Solve Yet

Do not initially build direct multi-customer deployment,
repo-per-customer architecture, a private Bicep registry, automatic
drift remediation, or every possible customer exception.

## Suggested Repository

``` text
sentinel-platform/
├── .claude/skills/
├── .github/workflows/
├── bicep/modules/
├── config/
├── docs/
├── examples/
├── scripts/
└── tests/
```

## Core Rules

-   Parameterize customer/environment values.
-   Never store secrets in Git.
-   Prefer managed identities/workload federation.
-   Prefer native Microsoft connectors where practical.
-   Preserve native schemas unless transformation has a documented
    reason.
-   Record why defaults were selected.
-   AI-generated IaC must build, lint, and be reviewed.
-   Explicitly document manual/portal-only steps.

## First Sprint

Create the repo, verify tools, deploy a workspace + Sentinel with Bicep,
add prerequisite/deployment validation scripts, add build/lint CI,
create the first Confluence page, and add the first two Claude skills.

# Step 1 -- Tooling and Prerequisites

## Required Tools

-   Git
-   GitHub CLI (`gh`)
-   Azure CLI (`az`)
-   Bicep CLI through Azure CLI
-   PowerShell 7 (`pwsh`)
-   VS Code or preferred editor
-   Claude Code

## PowerShell Modules

``` powershell
Install-Module Az.Accounts -Scope CurrentUser
Install-Module Az.Resources -Scope CurrentUser
Install-Module Az.OperationalInsights -Scope CurrentUser
Install-Module Az.SecurityInsights -Scope CurrentUser
Install-Module Az.Monitor -Scope CurrentUser
```

Likely later: `Az.ManagedServiceIdentity`, `Az.LogicApp`, and selected
Microsoft Graph modules when justified.

## Verify

``` bash
git --version
gh --version
az version
az bicep version
pwsh --version
claude --version
```

## Decisions

-   Safe internal Azure test subscription/resource group?
-   GitHub Actions permitted?
-   OIDC/workload identity federation permitted?
-   Atlassian MCP permitted?
-   What Azure permissions can development identities receive?

## Not Needed Yet

Terraform, private Bicep registry, customer credentials, custom MCP
servers, or a dedicated drift platform.

# Step 2 -- Repository Foundation

## Goal

Create a central reference implementation, preferably named
`sentinel-platform` or `sentinel-reference-architecture`.

## Structure

``` text
sentinel-platform/
├── .claude/skills/
├── .github/workflows/
├── bicep/modules/
├── config/
├── docs/
├── examples/
├── scripts/
└── tests/
```

## Branching

Use `main`, feature branches, and pull requests. Keep
organization-required approval controls.

## Never Commit

Secrets, private keys, tokens, credentials, raw customer log data, or
sensitive exports.

## Versioning

Plan for tagged releases such as `v0.1.0`, `v0.2.0`, and eventually
`v1.0.0`.

## Decisions

-   Can you create the org repo?
-   Required reviewers/checks?
-   GitHub Actions allowed?
-   Repository visibility?
-   Who owns the repo long term?

# Step 3 -- Architecture and Decision Records

## Goal

Document choices before they become accidental standards.

For each component capture: purpose, Microsoft-supported approach,
proposed default, configurable choices, licensing, permissions, IaC
support, manual steps, validation, owner, and exceptions.

## ADR Starter

``` markdown
# Decision: <title>
Status: Proposed | Accepted | Superseded
Date:
Owner:

## Context
## Options
## Decision
## Why
## Exceptions
## Validation
## References
```

## Early Decisions

-   Bicep as primary IaC.
-   Native connectors preferred.
-   DCR transformation strategy.
-   ASIM strategy.
-   Retention strategy.
-   Naming/tags.
-   Managed identities.
-   RBAC.
-   Portal-change policy.
-   Analytics/content ownership.
-   Customer-managed vs MSSP-managed deployment.

Keep uncertain choices marked **Proposed** until tested and reviewed.

# Step 4 -- First Bicep Baseline

## Goal

Prove the smallest useful deployment.

## First Resources

1.  Log Analytics workspace
2.  Sentinel onboarding
3.  Basic workspace settings
4.  Tags
5.  Useful outputs

## Layout

``` text
bicep/
├── main.bicep
└── modules/
    ├── log-analytics.bicep
    └── sentinel.bicep
examples/
└── example.bicepparam
```

## Rules

No hard-coded tenant/subscription IDs, secrets, or customer-specific
values in reusable modules.

## Build and Lint

``` bash
az bicep build --file bicep/main.bicep
az bicep lint --file bicep/main.bicep
```

Linting checks code quality and known problematic patterns without
deploying. Build asks whether it compiles; lint asks whether it violates
known guidance.

## Expansion Order

Retention → DCR/DCE → connectors → analytics → automation → playbooks →
workbooks → ASIM/custom parsing where justified.

## Decisions

Resource-group vs subscription scope, existing vs new workspace support,
retention defaults, tags, naming, and conditional resources.

# Step 5 -- PowerShell Validation

## Principle

Use PowerShell for orchestration, discovery, and validation---not as a
second desired-state engine.

## Initial Scripts

``` text
scripts/
├── Test-Prerequisites.ps1
├── Deploy-Sentinel.ps1
├── Test-SentinelDeployment.ps1
└── Get-SentinelInventory.ps1
```

### Test-Prerequisites.ps1

Check authentication, context, target RG, modules, required parameters,
and relevant prerequisites.

### Deploy-Sentinel.ps1

A thin wrapper around Bicep validation/what-if/deployment.

### Test-SentinelDeployment.ps1

Verify workspace, Sentinel onboarding, expected settings, and expected
resources.

### Get-SentinelInventory.ps1

Start small; later this can feed snapshot/drift tooling.

## Modules

`Az.Accounts`, `Az.Resources`, `Az.OperationalInsights`,
`Az.SecurityInsights`, `Az.Monitor`.

# Step 6 -- Confluence Documentation

## Goal

Make documentation part of the implementation workflow.

The documentation skill should work without MCP first. If approved
later, connect Claude to Atlassian/Confluence for search/create/update.

## Standard Page

-   Overview
-   Purpose
-   Architecture
-   Prerequisites
-   Licensing
-   Permissions
-   Default Configuration
-   Configurable Options
-   IaC Implementation
-   Manual Implementation
-   Validation
-   Operations
-   Rollback
-   Customer Responsibilities
-   MSSP Responsibilities
-   Exceptions
-   References
-   Last Reviewed

## Rules

Separate Microsoft guidance from organizational recommendations. Explain
why defaults exist. Mark assumptions. Identify licensing, roles, manual
steps, validation, and rollback.

## Decisions

Atlassian MCP availability, page hierarchy, review process, and whether
Git or Confluence is authoritative for each type of information.

Recommended: Git owns code/ADRs; Confluence owns consumable architecture
and operational documentation.

# Step 7 -- Claude Skills

## Start With

1.  `sentinel-architecture`
2.  `confluence-documentation`

Add skills only after repeated work justifies them.

## Layout

``` text
.claude/skills/
├── sentinel-architecture/
│   ├── SKILL.md
│   └── references/
└── confluence-documentation/
    ├── SKILL.md
    └── references/
```

## Future Skills

-   sentinel-iac
-   sentinel-content
-   sentinel-validation
-   sentinel-research
-   sentinel-drift

## Rule

A skill should capture a repeatable workflow, engineering standard, or
review behavior---not simply contain general product documentation.

# Skill Starter -- Sentinel Architecture

## Purpose

Design and review greenfield Microsoft Sentinel implementations against
the current proposed baseline.

## Principles

-   Prefer supported Microsoft-native capabilities.
-   Prefer native connectors where practical.
-   Preserve native Microsoft schemas unless transformation has a
    documented benefit.
-   Use DCR transformations where appropriate.
-   Treat ASIM primarily as a normalization/query abstraction.
-   Prefer managed identities and least privilege.
-   Separate reusable implementation from customer parameters.
-   Identify licensing and permission dependencies.
-   Identify settings that cannot reliably be managed through IaC.
-   Do not promote proposed patterns to standards without
    evidence/review.

## Required Architecture Output

State the requirement, recommendation, alternatives, tradeoffs, customer
decision points, IaC support, validation method, and authoritative
references.

## IaC Rule

Generated Bicep must build and lint before being considered complete.
Never hard-code secrets, tenant IDs, subscription IDs, or customer
values in reusable modules.

# Skill Starter -- Confluence Documentation

## Purpose

Create concise operational and architecture documentation for Sentinel
implementations.

## Audience

Sentinel engineers, SOC engineers, customer security teams, and
technical stakeholders.

## Required Sections

Overview, Purpose, Architecture, Prerequisites, Licensing Requirements,
Permissions, Default Configuration, Configurable Options, IaC
Implementation, Manual Implementation, Validation, Operational
Considerations, Rollback, Customer Responsibilities, MSSP
Responsibilities, Exceptions, References, Last Reviewed.

## Rules

-   Be concise and operational.
-   Explain why defaults were selected.
-   Distinguish Microsoft guidance from organizational recommendations.
-   Do not invent licensing or product behavior.
-   Mark unresolved questions and assumptions.
-   Include useful commands/examples.
-   Link implementation to a release/version when available.

# Step 8 -- GitHub CI Validation

## Goal

Reject obviously broken IaC without building a production customer
deployment platform.

## Initial PR Checks

-   Bicep build
-   Bicep lint
-   PowerShell checks
-   Required-file checks
-   Security scanning later when selected

``` text
Feature branch → PR → build/lint/checks → human review → main
```

## Do Not Add Yet

Automatic customer deployment, broad Azure credentials, automatic
remediation, or multi-customer matrix deployment.

## Decisions

Runner type, OIDC federation, approvals, security scanning, and internal
test environment.

# Step 9 -- Customer Handoff

## Goal

Support customers that deploy themselves.

## Levels

-   Fully parameterized package
-   Partially parameterized package
-   Generic reference package

## Package

``` text
deployment-package/
├── main.bicep
├── modules/
├── customer.bicepparam
├── customer.bicepparam.example
├── README.md
└── validation/
```

## Rules

Bicep remains the maintained source. Generate ARM when required. Never
guess unknown customer values. Feature enablement and licensing
assumptions should be explicit.

## Decisions

Who deploys, who validates, who owns later changes, portal-change
policy, and upgrade delivery.

# Step 10 -- Sentinel Content-as-Code (Later)

## Goal

Evaluate Microsoft's native Sentinel repository integration only after
the baseline IaC is stable.

## Potential Scope

Analytics rules, automation rules, hunting queries, parsers, playbooks,
workbooks, and other content supported by the current Microsoft feature
set.

## Why Later

This introduces a second deployment path. Do not mix it into the first
Bicep proof-of-concept.

## Questions

-   Which content should Bicep deploy?
-   Which content should native Sentinel repository sync own?
-   How are portal changes handled?
-   Does customer GitHub policy allow the integration?
-   How does this work for customers that deploy manually?
-   Does this simplify or complicate the customer model?

## Rule

A resource/content type should have one clearly documented authoritative
deployment path.

# Step 11 -- Snapshots and Drift (Later)

## Goal

Know what changed after deployment and retain useful historical
configuration.

## Model

``` text
Desired state = Git/Bicep + parameters
Observed state = Azure/Sentinel inventory
Comparison = drift
```

## First Evaluate Existing Tools

Before writing custom drift tooling, evaluate Microsoft/native and
established community GitOps/Sentinel-as-code projects. Avoid recreating
a mature capability.

## If Custom Inventory Is Needed

Normalize volatile fields such as timestamps, etags, provisioning
metadata, generated IDs where appropriate, and array ordering before
comparison.

## Drift Types

-   Approved/customer exception
-   Unapproved portal drift
-   Platform-version drift

## Snapshot Candidates

Workspace settings, retention, DCR/DCE, connectors, analytics,
automation, workbooks, playbooks, RBAC, identities, diagnostic settings,
and relevant solution/content state.

## Decisions

Snapshot frequency, storage location, sensitive metadata policy,
alerting method, remediation vs PR/review, and customer-managed snapshot
process.

# Step 12 -- Multi-Customer Delivery (Later)

## Goal

Support mixed customer deployment restrictions without changing the
reusable baseline.

## Likely Mature Pattern

``` text
sentinel-platform
      |
      +--> versioned modules/releases
              |
       +------+------+------+
       |             |      |
 Customer A     Customer B  Customer C
 deployment      deployment  manual
```

Potentially use customer-specific repos for parameters, exceptions,
identity, approval, and deployment workflow.

## Important Separation

Central platform owns reusable implementation and standards.
Customer-specific locations own environment values, exceptions,
deployment identity, and local workflow.

## Possible Future Distribution

-   Git release package
-   customer GitHub
-   customer Azure DevOps
-   MSSP GitHub Actions
-   private Bicep registry/ACR
-   manual Bicep/ARM handoff

## Security

Avoid one identity with access to every customer Azure environment.
Prefer customer-scoped identities and workload federation.

## Decisions

Repo-per-customer vs other isolation, platform version pinning, upgrade
process, identity ownership, approval ownership, and customer code
ownership.

# Step 13 -- Open Decisions Checklist

Use this as a backlog, not a list of things that must be solved
immediately.

## Now

-   [ ] Repository name/owner
-   [ ] Test Azure environment
-   [ ] Bicep baseline scope
-   [ ] Naming/tags
-   [ ] Workspace retention proposal
-   [ ] PR/check requirements
-   [ ] Confluence page structure
-   [ ] First Claude skills

## Soon

-   [ ] Existing workspace support
-   [ ] Connector strategy
-   [ ] DCR strategy
-   [ ] ASIM strategy
-   [ ] Analytics/automation ownership
-   [ ] Validation standard
-   [ ] Release/versioning scheme

## Later

-   [ ] Native Sentinel repository integration
-   [ ] Drift/snapshot tool selection
-   [ ] Customer-specific repo model
-   [ ] Private Bicep registry
-   [ ] Direct customer deployment
-   [ ] Customer-scoped GitHub environments/identities
-   [ ] Automatic upgrade workflow
-   [ ] Automatic drift remediation

## Decision Test

Before implementing a later item ask: Is there a real requirement now?
Does an existing trusted tool solve it? Who owns it? How will it be
validated? What new security/customer-isolation risk does it introduce?

# MSSP Microsoft Sentinel Lifecycle

At a high level, a greenfield Microsoft Sentinel deployment should be
treated as a **lifecycle**, not just "turn on connectors and start
writing detections."

## 1. Discovery / Requirements

-   What are we protecting and what are the customer's priorities?
-   Microsoft licensing: M365 E3/E5, MDE, MDI, MDO, Entra P1/P2, etc.
-   Azure subscriptions/tenants and hybrid/on-prem footprint
-   Third-party security products and infrastructure
-   Compliance/retention requirements
-   Expected ingestion volume and budget
-   MSSP/customer responsibility boundaries
-   Incident escalation, notification, and SLA expectations

## 2. Design the Sentinel Architecture

-   Subscription/resource group structure
-   Log Analytics workspace strategy
-   Region/data residency
-   RBAC and least privilege
-   MSSP cross-tenant access, typically Azure Lighthouse
-   Retention/archive strategy
-   Dedicated vs. shared customer resources
-   Naming/tagging standards
-   Dev/test/prod strategy if appropriate

## 3. Design the Data Ingestion Strategy

-   Inventory required log sources
-   Prioritize security-value data instead of simply ingesting
    everything
-   Prefer native Sentinel connectors
-   Azure Monitor Agent + DCRs where applicable
-   Syslog/CEF for appliances
-   API/Event Hub/custom collection only where necessary
-   Determine which tables each connector actually produces
-   Normalize where useful with **ASIM**
-   Filter noisy/unnecessary data before ingestion where possible
-   Estimate GB/day and Sentinel/Log Analytics cost

## 4. Deploy the Baseline

-   Sentinel workspace
-   RBAC/Lighthouse
-   Connectors
-   DCRs
-   Content Hub solutions
-   Analytics rules
-   Watchlists
-   ASIM parsers/functions
-   Automation rules
-   Logic Apps/playbooks
-   Workbooks/dashboards
-   Threat intelligence feeds

Ideally, most of this becomes **IaC/Git-controlled configuration**,
rather than analysts manually configuring every tenant.

## 5. Validate Telemetry

This is one of the most important MSSP steps and is easy to
underestimate.

Don't just verify that a connector says **Connected**. Validate:

-   Expected tables exist
-   Events are actually arriving
-   Expected event types exist
-   Volume is reasonable
-   Timestamp/latency is reasonable
-   Required fields are populated
-   Customer licensing actually supports the telemetry you expected

Build some sort of **data-source health matrix**:

`Source → Connector → Table(s) → Expected volume → Last seen → Health`

## 6. Build / Tune Detection Coverage

-   Start with Microsoft content where it makes sense
-   Map detections to MITRE ATT&CK / customer use cases
-   Tune thresholds and exclusions
-   Identify detection dependencies on particular tables/products
-   Add customer-specific detections
-   Test detections using known activity or simulation
-   Track false-positive rates
-   Version detections and document why tuning decisions were made

## 7. Design Incident Operations

-   Severity model
-   Incident ownership
-   MSSP triage procedures
-   Customer escalation path
-   Evidence requirements
-   Ticketing integration
-   Automation boundaries
-   What analysts can automatically contain versus what requires
    customer approval
-   Runbooks for common incident types

## 8. Operationalize Monitoring

Now you're monitoring **Sentinel itself in addition to security
events**:

-   Connector failures
-   Missing/stale tables
-   Sudden ingestion drops/spikes
-   DCR/collector failures
-   Analytics rules that stop firing
-   Logic App/playbook failures
-   API authentication/certificate expiration
-   Ingestion latency
-   Daily ingestion and cost anomalies
-   Retention/archive status

## 9. Continuous Maintenance

-   Microsoft connector/schema changes
-   New Sentinel Content Hub releases
-   Deprecated connectors/APIs
-   Detection updates
-   ASIM changes
-   Customer infrastructure changes
-   New products/licenses
-   New log sources
-   Detection tuning
-   RBAC/access reviews
-   Credential/certificate rotation
-   Cost optimization
-   Periodic coverage/gap assessments

## Managed Service Model

The MSSP architecture should ultimately look roughly like:

**Customer environment → ingestion/normalization → Sentinel → detections
→ incidents → automation → MSSP SOC → customer escalation**

with a second operational layer watching the whole thing:

**Telemetry health + detection health + automation health + cost +
configuration drift**

That second layer is what turns a Sentinel deployment into a **managed
Sentinel service** instead of just a Sentinel installation.