🛡️ Security Architect Agent Specification

🎯 Purpose

The Security Architect Agent ensures that every microservice, API, event stream, database, and AI capability generated by the ConnectSoft AI Software Factory adheres to a Security-by-Design model — aligned with Zero Trust, Multi-Tenant SaaS, and Cloud-Native principles.

Its purpose is to eliminate security drift, automate protection, and propagate identity-aware controls into every output from all agents.

---

🔐 Key Security Goals

Goal	Outcome
🔑 Access Control	Ensure all APIs and resources require scopes, roles, or claims
🧾 Auditability	Every policy, secret, and access control is traceable and versioned
🧍 Least Privilege	Services and agents are only granted access they need
💬 API Trust Zones	Define boundary trust levels (internal vs external) and access expectations
🧬 End-to-End Encryption	Automatically inject TLS, field-level encryption metadata
🔍 Observability of Security Events	Publish violations, token anomalies, or privilege escalations
☠️ Secret Hygiene	Ensure secrets are never embedded in source; enforce managed retrieval

---

🔓 Without This Agent

Without the Security Architect Agent, the platform is exposed to:

• Misconfigured APIs lacking authorization or token validation
• Unscoped event publishing or cross-tenant data leakage
• Secrets embedded in generated source code
• Inconsistent scope definitions and token parsing logic
• Lack of audit trails for access control, leading to compliance failure
• Missing encryption of PII or sensitive fields
• No automatic enforcement of rate limiting or denial of service protection

---

🔒 With This Agent

With the Security Architect Agent, ConnectSoft ensures:

✅ Every API and event route includes validated OAuth2 scopes and optional role/claim-based conditions
✅ Secrets are automatically referenced from secure stores (e.g., Azure Key Vault, HashiCorp Vault)
✅ Field-level encryption policies are injected into both schema and access policies
✅ Security rules are emitted as machine-readable and human-reviewable artifacts
✅ All access control violations or anomalies trigger observability events

---

💡 Position in the Factory

This agent sits at the cross-cutting enforcement layer across:

• APIs (OpenAPI scopes, rate limits, OAuth2 flows)
• Events (stream authorization, subscriber ACLs)
• Data (PII encryption, masking, audit retention)
• Identity (roles, claims, users, access tokens)
• Secrets (service-to-service identity, encrypted transport)

---

📘 Example Tasks Performed

Task	Output
Define API scopes per endpoint	api-security.yaml
Assign roles to scopes	access-policy-map.yaml
Detect PII fields requiring encryption	encryption-policy.yaml
Enforce mTLS for service-to-service traffic	trust-boundary-map.yaml
Publish SecurityPolicyPublished event after generation	security-events.json

---

🧭 Summary

The Security Architect Agent enforces:

• ✅ Secure by default: no endpoint without access control
• ✅ Compliant by structure: PII, keys, and sessions are tagged and managed
• ✅ Traceable by design: Every scope, secret, and token rule is logged and versioned
• ✅ Zero Trust ready: No agent or service trusts another by default
• ✅ Automated remediation: Detect, log, and respond to missing, misused, or excessive privileges

---

🧭 Scope of Influence

The Security Architect Agent operates across the entire ConnectSoft Software Factory stack, embedding security architecture at every level:

• 🧩 Microservice APIs
• 📬 Event-driven messaging
• 🧱 Data storage
• 🤝 Inter-service communication
• 🧑 Identity and access control
• 🔐 Secret management
• 📦 Deployment and runtime boundary protection

---

🔷 Key System Layers Affected

Layer	Influence
API Layer	Defines and validates OAuth2 scopes, claims, and rate limits per route
Event Bus	Enforces publisher/subscriber ACLs, topic-level scopes, and signing
Database	Ensures field-level PII tags, encryption hints, masking, and RBAC triggers
Infrastructure (K8s, Mesh)	Generates mTLS service policies, workload identity binding
IAM (AuthN/AuthZ)	Defines and version-controls scopes, roles, claim sets
Secrets & Key Management	Declares expected secrets, references, and KMS policies

---

📘 Platform Capabilities It Governs

Capability	Examples
Scopes & Claims	invoice.read, client.write, admin.fullAccess, JWT claims enforcement
Rate Limiting & Throttling	Max requests per user, IP, service
Zero Trust	No implicit trust — all access must be scoped and authenticated
Audit Trail Hooks	Field-level logging of access and modification (e.g., email, role)
mTLS Enforcement	Required between agents, gateways, and services
Role Mapping	support_agent → read:clients, create:notes
PII/Compliance	Flags ssn, dob, email, etc. for encryption, retention, masking

---

⚙️ Boundaries of Enforcement

Area	Included
✅ REST APIs (OpenAPI)	Auth required + scopes + security definitions
✅ Async APIs (AsyncAPI)	Event-based trust and access control
✅ Schema enforcement	Sensitive field encryption and access policy generation
✅ Secrets	Declaration and vault reference injection
✅ Token models	JWT validation, issuer/audience, signing algos
✅ Multi-tenant separation	Tenant ID validation, cross-tenant isolation
✅ CI/CD context	Prevents deployment of unprotected APIs or secrets in source

---

🛑 Out of Scope

Area	Handled by
Runtime token validation logic	IAM Microservice (auth server)
Secret rotation	Secrets Manager (e.g., Azure Key Vault, Vault)
User provisioning and login	Identity Microservice
Intrusion detection	Platform-level infrastructure monitoring

---

🧠 Sample Security Assertions Injected

GET /invoices:
  security:
    oauth2:
      scopes: [invoice.read]
    rateLimit:
      requestsPerMinute: 120
    trace:
      required_headers: [trace_id, user_id]

client.email:
  pii: true
  encrypted: true
  masked: true

service-secrets:
  - name: signing-key
    type: rsa
    source: AzureKeyVault
    path: /connectsoft/invoice/signing-key

---

✅ Summary of Control Surface

Category	Controlled
🔒 Access (who)	✅ Roles, scopes, claims
🔐 Secrets (what)	✅ Declaration + no hardcoding
🛡️ Trust (where)	✅ Network policy, origin restrictions
🧾 Audit (when/why)	✅ Token traceability + observability events
☁️ Boundaries	✅ Cross-agent, cross-tenant, CI/CD scoped enforcement

---

📋 Core Responsibilities

The Security Architect Agent is responsible for generating, enforcing, and publishing the complete security blueprint for any microservice or system component within the ConnectSoft AI Software Factory.

It automates access control, encryption strategy, secret usage, and trust boundary enforcement in every generated asset — ensuring secure-by-default service behavior.

---

🔐 1. Scope & Claim Modeling

Task	Output
Generate OAuth2 scopes per API route	api-security.yaml
Map scopes to roles (RBAC) and claims (ABAC)	access-policy-map.yaml
Version and tag scopes with audit metadata	scope-definitions.json
Create claim-based rules for advanced permissions	e.g., "department = 'support'" AND "location = 'EU'"

---

🧾 2. Security Metadata for APIs and Events

Task	Output
Inject OpenAPI security: block with scopes and flows	REST & gRPC APIs
Annotate AsyncAPI topics with required publish_scope / subscribe_scope	event-security.yaml
Define required headers: trace_id, user_id, client_id	Observability-first enforcement
Tag internal vs external trust levels	trust-boundary-map.yaml

---

🔐 3. PII & Data Protection Controls

Task	Output
Detect sensitive fields (email, ssn, dob)	encryption-policy.yaml
Tag fields as x-encrypted, x-sensitive, x-mask: true	Used by database and adapter generators
Generate redaction/obfuscation policy per field type	Auto-tag in schemas and retention maps

---

🔑 4. Secrets and Key Management

Task	Output
Declare all required secrets for a service	service-secrets.yaml
Reference secrets from Azure Key Vault / Vault	With path, version, and TTL
Ensure no hardcoded tokens in artifacts	Auto-scan templates and code
Inject trust anchors for mTLS	Cert and CA policy map for internal comms

---

🧍 5. Rate Limiting and Abuse Protection

Task	Output
Annotate API routes with throttling metadata	rate-limit-policy.yaml
Define rules per service, IP, client_id, or user_id
Allow exemptions for internal traffic	Based on x-origin: internal or trust tag

---

📢 6. Policy Publication & Observability

Task	Output
Emit SecurityPolicyPublished event with version and trace_id	security-events.json
Generate Markdown and YAML summaries for human review	Optional: security-summary.md
Emit span templates for access denied, rate limit triggered, and missing scope events	Used by Observability Agent

---

🛡️ 7. Governance Enforcement

Task	Effect
Block generation of APIs without security: tag	✅
Require all services to declare required secrets	✅
Prevent deployment if PII field lacks encryption tag	✅
Log scope/claim drift from previous version	🔁 auto-correct or escalate
Validate token strategy (algorithms, claims) for integrity	e.g., no none, enforce RS256

---

✅ Summary of Responsibilities

Responsibility Area	Artifact
OAuth2 scopes, roles, claims	api-security.yaml, access-policy-map.yaml
PII/Field-level security	encryption-policy.yaml, field-retention-map.yaml
Secrets usage	service-secrets.yaml
Trust zones, identity enforcement	trust-boundary-map.yaml
Publishing	SecurityPolicyPublished (event)
Observability & diagnostics	security-span-map.yaml, security-events.json

---

📥 Core Inputs

The Security Architect Agent relies on upstream architectural artifacts, compliance definitions, and domain metadata to:

• Derive access scopes
• Map roles and claims
• Identify sensitive fields
• Generate secure token and secret usage models
• Validate trust relationships and origin boundaries

---

📂 Required Input Artifacts

Artifact	Source Agent	Purpose
api-surface-summary.md / openapi.yaml	API Designer Agent	Enumerates all routes and methods requiring protection
event-catalog.yaml	Event-Driven Architect Agent	Defines pub/sub flows and message types
field-retention-map.yaml	Data Architect / Compliance Agent	Identifies PII, redactable, encrypted fields
application-architecture.md	Application Architect Agent	Declares multi-tenancy, origin trust zones, cross-service dependencies
security-policies.yaml	Solution/Platform Architect	Global security posture, e.g., allowed auth flows, required encryption
previous-security-spec.yaml (optional)	CI or prior generation	Enables diffing of scopes, claims, policies
trace_id, service_name, bounded_context	Orchestrator	For versioning, event publication, and lineage

---

📘 Sample Artifacts

🔹 api-surface-summary.md

| Endpoint           | Method | Description        |
|--------------------|--------|--------------------|
| /invoices          | GET    | List invoices      |
| /invoices/{id}     | DELETE | Delete an invoice  |
| /clients/{id}      | PATCH  | Update client info |

→ Used to generate scope: invoice.read, invoice.delete, client.write

---

🔹 field-retention-map.yaml

client.email:
  pii: true
  encrypted: true
  redactable: true

invoice.amount:
  pii: false
  encrypted: false

→ Triggers x-sensitive, x-encrypted flags in schema + encryption policies

---

🔹 application-architecture.md (excerpt)

This service is exposed externally via public REST API.

- Must require OAuth2 with PKCE
- mTLS required between API Gateway and downstream services
- tenant_id must be validated on all incoming requests

→ Used to set trust levels and token validation flow

---

🔹 security-policies.yaml

allowed_auth_flows: [authorization_code, client_credentials]
require_mtls: true
token_signing_algorithms: [RS256]
minimum_password_length: 14
scopes_must_be_versioned: true

→ Controls security blueprint rules

---

📑 Optional: previous-security-spec.yaml

Used to detect changes like added/removed scopes, role reassignment, token algorithm changes

scopes:
  - name: client.read
    version: v1
    roles: [support_agent]
  - name: admin.fullAccess
    version: v1
    roles: [admin]

---

✅ Input Validation Rules

Rule	Description
Every API path must have a valid HTTP method	✅
All sensitive fields must appear in field-retention-map.yaml	✅
Roles and claims must be uniquely named and scoped	✅
All required secrets must have declared source + TTL	✅
Every event must have publish_scope and/or subscribe_scope	✅

---

📦 Aggregated Input Prompt Example

assignment: generate-security-spec

project:
  trace_id: trace-security-8842
  service_name: ClientService
  bounded_context: CRM

inputs:
  openapi_url: https://.../client/openapi.yaml
  retention_map_url: https://.../client/field-retention-map.yaml
  application_architecture_url: https://.../client/app-architecture.md
  global_policies_url: https://.../security/security-policies.yaml
  previous_security_url: https://.../client/security-v1.yaml

settings:
  generate_claims_map: true
  enforce_rate_limits: true
  emit_security_events: true

---

📤 Core Outputs

The Security Architect Agent emits a security specification bundle that defines, enforces, and documents:

• API and event-level access controls
• Role and claim-based permission mappings
• Field-level data protection strategies
• Secret usage declarations
• Trust boundaries and transport-level security
• Lifecycle events for policy observability

These outputs are machine-readable for CI/CD validation and human-readable for security audit review.

---

📦 Output Artifact Summary

Artifact	Format	Purpose
api-security.yaml	YAML	Per-endpoint OAuth2 scopes, required claims, rate limits
access-policy-map.yaml	YAML	Role → scopes and claims (RBAC/ABAC)
encryption-policy.yaml	YAML	Field-level encryption and masking rules
service-secrets.yaml	YAML	Declared secrets, reference paths, vault source
rate-limit-policy.yaml	YAML	Limits per route/client/service
trust-boundary-map.yaml	YAML	mTLS, internal vs external service boundaries
security-events.json	JSON	Emitted events like SecurityPolicyPublished, violations
security-summary.md	Markdown	Human-readable policy report (optional)

---

🧾 Artifact Details

🔐 api-security.yaml

paths:
  /clients:
    GET:
      scopes: [client.read]
      rateLimit:
        requestsPerMinute: 100
      requires_mtls: true
  /admin/reports:
    GET:
      scopes: [admin.fullAccess]
      required_claims: [role=admin, department=security]

---

👤 access-policy-map.yaml

roles:
  support_agent:
    scopes:
      - client.read
      - note.write
  admin:
    scopes:
      - "*"
    claims:
      - role=admin
      - clearance_level >= 3

---

🔏 encryption-policy.yaml

fields:
  client.email:
    encrypted: true
    pii: true
    masked: true
  client.ssn:
    encrypted: true
    redactable: true

---

🔑 service-secrets.yaml

secrets:
  - name: jwt-signing-key
    source: AzureKeyVault
    path: /connectsoft/auth/jwt-signing-key
    type: rsa
    rotation_policy: 90d
  - name: encryption-key
    source: HashiCorpVault
    path: /secrets/encryption-key

---

🧭 trust-boundary-map.yaml

zones:
  external:
    requires_mtls: true
    token_validation: enabled
  internal:
    trusted_proxies: [api-gateway, audit-service]
    allow_client_credentials_flow: true

---

🚦 rate-limit-policy.yaml

rules:
  global:
    max_requests_per_minute: 500
  paths:
    /clients:
      GET:
        requestsPerMinute: 100
        burst: 20
    /admin/reports:
      GET:
        requestsPerMinute: 25

---

📢 security-events.json

{
  "event": "SecurityPolicyPublished",
  "traceId": "trace-security-8842",
  "service": "ClientService",
  "version": "v2.0.0",
  "artifacts": {
    "apiSecurity": "https://.../api-security.yaml",
    "accessMap": "https://.../access-policy-map.yaml"
  },
  "timestamp": "2025-05-01T23:50:00Z"
}

---

✅ Output Quality Criteria

Criteria	Rule
All routes must have a scopes: field	✅
PII fields must have encrypted: true or masked: true	✅
Each secret must define source and path	✅
Trust zones must distinguish internal/external services	✅
At least one security lifecycle event emitted	✅

---

📚 Knowledge Base Overview

The Security Architect Agent relies on a deep and continually evolving knowledge base to generate secure, compliant, and scalable policies for:

• Access control
• Token validation
• Encryption and masking
• Trust boundaries
• Secret management
• Identity-based routing and enforcement

This knowledge base blends static rule sets with learned security patterns from previously generated services and cross-agent schemas.

---

🧠 1. Scope & Role Naming Conventions

Pattern	Description
resource.verb	client.read, invoice.write, report.generate
Hierarchical scopes	admin.*, billing.*, tenant.manage
Role naming	support_agent, system_admin, org_owner
Claim patterns	department = sales, clearance_level >= 3
Versioning	client.read.v1, admin.fullAccess.v2 (if scopes_must_be_versioned: true)

---

🔒 2. Known Sensitive Field Patterns

Field Pattern	Auto-Tagged As
email, ssn, dob, phone, passport_number	x-sensitive, x-encrypted, x-mask
password, api_key, refresh_token	secret = true, enforce vault retrieval
trace_id, user_id, client_id	audit_required = true
ip_address, geo_location	obfuscate-at-export = true

---

📦 3. Secret Hygiene and Source Standards

Rule	Standard
Secrets must not be embedded in generated code	✅ auto-scan and strip
Allowed secret sources	Azure Key Vault, HashiCorp Vault, AWS Secrets Manager
Recommended secret TTL	90 days unless explicitly tagged
Secrets in config files	Only allowed if redacted and sourced from vault on startup
KMS Enforcement	Required for encryption of at-rest data

---

🧾 4. Token Security Patterns

Pattern	Best Practice
Signing algorithm	Enforce RS256, ES256 (no none or HS256 in production)
Required claims	exp, iat, sub, aud, scope, tenant_id
Scope binding	Scope must match method + path + role
Audience validation	Audience must match service or external boundary
Key rotation strategy	kid header required; JWKs auto-sync every 1h

---

🛡️ 5. Trust Boundary Classifications

Zone	Policy
external	mTLS required, OAuth2 required, claims validated
internal	mTLS preferred, short-lived client credentials tokens
sandbox	Mock secrets and reduced scopes
shared	Token-scoped access with tenant isolation enforced

---

🔁 6. Security Drift Detection Memory

Detection	Trigger
Role was removed but still assigned	Warn, rollback, or reassign
Scope changed without claim mapping	Block publication or mark as breaking
Field previously encrypted: true is now false	Escalate and mark as regression
Scope removed from endpoint	Validate claim/role fallbacks or block contract publication

---

📘 7. Reusable Security Snippets

Use Case	Output Snippet
Protecting GET /admin/users	Require admin.fullAccess + role = admin
Masking email in logs	x-mask: true, masking_profile: default.email
Multi-tenant trust	Require tenant_id in token + access filter in query
Internal call from API Gateway to service	mTLS with aud = internal + client_id whitelist

---

🧠 Semantic Memory Match Example

query: "Protect route /clients/{id}"
result:
  scope: client.read
  required_claims: [role=support_agent]
  rate_limit: 100 rpm
  trace_fields: [trace_id, tenant_id, user_id]

---

✅ Knowledge Base Summary

Category	Description
Scope naming and versioning	Consistent naming across services
Claim rules and role mappings	Memory-guided reuse
PII pattern detection	Learned rules + glossary patterns
Secret patterns	Vault-only enforcement + TTL best practices
Token enforcement	JWT claims, signing, and trust propagation
Trust zones	Boundary-level protections and policy fallback detection

---

🔄 End-to-End Process Flow

The Security Architect Agent executes a multi-phase, memory-guided process to generate and validate security policies that protect:

• APIs
• Events
• Data fields
• Secrets
• Trust boundaries

The process is orchestrated via Semantic Kernel skills, with each step traceable, observable, and retry-safe.

---

📋 Step-by-Step Flow

Step	Description
1️⃣ Parse Inputs	- Load and validate the following input files: - openapi.yaml, api-surface-summary.md, field-retention-map.yaml, application-architecture.md, security-policies.yaml, and previous-security-spec.yaml (if present). - Extract necessary information such as: - All routes and HTTP methods - Sensitive fields and masking hints - Trust boundary types (external/internal/sandbox) - Existing scopes, roles, and claims (for comparison).
2️⃣ Scope and Access Rule Generation	- For each route, the following tasks are performed: - Suggest a scope using semantic naming (e.g., resource.verb) - Determine if a role or claim is required (support for ABAC) - Generate scope version (e.g., client.read.v2) if enabled. - Emit the following files: - api-security.yaml - access-policy-map.yaml.
3️⃣ PII and Field-Level Encryption Enforcement	- Match all fields marked as pii: true from the field-retention-map.yaml file. - Generate the following: - encryption-policy.yaml with flags: encrypted, masked, redactable. - Enforcement hints for adapters and schema agents to handle encryption and data masking properly.
4️⃣ Secret Declaration and Trust Planning	- Detect secret usages (e.g., JWT signing keys, encryption keys, API keys). - Emit the following files: - service-secrets.yaml - trust-boundary-map.yaml based on call graphs and architecture. - Validate that: - Each secret must be externalized for security. - Trust zones must align with the origin of traffic to ensure proper security boundary enforcement.
5️⃣ Rate Limit and Throttle Mapping	- For each API route, suggest rate limits: - Base RPM (Requests Per Minute) - Burst and exemption flags for handling traffic spikes. - Emit the rate-limit-policy.yaml file containing the rate-limiting configuration.
6️⃣ Security Drift & Scope Diff Check	- If previous-security-spec.yaml is available, perform the following checks: - Detect scope removal or changes. - Compare role → scope mappings to detect discrepancies. - Flag breaking changes or missing encryption to ensure security consistency.
7️⃣ Emit Artifacts and Events	- Outputs include: - api-security.yaml, access-policy-map.yaml, encryption-policy.yaml, service-secrets.yaml, rate-limit-policy.yaml, trust-boundary-map.yaml, and security-events.json. - Emit the SecurityPolicyPublished event containing: - Trace ID - Version - Artifact links - Change summary (if applicable).

---

1️⃣ Parse Inputs

• Load and validate:

  • openapi.yaml, api-surface-summary.md
  • field-retention-map.yaml
  • application-architecture.md
  • security-policies.yaml
  • previous-security-spec.yaml (if present)

• Extract:

  • All routes and HTTP methods
  • Sensitive fields and masking hints
  • Trust boundary types (external/internal/sandbox)
  • Existing scopes, roles, claims (for comparison)

---

2️⃣ Scope and Access Rule Generation

• For each route:

  • Suggest scope using semantic naming: resource.verb
  • Determine if role or claim is required (ABAC support)
  • Generate scope version (client.read.v2) if enabled

• Emit:

  • api-security.yaml
  • access-policy-map.yaml

---

3️⃣ PII and Field-Level Encryption Enforcement

• Match all pii: true fields from field-retention-map.yaml
• Generate:
  • encryption-policy.yaml with flags: encrypted, masked, redactable
  • Enforcement hints for adapters and schema agent

---

4️⃣ Secret Declaration and Trust Planning

• Detect secret usages (e.g., JWT signing keys, encryption keys, API keys)

• Emit:

  • service-secrets.yaml
  • trust-boundary-map.yaml based on call graphs and architecture

• Validate:

  • Each secret must be externalized
  • Trust zones must align with origin of traffic

---

5️⃣ Rate Limit and Throttle Mapping

• For each API route, suggest:
  • Base RPM (requests per minute)
  • Burst and exemption flags
• Emit rate-limit-policy.yaml

---

6️⃣ Security Drift & Scope Diff Check

• If previous-security-spec.yaml is available:
  • Detect scope removal or changes
  • Compare role → scope mappings
  • Flag breaking changes or missing encryption

---

7️⃣ Emit Artifacts and Events

• Outputs:

  • api-security.yaml, access-policy-map.yaml
  • encryption-policy.yaml, service-secrets.yaml, rate-limit-policy.yaml
  • trust-boundary-map.yaml, security-events.json

• Emit SecurityPolicyPublished with:

  • Trace ID
  • Version
  • Artifact links
  • Change summary (if applicable)

---

🧠 Flow Diagram (Mermaid)

flowchart TD
    A[Parse Inputs + Previous Specs] --> B[Generate Scopes and Roles]
    B --> C[Encrypt + Mask Sensitive Fields]
    C --> D[Declare Secrets + Trust Zones]
    D --> E[Rate Limit and Scope Diff]
    E --> F[Emit Artifacts + SecurityPolicyPublished]

Hold "Alt" / "Option" to enable pan & zoom

---

📈 Observability & Telemetry

Span	Purpose
scope_generation.duration_ms	Time to assign all endpoint scopes
pii_field_tagging.total	Count of fields encrypted or masked
secret_detection.retry_count	Times fallback or fix was applied
breaking_change_detected	True/False — triggers version bump
security_event_published	Lifecycle signal for CI/CD

---

🔁 Retry & Fallback Handling

Scenario	Fallback
Scope missing for endpoint	Use inferred scope + append .inferred tag
Unknown secret source	Default to AzureKeyVault, emit warning
Role-scope mismatch	Auto-generate new role or escalate for review
Missing trace_id / user_id fields	Inject into API security map and observability policy

---

🛠️ Skills and Kernel Functions

The Security Architect Agent is composed of modular Semantic Kernel (.NET) skills, each focused on a specific layer of security enforcement and policy generation.
All skills are designed to support retry logic, span observability, and composability across service types.

---

🔐 1. Scope & Claim Modeling Skills

Skill	Purpose
ScopeGeneratorSkill	Suggests scopes for each endpoint (e.g., client.read, invoice.write)
RoleToScopeMapperSkill	Maps platform-defined roles to valid scope sets
ClaimRuleBuilderSkill	Constructs ABAC-style claim conditions (role=admin, level > 2)
ScopeDiffDetectorSkill	Compares previous-security-spec.yaml to detect breaking changes or missing mappings

---

🔏 2. Sensitive Field & PII Protection Skills

Skill	Purpose
FieldSensitivityTaggerSkill	Detects pii, x-encrypted, and x-mask field requirements
EncryptionPolicyAssemblerSkill	Emits encryption-policy.yaml with compliant tags
MaskingProfileSelectorSkill	Suggests masking templates (default.email, ssn.partial)
AuditFieldEnforcerSkill	Ensures trace_id, user_id, tenant_id appear in logs and security maps

---

🔑 3. Secret & Trust Skills

Skill	Purpose
SecretUsageScannerSkill	Detects JWT signing keys, API keys, encryption secrets
SecretDeclarationEmitterSkill	Emits service-secrets.yaml with vault source/path
TrustBoundaryClassifierSkill	Classifies internal, external, shared, and sandbox zones
MTLSPolicyPlannerSkill	Adds mTLS requirement between services in trust boundary map

---

🚦 4. Rate Limit & Abuse Prevention

Skill	Purpose
RateLimitRuleGeneratorSkill	Suggests requestsPerMinute, burst, backoff based on endpoint type
ThrottleExemptionTaggerSkill	Marks internal or elevated-role users for reduced enforcement
RateLimitPolicyEmitterSkill	Outputs rate-limit-policy.yaml with detailed configs

---

📡 5. Lifecycle and Observability Skills

Skill	Purpose
SecurityPolicyPublisherSkill	Emits the SecurityPolicyPublished event, including trace ID and relevant links to ensure that the policy is properly published and tracked.
SecuritySpanTemplateGeneratorSkill	Injects span templates into security-events.json for comprehensive logging and traceability. Example spans include: - access_denied: Logs when access is denied. - token_expired: Logs when a token expires. - rate_limit_triggered: Logs when the rate limit is triggered.
ChangelogEmitterSkill	(Optional) Emits the security-changelog.md file if a version bump is required, ensuring traceability and change management for security-related changes.

---

🧩 Skill Composition Flow

flowchart TD
    A[ScopeGeneratorSkill] --> B[ClaimRuleBuilderSkill]
    B --> C[FieldSensitivityTaggerSkill]
    C --> D[SecretDeclarationEmitterSkill]
    D --> E[RateLimitRuleGeneratorSkill]
    E --> F[SecurityPolicyPublisherSkill]

Hold "Alt" / "Option" to enable pan & zoom

---

🔁 Retry Behaviors (Auto-Fixable Failures)

Skill	Retry Trigger	Correction
ScopeGeneratorSkill	Scope already exists with different claims	Suffix version (.v2) or auto-namespace
SecretDeclarationEmitterSkill	Secret missing source	Default to Azure Key Vault + warn
TrustBoundaryClassifierSkill	Undeclared origin service	Assume external unless whitelisted
RateLimitRuleGeneratorSkill	Too aggressive	Fallback to conservative template (60rpm, burst=5)

---

📈 Skill Metrics Emitted

Metric	Description
scope_generated_total	Count of new scopes created
pii_fields_tagged_total	Number of fields marked for encryption/masking
rate_limit_rules_applied_total	Endpoint-level throttling annotations
trust_boundary_conflict_count	Detected policy mismatches across origin zones
security_event_emitted	Lifecycle events logged to CI and dashboards

---

🛠️ Core Technologies Used

The Security Architect Agent leverages a robust ecosystem of identity, encryption, vaulting, and policy-as-code technologies, all orchestrated within the ConnectSoft AI Software Factory using Semantic Kernel (.NET).

These tools ensure secure-by-default generation, policy propagation, and runtime compliance across all service types.

---

🔐 1. Authentication & Authorization Protocols

Technology	Role
OAuth2	Standard for scopes, flows (PKCE, client credentials)
OpenID Connect	Enriches tokens with identity and claims
JWT (JSON Web Tokens)	Default token format (RS256 recommended)
JWK (Key Set)	Token signature verification and rotation
ABAC/RBAC DSLs	YAML-based policies for claim and role mappings

---

🔑 2. Secret Management & Encryption

Tool	Purpose
Azure Key Vault	Default source for managed secrets, JWT signing keys, DB passwords
HashiCorp Vault	Optional self-hosted secrets manager
KMS (Azure, AWS)	Encrypt fields at rest, rotate encryption keys
Field-level tagging DSL	Defines encrypted, mask, redactable, and ttl in YAML format
Secrets-as-Code Injection	Secure referencing via service-secrets.yaml

---

🧰 3. Policy & Access Enforcement

Tool	Purpose
OPA (Open Policy Agent) (optional downstream enforcement)	Enforce runtime claims and resource access
ConnectSoft Access Map	access-policy-map.yaml describes scopes, roles, conditions
Trust Boundary Mapper	Emits trust-boundary-map.yaml to define internal/external boundaries
Rate Limiter DSL	Defines throttling rules, per-IP/client limits

---

📄 4. Schema and API Integration

Artifact	Role
openapi.yaml	Annotated with security: blocks, scopes, headers
asyncapi.yaml	Annotated with publish/subscribe scope requirements
schema.yaml	Injects x-sensitive, x-encrypted, x-mask on fields
field-retention-map.yaml	Used to correlate PII fields with encryption policy

---

📡 5. Telemetry and Event Publishing

Technology	Function
OpenTelemetry	Emit spans for scope_generation, token_violation, rate_limit_triggered
Azure Event Grid	Publish SecurityPolicyPublished and change events
Prometheus + Grafana	Visualize enforcement metrics across services
Application Insights / ELK	Capture logs from rejected tokens, audit failures

---

📦 6. Output Formats & Compatibility

Format	Description
api-security.yaml	Machine-parseable contract for scopes and claims
access-policy-map.yaml	RBAC + ABAC definitions for services
encryption-policy.yaml	Field-level controls for encryption, masking, redaction
service-secrets.yaml	Secret sources, TTLs, vault paths
security-events.json	Lifecycle signals for observability and CI/CD
security-summary.md	(Optional) audit-friendly Markdown summary

---

🛡️ 7. Compliance Standards Alignment

Standard	Alignment Actions
SOC 2	Audit trail on access policy changes, secrets versioning
GDPR	Redaction, right-to-be-forgotten tagging, masking policies
HIPAA	Field-level protection, encryption at rest, access logs
Zero Trust	No implicit trust between services, mTLS + identity required
PCI-DSS	Masking of cardholder fields, role segregation

---

🧠 Agent Tooling Infrastructure

Technology	Description
Semantic Kernel (.NET)	Agent framework and orchestration layer
YAML DSL processors	Custom schema validators for all *.yaml policies
Mermaid / Markdown generators	Optional doc rendering for security-summary.md
CI/CD Integration (Azure Pipelines)	Gatekeeper for schema validation and contract promotion

---

✅ Summary

Layer	Tools Used
Authentication & Tokenization	OAuth2, OIDC, JWT, JWK
Secrets & Encryption	Azure Key Vault, Vault, KMS
Access Control	access-policy-map.yaml, OPA
Observability	OpenTelemetry, Event Grid
Compliance	SOC 2, GDPR, HIPAA mappings
Output	YAML/JSON contracts, Markdown summaries

---

📜 System Prompt (Bootstrapping Instruction)

The System Prompt defines the initial operating context and expectations of the Security Architect Agent. It ensures that every generated output is secure-by-default, zero-trust aligned, and compliant with ConnectSoft’s platform security model.

---

✅ Full System Prompt (Plain Text)

You are the **Security Architect Agent** within the ConnectSoft AI Software Factory.

Your responsibility is to ensure that all services, APIs, event streams, and storage layers follow a **Security-by-Design** approach and align with Zero Trust principles.

---

## Your Core Tasks:

1. For every API or event:
   - Generate required OAuth2 scopes (e.g., `invoice.read`, `admin.fullAccess`)
   - Map roles to scopes and claims using `access-policy-map.yaml`
   - Annotate `openapi.yaml` and `asyncapi.yaml` with `security` sections

2. For every sensitive field:
   - Tag as `x-sensitive: true`, `x-encrypted: true`, `x-mask: true` if applicable
   - Ensure presence in `encryption-policy.yaml`

3. For every secret or credential:
   - Ensure declaration in `service-secrets.yaml` with source and TTL
   - Prevent any secrets from being hardcoded into generated artifacts

4. For every route:
   - Define rate limits in `rate-limit-policy.yaml`
   - Flag exempt services (e.g., internal agents or trusted CI clients)

5. For service-level trust:
   - Emit `trust-boundary-map.yaml` describing inter-service mTLS zones
   - Enforce identity-based policies for access (e.g., `aud`, `client_id` validation)

6. Publish:
   - `api-security.yaml`, `access-policy-map.yaml`, `encryption-policy.yaml`, `rate-limit-policy.yaml`
   - `security-events.json` with `SecurityPolicyPublished` or `TokenScopeViolationDetected`

---

## Required Output Standards:

- All scopes must be namespaced (e.g., `client.read`, `billing.generateStatement`)
- Every PII field must be tagged and included in encryption map
- Trust boundaries must be versioned and traceable via `trace_id`
- All events must be published to `SecurityEventStream` or output to `security-events.json`
- Output files must include metadata: `agent_version`, `trace_id`, `schema_version`

---

## Versioning:

- Changes in roles, scopes, encryption strategy, or token model = bump policy version
- Breaking security drift = emit changelog + block CI/CD until resolved

---

## Observability:

- Emit spans for:
  - Scope generation
  - Token validation failures
  - Rate limit triggers
  - Secret declaration gaps

- Ensure each span includes `trace_id`, `agent_version`, `service_name`

---

## Policy Failures:

If a violation or incomplete configuration is detected:
- Retry with default/fallback enforcement
- Emit `SecurityPolicyWarning` or `SecurityContractFailed` event
- Block publication if access cannot be resolved safely

---

🧭 Summary of Agent Behavior

With this system prompt:

• All services get scoped, claim-driven access enforcement
• PII fields are always protected and traceable
• Secrets are externalized and source-bound
• Trust boundaries are explicit and contractually enforced
• Outputs are auditable, versioned, and compliance-ready

---

📥 Input Prompt Template

The Security Architect Agent is activated by a YAML-based input prompt provided by ConnectSoft’s orchestration layer.
This prompt defines:

• Service context and traceability metadata
• Links to all relevant source documents (API specs, compliance maps, secrets, architecture)
• Enforcement settings and feature flags
• Output format expectations

---

✅ Example Input Prompt (YAML)

assignment: generate-security-spec

project:
  trace_id: "trace-security-55429"
  project_id: "connectsoft-saas"
  bounded_context: "CRM"
  service_name: "ClientService"
  agent_version: "1.4.0"

inputs:
  openapi_url: "https://artifacts.connectsoft.dev/client/openapi.yaml"
  event_catalog_url: "https://artifacts.connectsoft.dev/client/event-catalog.yaml"
  field_retention_map_url: "https://artifacts.connectsoft.dev/client/field-retention-map.yaml"
  application_architecture_url: "https://artifacts.connectsoft.dev/client/application-architecture.md"
  security_policies_url: "https://artifacts.connectsoft.dev/platform/security-policies.yaml"
  previous_security_spec_url: "https://artifacts.connectsoft.dev/client/security-v1.yaml"

settings:
  enforce_rate_limits: true
  scopes_must_be_versioned: true
  allow_client_credentials_flow: true
  generate_access_summary_markdown: true
  emit_security_events: true

---

📂 Required Fields

📦 project

Field	Description
trace_id	Unique identifier for traceability across all artifacts
service_name	The microservice the security spec applies to
bounded_context	Domain context of the service
agent_version	Version of the Security Architect Agent executing the spec

---

📚 inputs

Artifact	Purpose
openapi_url	Enumerates all routes to generate scopes and security: blocks
event_catalog_url	Defines events and required publish/subscribe_scope
field_retention_map_url	Maps sensitive fields to encryption/masking requirements
application_architecture_url	Declares trust zones and internal/external route exposure
security_policies_url	Global policy posture (e.g., allowed auth flows, token rules)
previous_security_spec_url	Enables diffing for scope/role drift detection (optional)

---

⚙️ settings

Flag	Description
enforce_rate_limits	Enables generation of rate-limit-policy.yaml
scopes_must_be_versioned	Appends .vX to scopes for CI traceability
allow_client_credentials_flow	Enables token strategy compatibility for internal services
generate_access_summary_markdown	Produces security-summary.md for audit reports
emit_security_events	Publishes SecurityPolicyPublished, ScopeViolationDetected, etc.

---

✅ Minimal Prompt Example

assignment: generate-security-spec
project:
  service_name: InvoiceService
  trace_id: trace-994

inputs:
  openapi_url: https://.../invoice/openapi.yaml
  field_retention_map_url: https://.../invoice/field-retention.yaml
  security_policies_url: https://.../security/global.yaml

settings:
  scopes_must_be_versioned: true

---

🧾 Validation Rules

Rule	Description
trace_id, service_name, and openapi_url are required	✅
field_retention_map_url must be present for PII enforcement	✅
security_policies_url required for platform-level constraints	✅
If scopes_must_be_versioned, all generated scopes must end in .vX	✅
Secrets and token models must align with application_architecture.md	✅

---

📈 Trace Metadata Injected into All Outputs

metadata:
  trace_id: trace-security-55429
  service_name: ClientService
  schema_version: v2.1.0
  agent_version: 1.4.0
  generated_on: 2025-05-01T23:59:00Z

---

📤 Output Expectations

The Security Architect Agent generates a complete, versioned, and policy-compliant security specification bundle.
These artifacts are:

• Machine-readable for CI/CD and enforcement agents
• Human-readable (optional) for audits and governance
• Traceable, version-controlled, and lifecycle-linked via events

---

📦 Output Artifact Summary

Artifact	Format	Purpose
api-security.yaml	YAML	Declares OAuth2 scopes, roles, claims per route
access-policy-map.yaml	YAML	Maps roles to scopes and/or claims (RBAC/ABAC)
encryption-policy.yaml	YAML	Flags fields for encryption, masking, or redaction
service-secrets.yaml	YAML	Declares secrets with vault path, type, TTL
rate-limit-policy.yaml	YAML	Throttling rules per method, IP, or role
trust-boundary-map.yaml	YAML	Describes internal vs external communication requirements
security-events.json	JSON	Contains emitted lifecycle or anomaly events
security-summary.md (optional)	Markdown	Human-readable summary for audit or manual review

---

📘 Example: api-security.yaml

paths:
  /clients:
    GET:
      scopes: [client.read.v2]
      requires_mtls: true
      rate_limit:
        rpm: 100
        burst: 10
  /admin/reports:
    GET:
      scopes: [admin.fullAccess.v1]
      required_claims: [role=admin, clearance_level=3]

---

👤 Example: access-policy-map.yaml

roles:
  support_agent:
    scopes:
      - client.read.v2
      - note.write.v1
  admin:
    scopes: ["*"]
    claims:
      - role=admin
      - clearance_level >= 3

---

🔐 Example: encryption-policy.yaml

fields:
  client.email:
    encrypted: true
    pii: true
    mask: true
    masking_profile: default.email
  client.ssn:
    encrypted: true
    redactable: true

---

🔑 Example: service-secrets.yaml

secrets:
  - name: jwt-signing-key
    source: AzureKeyVault
    path: /connectsoft/auth/jwt-signing-key
    rotation_policy: 90d
  - name: db-password
    source: HashiCorpVault
    path: /connectsoft/db/invoice-password
    type: password

---

🧭 Example: trust-boundary-map.yaml

zones:
  internal:
    trusted_proxies: [api-gateway]
    requires_mtls: true
    token_flow: client_credentials
  external:
    requires_mtls: true
    token_flow: authorization_code
    audience_validation: required

---

📡 Example: security-events.json

{
  "event": "SecurityPolicyPublished",
  "trace_id": "trace-security-55429",
  "service": "ClientService",
  "version": "v2.1.0",
  "artifacts": {
    "apiSecurity": "https://.../api-security.yaml",
    "accessMap": "https://.../access-policy-map.yaml"
  },
  "timestamp": "2025-05-01T23:59:00Z"
}

---

📑 (Optional) security-summary.md

A Markdown summary for governance review boards, DevSecOps, and documentation purposes.

---

✅ Output Quality Checklist

Rule	Enforced
Every route must include a scopes: declaration	✅
Every PII field must appear in encryption-policy.yaml	✅
All secrets must have source, type, and path	✅
Internal/external zones must be declared in trust map	✅
At least one SecurityPolicyPublished event is emitted	✅
All outputs include trace_id, agent_version, and schema_version	✅

---

🧠 Memory Model Overview

The Security Architect Agent uses a multi-layered memory model to ensure:

• Consistent scope and claim generation across services
• Role and permission reuse
• Enforcement of historical encryption and trust policies
• Security drift detection (between spec versions)
• Anomaly correction via past patterns and fallback models

This memory includes short-term (in-session) memory and long-term (cross-service semantic) memory.

---

🕐 Short-Term Memory (Session Scoped)

Memory Component	Description
routes_scanned[]	All API endpoints and event topics processed
generated_scopes[]	Scopes proposed per endpoint
claims_applied[]	Any required claims or role-based access
sensitive_fields[]	PII fields tagged for protection
secrets_declared[]	All secrets referenced in this run
trust_zones_defined[]	Internal, external, shared boundaries detected
diff_detected[]	Changes between current and previous-security-spec.yaml
rate_limits_applied[]	RPM/burst metadata assigned per route

---

📚 Long-Term Semantic Memory (Cross-Service)

🔐 1. Scope & Role History

Feature	Purpose
Scope usage frequency	Helps avoid unnecessary proliferation
Known role mappings	Maps support_agent → client.read, note.write
Scopes tagged as "privileged"	Requires claims enforcement (e.g., admin.*)
Scope version history	Tracks semantic changes across client.read.v1 → v2

---

🧾 2. Field Protection Policies

Match	Policy
email, ssn, dob, phone_number	encrypted: true, mask: true, audit: true
Custom field marked pii: true	Enforce redactable: true
Previously encrypted field now untagged	Raise warning: encryption-downgrade-risk

---

🔐 3. Secret Management Patterns

Detected Pattern	Action
JWT signing key present	Require type: rsa, rotation_policy <= 90d
Password fields	Default source = Vault or AzureKeyVault
Hardcoded token in spec	Redact, replace with source_ref and emit warning

---

🧭 4. Trust Boundary Policy Cache

Zone	Default Behaviors
external	mTLS required, token required, rate limit enabled
internal	Client credentials accepted, optional mTLS
sandbox	Reduced claims enforcement, dummy secrets
shared	Scoped token access, tenant isolation enforced

---

🧠 Memory Query Example

query: "What are the default access rules for /admin/settings?"
memory_match:
  scope: admin.fullAccess
  required_claims: [role=admin, clearance_level >= 3]
  zone: external
  mTLS: true
  rate_limit: 25 rpm
  version: admin.fullAccess.v2

---

🧠 Drift Detection and Changelog Memory

Change Detected	Result
Scope removed from endpoint	Raise warning, emit diff entry
Role deleted but still assigned to scope	Auto-remap or escalate
Claims relaxed in access-policy-map.yaml	Suggest escalation or block
Secret source changed from Vault to inline	Escalate to Governance Agent

---

📈 Memory-Aware Changelog Example

changelog:
  version: v2.2.0
  changes:
    - scope_added: note.delete
    - role_scope_reassignment: admin now has note.delete
    - field_encryption_added: client.ssn
    - rate_limit_increased: /clients GET from 60 to 100 rpm
    - trust_zone_promoted: /admin/* moved to external

---

✅ Benefits of Memory Usage

Value	Description
Consistent access modeling	Scopes and roles evolve predictably
Reuse reduces redundancy	Avoids generating 10+ duplicate scopes
Tracks security regressions	Detects field decryption, missing scope bindings
Supports changelogs & CI validation	Required for policy diff pipelines
Enhances fallback safety	Uses past scopes/claims to resolve errors when uncertain

---

✅ Validation and Correction Pipeline

The Security Architect Agent performs multi-layered validation of all generated security artifacts to ensure:

• Policies are complete, traceable, and compliant
• Secrets are externalized
• Scopes and roles are logically consistent
• No breaking changes are introduced without detection
• Outputs are safe for CI/CD pipeline promotion

It automatically corrects, diffs, or escalates based on validation outcomes.

---

🧪 Validation Phases

1️⃣ Schema and Syntax Validation

Artifact	Check
api-security.yaml	Valid YAML, all endpoints present, required scopes defined
access-policy-map.yaml	Unique role names, no orphan scopes, claims resolvable
encryption-policy.yaml	Field names match schema, masking/encryption flags consistent
service-secrets.yaml	All secrets include name, source, path, and type
trust-boundary-map.yaml	Zones well-formed, consistent with app architecture

---

2️⃣ Cross-Artifact Consistency Checks

Rule	Example
Every route in openapi.yaml must exist in api-security.yaml	✅
All pii: true fields in field-retention-map.yaml must be present in encryption-policy.yaml	✅
Roles in access-policy-map.yaml must map to existing scopes	✅
Secrets must be declared in Vault or Key Vault (no source: none)	✅
Scope versions must be monotonic and consistent across updates	✅

---

3️⃣ Security Drift and Regression Detection

Check	Outcome
Scope removed or reassigned	Log as breaking change, block pipeline if unapproved
Encryption tag removed from a previously protected field	Raise critical warning
Trust zone changed from internal → external	Revalidate mTLS, token scope, and claims
Claim requirement relaxed (e.g., role: admin → role: user)	Mark as potential escalation risk

---

🔁 Auto-Correction Behaviors

Issue Detected	Correction
Scope missing for new endpoint	Suggest resource.verb.vX, add to api-security.yaml
Secret missing source	Default to Azure Key Vault, emit warning
PII field unencrypted	Tag as x-encrypted: true, suggest masking profile
Rate limit too permissive (>1000rpm)	Lower to default per service class
Missing required claims on admin.* scope	Suggest role=admin, clearance_level >= 3

---

📜 Correction Example Log

{
  "trace_id": "trace-sec-11992",
  "skill": "ScopeGeneratorSkill",
  "retry": 1,
  "issue": "Missing scope for DELETE /clients/{id}",
  "suggested_scope": "client.delete.v1",
  "correction_applied": true
}

---

🚨 Escalation Triggers

Trigger	Action
3+ unresolvable secrets	Block SecurityPolicyPublished, emit SecurityContractFailed
Trust boundary downgrade (external → internal)	Escalate to Governance Agent
Breaking scope/claim diff	Emit SecurityDriftDetected, require manual approval
PII field encryption downgraded	Block output, emit DataProtectionViolationDetected

---

📈 Observability Metrics Emitted

Metric	Description
scope_generation_failures_total	Number of scopes that required fallback
pii_encryption_missed_total	PII fields missing encryption on first pass
policy_retry_count_by_skill	Retry behavior by skill (used for tuning + audit)
security_drift_detected_total	Total breaking changes compared to prior spec
secrets_missing_source_total	Count of secrets declared without valid vault reference

---

✅ Final Output Guarantee

A SecurityPolicyPublished event is emitted only if:

• All security YAML files pass validation
• All PII fields are covered by encryption policy
• No hardcoded secrets are present
• Role and scope mappings are valid
• All trust zones are respected
• Traceability fields (trace_id, service_name, version) are included in all artifacts

---

🤝 Collaboration Interfaces

The Security Architect Agent operates as a cross-cutting policy generator and enforcer.
It integrates with upstream structural agents and downstream enforcement, DevOps, and observability agents to propagate Zero Trust, compliance, and identity-aware controls.

---

🔼 Upstream Inputs

Agent	Artifacts Provided
API Designer Agent	openapi.yaml, api-surface-summary.md — used for scope generation
Event-Driven Architect Agent	event-catalog.yaml — defines event topics for pub/sub scopes
Data Architect Agent	field-retention-map.yaml, schema.yaml — identifies PII/encrypted fields
Application Architect Agent	application-architecture.md — trust boundaries, origin mapping
Compliance Architect Agent	retention-policy.yaml — additional field compliance enforcement
Solution Architect Agent	security-policies.yaml — global platform-wide security constraints
Glossary Agent (optional)	Glossary entries for common roles, reusable claims, known risk vocab

---

🔽 Downstream Consumers

Agent	Artifacts Consumed
Adapter Generator Agent	access-policy-map.yaml, encryption-policy.yaml — applies RBAC/ABAC enforcement, encrypts/masks fields
DevOps Architect Agent	service-secrets.yaml, trust-boundary-map.yaml — deploys secrets and network policies
API Gateway Configurator Agent	api-security.yaml, rate-limit-policy.yaml — applies per-route security
Test Generator Agent	access-policy-map.yaml, security-summary.md — generates negative access tests, rate limit checks
Observability Agent	security-events.json — listens to and emits trace events for security enforcement violations
Developer Portal Generator Agent	security-summary.md — embeds access rules and data protection indicators in UI

---

📢 Events Emitted

Event	Trigger
SecurityPolicyPublished	Emitted when spec generation completes successfully
SecurityContractFailed	Blocker event if secrets or scope/role violations exist
SecurityDriftDetected	Emitted on version regression, dropped encryption, or deleted roles
ScopeViolationDetected	Optional runtime signal when token lacks required scope (emitted by downstream agent but spec-driven)

---

🔐 Policy Distribution Points

Target	Format	Function
API Gateway	api-security.yaml, rate limits	Enables routing enforcement + JWT validation
Identity Microservice	access-policy-map.yaml	Loads RBAC/ABAC for JWT validation service
Secrets Manager Integration	service-secrets.yaml	Drives Azure Key Vault / Vault resource creation
Service Mesh / mTLS Layer	trust-boundary-map.yaml	Informs service-to-service trust and isolation policies

---

🔄 Collaboration Flow Diagram

flowchart TD
    API_Designer -->|openapi.yaml| SecurityArchitect
    DataArchitect -->|field-retention-map.yaml| SecurityArchitect
    EventArchitect -->|event-catalog.yaml| SecurityArchitect
    ComplianceArchitect -->|retention-policies.yaml| SecurityArchitect

    SecurityArchitect --> AdapterGenerator
    SecurityArchitect --> DevOpsArchitect
    SecurityArchitect --> APIGatewayConfigurator
    SecurityArchitect --> ObservabilityAgent
    SecurityArchitect --> TestGenerator
    SecurityArchitect --> DeveloperPortal

Hold "Alt" / "Option" to enable pan & zoom

---

🧠 Traceability Integration

All artifacts and emitted events include:

metadata:
  trace_id: trace-security-99821
  service_name: ClientService
  schema_version: v2.3.0
  agent_version: 1.4.1
  generated_on: 2025-05-02T00:15:00Z

This enables all downstream agents to align to the same execution trace, ensuring auditability and lifecycle tracking.

---

📡 Observability & Traceability

The Security Architect Agent is fully observable via OpenTelemetry, emits structured events for CI/CD pipelines, and includes embedded metadata for:

• Runtime validation (JWTs, secrets, encryption)
• Policy change tracking (version diffs, trust changes)
• Access control drift detection
• Data protection coverage reporting

All generated files and events carry full agent and execution metadata.

---

🛰️ Emitted Spans

Span Name	Description
scope_generation	Emitted for every scope inferred or diffed
pii_encryption_applied	Field tagging spans (e.g., email, ssn)
secret_declared	Vault reference creation
rate_limit_computed	Rate control decisions per route
security_policy_published	Final span for full contract output
security_drift_detected	Span with severity, version delta, and violated entity

Each span includes:
✅ trace_id
✅ service_name
✅ agent_version
✅ duration_ms
✅ status

---

📢 Lifecycle Event Emission

🔔 SecurityPolicyPublished (Success Signal)

{
  "event": "SecurityPolicyPublished",
  "service": "ClientService",
  "version": "v2.1.0",
  "trace_id": "trace-sec-88239",
  "agent_version": "1.4.1",
  "artifacts": {
    "accessMap": "https://.../access-policy-map.yaml",
    "apiSecurity": "https://.../api-security.yaml"
  },
  "timestamp": "2025-05-02T00:17:00Z"
}

---

⚠️ SecurityContractFailed (Blocking Signal)

Emitted when critical security violation is found and generation is aborted:

• Missing encryption on PII
• Downgraded scope protection
• Role mapping broken
• Secret declared with source: none
• Trust downgrade without mTLS enforcement

---

📊 Dashboards & CI/CD Integration

Dashboard Tile	Source
🔒 Scope Coverage %	api-security.yaml per service
🔐 Secrets Declared / Used	service-secrets.yaml
📉 Drift/Regression Count	Diff engine vs previous spec
🚦 Rate Limit Violations	From runtime Observability Agent
🧪 Token Failure Paths	From security span trace logs
✅ Spec Version & Changelog	From embedded metadata and published events

---

🛠️ Governance Hooks

Action	Result
security-policy.yaml regression	Block promotion to staging/prod
Secrets missing source	Red-flag in CI/CD checks
Trust downgrade	Escalation to human-in-the-loop reviewer
Drift in claim mapping	Notify Compliance Agent + force manual override

---

✅ Final Security Outcomes

With the Security Architect Agent, ConnectSoft ensures:

• ✅ No microservice is deployed without role- or claim-based protection
• ✅ PII data is always tagged, masked, or encrypted
• ✅ Secrets are never exposed in code — only referenced securely
• ✅ Trust zones and traffic origin are enforced via mTLS
• ✅ Full lifecycle of security design is traceable, diffable, and CI-integrated

---

📦 Output Recap

Artifact	Description
api-security.yaml	Route-based scopes, rate limits, mTLS flags
access-policy-map.yaml	Role-based and claim-based mappings
encryption-policy.yaml	Field-level PII/secret tagging
service-secrets.yaml	Secrets with path, type, TTL
trust-boundary-map.yaml	External/internal zones, token validation rules
security-events.json	Lifecycle event feed for observability and audit
security-summary.md	Optional human-readable changelog and role diagram