From 2222a00486cd1f108c4721b802951d25e04d3424 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kim=20Harjam=C3=A4ki?= Date: Wed, 8 Jul 2026 15:02:32 +0300 Subject: [PATCH 1/2] docs: add DoNotEnforce policy pointer to README + docs-as-code wiki tree - README: one-line pointer to the DoNotEnforce policy assignment (found on main) and the in-progress ADR (PR #13) that will formally record it; freshness footer - wiki: Home, Architecture (service model + NO-AZURE deploy-lock posture of impl/ stubs), Operations, Decisions - Adds codex:generate-image placeholder per docs/VISION.md house style --- README.md | 9 +++++++ docs/wiki/Architecture.md | 55 +++++++++++++++++++++++++++++++++++++++ docs/wiki/Decisions.md | 32 +++++++++++++++++++++++ docs/wiki/Home.md | 31 ++++++++++++++++++++++ docs/wiki/Operations.md | 53 +++++++++++++++++++++++++++++++++++++ 5 files changed, 180 insertions(+) create mode 100644 docs/wiki/Architecture.md create mode 100644 docs/wiki/Decisions.md create mode 100644 docs/wiki/Home.md create mode 100644 docs/wiki/Operations.md diff --git a/README.md b/README.md index c2d0cfb..4258ef6 100644 --- a/README.md +++ b/README.md @@ -85,6 +85,13 @@ pretending to be those services. - Diagrams: [`docs/22-diagrams/README.md`](docs/22-diagrams/README.md) - Threat model: [`docs/23-threat-model.md`](docs/23-threat-model.md) - Static site: [`docs/index.html`](docs/index.html) +- Policy enforcement mode: the landing-zone `allowed-locations` policy assignment + ([`impl/azure/landing-zone/bicep/modules/policy-assignments.bicep`](impl/azure/landing-zone/bicep/modules/policy-assignments.bicep)) + is set to `enforcementMode: 'DoNotEnforce'` (audit-only rollout state). A formal ADR recording + this decision is in progress (PR #13, `fix(bicep): pin API versions and record DoNotEnforce ADR`); + it is not yet present in `docs/adr/` on `main`. +- Docs-as-code wiki (Home, Architecture, Operations, Decisions): + [`docs/wiki/`](docs/wiki/Home.md) - [Wiki](https://github.com/Coding-Autopilot-System/cloud-security-service-model/wiki) - overview, service definition, architecture, metrics & compliance ## Service lifecycle @@ -130,3 +137,5 @@ The repository includes: ## License See [`LICENSE`](LICENSE). + + diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md new file mode 100644 index 0000000..bbe4e8f --- /dev/null +++ b/docs/wiki/Architecture.md @@ -0,0 +1,55 @@ +# Architecture + +The Cloud Security Service is a comprehensive, scalable, measurable security posture model +across Azure and hybrid environments, connecting platform engineering, security operations, and +application teams to a controls-as-code foundation. + +```mermaid +graph TD + subgraph Consumers + AppTeams[Application Teams] + PlatformEng[Platform Engineering] + RiskComp[Risk and Compliance] + end + subgraph CloudSecurityService[Cloud Security Service] + PolicyEngine["Policy Engine\nAzure Policy / OPA"] + IdentityAccess["Identity and Access\nEntra ID / RBAC"] + ThreatDetection["Threat Detection\nDefender for Cloud"] + SIEM["SIEM and Logging\nMicrosoft Sentinel"] + end + subgraph OperationsAndGovernance[Operations and Governance] + SecOps["Security Operations / SOC"] + IncidentResponse[Incident Response] + AuditEvidence[Audit and Evidence] + end + Consumers --> CloudSecurityService + CloudSecurityService --> OperationsAndGovernance +``` + + + +## What this repo is (and isn't) + +This repository is an operating-model artifact — service scope, governance, metrics, runbooks, +and implementation stubs — not a deployed security platform. `impl/azure/` and `impl/hybrid/` +contain Bicep and policy-as-code *examples* meant to be extended in a consumer's own +environment; nothing in this repo is deployed from this workspace. + +## Deployment lock (NO-AZURE posture) + +Consistent with the workspace-wide NO-AZURE-deploy hard lock, the Bicep and policy-as-code +under `impl/` are authored, linted, and reviewed as reference implementation stubs — bicep-ready +— but never deployed from this workspace. Azure deployment of any resource this repo describes +is locked until a future milestone is deliberately reached. + +## Policy enforcement mode: DoNotEnforce (in progress) + +The landing-zone `allowed-locations` policy assignment +([`impl/azure/landing-zone/bicep/modules/policy-assignments.bicep`](../../impl/azure/landing-zone/bicep/modules/policy-assignments.bicep)) +is currently set to `enforcementMode: 'DoNotEnforce'` with `rolloutState: 'audit'` — the policy +evaluates and reports compliance without blocking deployments, the standard audit-before-enforce +rollout pattern. A formal ADR documenting this decision (Phase 33 P4) is in progress in PR #13 +(`fix(bicep): pin API versions and record DoNotEnforce ADR`) and is not yet present in +`docs/adr/` on `main`. See [Decisions](Decisions.md). + + diff --git a/docs/wiki/Decisions.md b/docs/wiki/Decisions.md new file mode 100644 index 0000000..6128244 --- /dev/null +++ b/docs/wiki/Decisions.md @@ -0,0 +1,32 @@ +# Decisions + +## Phase summaries (`.planning/phases/`) + +| Phase | Topic | +|---|---| +| [01-enterprise-audit](../../.planning/phases/01-enterprise-audit/) | Enterprise hardening audit | + +## Audits and debug records + +- [`.planning/audits/`](../../.planning/audits/) +- [`.planning/debug/`](../../.planning/debug/) + +## In-progress decision: DoNotEnforce policy assignment (Phase 33 P4) + +The `allowed-locations` policy assignment in +[`impl/azure/landing-zone/bicep/modules/policy-assignments.bicep`](../../impl/azure/landing-zone/bicep/modules/policy-assignments.bicep) +is set to `enforcementMode: 'DoNotEnforce'` (audit-only rollout) on `main` today. The formal ADR +capturing the rationale is being written in open PR #13 +(`fix(bicep): pin API versions and record DoNotEnforce ADR`) and had not merged to `main` as of +this writing — `gh pr view 13` reports `state: OPEN`, `mergedAt: null`. Once merged, this page +should be updated to link the landed ADR file directly. + +## Architecture Decision Records (`docs/adr/`) + +[`docs/adr/`](../adr/README.md) is the formal ADR home for this repo, governed by the rule that +any major technical decision or new dependency must be recorded there (Context / Decision / +Consequences, sequentially numbered: `001-record-architecture-decisions.md`, +`002-use-azure-functions.md`, etc.). No ADR files exist on `main` as of this writing — the +directory holds only the governance README. + + diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md new file mode 100644 index 0000000..a34600f --- /dev/null +++ b/docs/wiki/Home.md @@ -0,0 +1,31 @@ +# cloud-security-service-model Wiki + +`cloud-security-service-model` is a public-safe, enterprise-grade operating model for a Cloud +Security Service delivered as a service/product for Azure and hybrid environments. It is a +**docs-only repo** — Markdown, Mermaid diagrams, and Bicep/policy-as-code implementation stubs; +no application code, no test suite. + +## Who it's for + +Head of Cloud Platform Services, security leadership (CISO org), cloud engineering leads, +audit/compliance stakeholders. + +## How to consume + +1. Start with the [executive overview](../00-executive-overview.md) and + [service definition](../01-service-definition.md). +2. Use the [operating model](../05-operating-model.md) and + [metrics & KPIs](../07-metrics-and-kpis.md) to set expectations. +3. Apply the [templates](../21-templates/README.md) and + [runbooks](../20-runbooks/README.md) in operational workflows. +4. Extend the [implementation stubs](../../impl/) in your own environment. + +## Where to go next + +- [Architecture](Architecture.md) — service model architecture and the NO-AZURE deploy / + bicep-ready posture of the implementation stubs +- [Operations](Operations.md) — verified navigation and validation commands +- [Decisions](Decisions.md) — index of recorded architectural decisions, including the + in-progress DoNotEnforce policy ADR + + diff --git a/docs/wiki/Operations.md b/docs/wiki/Operations.md new file mode 100644 index 0000000..8558e7d --- /dev/null +++ b/docs/wiki/Operations.md @@ -0,0 +1,53 @@ +# Operations + +This is a docs-only repository — there is no application build, test suite, or coverage gate. +"Operations" here means navigating and validating the documentation set itself. + +## Repo structure + +- `/docs` — service model documentation and diagrams (numbered `00`–`23`, runbooks, templates, + Mermaid diagram sources) +- `/impl` — Azure and hybrid implementation stubs (Bicep, policy-as-code, Sentinel examples) +- `/agile` — backlog, ceremonies, and metrics + +## CI workflows + +| Workflow | Purpose | +|---|---| +| `ci.yml` | Repository CI checks | +| `codeql.yml` | CodeQL static analysis | +| `pr-lint.yml` | PR metadata/title linting | +| `stale.yml` | Stale issue/PR sweep | +| `static.yml` | Publishes the static docs site (`docs/index.html`) | + +There is no coverage-percentage badge in this repo — it has no application code to instrument. + +## Validating docs locally + +Per this repo's `CLAUDE.md` editing rules, run markdownlint before committing doc changes: + +```bash +npx markdownlint-cli docs/ +``` + +There is also a repository validation script: + +```bash +./scripts/validate-repository.sh +``` + +## Using the static site + +Open [`docs/index.html`](../index.html) to browse a minimal HTML version of the content with +navigation and search, or the built pages under [`docs/pages/`](../pages/). + +## Quick navigation + +- Executive overview: [`docs/00-executive-overview.md`](../00-executive-overview.md) +- Service definition: [`docs/01-service-definition.md`](../01-service-definition.md) +- Operating model: [`docs/05-operating-model.md`](../05-operating-model.md) +- Metrics & KPIs: [`docs/07-metrics-and-kpis.md`](../07-metrics-and-kpis.md) +- Runbooks: [`docs/20-runbooks/README.md`](../20-runbooks/README.md) +- Threat model: [`docs/23-threat-model.md`](../23-threat-model.md) + + From 6e80204d477081ce98231905b7ade085b674cfc0 Mon Sep 17 00:00:00 2001 From: root Date: Wed, 8 Jul 2026 16:18:49 +0300 Subject: [PATCH 2/2] fix(docs): wrap architecture image directive for markdownlint --- docs/wiki/Architecture.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/wiki/Architecture.md b/docs/wiki/Architecture.md index bbe4e8f..159d3f5 100644 --- a/docs/wiki/Architecture.md +++ b/docs/wiki/Architecture.md @@ -26,7 +26,15 @@ graph TD CloudSecurityService --> OperationsAndGovernance ``` - + ## What this repo is (and isn't)