proagents 1.6.17 → 1.6.18

package/.proagents/secrets/README.md

@@ -1,278 +0,0 @@
-# Secret Management
-
-Secure handling of API keys, credentials, and sensitive data.
-
----
-
-## Overview
-
-Protect sensitive information throughout the development lifecycle.
-
-## Documentation
-
-| Document | Description |
-|----------|-------------|
-| [Secret Storage](./storage.md) | Where to store secrets |
-| [Secret Rotation](./rotation.md) | Rotating credentials |
-| [Access Control](./access-control.md) | Who can access secrets |
-| [Scanning](./scanning.md) | Detecting leaked secrets |
-
----
-
-## Secret Types
-
-| Type | Examples | Storage |
-|------|----------|---------|
-| API Keys | Stripe, Twilio, OpenAI | Vault/SSM |
-| Database | Connection strings, passwords | Vault/SSM |
-| Authentication | JWT secrets, OAuth credentials | Vault/SSM |
-| Infrastructure | AWS keys, SSH keys | Vault/SSM |
-| Encryption | AES keys, certificates | Vault/HSM |
-
----
-
-## Configuration
-
-### Secret Sources
-
-```yaml
-# proagents.config.yaml
-secrets:
-  # Primary source
-  provider: "aws-ssm"  # aws-ssm, vault, azure-keyvault, gcp-secrets
-
-  # Provider config
-  aws_ssm:
-    region: "us-east-1"
-    prefix: "/myapp/"
-
-  # Fallback for development
-  development:
-    provider: "dotenv"
-    file: ".env.local"
-```
-
-### Secret References
-
-```yaml
-# Reference secrets in config
-database:
-  url: "${secrets.DATABASE_URL}"
-
-api:
-  stripe_key: "${secrets.STRIPE_SECRET_KEY}"
-```
-
----
-
-## Secret Scanning
-
-### Pre-Commit Scanning
-
-```yaml
-secrets:
-  scanning:
-    enabled: true
-
-    # When to scan
-    hooks:
-      - "pre-commit"
-      - "pre-push"
-
-    # What to scan for
-    patterns:
-      - name: "AWS Access Key"
-        pattern: "AKIA[0-9A-Z]{16}"
-
-      - name: "Generic API Key"
-        pattern: "api[_-]?key['\"]?\\s*[:=]\\s*['\"][a-zA-Z0-9]{32,}"
-
-      - name: "Private Key"
-        pattern: "-----BEGIN (RSA|DSA|EC|OPENSSH) PRIVATE KEY-----"
-
-    # Block on detection
-    block_commit: true
-```
-
-### Scanning Commands
-
-```bash
-# Scan for secrets
-proagents secrets scan
-
-# Scan specific files
-proagents secrets scan src/
-
-# Scan git history
-proagents secrets scan --history
-
-# Check if clean
-proagents secrets check
-```
-
----
-
-## Secret Rotation
-
-### Rotation Policy
-
-```yaml
-secrets:
-  rotation:
-    enabled: true
-
-    policies:
-      # Rotate database passwords monthly
-      database:
-        interval: "30d"
-        auto_rotate: true
-
-      # Rotate API keys quarterly
-      api_keys:
-        interval: "90d"
-        auto_rotate: false
-        notify_before: "7d"
-
-      # Never auto-rotate these
-      encryption_keys:
-        auto_rotate: false
-        manual_review: true
-```
-
-### Rotation Commands
-
-```bash
-# Check rotation status
-proagents secrets rotation-status
-
-# Rotate specific secret
-proagents secrets rotate DATABASE_PASSWORD
-
-# Schedule rotation
-proagents secrets schedule-rotation API_KEY --date "2024-03-01"
-```
-
----
-
-## Access Control
-
-### Permission Model
-
-```yaml
-secrets:
-  access:
-    roles:
-      developer:
-        read:
-          - "development/*"
-        write: []
-
-      devops:
-        read:
-          - "development/*"
-          - "staging/*"
-          - "production/*"
-        write:
-          - "development/*"
-          - "staging/*"
-
-      admin:
-        read: ["*"]
-        write: ["*"]
-```
-
-### Audit Logging
-
-```yaml
-secrets:
-  audit:
-    enabled: true
-    log_access: true
-    log_changes: true
-
-    # Where to send logs
-    destinations:
-      - "cloudwatch"
-      - "splunk"
-```
-
----
-
-## Best Practices
-
-### Do's
-
-```
-✅ Use secret managers (not env files in production)
-✅ Rotate secrets regularly
-✅ Audit secret access
-✅ Use different secrets per environment
-✅ Encrypt secrets at rest and in transit
-✅ Limit secret access by role
-✅ Scan for leaked secrets
-```
-
-### Don'ts
-
-```
-❌ Commit secrets to git
-❌ Log secrets in application logs
-❌ Share secrets via Slack/email
-❌ Use same secrets across environments
-❌ Store secrets in code comments
-❌ Hardcode secrets in source code
-```
-
----
-
-## Emergency Procedures
-
-### Secret Leak Response
-
-```bash
-# 1. Immediately revoke the leaked secret
-proagents secrets revoke LEAKED_SECRET
-
-# 2. Rotate to new value
-proagents secrets rotate LEAKED_SECRET --emergency
-
-# 3. Audit access
-proagents secrets audit LEAKED_SECRET --since "24h"
-
-# 4. Scan for exposure
-proagents secrets scan --history
-```
-
-### Leak Response Checklist
-
-- [ ] Revoke compromised secret immediately
-- [ ] Generate new secret
-- [ ] Update all services using the secret
-- [ ] Check for unauthorized access
-- [ ] Scan git history for exposure
-- [ ] Document incident
-- [ ] Review access controls
-
----
-
-## Commands Reference
-
-```bash
-# List secrets (names only, not values)
-proagents secrets list
-
-# Get secret value (requires auth)
-proagents secrets get DATABASE_URL
-
-# Set secret
-proagents secrets set API_KEY "value" --env production
-
-# Delete secret
-proagents secrets delete OLD_SECRET
-
-# Sync secrets to environment
-proagents secrets sync --env staging
-
-# Export for backup (encrypted)
-proagents secrets export --encrypt --output secrets.enc
-```

package/.proagents/secrets/access-control.md

@@ -1,443 +0,0 @@
-# Secret Access Control
-
-Managing who and what can access secrets.
-
----
-
-## Access Principles
-
-| Principle | Description |
-|-----------|-------------|
-| **Least Privilege** | Grant minimum necessary access |
-| **Need to Know** | Only those who need it get access |
-| **Separation of Duties** | No single person has all access |
-| **Audit Everything** | Log all access attempts |
-
----
-
-## Role-Based Access
-
-### Configuration
-
-```yaml
-# proagents.config.yaml
-secrets:
-  access_control:
-    enabled: true
-
-    roles:
-      # Read-only access
-      viewer:
-        permissions:
-          - "secrets:read"
-        allowed_secrets:
-          - "public/*"
-
-      # Developer access
-      developer:
-        permissions:
-          - "secrets:read"
-        allowed_secrets:
-          - "development/*"
-          - "staging/*"
-        denied_secrets:
-          - "*/credentials"
-          - "*/api-keys"
-
-      # Operations access
-      operator:
-        permissions:
-          - "secrets:read"
-          - "secrets:rotate"
-        allowed_secrets:
-          - "*"
-        environments:
-          - "staging"
-          - "production"
-
-      # Admin access
-      admin:
-        permissions:
-          - "secrets:*"
-        allowed_secrets:
-          - "*"
-```
-
-### User Assignment
-
-```yaml
-secrets:
-  access_control:
-    users:
-      "developer@company.com":
-        roles: ["developer"]
-        teams: ["frontend"]
-
-      "ops@company.com":
-        roles: ["operator"]
-        teams: ["platform"]
-
-      "admin@company.com":
-        roles: ["admin"]
-        mfa_required: true
-
-    # Team-based access
-    teams:
-      frontend:
-        allowed_secrets:
-          - "frontend/*"
-
-      backend:
-        allowed_secrets:
-          - "backend/*"
-          - "database/*"
-
-      platform:
-        allowed_secrets:
-          - "*"
-```
-
----
-
-## Service Access
-
-### Service Accounts
-
-```yaml
-secrets:
-  access_control:
-    services:
-      # API service
-      api-service:
-        allowed_secrets:
-          - "database/connection-string"
-          - "redis/url"
-          - "jwt/signing-key"
-        environments:
-          - "${ENVIRONMENT}"
-
-      # Worker service
-      worker-service:
-        allowed_secrets:
-          - "database/connection-string"
-          - "queue/credentials"
-        environments:
-          - "${ENVIRONMENT}"
-
-      # CI/CD pipeline
-      ci-pipeline:
-        allowed_secrets:
-          - "ci/*"
-          - "npm/token"
-        allowed_operations:
-          - "read"
-```
-
-### Kubernetes Service Accounts
-
-```yaml
-secrets:
-  access_control:
-    kubernetes:
-      # Bind service accounts to secret access
-      bindings:
-        - service_account: "api-service"
-          namespace: "production"
-          secrets:
-            - "database-credentials"
-            - "api-keys"
-
-        - service_account: "worker"
-          namespace: "production"
-          secrets:
-            - "database-credentials"
-            - "queue-credentials"
-```
-
----
-
-## Access Policies
-
-### Policy Definition
-
-```yaml
-secrets:
-  access_control:
-    policies:
-      # Time-based access
-      production_access:
-        name: "Production Access"
-        conditions:
-          - type: "time_window"
-            days: ["monday", "tuesday", "wednesday", "thursday", "friday"]
-            hours: ["09:00", "18:00"]
-            timezone: "America/New_York"
-
-          - type: "ip_range"
-            ranges:
-              - "10.0.0.0/8"
-              - "192.168.1.0/24"
-
-      # Emergency access
-      emergency_access:
-        name: "Emergency Access"
-        conditions:
-          - type: "requires_approval"
-            approvers: ["security-team", "on-call-manager"]
-
-          - type: "time_limited"
-            duration: "4h"
-
-          - type: "audit_required"
-            notify: ["security@company.com"]
-```
-
-### Vault Policies
-
-```hcl
-# vault/policies/api-service.hcl
-path "secret/data/api/*" {
-  capabilities = ["read"]
-}
-
-path "secret/data/database/connection" {
-  capabilities = ["read"]
-}
-
-path "database/creds/api-role" {
-  capabilities = ["read"]
-}
-
-# Deny access to admin secrets
-path "secret/data/admin/*" {
-  capabilities = ["deny"]
-}
-```
-
-### AWS IAM Policies
-
-```json
-{
-  "Version": "2012-10-17",
-  "Statement": [
-    {
-      "Sid": "AllowReadSecrets",
-      "Effect": "Allow",
-      "Action": [
-        "secretsmanager:GetSecretValue"
-      ],
-      "Resource": [
-        "arn:aws:secretsmanager:*:*:secret:myapp/production/*"
-      ],
-      "Condition": {
-        "StringEquals": {
-          "aws:PrincipalTag/Environment": "production"
-        }
-      }
-    },
-    {
-      "Sid": "DenyAdminSecrets",
-      "Effect": "Deny",
-      "Action": [
-        "secretsmanager:*"
-      ],
-      "Resource": [
-        "arn:aws:secretsmanager:*:*:secret:myapp/admin/*"
-      ]
-    }
-  ]
-}
-```
-
----
-
-## Access Auditing
-
-### Audit Configuration
-
-```yaml
-secrets:
-  access_control:
-    audit:
-      enabled: true
-
-      # Events to log
-      events:
-        - "secret_accessed"
-        - "secret_created"
-        - "secret_updated"
-        - "secret_deleted"
-        - "access_denied"
-        - "policy_changed"
-
-      # Log details
-      log_details:
-        - "timestamp"
-        - "user"
-        - "service"
-        - "secret_name"
-        - "action"
-        - "ip_address"
-        - "user_agent"
-
-      # Storage
-      destinations:
-        - type: "cloudwatch"
-          log_group: "/security/secret-access"
-
-        - type: "siem"
-          endpoint: "${SIEM_ENDPOINT}"
-
-      # Retention
-      retention: "2 years"
-```
-
-### Audit Alerts
-
-```yaml
-secrets:
-  access_control:
-    alerts:
-      # Suspicious access
-      - name: "Unusual Secret Access"
-        condition: |
-          access_count > normal_baseline * 3
-          AND time_of_day NOT IN business_hours
-        severity: "warning"
-        notify: ["security-team"]
-
-      # Access denied spike
-      - name: "Multiple Access Denied"
-        condition: "access_denied_count > 10 IN 5m"
-        severity: "critical"
-        notify: ["security-team", "pagerduty"]
-
-      # Sensitive secret access
-      - name: "Sensitive Secret Accessed"
-        condition: "secret_path MATCHES 'admin/*'"
-        severity: "info"
-        notify: ["security-team"]
-```
-
----
-
-## Emergency Access
-
-### Break-Glass Procedure
-
-```yaml
-secrets:
-  access_control:
-    emergency:
-      enabled: true
-
-      # Break-glass accounts
-      break_glass:
-        accounts:
-          - id: "emergency-1"
-            stored_in: "physical_safe"
-            access_log: "mandatory"
-
-          - id: "emergency-2"
-            stored_in: "cto_vault"
-            access_log: "mandatory"
-
-      # Procedure
-      procedure:
-        steps:
-          - "Contact security team"
-          - "Document incident number"
-          - "Retrieve break-glass credentials"
-          - "Access required secrets"
-          - "Complete incident report"
-          - "Rotate compromised credentials"
-
-      # Automatic actions
-      on_use:
-        - "alert_security_team"
-        - "start_audit_recording"
-        - "expire_in_4_hours"
-        - "require_followup_report"
-```
-
----
-
-## Implementation
-
-### Access Check Middleware
-
-```typescript
-// middleware/secretAccess.ts
-import { SecretAccessPolicy } from '../policies';
-
-export function checkSecretAccess(
-  user: User,
-  secretPath: string,
-  operation: 'read' | 'write' | 'delete'
-): boolean {
-  // Get user's roles and policies
-  const policies = getUserPolicies(user);
-
-  // Check each policy
-  for (const policy of policies) {
-    if (policy.allows(secretPath, operation)) {
-      // Log access
-      auditLog.record({
-        user: user.id,
-        secret: secretPath,
-        operation,
-        allowed: true,
-        timestamp: new Date(),
-      });
-      return true;
-    }
-  }
-
-  // Access denied
-  auditLog.record({
-    user: user.id,
-    secret: secretPath,
-    operation,
-    allowed: false,
-    timestamp: new Date(),
-  });
-
-  return false;
-}
-```
-
----
-
-## Commands
-
-```bash
-# Check access for user
-proagents secrets check-access --user developer@company.com --secret database/password
-
-# List user permissions
-proagents secrets permissions --user developer@company.com
-
-# Grant access
-proagents secrets grant --user developer@company.com --secret api/key --permission read
-
-# Revoke access
-proagents secrets revoke --user developer@company.com --secret api/key
-
-# View audit log
-proagents secrets audit-log --last 24h
-
-# Request emergency access
-proagents secrets emergency-access --reason "Production incident" --duration 4h
-```
-
----
-
-## Best Practices
-
-1. **Least Privilege**: Start with no access, grant as needed
-2. **Regular Reviews**: Audit access quarterly
-3. **Separation of Duties**: No one person has all keys
-4. **Time-Based Access**: Limit access to business hours when possible
-5. **Audit Everything**: Log all access, successful or not
-6. **Emergency Procedures**: Document and test break-glass access
-7. **Automate Reviews**: Use tools to flag excessive permissions