@monoes/monomindcli 2.15.3 → 2.15.5

package/org-skills/secrets-vault-manager/references/cloud_secret_stores.md

@@ -0,0 +1,354 @@
+# Cloud Secret Store Reference
+
+## Provider Comparison
+
+### Feature Matrix
+
+| Feature | AWS Secrets Manager | Azure Key Vault | GCP Secret Manager |
+|---------|--------------------|-----------------|--------------------|
+| **Secret types** | String, binary | Secrets, keys, certificates | String, binary |
+| **Max secret size** | 64 KB | 25 KB (secret), 200 KB (cert) | 64 KB |
+| **Versioning** | Automatic (all versions) | Manual enable per secret | Automatic |
+| **Rotation** | Built-in Lambda rotation | Custom via Functions/Logic Apps | Custom via Cloud Functions |
+| **Encryption** | AWS KMS (default or CMK) | HSM-backed (FIPS 140-2 L2) | Google-managed or CMEK |
+| **Cross-region** | Replication to multiple regions | Geo-redundant by SKU | Replication supported |
+| **Access control** | IAM + resource-based policies | RBAC + access policies | IAM bindings |
+| **Audit** | CloudTrail | Azure Monitor + Diagnostics | Cloud Audit Logs |
+| **Secret references** | ARN | Vault URI + secret name | Resource name |
+| **Cost model** | $0.40/secret/mo + $0.05/10K calls | $0.03/10K ops (Standard) | $0.06/10K access ops |
+| **Free tier** | No | No | 6 active versions free |
+
+### Decision Guide
+
+**Choose AWS Secrets Manager when:**
+- Fully on AWS
+- Need native RDS/Aurora/Redshift rotation
+- Using ECS/EKS with native AWS IAM integration
+- Cross-account secret sharing via resource policies
+
+**Choose Azure Key Vault when:**
+- Azure-primary workloads
+- Certificate lifecycle management is critical (built-in CA integration)
+- Need HSM-backed key protection (Premium SKU)
+- Azure AD conditional access integration required
+
+**Choose GCP Secret Manager when:**
+- GCP-primary workloads
+- Using GKE with Workload Identity
+- Want simplest API surface (few concepts, fast to integrate)
+- Cost-sensitive (generous free tier)
+
+**Choose HashiCorp Vault when:**
+- Multi-cloud or hybrid environments
+- Dynamic secrets (database, cloud IAM, SSH) are primary use case
+- Need transit encryption, PKI, or SSH CA
+- Regulatory requirement for self-hosted secret management
+
+## AWS Secrets Manager
+
+### Access Patterns
+
+```python
+import boto3
+import json
+from botocore.exceptions import ClientError
+
+def get_secret(secret_name, region="us-east-1"):
+    """Retrieve secret from AWS Secrets Manager."""
+    client = boto3.client("secretsmanager", region_name=region)
+    try:
+        response = client.get_secret_value(SecretId=secret_name)
+    except ClientError as e:
+        code = e.response["Error"]["Code"]
+        if code == "ResourceNotFoundException":
+            raise ValueError(f"Secret {secret_name} not found")
+        elif code == "DecryptionFailureException":
+            raise RuntimeError("KMS decryption failed — check key permissions")
+        raise
+    if "SecretString" in response:
+        return json.loads(response["SecretString"])
+    return response["SecretBinary"]
+```
+
+### Rotation with Lambda
+
+```python
+# rotation_lambda.py — skeleton for custom rotation
+def lambda_handler(event, context):
+    secret_id = event["SecretId"]
+    step = event["Step"]
+    token = event["ClientRequestToken"]
+    client = boto3.client("secretsmanager")
+
+    if step == "createSecret":
+        # Generate new credentials
+        new_password = generate_password()
+        client.put_secret_value(
+            SecretId=secret_id,
+            ClientRequestToken=token,
+            SecretString=json.dumps({"password": new_password}),
+            VersionStages=["AWSPENDING"],
+        )
+    elif step == "setSecret":
+        # Apply new credentials to the target service
+        pending = get_secret_version(client, secret_id, "AWSPENDING", token)
+        apply_credentials(pending)
+    elif step == "testSecret":
+        # Verify new credentials work
+        pending = get_secret_version(client, secret_id, "AWSPENDING", token)
+        test_connection(pending)
+    elif step == "finishSecret":
+        # Mark AWSPENDING as AWSCURRENT
+        client.update_secret_version_stage(
+            SecretId=secret_id,
+            VersionStage="AWSCURRENT",
+            MoveToVersionId=token,
+            RemoveFromVersionId=get_current_version(client, secret_id),
+        )
+```
+
+### IAM Policy for Secret Access
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["secretsmanager:GetSecretValue"],
+      "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:production/api/*",
+      "Condition": {
+        "StringEquals": {
+          "aws:RequestedRegion": "us-east-1"
+        }
+      }
+    }
+  ]
+}
+```
+
+### Cross-Account Access
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {"AWS": "arn:aws:iam::987654321098:role/shared-secret-reader"},
+      "Action": "secretsmanager:GetSecretValue",
+      "Resource": "*",
+      "Condition": {
+        "ForAnyValue:StringEquals": {
+          "secretsmanager:VersionStage": "AWSCURRENT"
+        }
+      }
+    }
+  ]
+}
+```
+
+## Azure Key Vault
+
+### Access Patterns
+
+```python
+from azure.identity import DefaultAzureCredential, ManagedIdentityCredential
+from azure.keyvault.secrets import SecretClient
+
+def get_secret(vault_url, secret_name, use_managed_identity=True):
+    """Retrieve secret from Azure Key Vault."""
+    if use_managed_identity:
+        credential = ManagedIdentityCredential()
+    else:
+        credential = DefaultAzureCredential()
+    client = SecretClient(vault_url=vault_url, credential=credential)
+    return client.get_secret(secret_name).value
+
+def list_secrets(vault_url):
+    """List all secret names (not values)."""
+    credential = DefaultAzureCredential()
+    client = SecretClient(vault_url=vault_url, credential=credential)
+    return [s.name for s in client.list_properties_of_secrets()]
+```
+
+### RBAC vs Access Policies
+
+**RBAC (recommended):**
+- Uses Azure AD roles (`Key Vault Secrets User`, `Key Vault Secrets Officer`)
+- Managed at subscription/resource group/vault level
+- Audit via Azure AD activity logs
+
+**Access Policies (legacy):**
+- Per-vault configuration
+- Object ID based
+- No inheritance from resource group
+
+```bash
+# Assign RBAC role
+az role assignment create \
+  --role "Key Vault Secrets User" \
+  --assignee <service-principal-id> \
+  --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.KeyVault/vaults/<vault>
+```
+
+### Certificate Management
+
+Azure Key Vault has first-class certificate management with automatic renewal:
+
+```bash
+# Create certificate with auto-renewal
+az keyvault certificate create \
+  --vault-name my-vault \
+  --name api-tls \
+  --policy @cert-policy.json
+
+# cert-policy.json
+{
+  "issuerParameters": {"name": "Self"},
+  "keyProperties": {"keyType": "RSA", "keySize": 2048},
+  "lifetimeActions": [
+    {"action": {"actionType": "AutoRenew"}, "trigger": {"daysBeforeExpiry": 30}}
+  ],
+  "x509CertificateProperties": {
+    "subject": "CN=api.example.com",
+    "validityInMonths": 12
+  }
+}
+```
+
+## GCP Secret Manager
+
+### Access Patterns
+
+```python
+from google.cloud import secretmanager
+
+def get_secret(project_id, secret_id, version="latest"):
+    """Retrieve secret from GCP Secret Manager."""
+    client = secretmanager.SecretManagerServiceClient()
+    name = f"projects/{project_id}/secrets/{secret_id}/versions/{version}"
+    response = client.access_secret_version(request={"name": name})
+    return response.payload.data.decode("UTF-8")
+
+def create_secret(project_id, secret_id, secret_value):
+    """Create a new secret with initial version."""
+    client = secretmanager.SecretManagerServiceClient()
+    parent = f"projects/{project_id}"
+
+    # Create the secret resource
+    secret = client.create_secret(
+        request={
+            "parent": parent,
+            "secret_id": secret_id,
+            "secret": {"replication": {"automatic": {}}},
+        }
+    )
+
+    # Add a version with the secret value
+    client.add_secret_version(
+        request={
+            "parent": secret.name,
+            "payload": {"data": secret_value.encode("UTF-8")},
+        }
+    )
+    return secret.name
+```
+
+### Workload Identity for GKE
+
+Eliminate service account key files by binding Kubernetes service accounts to GCP IAM:
+
+```bash
+# Create IAM binding
+gcloud iam service-accounts add-iam-policy-binding \
+  secret-accessor@my-project.iam.gserviceaccount.com \
+  --role roles/iam.workloadIdentityUser \
+  --member "serviceAccount:my-project.svc.id.goog[namespace/ksa-name]"
+
+# Annotate Kubernetes service account
+kubectl annotate serviceaccount ksa-name \
+  --namespace namespace \
+  iam.gke.io/gcp-service-account=secret-accessor@my-project.iam.gserviceaccount.com
+```
+
+### IAM Policy
+
+```bash
+# Grant secret accessor role to a service account
+gcloud secrets add-iam-policy-binding my-secret \
+  --member="serviceAccount:my-app@my-project.iam.gserviceaccount.com" \
+  --role="roles/secretmanager.secretAccessor"
+```
+
+## Cross-Cloud Patterns
+
+### Abstraction Layer
+
+When operating multi-cloud, create a thin abstraction that normalizes secret access:
+
+```python
+# secret_client.py — cross-cloud abstraction
+class SecretClient:
+    def __init__(self, provider, **kwargs):
+        if provider == "aws":
+            self._client = AWSSecretClient(**kwargs)
+        elif provider == "azure":
+            self._client = AzureSecretClient(**kwargs)
+        elif provider == "gcp":
+            self._client = GCPSecretClient(**kwargs)
+        elif provider == "vault":
+            self._client = VaultSecretClient(**kwargs)
+        else:
+            raise ValueError(f"Unknown provider: {provider}")
+
+    def get(self, key):
+        return self._client.get(key)
+
+    def set(self, key, value):
+        return self._client.set(key, value)
+```
+
+### Migration Strategy
+
+When migrating between providers:
+
+1. **Dual-write phase** — Write to both old and new store simultaneously
+2. **Dual-read phase** — Read from new store, fallback to old
+3. **Cut-over** — Read exclusively from new store
+4. **Cleanup** — Remove secrets from old store after grace period
+
+### Secret Synchronization
+
+For hybrid setups (e.g., Vault as primary, cloud SM for specific workloads):
+
+- Use Vault's cloud secret engines to generate cloud-native credentials dynamically
+- Or use External Secrets Operator to sync from Vault into cloud-native stores
+- Never manually copy secrets between stores — always automate
+
+## Caching and Performance
+
+### Client-Side Caching
+
+All three cloud providers support caching SDKs:
+
+- **AWS:** `aws-secretsmanager-caching-python` — caches with configurable TTL
+- **Azure:** Built-in HTTP caching in SDK, or use Azure App Configuration
+- **GCP:** No official caching library — implement in-process cache with TTL
+
+### Caching Rules
+
+1. Cache TTL should be shorter than rotation period (e.g., cache 5 min if rotating every 30 days)
+2. Implement cache invalidation on secret version change events
+3. Never cache secrets to disk — in-memory only
+4. Log cache hits/misses for debugging rotation issues
+
+## Compliance Mapping
+
+| Requirement | AWS SM | Azure KV | GCP SM | Vault |
+|------------|--------|----------|--------|-------|
+| SOC 2 audit trail | CloudTrail | Monitor logs | Audit Logs | Audit device |
+| HIPAA encryption | KMS (BAA) | HSM (BAA) | CMEK (BAA) | Auto-encrypt |
+| PCI DSS key mgmt | KMS compliance | Premium HSM | CMEK | Transit engine |
+| GDPR data residency | Region selection | Region selection | Region selection | Self-hosted |
+| ISO 27001 | Certified | Certified | Certified | Self-certify |

package/org-skills/secrets-vault-manager/references/emergency_procedures.md

@@ -0,0 +1,280 @@
+# Emergency Procedures Reference
+
+## Secret Leak Response Playbook
+
+### Severity Classification
+
+| Severity | Definition | Response Time | Example |
+|----------|-----------|---------------|---------|
+| **P0 — Critical** | Production credentials exposed publicly | Immediate (15 min) | Database password in public GitHub repo |
+| **P1 — High** | Internal credentials exposed beyond intended scope | 1 hour | API key in build logs accessible to wider org |
+| **P2 — Medium** | Non-production credentials exposed | 4 hours | Staging DB password in internal wiki |
+| **P3 — Low** | Expired or limited-scope credential exposed | 24 hours | Rotated API key found in old commit history |
+
+### P0/P1 Response Procedure
+
+**Phase 1: Contain (0-15 minutes)**
+
+1. **Identify the leaked secret**
+   - What credential was exposed? (type, scope, permissions)
+   - Where was it exposed? (repo, log, error page, third-party service)
+   - When was it first exposed? (commit timestamp, log timestamp)
+   - Is the exposure still active? (repo public? log accessible?)
+
+2. **Revoke immediately**
+   - Database password: `ALTER ROLE app_user WITH PASSWORD 'new_password';`
+   - API key: Regenerate via provider console/API
+   - Vault token: `vault token revoke <token>`
+   - AWS access key: `aws iam delete-access-key --access-key-id <key>`
+   - Cloud service account: Delete and recreate key
+   - TLS certificate: Revoke via CA, generate new certificate
+
+3. **Remove exposure**
+   - Public repo: Remove file, force-push to remove from history, request GitHub cache purge
+   - Build logs: Delete log artifacts, rotate CI/CD secrets
+   - Error page: Deploy fix to suppress secret in error output
+   - Third-party: Contact vendor for log purge if applicable
+
+4. **Deploy new credentials**
+   - Update secret store with rotated credential
+   - Restart affected services to pick up new credential
+   - Verify services are healthy with new credential
+
+**Phase 2: Assess (15-60 minutes)**
+
+5. **Audit blast radius**
+   - Query Vault/cloud SM audit logs for the compromised credential
+   - Check for unauthorized usage during the exposure window
+   - Review network logs for suspicious connections from unknown IPs
+   - Check if the compromised credential grants access to other secrets (privilege escalation)
+
+6. **Notify stakeholders**
+   - Security team (always)
+   - Service owners for affected systems
+   - Compliance team if regulated data was potentially accessed
+   - Legal if customer data may have been compromised
+   - Executive leadership for P0 incidents
+
+**Phase 3: Recover (1-24 hours)**
+
+7. **Rotate adjacent credentials**
+   - If the leaked credential could access other secrets, rotate those too
+   - If a Vault token leaked, check what policies it had — rotate everything accessible
+
+8. **Harden against recurrence**
+   - Add pre-commit hook to detect secrets (e.g., `gitleaks`, `detect-secrets`)
+   - Review CI/CD pipeline for secret masking
+   - Audit who has access to the source of the leak
+
+**Phase 4: Post-Mortem (24-72 hours)**
+
+9. **Document incident**
+   - Timeline of events
+   - Root cause analysis
+   - Impact assessment
+   - Remediation actions taken
+   - Preventive measures added
+
+### Response Communication Template
+
+```
+SECURITY INCIDENT — SECRET EXPOSURE
+Severity: P0/P1
+Time detected: YYYY-MM-DD HH:MM UTC
+Secret type: [database password / API key / token / certificate]
+Exposure vector: [public repo / build log / error output / other]
+Status: [CONTAINED / INVESTIGATING / RESOLVED]
+
+Immediate actions taken:
+- [ ] Credential revoked at source
+- [ ] Exposure removed
+- [ ] New credential deployed
+- [ ] Services verified healthy
+- [ ] Audit log review in progress
+
+Blast radius assessment: [PENDING / COMPLETE — no unauthorized access / COMPLETE — unauthorized access detected]
+
+Next update: [time]
+Incident commander: [name]
+```
+
+## Vault Seal/Unseal Procedures
+
+### Understanding Seal Status
+
+Vault uses a **seal** mechanism to protect the encryption key hierarchy. When sealed, Vault cannot decrypt any data or serve any requests.
+
+```
+Sealed State:
+  Vault process running → YES
+  API responding → YES (503 Sealed)
+  Serving secrets → NO
+  All active leases → FROZEN (not revoked)
+  Audit logging → NO
+
+Unsealed State:
+  Vault process running → YES
+  API responding → YES (200 OK)
+  Serving secrets → YES
+  Active leases → RESUMING
+  Audit logging → YES
+```
+
+### When to Seal Vault (Emergency Only)
+
+Seal Vault when:
+- Active intrusion on Vault infrastructure is confirmed
+- Vault server compromise is suspected (unauthorized root access)
+- Encryption key material may have been extracted
+- Regulatory/legal hold requires immediate data access prevention
+
+**Do NOT seal for:**
+- Routine maintenance (use graceful shutdown instead)
+- Single-node issues in HA cluster (let standby take over)
+- Suspected secret leak (revoke the secret, don't seal Vault)
+
+### Seal Procedure
+
+```bash
+# Seal a single node
+vault operator seal
+
+# Seal all nodes (HA cluster)
+# Seal each node individually — leader last
+vault operator seal -address=https://vault-standby-1:8200
+vault operator seal -address=https://vault-standby-2:8200
+vault operator seal -address=https://vault-leader:8200
+```
+
+**Impact of sealing:**
+- All active client connections dropped immediately
+- All token and lease timers paused
+- Applications lose secret access — prepare for cascading failures
+- Monitoring will fire alerts for sealed state
+
+### Unseal Procedure (Shamir Keys)
+
+Requires a quorum of key holders (e.g., 3 of 5).
+
+```bash
+# Each key holder provides their unseal key
+vault operator unseal <key-1>
+vault operator unseal <key-2>
+vault operator unseal <key-3>
+# Vault unseals after reaching threshold
+```
+
+**Operational checklist after unseal:**
+1. Verify health: `vault status` shows `Sealed: false`
+2. Check audit devices: `vault audit list` — confirm all enabled
+3. Check auth methods: `vault auth list`
+4. Verify HA status: `vault operator raft list-peers`
+5. Check lease count: monitor `vault.expire.num_leases`
+6. Verify applications reconnecting (check application logs)
+
+### Unseal Procedure (Auto-Unseal)
+
+If using cloud KMS auto-unseal, Vault unseals automatically on restart:
+
+```bash
+# Restart Vault service
+systemctl restart vault
+
+# Verify unseal (should happen within seconds)
+vault status
+```
+
+**If auto-unseal fails:**
+- Check cloud KMS key permissions (IAM role may have been modified)
+- Check network connectivity to cloud KMS endpoint
+- Check KMS key status (not disabled, not scheduled for deletion)
+- Check Vault logs: `journalctl -u vault -f`
+
+## Mass Credential Rotation Procedure
+
+When a broad compromise requires rotating many credentials simultaneously.
+
+### Pre-Rotation Checklist
+
+- [ ] Identify all credentials in scope
+- [ ] Map credential dependencies (which services use which credentials)
+- [ ] Determine rotation order (databases before applications)
+- [ ] Prepare rollback plan for each credential
+- [ ] Notify all service owners
+- [ ] Schedule maintenance window if zero-downtime not possible
+- [ ] Stage new credentials in secret store (but don't activate yet)
+
+### Rotation Order
+
+1. **Infrastructure credentials** — Database root passwords, cloud IAM admin keys
+2. **Service credentials** — Application database users, API keys
+3. **Integration credentials** — Third-party API keys, webhook secrets
+4. **Human credentials** — Force password reset, revoke SSO sessions
+
+### Rollback Plan
+
+For each credential, document:
+- Previous value (store in sealed emergency envelope or HSM)
+- How to revert (specific command or API call)
+- Verification step (how to confirm old credential works)
+- Maximum time to rollback (SLA)
+
+## Vault Recovery Procedures
+
+### Lost Unseal Keys
+
+If unseal keys are lost and auto-unseal is not configured:
+
+1. **If Vault is currently unsealed:** Enable auto-unseal immediately, then reseal/unseal with KMS
+2. **If Vault is sealed:** Data is irrecoverable without keys. Restore from Raft snapshot backup
+3. **Prevention:** Store unseal keys in separate, secure locations (HSMs, safety deposit boxes). Use auto-unseal for production.
+
+### Raft Cluster Recovery
+
+**Single node failure (cluster still has quorum):**
+```bash
+# Remove failed peer
+vault operator raft remove-peer <failed-node-id>
+
+# Add replacement node
+# (new node joins via retry_join in config)
+```
+
+**Loss of quorum (majority of nodes failed):**
+```bash
+# On a surviving node with recent data
+vault operator raft join -leader-ca-cert=@ca.crt https://surviving-node:8200
+
+# If no node survives, restore from snapshot
+vault operator raft snapshot restore /backups/latest.snap
+```
+
+### Root Token Recovery
+
+If root token is lost (it should be revoked after initial setup):
+
+```bash
+# Generate new root token (requires unseal key quorum)
+vault operator generate-root -init
+# Each key holder provides their key
+vault operator generate-root -nonce=<nonce> <unseal-key>
+# After quorum, decode the encoded token
+vault operator generate-root -decode=<encoded-token> -otp=<otp>
+```
+
+**Best practice:** Generate a root token only when needed, complete the task, then revoke it:
+```bash
+vault token revoke <root-token>
+```
+
+## Incident Severity Escalation Matrix
+
+| Signal | Escalation |
+|--------|-----------|
+| Single secret exposed in internal log | P2 — Rotate secret, add log masking |
+| Secret in public repository (no evidence of use) | P1 — Immediate rotation, history scrub |
+| Secret in public repository (evidence of unauthorized use) | P0 — Full incident response, legal notification |
+| Vault node compromised | P0 — Seal cluster, rotate all accessible secrets |
+| Cloud KMS key compromised | P0 — Create new key, re-encrypt all secrets, rotate all credentials |
+| Audit log gap detected | P1 — Investigate cause, assume worst case for gap period |
+| Multiple failed auth attempts from unknown source | P2 — Block source, investigate, rotate targeted credentials |