diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..2ad92cf --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @Coding-Autopilot-System/core diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..f6faee6 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,10 @@ +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + groups: + github-actions: + patterns: + - "*" diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 6b8a8dc..a34baf4 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,7 +1,8 @@ -# Summary +## Description + -## Checklist -- [ ] Docs updated -- [ ] Diagrams updated -- [ ] Evidence links updated -- [ ] Security impact assessed +## SDLC Verification +- [ ] Code follows CAS architecture (`AGENTS.md`) +- [ ] Tested via `gsd-verify-work` +- [ ] No embedded secrets or credentials +- [ ] Passed `gsd-code-review` diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..86eaa2a --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,29 @@ +name: "CodeQL" +on: + push: + branches: [ "main", "master" ] + pull_request: + branches: [ "main", "master" ] +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + strategy: + fail-fast: false + matrix: + language: [ 'javascript' ] + steps: + - name: Checkout repository + uses: actions/checkout@v4 + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 diff --git a/.github/workflows/pages.yml b/.github/workflows/pages.yml new file mode 100644 index 0000000..6c1d78d --- /dev/null +++ b/.github/workflows/pages.yml @@ -0,0 +1,36 @@ +name: Deploy Pages +on: + push: + branches: + - main + - master +permissions: + contents: read + pages: write + id-token: write +concurrency: + group: "pages" + cancel-in-progress: false +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: pip install mkdocs-material + - run: mkdocs build + - uses: actions/upload-pages-artifact@v3 + with: + path: ./site + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/pr-lint.yml b/.github/workflows/pr-lint.yml new file mode 100644 index 0000000..aa9c466 --- /dev/null +++ b/.github/workflows/pr-lint.yml @@ -0,0 +1,15 @@ +name: "PR Lint" +on: + pull_request_target: + types: + - opened + - edited + - synchronize +jobs: + main: + name: Validate PR title + runs-on: ubuntu-latest + steps: + - uses: amannn/action-semantic-pull-request@v5 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml new file mode 100644 index 0000000..217ed17 --- /dev/null +++ b/.github/workflows/stale.yml @@ -0,0 +1,15 @@ +name: "Close stale issues and PRs" +on: + schedule: + - cron: "30 1 * * *" +jobs: + stale: + runs-on: ubuntu-latest + steps: + - uses: actions/stale@v8 + with: + days-before-stale: 60 + days-before-close: 7 + stale-issue-message: "This issue is stale because it has been open 60 days with no activity." + stale-pr-message: "This PR is stale because it has been open 60 days with no activity." + operations-per-run: 50 diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..456e2f0 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,14 @@ +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.5.0 + hooks: + - id: trailing-whitespace + - id: end-of-file-fixer + - id: check-merge-conflict + - id: check-yaml + - id: check-json + - id: check-added-large-files +- repo: https://github.com/gitleaks/gitleaks + rev: v8.18.2 + hooks: + - id: gitleaks diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..46da89d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,3 @@ +# Context + +See the root workspace [AGENTS.md](../../AGENTS.md). diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..979152b --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,33 @@ +# cloud-security-service-model + +Enterprise cloud security operating model documentation — a comprehensive, audit-ready security framework for Azure hybrid environments. This is a **docs-only repo** (Markdown, Mermaid diagrams, HTML). No application code. + +## What's Here + +| Directory | Content | +|---|---| +| `docs/01–19` | Core service model docs: definition, catalog, architecture principles, governance, metrics, operating model, incident response, vulnerability management, access management, data protection, DevSecOps | +| `docs/20-runbooks/` | Operational runbooks (incident triage, vuln response, policy drift, break-glass access, Sentinel tuning) | +| `docs/21-templates/` | Reusable templates (change request, exception, incident report, postmortem, KPI dashboard) | +| `docs/22-diagrams/` | Mermaid source files for all architecture and process diagrams | +| `agile/` | Sprint ceremonies, backlog, OKRs, KPI cadence | +| `impl/azure/sentinel/` | Sentinel playbook examples | + +## Conventions + +- All diagrams are Mermaid (`.mmd` files in `docs/22-diagrams/`) — they render natively in GitHub +- Template files use `template-` prefix in `docs/21-templates/` +- Runbook files use `rbk-NNN-` prefix +- No code, no builds, no test suites — pure documentation +- `.editorconfig` enforces consistent whitespace + +## Editing Rules + +- Keep docs enterprise-grade in tone — no toy/demo language +- Update diagrams alongside prose when process flows change +- Run markdownlint (`npx markdownlint-cli docs/`) before committing +- All PRs should use `.github/pull_request_template.md` + +## GSD Workflow + +Use `/gsd:quick` for doc edits. For large restructures, use `/gsd:plan-phase`. diff --git a/README.md b/README.md index 6a07fe0..c2d0cfb 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,8 @@ # cloud-security-service-model +[![CI](https://github.com/Coding-Autopilot-System/cloud-security-service-model/actions/workflows/ci.yml/badge.svg)](https://github.com/Coding-Autopilot-System/cloud-security-service-model/actions/workflows/ci.yml) [![CodeQL](https://github.com/Coding-Autopilot-System/cloud-security-service-model/actions/workflows/codeql.yml/badge.svg)](https://github.com/Coding-Autopilot-System/cloud-security-service-model/actions/workflows/codeql.yml) + + [![CI](https://github.com/Coding-Autopilot-System/cloud-security-service-model/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Coding-Autopilot-System/cloud-security-service-model/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) diff --git a/docs/02-service-catalog.md b/docs/02-service-catalog.md index 101be89..3fc155a 100644 --- a/docs/02-service-catalog.md +++ b/docs/02-service-catalog.md @@ -1,6 +1,7 @@ # Service Catalog ## Core services + | Service | Description | Owner | Key Outputs | | --- | --- | --- | --- | | Policy-as-Code | Baseline policies and initiatives for Azure and hybrid | Cloud Security Service | Policy initiatives, assignments, compliance reports | @@ -10,6 +11,7 @@ | Risk & Audit | Evidence and risk reporting | Service Manager | Risk register, audit evidence packs | ## Optional services + | Service | Description | Trigger | | --- | --- | --- | | Configuration Review | Targeted posture review for workloads | Quarterly reviews or upon request | diff --git a/docs/05-operating-model.md b/docs/05-operating-model.md index c3162be..b0542a8 100644 --- a/docs/05-operating-model.md +++ b/docs/05-operating-model.md @@ -25,6 +25,7 @@ See the lifecycle model diagram: [`22-diagrams/security-operating-model.mmd`](22 repeatable controls, and shared accountability. ## Ceremonies and cadence + | Ceremony | Cadence | Owner | Outputs | | --- | --- | --- | --- | | Weekly ops review | Weekly | Service Manager | KPI deltas, top risks, open incidents | diff --git a/docs/07-metrics-and-kpis.md b/docs/07-metrics-and-kpis.md index b7cab01..fd175e9 100644 --- a/docs/07-metrics-and-kpis.md +++ b/docs/07-metrics-and-kpis.md @@ -1,6 +1,7 @@ # Metrics and KPIs ## KPI catalog + | KPI | Definition | Formula | Data Sources | Target | Owner | Cadence | | --- | --- | --- | --- | --- | --- | --- | | Policy compliance % | Percentage of resources compliant with baseline policies | Compliant resources / total in scope | Policy compliance reports | ≥ 95% | Service Manager | Weekly | @@ -12,6 +13,7 @@ | Backup restore test success rate | Successful restore tests | Successful tests / total tests | Backup reports | ≥ 95% | Platform Ops | Quarterly | ## SLA/SLO targets (service-level) + | Service area | SLA/SLO | Definition | Target | Owner | | --- | --- | --- | --- | --- | | Incident response | SLO | SEV1 acknowledgment time | ≤ 15 minutes | Incident Commander | @@ -21,6 +23,7 @@ | Exception handling | SLA | Exception review turnaround | ≤ 10 business days | Risk Owner | ## Sample dashboard (mock) + | Metric | Current | Target | Status | | --- | --- | --- | --- | | Policy compliance % | 96.4% | ≥ 95% | On track | diff --git a/docs/08-roadmap-and-maturity.md b/docs/08-roadmap-and-maturity.md index 6a39b77..c241ac1 100644 --- a/docs/08-roadmap-and-maturity.md +++ b/docs/08-roadmap-and-maturity.md @@ -27,6 +27,7 @@ **Risks:** complacency, reduced focus on hygiene. ## Sample 12-month roadmap + | Quarter | Focus | Key Deliverables | | --- | --- | --- | | Q1 | Foundation | Landing zone baseline, policy-as-code MVP, SIEM onboarding | diff --git a/docs/11-incident-response.md b/docs/11-incident-response.md index 0459000..15ad0ee 100644 --- a/docs/11-incident-response.md +++ b/docs/11-incident-response.md @@ -4,6 +4,7 @@ Prepare → Detect → Contain → Eradicate → Recover → Learn ## Severity model + | Severity | Description | Example | | --- | --- | --- | | SEV1 | Critical impact to multiple services or regulatory exposure | Widespread credential compromise | diff --git a/docs/14-vulnerability-management.md b/docs/14-vulnerability-management.md index 7d9d53c..ded77d2 100644 --- a/docs/14-vulnerability-management.md +++ b/docs/14-vulnerability-management.md @@ -11,6 +11,7 @@ 4. Verify fixes and update evidence. ## SLAs + | Severity | Target remediation | | --- | --- | | Critical | 7 days | diff --git a/docs/21-templates/template-kpi-dashboard.md b/docs/21-templates/template-kpi-dashboard.md index d305d05..e7a4642 100644 --- a/docs/21-templates/template-kpi-dashboard.md +++ b/docs/21-templates/template-kpi-dashboard.md @@ -2,10 +2,10 @@ | KPI | Current | Target | Owner | Status | | --- | --- | --- | --- | --- | -| Policy compliance % | | ≥ 95% | Service Manager | | -| MTTR (critical) | | ≤ 7 days | Remediation Lead | | -| TTD | | ≤ 15 min | SecOps | | -| TTC | | ≤ 4 hours | Incident Commander | | -| Privileged access exposure | | 0 standing admins | Identity Lead | | -| Misconfiguration trend | | Decreasing | Service Manager | | -| Backup restore tests | | ≥ 95% | Platform Ops | | +| Policy compliance % | | ≥ 95% | Service Manager | | +| MTTR (critical) | | ≤ 7 days | Remediation Lead | | +| TTD | | ≤ 15 min | SecOps | | +| TTC | | ≤ 4 hours | Incident Commander | | +| Privileged access exposure | | 0 standing admins | Identity Lead | | +| Misconfiguration trend | | Decreasing | Service Manager | | +| Backup restore tests | | ≥ 95% | Platform Ops | | diff --git a/docs/21-templates/template-postmortem.md b/docs/21-templates/template-postmortem.md index 17dca34..6535c70 100644 --- a/docs/21-templates/template-postmortem.md +++ b/docs/21-templates/template-postmortem.md @@ -11,6 +11,7 @@ ## What didn’t go well ## Action items + | Action | Owner | Due date | Status | | --- | --- | --- | --- | diff --git a/docs/adr/README.md b/docs/adr/README.md new file mode 100644 index 0000000..a2ac3c6 Binary files /dev/null and b/docs/adr/README.md differ diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..ad511dd --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,81 @@ +# Cloud Security Service Architecture + +The Cloud Security Service is designed to provide a comprehensive, scalable, and measurable security posture across Azure and hybrid environments. It leverages cloud-native capabilities integrated with enterprise governance processes. + +## High-Level Architecture + +The following diagram illustrates the core components and workflow of the Cloud Security Service, showing how platform engineering, security operations, and application teams interact with the controls-as-code foundation. + +```mermaid +graph TD + %% Define Styles + classDef consumers fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,color:#000; + classDef core fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#000; + classDef governance fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#000; + classDef external fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#000; + + %% Consumers + subgraph Consumers + AppTeams[Application Teams]:::consumers + PlatformEng[Platform Engineering]:::consumers + RiskComp[Risk & Compliance]:::consumers + end + + %% Core Services + subgraph CloudSecurityService[Cloud Security Service] + PolicyEngine[Policy Engine
Azure Policy / OPA]:::core + IdentityAccess[Identity & Access
Entra ID / RBAC]:::core + ThreatDetection[Threat Detection
Defender for Cloud]:::core + SIEM[SIEM & Logging
Microsoft Sentinel]:::core + end + + %% Governance & Ops + subgraph OperationsAndGovernance[Operations & Governance] + SecOps[Security Operations / SOC]:::governance + IncidentResponse[Incident Response]:::governance + AuditEvidence[Audit & Evidence]:::governance + end + + %% External Interfaces + ITSM[ITSM / ServiceNow]:::external + + %% Relationships + AppTeams -->|Consume Standards &
Deploy Workloads| PolicyEngine + PlatformEng -->|Build Landing Zones| PolicyEngine + PlatformEng -->|Configure Baselines| IdentityAccess + + PolicyEngine -->|Enforce & Audit| AppTeams + IdentityAccess -->|Authenticate & Authorize| AppTeams + + AppTeams -->|Logs & Telemetry| SIEM + PolicyEngine -->|Compliance Data| ThreatDetection + ThreatDetection -->|Alerts| SIEM + + SIEM -->|Triage & Investigate| SecOps + SecOps -->|Escalate| IncidentResponse + IncidentResponse -->|Tickets / Workflows| ITSM + + PolicyEngine -->|Compliance Reports| AuditEvidence + AuditEvidence -->|Review & Attest| RiskComp +``` + +## Component Details + +### 1. Policy Engine (Controls-as-Code) +The policy engine acts as the governance guardrail, continuously evaluating resource configurations against defined security standards (e.g., Azure Policy, OPA). It provides both preventative (deny) and detective (audit) controls. + +### 2. Identity & Access +Centralized identity management ensures least privilege access. This includes RBAC definitions, conditional access policies, and identity protection mechanisms. + +### 3. Threat Detection +Continuous monitoring of cloud workloads to identify suspicious activities or vulnerabilities. Findings are aggregated and prioritized based on risk context. + +### 4. SIEM & Logging +A centralized repository for security logs and telemetry. It correlates events across the environment to surface high-fidelity alerts to the Security Operations Center (SOC). + +## Feedback Loops + +The architecture incorporates continuous feedback loops: +- **Detection Tuning**: SecOps feedback refines SIEM rules and threat detection thresholds to reduce false positives. +- **Policy Refinement**: Application team feedback on policy friction leads to exception management or policy adjustments. +- **Automated Remediation**: Where possible, alerts trigger automated playbooks to remediate common misconfigurations. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..8f7eab2 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,27 @@ +# Cloud Security Service Model + +Welcome to the Cloud Security Service Model documentation. This repository defines an +enterprise-grade cloud security operating model for Azure and hybrid environments. +It outlines service scope, governance, controls-as-code, metrics, and measurable outcomes. + +## Getting Started for Developers + +As a developer or platform engineer, you interact with the Cloud Security Service primarily through: +- **Landing Zones & Policies**: Standardized environments governed by policy-as-code. +- **Identity & Access**: Baseline identity configurations for robust authentication. +- **Monitoring & Logging**: Centralized logging for auditing and incident response. + +### Quick Links + +- [Architecture Overview](architecture.md) - High-level architecture and logic. +- [Executive Overview](00-executive-overview.md) - Business value and context. +- [Service Definition](01-service-definition.md) - Mission, scope, and interfaces. +- [Operating Model](05-operating-model.md) - How we operate day-to-day. +- [Metrics & KPIs](07-metrics-and-kpis.md) - How we measure success. + +## Core Principles + +1. **Security as a Service**: We provide security capabilities as consumable services, not just blockers. +2. **Controls-as-Code**: Policies, alerts, and configurations are managed as code for reproducibility and auditability. +3. **Shared Responsibility**: Clear boundaries between what the security service owns and what application teams own. +4. **Audit-Ready by Design**: Continuous compliance monitoring and automated evidence collection. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..9cd990d --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,62 @@ +site_name: cloud-security-service-model Documentation +site_description: Autonomous GitHub workflow engine for the Coding Autopilot System. +site_url: https://Coding-Autopilot-System.github.io/gsd-orchestrator/ + +theme: + name: material + font: + text: Roboto + code: Roboto Mono + palette: + # Palette toggle for light mode + - media: "(prefers-color-scheme: light)" + scheme: default + primary: indigo + accent: blue + toggle: + icon: material/brightness-7 + name: Switch to dark mode + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: indigo + accent: blue + toggle: + icon: material/brightness-4 + name: Switch to light mode + features: + - navigation.tabs + - navigation.sections + - navigation.top + - navigation.indexes + - search.suggest + - search.highlight + - search.share + - content.code.copy + - content.action.edit + - content.action.view + +repo_name: Coding-Autopilot-System/cloud-security-service-model +repo_url: https://github.com/Coding-Autopilot-System/cloud-security-service-model +edit_uri: edit/main/docs/ + +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format + - admonition + - pymdownx.details + - pymdownx.tasklist: + custom_checkbox: true + +plugins: + - search +