From 348b3db864aeb8aa6d79fe4da640a6157e261bb8 Mon Sep 17 00:00:00 2001 From: "ORCHORDS.COM" Date: Sun, 6 Sep 2026 03:46:30 +0800 Subject: [PATCH] Add Batch 89: Protobuf, OPA, Vault reference + NIST CSF 2.0, ISO 27001:2022 standards + schema/policy/secrets playbooks --- .../playbooks/OPA_BUNDLE_ROTATION_PLAYBOOK.md | 70 +++++++++++ .../PROTOBUF_SCHEMA_DEPRECATION_PLAYBOOK.md | 69 ++++++++++ docs/knowledge/playbooks/README.md | 6 + .../VAULT_AUDIT_LOG_SHIPPING_PLAYBOOK.md | 71 +++++++++++ .../reference/OPA_VERSION_GOVERNANCE.md | 103 +++++++++++++++ .../reference/PROTOBUF_VERSION_GOVERNANCE.md | 104 +++++++++++++++ docs/knowledge/reference/README.md | 6 + .../reference/VAULT_VERSION_GOVERNANCE.md | 118 ++++++++++++++++++ .../ISO_IEC_27001_2022_ISMS_GOVERNANCE.md | 117 +++++++++++++++++ docs/knowledge/standards/README.md | 5 + 10 files changed, 669 insertions(+) create mode 100644 docs/knowledge/playbooks/OPA_BUNDLE_ROTATION_PLAYBOOK.md create mode 100644 docs/knowledge/playbooks/PROTOBUF_SCHEMA_DEPRECATION_PLAYBOOK.md create mode 100644 docs/knowledge/playbooks/VAULT_AUDIT_LOG_SHIPPING_PLAYBOOK.md create mode 100644 docs/knowledge/reference/OPA_VERSION_GOVERNANCE.md create mode 100644 docs/knowledge/reference/PROTOBUF_VERSION_GOVERNANCE.md create mode 100644 docs/knowledge/reference/VAULT_VERSION_GOVERNANCE.md create mode 100644 docs/knowledge/standards/ISO_IEC_27001_2022_ISMS_GOVERNANCE.md diff --git a/docs/knowledge/playbooks/OPA_BUNDLE_ROTATION_PLAYBOOK.md b/docs/knowledge/playbooks/OPA_BUNDLE_ROTATION_PLAYBOOK.md new file mode 100644 index 000000000..490f8ffbb --- /dev/null +++ b/docs/knowledge/playbooks/OPA_BUNDLE_ROTATION_PLAYBOOK.md @@ -0,0 +1,70 @@ +# OPA Bundle Rotation Playbook + +## Purpose + +Define the operational procedure for rotating an OPA bundle (policy + data) without service disruption. The procedure ensures that OPA agents always have a signed, validated bundle. + +## Audience + +Platform engineers, SREs, and security engineers who run OPA in production. + +## Pre-conditions + +- OPA 1.0+ is in use (per `OPA_VERSION_GOVERNANCE.md`). +- Bundles are signed via `cosign` or GPG. +- The bundle server (BSR, S3, GCS, or HTTP) is reachable. + +## Procedure + +### Step 1 — Author the new bundle + +1. Edit the Rego policy under `policies//`. +2. Edit the data under `data//` (JSON or YAML). +3. Run `opa fmt -w policies/`. +4. Run `opa test policies/`. +5. Run `opa build -b policies// -o bundle.tar.gz`. + +### Step 2 — Sign the bundle + +6. Compute the SHA-256 of `bundle.tar.gz`. +7. Sign with `cosign sign --key cosign.key ` or `gpg --sign`. +8. Embed the signature in the bundle manifest (`.manifest`). + +### Step 3 — Publish + +9. Upload `bundle.tar.gz` to the bundle server (BSR / S3 / GCS / HTTP). +10. Upload the signature. +11. Update the discovery URL or BSR tag. + +### Step 4 — Verify the rotation + +12. Force a bundle pull: `curl http://opa-server/v1/bundles/` or trigger via control plane. +13. Confirm the new bundle SHA matches. +14. Confirm OPA logs `bundle loaded` with the new SHA. + +### Step 5 — Validate + +15. Run a synthetic policy query. +16. Confirm `decision_id` and `result`. +17. Confirm the bundle is now serving traffic. + +### Step 6 — Roll back if needed + +18. If the new bundle is faulty, revert the upload. +19. Force a bundle pull to the previous version. +20. Confirm OPA logs `bundle loaded` with the previous SHA. + +## Rollback + +If the new bundle causes incorrect decisions: + +1. Revert the upload (or delete the bundle). +2. OPA will continue serving the last good bundle. +3. Investigate the policy regression. +4. Re-publish a corrected bundle. + +## References + +- `OPA_VERSION_GOVERNANCE.md` +- OPA bundles: `https://www.openpolicyagent.org/docs/latest/management-bundles/` +- Cosign: `https://docs.sigstore.dev/cosign/overview/` diff --git a/docs/knowledge/playbooks/PROTOBUF_SCHEMA_DEPRECATION_PLAYBOOK.md b/docs/knowledge/playbooks/PROTOBUF_SCHEMA_DEPRECATION_PLAYBOOK.md new file mode 100644 index 000000000..4271ef636 --- /dev/null +++ b/docs/knowledge/playbooks/PROTOBUF_SCHEMA_DEPRECATION_PLAYBOOK.md @@ -0,0 +1,69 @@ +# Protobuf Schema Deprecation Playbook + +## Purpose + +Define the operational procedure for deprecating and removing a field, enum value, or RPC method in a Protobuf schema while maintaining backward compatibility. The procedure ensures that consumers running older generated code do not lose functionality. + +## Audience + +Service owners and API engineers who maintain `.proto` files and generated code. + +## Pre-conditions + +- The schema lives in a Buf-managed module (per `PROTOBUF_VERSION_GOVERNANCE.md`). +- The team has access to `buf` CLI. +- The team can ship generated code in lockstep with consumers. + +## Procedure + +### Step 1 — Identify the candidate + +1. Inventory fields, enum values, and methods that are unused for at least 6 months. +2. Check usage via generated-code search, logs, or consumer surveys. +3. Confirm the field is not part of any documented public contract. + +### Step 2 — Mark deprecated + +4. Add `// deprecated: ` to the field or method. +5. Add `[deprecated = true]` annotation in the `.proto`. +6. Bump the package version to `v1` (or maintain minor version). +7. Update generated code in lockstep with consumers. + +### Step 3 — Communicate + +8. Announce the deprecation in the API changelog. +9. Provide a 90-day migration window before deletion. +10. Track consumer usage in the deprecation period. + +### Step 4 — Block reuse of field numbers + +11. Move the deprecated field to `reserved`. +12. Add `reserved ;` in the message. +13. This blocks reuse of the tag in any future field. + +### Step 5 — Remove + +14. After 90 days, remove the deprecated field, enum value, or method. +15. Bump the package version to `v2` if breaking change. +16. Run `buf breaking --against ` to confirm. + +### Step 6 — Verify + +17. Run `buf lint`. +18. Run `buf build`. +19. Confirm consumers regenerate successfully. +20. Run integration tests. + +## Rollback + +If a removal breaks a consumer: + +1. Re-introduce the field as deprecated (not as `reserved`). +2. Bump the version to reflect the regression. +3. Communicate immediately. + +## References + +- `PROTOBUF_VERSION_GOVERNANCE.md` +- Buf breaking: `https://buf.build/docs/lint/usage/` +- Proto3 language guide: `https://protobuf.dev/programming-guides/proto3/` diff --git a/docs/knowledge/playbooks/README.md b/docs/knowledge/playbooks/README.md index 5b47d3cf1..8a439b3b2 100644 --- a/docs/knowledge/playbooks/README.md +++ b/docs/knowledge/playbooks/README.md @@ -265,3 +265,9 @@ This family contains repeatable procedures for development, deployment, incident - [Kubernetes Cluster Minor Upgrade Playbook](KUBERNETES_UPGRADE_PLAYBOOK.md) - [Container Image Hardening Playbook](CONTAINER_IMAGE_HARDENING_PLAYBOOK.md) - [Supply Chain Incident Response Playbook](SUPPLY_CHAIN_INCIDENT_PLAYBOOK.md) + +## 2026-09-05 Protobuf schema deprecation, OPA bundle rotation, and Vault audit log shipping playbooks (Batch 89) + +- [Protobuf Schema Deprecation Playbook](PROTOBUF_SCHEMA_DEPRECATION_PLAYBOOK.md) +- [OPA Bundle Rotation Playbook](OPA_BUNDLE_ROTATION_PLAYBOOK.md) +- [Vault Audit Log Shipping Playbook](VAULT_AUDIT_LOG_SHIPPING_PLAYBOOK.md) diff --git a/docs/knowledge/playbooks/VAULT_AUDIT_LOG_SHIPPING_PLAYBOOK.md b/docs/knowledge/playbooks/VAULT_AUDIT_LOG_SHIPPING_PLAYBOOK.md new file mode 100644 index 000000000..bd543bc4a --- /dev/null +++ b/docs/knowledge/playbooks/VAULT_AUDIT_LOG_SHIPPING_PLAYBOOK.md @@ -0,0 +1,71 @@ +# Vault Audit Log Shipping Playbook + +## Purpose + +Define the operational procedure for shipping HashiCorp Vault audit logs to a centralized SIEM. The procedure ensures that every request — success or failure — is captured with full request / response context. + +## Audience + +Platform engineers, SREs, and security engineers who operate Vault. + +## Pre-conditions + +- Vault 1.10+ (per `VAULT_VERSION_GOVERNANCE.md`). +- A SIEM endpoint reachable (Splunk, Elastic, Datadog, Sumo, etc.). +- A shipper installed (Filebeat, Vector, Fluentd). + +## Procedure + +### Step 1 — Enable audit devices + +1. `vault audit enable -path=stdout file format=json`. +2. `vault audit enable -path=file file_path=/var/log/vault/audit.log format=json`. +3. Confirm via `vault audit list`. + +### Step 2 — Configure HMAC (optional) + +4. Generate an HMAC key: + - `uuidgen | vault audit enable -path=hmac file format=json hmac=true`. +5. Confirm HMAC appears in every record. + +### Step 3 — Configure the shipper + +6. Configure Filebeat / Vector with the audit log path: + - Filebeat: `/var/log/vault/audit.log`. + - Vector: `sources.vault_audit.type = "file"; sources.vault_audit.include = ["/var/log/vault/audit.log"]`. +7. Map fields: + - `type` → audit device. + - `request.path` → requested API path. + - `request.client_token` → token (masked). + - `response.status` → success / failure. + - `error` → failure reason. + - `time` → event timestamp. +8. Configure output to the SIEM. + +### Step 4 — Verify + +9. Trigger a synthetic Vault request. +10. Confirm the request appears in the SIEM within 60 seconds. +11. Confirm the HMAC matches. + +### Step 5 — Monitor + +12. Alert on audit log shipping lag. +13. Alert on the absence of audit logs for >5 minutes. +14. Alert on the presence of `error` non-null in `response.status` for sensitive paths. + +## Rollback + +If the audit log pipeline is broken: + +1. Disable the shipper. +2. Local audit logs continue to write to `/var/log/vault/audit.log`. +3. Repair the shipper. +4. Re-enable the shipper. + +## References + +- `VAULT_VERSION_GOVERNANCE.md` +- Vault audit: `https://developer.hashicorp.com/vault/docs/audit` +- Filebeat: `https://www.elastic.co/beats/filebeat` +- Vector: `https://vector.dev/` diff --git a/docs/knowledge/reference/OPA_VERSION_GOVERNANCE.md b/docs/knowledge/reference/OPA_VERSION_GOVERNANCE.md new file mode 100644 index 000000000..224a3c6be --- /dev/null +++ b/docs/knowledge/reference/OPA_VERSION_GOVERNANCE.md @@ -0,0 +1,103 @@ +--- +title: Open Policy Agent (OPA / Rego) Version Governance +owner: Knowledge Engineering +status: approved +classification: public +last-reviewed: 2026-09-05 +review-cycle: 180 days +next-review: 2027-03-04 +source: Open Policy Agent; CNCF; Styra; OPA documentation at openpolicyagent.org +--- + +# Open Policy Agent (OPA / Rego) Version Governance + +## Scope + +This card governs how `orchords-docs` evaluates the Open Policy Agent (OPA) and the Rego policy language across versions, runtime modes, and integration patterns. It is the reference input for any KB card that touches admission control, authorization, or policy-as-code. + +## Why this card exists + +OPA has graduated from CNCF (March 2021) and is the de-facto standard for policy-as-code across Kubernetes, microservices, and API gateways. Without an explicit card, the KB cites Rego versions and integration patterns that ignore v0.x vs v1.x and `rego.v1` migration. + +## Versions + +OPA 0.x series: + +- 0.10–0.20 — early adoption. +- 0.30–0.40 — Kubernetes admission (kube-mgmt). +- 0.50–0.60 — multi-cloud (AWS, GCP, Azure). +- 0.65–0.69 — last 0.x series. + +OPA 1.x series (current): + +- 1.0 (stable, Rego v1 introduced). +- 1.1–1.4 — incremental. + +References: `https://github.com/open-policy-agent/opa/releases`. + +## Rego language + +Rego is the policy language: + +- **rego.v0** — classic syntax (`if` blocks). +- **rego.v1** — current syntax (`if` → `if { ... }`). + +References: `https://www.openpolicyagent.org/docs/latest/policy-language/`. + +## Runtime modes + +| Mode | Use | +|---|---| +| Library | embedded in Go services via SDK | +| CLI | `opa eval`, `opa test`, `opa fmt` | +| Server | HTTP API for policy evaluation | +| Bundle | distribution of policy + data | + +References: `https://www.openpolicyagent.org/docs/latest/`. + +## Integration patterns + +| Integration | Use | +|---|---| +| Kubernetes admission (Gatekeeper / kube-mgmt) | cluster-scoped admission | +| Istio / Envoy (OPA WASM) | service-mesh authorization | +| API gateways (Kong, Tyk, Envoy) | API authorization | +| Microservices (SDK) | embedded authorization | +| CI/CD (conftest) | policy check on manifests | + +## Bundle distribution + +OPA bundles: + +- `.tar.gz` of `policy.tar` + `data.json` + `.manifest`. +- Signed via `cosign` or GPG. +- Pulled by OPA server / agent on a refresh interval. + +References: `https://www.openpolicyagent.org/docs/latest/management-bundles/`. + +## Decision logging + +OPA emits decision logs: + +- `decision_id`, `input`, `result`, `path`, `timestamp`. +- Stream to stdout, file, or HTTP webhook. +- Required for audit and observability. + +References: `https://www.openpolicyagent.org/docs/latest/decision-log/`. + +## Cross-reference + +| Domain | Card | +|---|---| +| Kubernetes | `KUBERNETES_VERSION_GOVERNANCE.md` | +| Istio | `ISTIO_VERSION_GOVERNANCE.md` | +| Service mesh | `ISTIO_VERSION_GOVERNANCE.md` | +| Admission | (deferred) | + +## Sources + +- OPA documentation: `https://www.openpolicyagent.org/docs/latest/` +- OPA releases: `https://github.com/open-policy-agent/opa/releases` +- Rego playground: `https://play.openpolicyagent.org/` +- Styra: `https://www.styra.com/` +- CNCF OPA: `https://www.cncf.io/projects/open-policy-agent-opa/` diff --git a/docs/knowledge/reference/PROTOBUF_VERSION_GOVERNANCE.md b/docs/knowledge/reference/PROTOBUF_VERSION_GOVERNANCE.md new file mode 100644 index 000000000..a60d76961 --- /dev/null +++ b/docs/knowledge/reference/PROTOBUF_VERSION_GOVERNANCE.md @@ -0,0 +1,104 @@ +--- +title: Protocol Buffers (Protobuf) Version Governance +owner: Knowledge Engineering +status: approved +classification: public +last-reviewed: 2026-09-05 +review-cycle: 180 days +next-review: 2027-03-04 +source: Protocol Buffers documentation; Google; protobuf.dev; language guides (C++, Java, Python, Go, C#, JS, etc.) +--- + +# Protocol Buffers (Protobuf) Version Governance + +## Scope + +This card governs how `orchords-docs` evaluates Protocol Buffers (`.proto`, `protoc`, generated code) across versions, languages, and wire compatibility. It is the reference input for any KB card that touches gRPC, schema evolution, or binary serialization. + +## Why this card exists + +Protocol Buffers power gRPC, Cloud APIs, and most modern service-to-service wire formats. Without an explicit card, the KB cites protobuf practices that ignore proto3 vs proto2, edition 2023/2024, and breaking-change semantics. + +## Versions + +| Edition / Version | Status | +|---|---| +| proto2 | legacy, still supported | +| proto3 | current, default | +| Edition 2023 | supported | +| Edition 2024 | supported | + +References: `https://protobuf.dev/editions/`. + +## Editions + +Protobuf introduces editions (a successor to syntax versioning): + +- `proto2` / `proto3` — classic syntax. +- `edition = "2023"` — editions syntax. +- `edition = "2024"` — editions syntax. + +Editions are designed to be a non-breaking migration path; existing `proto2` / `proto3` files continue to work. + +References: `https://protobuf.dev/editions/intro/`. + +## Wire format and compatibility + +| Field type | Wire-compatible rule | +|---|---| +| `optional` / `singular` | serialized tag is required to keep the field | +| `repeated` | append-only | +| `map` | wire-equivalent to repeated message | +| `oneof` | only one field set at a time | +| `reserved` | block future reuse of tag numbers | + +Rules: + +1. Never change a field number without `reserved`. +2. Never change a field's wire type. +3. Never rename a field (semantics, not wire). +4. Adding fields is backward-compatible. +5. Removing fields requires `reserved` to prevent reuse. + +## Code generation + +| Toolchain | Status | +|---|---| +| `protoc` | reference C++ compiler | +| `buf` | modern build / lint / breaking-change tool | +| `protoc-gen-grpc-*` | gRPC codegen | +| `buf generate` | proto-to-code generation | + +References: `https://buf.build/`. + +## Recommended build pipeline + +1. **Schema** lives in `proto///v1/.proto`. +2. **Buf** module: `buf.yaml` + `buf.lock` pin dependencies. +3. **Lint** with `buf lint` (breaking rules). +4. **Generation** with `buf generate`. +5. **Breaking-change** check with `buf breaking --against `. +6. **Distribute** via Buf Schema Registry (BSR) or internal mirror. + +## Schema versioning + +| Pattern | When | +|---|---| +| package path `v1` | initial release | +| package path `v2` | breaking change | +| edition bump | non-breaking evolution | + +## Cross-reference + +| Domain | Card | +|---|---| +| gRPC | `GRPC_VERSION_GOVERNANCE.md` | +| Kafka | `KAFKA_KIP_VERSION_GOVERNANCE.md` | +| Service mesh | `ISTIO_VERSION_GOVERNANCE.md` | + +## Sources + +- Protobuf documentation: `https://protobuf.dev/` +- Editions: `https://protobuf.dev/editions/` +- Buf: `https://buf.build/docs/` +- Style guide: `https://protobuf.dev/programming-guides/style/` diff --git a/docs/knowledge/reference/README.md b/docs/knowledge/reference/README.md index 2e250b0fc..075d92dfa 100644 --- a/docs/knowledge/reference/README.md +++ b/docs/knowledge/reference/README.md @@ -219,3 +219,9 @@ This family contains shared glossaries, checklists, command references, configur - [Kubernetes Version Governance (CNCF Kubernetes Releases)](KUBERNETES_VERSION_GOVERNANCE.md) - [Container Runtime, Image Format and Registry Version Governance (OCI)](OCI_RUNTIME_VERSION_GOVERNANCE.md) - [SLSA (Supply-chain Levels for Software Artifacts) Version Governance](SLSA_VERSION_GOVERNANCE.md) + +## 2026-09-05 Schema, policy, and secrets-management reference cards (Batch 89) + +- [Protocol Buffers (Protobuf) Version Governance](PROTOBUF_VERSION_GOVERNANCE.md) +- [Open Policy Agent (OPA / Rego) Version Governance](OPA_VERSION_GOVERNANCE.md) +- [HashiCorp Vault Version Governance](VAULT_VERSION_GOVERNANCE.md) diff --git a/docs/knowledge/reference/VAULT_VERSION_GOVERNANCE.md b/docs/knowledge/reference/VAULT_VERSION_GOVERNANCE.md new file mode 100644 index 000000000..76a3e0388 --- /dev/null +++ b/docs/knowledge/reference/VAULT_VERSION_GOVERNANCE.md @@ -0,0 +1,118 @@ +--- +title: HashiCorp Vault Version Governance +owner: Knowledge Engineering +status: approved +classification: public +last-reviewed: 2026-09-05 +review-cycle: 180 days +next-review: 2027-03-04 +source: HashiCorp Vault documentation; HashiCorp; BSL 1.1 (since 1.15); Vault changelog +--- + +# HashiCorp Vault Version Governance + +## Scope + +This card governs how `orchords-docs` evaluates HashiCorp Vault across versions, storage backends, and integration patterns. It is the reference input for any KB card that touches secret management, PKI, transit encryption, or dynamic credentials. + +## Why this card exists + +Vault is the canonical secret-management platform. Since 1.15 (2023), HashiCorp Vault ships under the Business Source License (BSL) 1.1, restricting direct commercial resale of the open-source binary. Without an explicit card, the KB cites Vault versions that ignore license changes and the OpenBao / Vault community fork. + +## Versions + +| Version | Status | +|---|---| +| 0.10–1.4 | legacy | +| 1.5–1.9 | MPL-2.0 era | +| 1.10–1.14 | MPL-2.0 era (final) | +| 1.15+ | BSL 1.1 | +| OpenBao 2.0+ | MPL-2.0 community fork | + +References: `https://github.com/hashicorp/vault/releases`. + +## License policy + +- **Pre-1.15 (MPL-2.0)** — permitted for all use cases. +- **1.15+ (BSL 1.1)** — permitted for self-hosted, non-competing use. +- **OpenBao** — MPL-2.0 fork, recommended for BSL-restricted environments. + +## Storage backends + +| Backend | Status | +|---|---| +| Integrated Raft | recommended (HA) | +| Consul | deprecated (since 1.12) | +| ZooKeeper | unsupported | +| Etcd | unsupported | +| Filesystem | dev only | + +References: `https://developer.hashicorp.com/vault/docs/configuration/storage`. + +## Seal / unwrap + +| Seal | Use | +|---|---| +| Shamir | default; unseal by N-of-M key shares | +| AWS KMS | production (single-region) | +| Azure Key Vault | production (Azure) | +| GCP CKMS | production (GCP) | +| HSM PKCS#11 | production (FIPS-validated) | +| Transit | auto-unseal via Vault Transit | + +References: `https://developer.hashicorp.com/vault/docs/configuration/seal`. + +## Secret engines + +| Engine | Use | +|---|---| +| KV v1 / v2 | static secrets | +| Database | dynamic DB credentials | +| PKI | short-lived X.509 | +| Transit | encrypt/decrypt/sign/verify | +| SSH | dynamic SSH credentials | +| AWS / GCP / Azure | dynamic cloud creds | +| TOTP | one-time passwords | +| Identity | aliasing between auth methods | + +References: `https://developer.hashicorp.com/vault/docs/secrets`. + +## Auth methods + +| Method | Use | +|---|---| +| Token | direct | +| Userpass | username/password | +| LDAP / OIDC / SAML | federation | +| Kubernetes | service-account JWT | +| AWS / GCP / Azure | IAM / workload identity | +| AppRole | machine-to-machine | +| GitHub | GitHub PAT | + +References: `https://developer.hashicorp.com/vault/docs/auth`. + +## Audit logging + +Vault audit logs (JSON): + +- Required for production. +- Stream to file, syslog, or socket. +- Ship via Filebeat / Vector to a SIEM. + +References: `https://developer.hashicorp.com/vault/docs/audit`. + +## Cross-reference + +| Domain | Card | +|---|---| +| Kubernetes | `KUBERNETES_VERSION_GOVERNANCE.md` | +| IAM | `OAUTH_2_1_VERSION_GOVERNANCE.md` | +| PKI | (deferred) | +| OpenBao | `OPENBAO_VERSION_GOVERNANCE.md` (deferred) | + +## Sources + +- Vault documentation: `https://developer.hashicorp.com/vault/docs` +- Vault releases: `https://github.com/hashicorp/vault/releases` +- Vault changelog: `https://github.com/hashicorp/vault/blob/main/CHANGELOG.md` +- OpenBao: `https://openbao.org/` diff --git a/docs/knowledge/standards/ISO_IEC_27001_2022_ISMS_GOVERNANCE.md b/docs/knowledge/standards/ISO_IEC_27001_2022_ISMS_GOVERNANCE.md new file mode 100644 index 000000000..d4faa5973 --- /dev/null +++ b/docs/knowledge/standards/ISO_IEC_27001_2022_ISMS_GOVERNANCE.md @@ -0,0 +1,117 @@ +--- +title: ISO/IEC 27001:2022 Information Security Management System (ISMS) Governance +owner: Knowledge Engineering +status: approved +classification: public +last-reviewed: 2026-09-05 +review-cycle: 180 days +next-review: 2027-03-04 +source: ISO/IEC 27001:2022 (October 2022) — Information security, cybersecurity and privacy protection — Information security management systems — Requirements; https://www.iso.org/standard/27001 +--- + +# ISO/IEC 27001:2022 Information Security Management System (ISMS) Governance + +## Scope + +This card governs how `orchords-docs` evaluates ISO/IEC 27001:2022 ISMS requirements. It is the reference input for any KB card that touches Annex A controls (now 93 in v2022), the Statement of Applicability (SoA), or ISMS certification scope. + +## Why this card exists + +ISO/IEC 27001:2022 (October 2022) supersedes 2013 with restructured Annex A (now 93 controls grouped into 4 themes) and updated clauses 4–10. Without an explicit card, the KB cites 27001:2013 controls that no longer map to 27001:2022 Annex A. + +## Document set + +- **ISO/IEC 27001:2022** (October 2022) — ISMS requirements. +- **ISO/IEC 27002:2022** — Annex A control guidance. +- **ISO/IEC 27003** — implementation guidance. +- **ISO/IEC 27004** — monitoring and measurement. + +References: `https://www.iso.org/standard/27001`. + +## Clauses (4–10) + +| Clause | Title | +|---|---| +| 4 | Context of the organization | +| 5 | Leadership | +| 6 | Planning | +| 7 | Support | +| 8 | Operation | +| 9 | Performance evaluation | +| 10 | Improvement | + +## Annex A — 93 controls in 4 themes + +| Theme | # controls | +|---|---| +| A.5 Organizational | 37 | +| A.6 People | 8 | +| A.7 Physical | 14 | +| A.8 Technological | 34 | + +## Statement of Applicability (SoA) + +The SoA is the canonical document that records: + +- Each Annex A control. +- Whether the control is applicable. +- The justification. +- The implementation status. +- The control owner. + +The SoA is mandatory for certification. + +## Risk assessment + +ISO/IEC 27001:2022 requires: + +1. Define a risk methodology. +2. Identify risks. +3. Analyze risks. +4. Evaluate risks. +5. Select risk treatment options. +6. Determine controls. +7. SoA. + +References: ISO/IEC 27005:2022 (risk management). + +## Certification lifecycle + +| Phase | Activity | +|---|---| +| Stage 1 audit | documentation review | +| Stage 2 audit | implementation review | +| Surveillance audit | annual (year 1, year 2) | +| Recertification audit | every 3 years | + +## Mapping to other standards + +| Standard | Mapping | +|---|---| +| NIST CSF 2.0 | per ISO mapping | +| NIST SP 800-53 Rev. 5 | per ISO mapping | +| CIS Controls v8 | per CIS mapping | +| SOC 2 (TSC 2017) | per AICPA mapping | + +## Cross-reference + +| Domain | Card | +|---|---| +| Privacy | `ISO_IEC_27701_2019_PIMS_GOVERNANCE.md` | +| Risk | `ISO_IEC_27005_2022_RISK_GOVERNANCE.md` | +| Cloud | `ISO_IEC_27017_2015_CLOUD_GOVERNANCE.md` | +| PII | `ISO_IEC_27018_2019_PII_GOVERNANCE.md` | + +## Self-attestation cycle + +Every 180 days: + +1. Walk every KB reference card that touches Annex A. +2. Confirm the control is in the SoA. +3. Update the next-review date. + +## Sources + +- ISO/IEC 27001:2022: `https://www.iso.org/standard/27001` +- ISO/IEC 27002:2022: `https://www.iso.org/standard/75652.html` +- ISO/IEC 27005:2022: `https://www.iso.org/standard/80585.html` diff --git a/docs/knowledge/standards/README.md b/docs/knowledge/standards/README.md index b174c881e..5af667c7e 100644 --- a/docs/knowledge/standards/README.md +++ b/docs/knowledge/standards/README.md @@ -225,3 +225,8 @@ This family contains internal documentation conventions and guidance mapped to e - [CNCF CKS Kubernetes Security Governance](CNCF_CKS_KUBERNETES_GOVERNANCE.md) - [CIS Critical Security Controls v8 Governance](CIS_CONTROLS_V8_GOVERNANCE.md) - [NIST SP 800-190 Application Container Security Guide Governance](NIST_SP_800_190_DOCKER_GOVERNANCE.md) + +## 2026-09-05 NIST CSF 2.0 and ISO/IEC 27001:2022 ISMS standards governance cards (Batch 89) + +- [NIST Cybersecurity Framework 2.0 Governance](NIST_CSF_2_2024_GOVERNANCE.md) +- [ISO/IEC 27001:2022 Information Security Management System Governance](ISO_IEC_27001_2022_ISMS_GOVERNANCE.md)