<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: performing-security-reference-architecture
description: >-
  Build reusable security reference architectures with standardized patterns, control
  mappings, and compliance templates that accelerate secure system design across
  enterprise environments.
domain: cybersecurity
subdomain: security-architecture
tags:
  - reference-architecture
  - security-patterns
  - control-catalog
  - nist
  - compliance-mapping
  - design-patterns
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: []
---

# Performing Security Reference Architecture

## Overview

Security reference architectures provide standardized, reusable blueprints for building
secure systems. This skill covers creating pattern catalogs, mapping controls to
compliance frameworks, and generating architecture decision records (ADRs) that
encode security rationale.

Mode: `[MODE: ARCHITECT]` — Reference architecture design and governance.

## Prerequisites

- Enterprise architecture documentation
- Compliance framework mappings (NIST 800-53, CIS, ISO 27001)
- Python 3.10+

## Key Concepts

### Reference Architecture Layers

| Layer | Components | Security Controls |
|-------|-----------|-------------------|
| **Presentation** | CDN, WAF, load balancer | TLS termination, bot protection, rate limiting |
| **Application** | API gateway, service mesh | AuthN/AuthZ, input validation, secrets mgmt |
| **Business Logic** | Microservices, functions | RBAC, audit logging, error handling |
| **Data** | Databases, caches, queues | Encryption at rest, column-level ACL, backup |
| **Infrastructure** | Compute, network, storage | Hardening, patching, segmentation |
| **Observability** | SIEM, logging, monitoring | Tamper-proof logs, alerting, correlation |

### Architecture Decision Record (ADR) Template

```markdown
# ADR-001: Mutual TLS for Service-to-Service Communication

## Status: Accepted
## Date: 2026-01-15

## Context
Internal services communicate over shared network segments. Without mutual
authentication, compromised services can impersonate others.

## Decision
All service-to-service communication uses mTLS via service mesh (Istio).
Certificate rotation automated via cert-manager with 24h TTL.

## Security Rationale
- Prevents STRIDE: Spoofing (mutual auth), Tampering (TLS integrity),
  Information Disclosure (encryption)
- Maps to: NIST AC-17, SC-8, SC-23; CIS Control 3.10

## Consequences
- Added latency: ~2ms per hop (acceptable)
- Certificate management overhead (mitigated by automation)
- All services must support TLS 1.3
```

### Control-to-Framework Mapping

```json
{
  "control": "encrypt-data-at-rest",
  "description": "All persistent data encrypted with AES-256-GCM",
  "mappings": {
    "nist_800_53": ["SC-28", "SC-28(1)"],
    "cis_v8": ["3.11"],
    "iso_27001": ["A.8.24"],
    "soc2": ["CC6.1"],
    "pci_dss": ["3.4", "3.5"]
  },
  "implementation": {
    "aws": "KMS with customer-managed CMK",
    "azure": "Azure Key Vault with HSM-backed keys",
    "gcp": "Cloud KMS with CMEK"
  }
}
```

### Security Pattern Catalog Entry

```yaml
pattern: api-gateway-auth
category: access-control
description: Centralized authentication at API gateway layer
components:
  - api-gateway
  - identity-provider
  - token-service
security_properties:
  - authentication-enforcement
  - token-validation
  - rate-limiting
threat_mitigations:
  - stride: [S, E]
  - attack: [T1078, T1190]
reference_implementations:
  - aws-api-gateway-cognito
  - kong-oidc
  - envoy-ext-authz
```

## Workflow

### Step 1: Catalog Security Patterns

```bash
node scripts/agent.js --action catalog --patterns patterns/
```

### Step 2: Map Controls to Frameworks

```bash
node scripts/agent.js --action map --controls controls.json --frameworks nist,cis,iso
```

### Step 3: Generate Reference Architecture

```bash
node scripts/agent.js --action generate --template three-tier --output ref-arch.json
```

### Step 4: Validate Coverage

```bash
node scripts/agent.js --action coverage --architecture ref-arch.json --framework nist_800_53
```

## Verification

- [ ] All architecture layers have defined security controls
- [ ] Controls mapped to at least two compliance frameworks
- [ ] ADRs document security rationale for key decisions
- [ ] Pattern catalog covers authentication, authorization, encryption, logging
- [ ] Reference architecture validated against target compliance framework
- [ ] Gap analysis produced for unmapped controls

## References

- [NIST SP 800-53 Rev 5 Control Catalog](https://csrc.nist.gov/publications/detail/sp/800-53/rev-5/final)
- [SABSA Security Architecture Framework](https://sabsa.org/)
- [TOGAF Security Architecture](https://pubs.opengroup.org/togaf-standard/)
