fedramp-20x-mcp 0.4.8__py3-none-any.whl

fedramp_20x_mcp/tools/evidence.py

@@ -0,0 +1,701 @@
+"""
+FedRAMP 20x MCP Server - Evidence Tools
+
+This module contains tool implementation functions for evidence.
+"""
+import json
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+async def get_infrastructure_code_for_ksi_impl(ksi_id: str, data_loader, get_infrastructure_template, infrastructure_type: str = "bicep") -> str:
+    """
+    Get Infrastructure-as-Code templates for automated KSI evidence collection.
+    
+    Provides Bicep or Terraform templates to deploy Azure resources needed for
+    collecting and storing evidence for specific KSI requirements.
+    
+    Args:
+        ksi_id: The KSI identifier (e.g., "KSI-IAM-01", "KSI-MLA-01")
+        infrastructure_type: Type of IaC template ("bicep" or "terraform")
+    
+    Returns:
+        Infrastructure-as-Code template with deployment instructions
+    """
+    # Normalize inputs
+    ksi_id = ksi_id.upper()
+    infrastructure_type = infrastructure_type.lower()
+    
+    # Get the KSI details
+    ksi = data_loader.get_ksi(ksi_id)
+    if not ksi:
+        return f"KSI '{ksi_id}' not found. Use list_ksi to see all available KSIs."
+    
+    ksi_name = ksi.get("name", ksi_id)
+    ksi_description = ksi.get("description", "")
+    
+    # Build the response based on KSI family
+    family = ksi_id.split("-")[1] if "-" in ksi_id else ""
+    
+    result = f"""# Infrastructure-as-Code for {ksi_id}: {ksi_name}
+
+**Requirement:** {ksi_description}
+
+## Evidence Collection Strategy
+
+This infrastructure automates evidence collection for {ksi_id} by:
+1. Deploying necessary Azure resources for monitoring/logging
+2. Configuring automated data collection
+3. Storing evidence in secure, immutable storage
+4. Providing APIs for Authorization Data Sharing (FRR-ADS)
+
+"""
+
+    # Add specific IaC templates based on KSI family
+    if family == "IAM":
+        result += _get_iam_infrastructure(ksi_id, infrastructure_type, get_infrastructure_template)
+    elif family == "MLA":
+        result += _get_mla_infrastructure(ksi_id, infrastructure_type, get_infrastructure_template)
+    elif family == "AFR":
+        result += _get_afr_infrastructure(ksi_id, infrastructure_type, get_infrastructure_template)
+    elif family == "CNA":
+        result += _get_cna_infrastructure(ksi_id, infrastructure_type, get_infrastructure_template)
+    elif family == "RPL":
+        result += _get_rpl_infrastructure(ksi_id, infrastructure_type, get_infrastructure_template)
+    elif family == "SVC":
+        result += _get_svc_infrastructure(ksi_id, infrastructure_type, get_infrastructure_template)
+    else:
+        result += _get_generic_infrastructure(ksi_id, infrastructure_type, get_infrastructure_template)
+    
+    result += """
+
+## Deployment Instructions
+
+### Prerequisites
+- Azure CLI installed and authenticated
+- Appropriate Azure subscription permissions
+- Resource group created for FedRAMP resources
+
+### Deploy with Azure CLI
+```bash
+# Create resource group if needed
+az group create --name rg-fedramp-evidence --location eastus
+
+# Deploy template
+az deployment group create \\
+    --resource-group rg-fedramp-evidence \\
+    --template-file main.bicep \\
+    --parameters @parameters.json
+
+# Verify deployment
+az deployment group show \\
+    --resource-group rg-fedramp-evidence \\
+    --name main
+```
+
+### Post-Deployment Configuration
+1. Configure data sources to send logs/metrics to deployed resources
+2. Set up automated collection schedules (Azure Functions/Automation)
+3. Test evidence collection end-to-end
+4. Integrate with Authorization Data Sharing API
+5. Document infrastructure in System Security Plan
+
+## Maintenance
+- Review storage capacity monthly
+- Update retention policies as needed
+- Test evidence retrieval quarterly
+- Update IaC templates when Azure resources change
+
+*Generated by FedRAMP 20x MCP Server - Infrastructure Code Tool*
+"""
+    
+    return result
+
+
+def _get_iam_infrastructure(ksi_id: str, infra_type: str, get_infrastructure_template) -> str:
+    """Generate IAM-specific infrastructure code using templates."""
+    return get_infrastructure_template('iam', infra_type)
+
+
+def _get_mla_infrastructure(ksi_id: str, infra_type: str, get_infrastructure_template) -> str:
+    """Generate MLA (Monitoring, Logging & Analysis) infrastructure code using templates."""
+    return get_infrastructure_template('mla', infra_type)
+
+
+def _get_afr_infrastructure(ksi_id: str, infra_type: str, get_infrastructure_template) -> str:
+    """Generate Authorization Framework infrastructure code using templates."""
+    return get_infrastructure_template('afr', infra_type)
+
+
+def _get_cna_infrastructure(ksi_id: str, infra_type: str, get_infrastructure_template) -> str:
+    """Generate Cloud Native Architecture infrastructure code using templates."""
+    return get_infrastructure_template('cna', infra_type)
+
+
+def _get_rpl_infrastructure(ksi_id: str, infra_type: str, get_infrastructure_template) -> str:
+    """Generate Recovery & Planning infrastructure code using templates."""
+    return get_infrastructure_template('rpl', infra_type)
+
+
+def _get_svc_infrastructure(ksi_id: str, infra_type: str, get_infrastructure_template) -> str:
+    """Generate Service Management infrastructure code using templates."""
+    return get_infrastructure_template('svc', infra_type)
+
+
+def _get_generic_infrastructure(ksi_id: str, infra_type: str, get_infrastructure_template) -> str:
+    """Generate generic evidence collection infrastructure using templates."""
+    return get_infrastructure_template('generic', infra_type)
+
+
+
+async def get_evidence_collection_code_impl(ksi_id: str, data_loader, get_code_template, language: str = "python") -> str:
+    """
+    Get code examples for collecting KSI evidence programmatically.
+    
+    Provides production-ready code in Python, C#, or PowerShell for automating
+    evidence collection and storage for specific KSI requirements.
+    
+    Args:
+        ksi_id: The KSI identifier (e.g., "KSI-IAM-01", "KSI-MLA-01")
+        language: Programming language ("python", "csharp", or "powershell")
+    
+    Returns:
+        Code examples with explanations for evidence collection
+    """
+    # Normalize inputs
+    ksi_id = ksi_id.upper()
+    language = language.lower()
+    
+    if language not in ["python", "csharp", "powershell"]:
+        return f"Language '{language}' not supported. Choose: python, csharp, or powershell"
+    
+    # Get the KSI details
+    ksi = data_loader.get_ksi(ksi_id)
+    if not ksi:
+        return f"KSI '{ksi_id}' not found. Use list_ksi to see all available KSIs."
+    
+    ksi_name = ksi.get("name", ksi_id)
+    ksi_description = ksi.get("description", "")
+    
+    result = f"""# Evidence Collection Code for {ksi_id}: {ksi_name}
+
+**Requirement:** {ksi_description}
+
+**Language:** {language.title()}
+
+## Overview
+
+This code automates evidence collection for {ksi_id} by:
+1. Querying Azure resources for compliance data
+2. Formatting evidence in a structured format
+3. Storing evidence in Azure Blob Storage
+4. Generating metadata for Authorization Data Sharing API
+
+"""
+
+    # Generate language-specific code based on KSI family
+    family = ksi_id.split("-")[1] if "-" in ksi_id else ""
+    
+    if language == "python":
+        result += _get_python_evidence_code(ksi_id, family, get_code_template)
+    elif language == "csharp":
+        result += _get_csharp_evidence_code(ksi_id, family, get_code_template)
+    elif language == "powershell":
+        result += _get_powershell_evidence_code(ksi_id, family, get_code_template)
+    
+    result += """
+
+## Deployment
+
+### Option 1: Azure Function (Scheduled)
+Deploy as an Azure Function with timer trigger for automated daily collection.
+
+### Option 2: Azure Automation Runbook
+Deploy as an Automation Runbook for scheduled execution.
+
+### Option 3: GitHub Actions
+Run via GitHub Actions on a schedule for evidence collection.
+
+## Testing
+
+Test the code locally before deploying:
+1. Set up Azure authentication (Azure CLI or Managed Identity)
+2. Run the script with test parameters
+3. Verify evidence is collected and stored correctly
+4. Check evidence format matches OSCAL/FRR-ADS requirements
+
+## Monitoring
+
+- Log all collection runs to Azure Monitor
+- Alert on collection failures
+- Track evidence volume over time
+- Monitor storage costs
+
+*Generated by FedRAMP 20x MCP Server - Evidence Collection Code Tool*
+"""
+    
+    return result
+
+
+def _get_python_evidence_code(ksi_id: str, family: str, get_code_template) -> str:
+    """Generate Python evidence collection code using templates."""
+    return get_code_template(family, 'python')
+
+
+def _get_csharp_evidence_code(ksi_id: str, family: str, get_code_template) -> str:
+    """Generate C# evidence collection code using templates."""
+    return get_code_template(family, 'csharp')
+
+
+def _get_powershell_evidence_code(ksi_id: str, family: str, get_code_template) -> str:
+    """Generate PowerShell evidence collection code using templates."""
+    return get_code_template(family, 'powershell')
+
+
+
+
+
+async def get_evidence_automation_architecture_impl(data_loader, scope: str = "all") -> str:
+    """
+    Get end-to-end architecture guidance for automated evidence collection.
+    
+    Provides architectural patterns, best practices, and complete automation
+    strategies for FedRAMP 20x evidence collection across all KSIs.
+    
+    Args:
+        scope: Scope of architecture ("all", "single-ksi", "category", or "minimal")
+    
+    Returns:
+        Architecture guidance with diagrams and implementation roadmap
+    """
+    scope = scope.lower()
+    
+    result = """# Evidence Collection Automation Architecture for FedRAMP 20x
+
+## Overview
+
+This architecture automates evidence collection for all FedRAMP 20x KSIs, providing:
+- Continuous, automated evidence gathering
+- Secure, immutable evidence storage
+- API access for Authorization Data Sharing (FRR-ADS)
+- Compliance tracking and reporting
+
+"""
+
+    if scope == "minimal":
+        result += """## Minimal Viable Architecture
+
+### Components
+1. **Azure Log Analytics** - Central logging repository
+2. **Azure Blob Storage** - Evidence storage with immutability
+3. **Azure Function** - Scheduled evidence collection
+4. **Managed Identity** - Secure authentication
+
+### Data Flow
+```
+Azure Resources → Log Analytics → Azure Function (daily) → Blob Storage → FRR-ADS API
+```
+
+### Setup Time: 2-3 days
+### Covers: 40-50 KSIs
+
+### Quick Start
+```bash
+# Deploy infrastructure
+az deployment group create --template-file minimal-architecture.bicep
+
+# Deploy collection function
+func azure functionapp publish func-evidence-collector
+
+# Verify
+curl https://func-evidence-collector.azurewebsites.net/api/health
+```
+
+Use `get_infrastructure_code_for_ksi` and `get_evidence_collection_code` for implementation details.
+"""
+    elif scope == "single-ksi":
+        result += """## Single KSI Architecture
+
+For implementing evidence collection for a single KSI:
+
+### Components
+1. **Data Source** - The Azure resource being monitored (e.g., Entra ID, Key Vault)
+2. **Collection Logic** - Script/Function to gather evidence
+3. **Evidence Storage** - Blob container for this KSI's evidence
+4. **Scheduler** - Timer trigger or schedule
+
+### Architecture Pattern
+```
+┌─────────────────┐
+│  Azure Resource │ (Data Source)
+│  (e.g., Entra)  │
+└────────┬────────┘
+         │ API Query
+         ▼
+┌─────────────────┐
+│ Azure Function  │ (Collection Logic)
+│ or Automation   │
+└────────┬────────┘
+         │ Store Evidence
+         ▼
+┌─────────────────┐
+│  Blob Storage   │ (Evidence Repository)
+│  /ksi-iam-01/   │
+└─────────────────┘
+```
+
+### Implementation Steps
+1. Use `get_infrastructure_code_for_ksi(ksi_id)` to deploy infrastructure
+2. Use `get_evidence_collection_code(ksi_id, language)` to implement collection
+3. Test manually, then enable scheduling
+4. Monitor for 1 week before marking as production-ready
+
+### Timeline: 1-2 days per KSI
+"""
+    elif scope == "category":
+        result += """## Category-Based Architecture
+
+For implementing evidence collection by KSI category (IAM, MLA, etc.):
+
+### Architecture by Category
+
+#### 1. IAM (Identity & Access Management) - 7 KSIs
+```
+Microsoft Entra ID → Microsoft Graph API → Evidence Collector → Blob Storage
+                                                    ↓
+                                            Log Analytics (audit)
+```
+**Collection Method:** Microsoft Graph API queries
+**Frequency:** Daily
+**Storage:** /iam-evidence/
+
+#### 2. MLA (Monitoring, Logging & Analysis) - 8 KSIs
+```
+All Azure Resources → Log Analytics Workspace → KQL Queries → Evidence Export
+                                                       ↓
+                                              Blob Storage /mla-evidence/
+```
+**Collection Method:** Kusto (KQL) queries
+**Frequency:** Continuous ingestion, daily export
+**Storage:** /mla-evidence/
+
+#### 3. AFR (Authorization Framework) - 11 KSIs
+```
+Multiple Sources → Aggregation Function → Unified Evidence Format → Blob Storage
+  ├─ Defender for Cloud (vulnerabilities)
+  ├─ Policy Compliance (assessments)
+  ├─ Log Analytics (CCM data)
+  └─ Azure Resource Graph (inventory)
+```
+**Collection Method:** Multiple APIs aggregated
+**Frequency:** Daily
+**Storage:** /afr-evidence/
+
+#### 4. CNA (Cloud Native Architecture) - 8 KSIs
+```
+AKS Cluster → Container Insights → Log Analytics → Evidence Collector
+     ├─ Network Policies
+     ├─ Pod Security Standards
+     └─ Policy Enforcement (OPA/Kyverno)
+```
+**Collection Method:** Kubernetes API + Container Insights
+**Frequency:** Continuous monitoring, daily summary
+**Storage:** /cna-evidence/
+
+#### 5. RPL (Recovery & Planning) - 4 KSIs
+```
+Recovery Services Vault → Backup Reports API → Evidence Collector → Blob Storage
+Azure Site Recovery → Replication Status API →
+```
+**Collection Method:** Backup/DR APIs
+**Frequency:** Daily
+**Storage:** /rpl-evidence/
+
+### Implementation Approach
+1. Deploy category infrastructure (use `get_infrastructure_code_for_ksi`)
+2. Implement all KSIs in category together
+3. Share collection logic where possible
+4. Test category as a unit
+
+### Timeline: 1 week per category
+"""
+    else:  # "all" or default
+        result += """## Complete Enterprise Architecture
+
+### High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         Azure Subscription                          │
+│                                                                     │
+│  ┌──────────────────┐        ┌──────────────────┐                 │
+│  │  Data Sources    │        │  Collection      │                 │
+│  │                  │        │  Orchestration   │                 │
+│  │ • Entra ID       │───────▶│                  │                 │
+│  │ • Defender       │        │ Azure Functions  │                 │
+│  │ • Log Analytics  │───────▶│ (Timer Triggers) │                 │
+│  │ • Key Vault      │        │                  │                 │
+│  │ • AKS Clusters   │───────▶│ OR               │                 │
+│  │ • Backup Vaults  │        │                  │                 │
+│  │ • Policy         │───────▶│ Azure Automation │                 │
+│  └──────────────────┘        │ (Runbooks)       │                 │
+│                              └────────┬──────────┘                 │
+│                                       │                            │
+│                                       ▼                            │
+│                              ┌─────────────────┐                  │
+│                              │ Evidence Storage │                  │
+│                              │                  │                  │
+│                              │ Blob Storage     │                  │
+│                              │ (GRS, Immutable) │                  │
+│                              │                  │                  │
+│                              │ /iam-evidence/   │                  │
+│                              │ /mla-evidence/   │                  │
+│                              │ /afr-evidence/   │                  │
+│                              │ /cna-evidence/   │                  │
+│                              │ /...             │                  │
+│                              └────────┬──────────┘                 │
+│                                       │                            │
+│                                       ▼                            │
+│                              ┌─────────────────┐                  │
+│                              │ FRR-ADS API     │                  │
+│                              │                  │                  │
+│                              │ App Service     │                  │
+│                              │ (OSCAL Format)  │                  │
+│                              └────────┬──────────┘                 │
+│                                       │                            │
+└───────────────────────────────────────┼────────────────────────────┘
+                                        │ HTTPS
+                                        ▼
+                              ┌─────────────────┐
+                              │  Consumers      │
+                              │ • FedRAMP PMO   │
+                              │ • Agencies      │
+                              │ • 3PAO          │
+                              └─────────────────┘
+```
+
+### Core Components
+
+#### 1. Data Collection Layer
+- **Azure Functions** (Recommended)
+  - Serverless, cost-effective
+  - Easy scheduling with timer triggers
+  - Supports Python, C#, PowerShell
+  - Managed Identity for authentication
+  
+- **Azure Automation** (Alternative)
+  - PowerShell-focused
+  - Built-in scheduling
+  - Better for complex workflows
+  
+**Recommendation:** Use Functions for new implementations
+
+#### 2. Evidence Storage Layer
+- **Azure Blob Storage**
+  - Geo-redundant (GRS) for durability
+  - Immutability enabled (WORM)
+  - 7-year retention for FedRAMP
+  - Encrypted at rest (Microsoft-managed keys)
+  - Soft delete enabled
+  
+**Container Structure:**
+```
+evidence-storage/
+├── iam-evidence/
+│   ├── ksi-iam-01/
+│   │   ├── 2025-12-01.json
+│   │   └── 2025-12-02.json
+│   └── ksi-iam-05/
+├── mla-evidence/
+├── afr-evidence/
+└── metadata/
+    └── collection-log.json
+```
+
+#### 3. Authorization Data Sharing API
+- **Azure App Service** or **Azure Functions** (HTTP triggers)
+- OAuth 2.0 or mTLS authentication
+- OSCAL format responses
+- Rate limiting (1000 req/hour per client)
+- Integrated with Blob Storage
+
+#### 4. Monitoring & Alerting
+- **Azure Monitor**
+  - Collection success/failure alerts
+  - Evidence storage metrics
+  - API performance monitoring
+  
+- **Log Analytics**
+  - Centralized logging for all collection activities
+  - Retention: 2 years minimum
+
+### Implementation Phases
+
+#### Phase 1: Foundation (Week 1-2)
+- [ ] Deploy core infrastructure (Blob Storage, Log Analytics)
+- [ ] Set up Managed Identity and RBAC
+- [ ] Create evidence storage containers
+- [ ] Deploy monitoring and alerting
+
+**Deliverables:** Infrastructure ready to receive evidence
+
+#### Phase 2: Priority KSIs (Week 3-6)
+Implement high-priority KSIs first:
+- [ ] KSI-MLA-01: SIEM/Logging (enables others)
+- [ ] KSI-IAM-01: MFA (quick win)
+- [ ] KSI-AFR-04: Vulnerability scanning
+- [ ] KSI-PIY-01: Automated inventory
+- [ ] KSI-SVC-06: Secret management
+
+**Deliverables:** 5 KSIs collecting evidence automatically
+
+#### Phase 3: Core Security (Week 7-10)
+- [ ] All IAM KSIs (7 total)
+- [ ] All MLA KSIs (8 total)
+- [ ] Incident Response KSIs (3 total)
+
+**Deliverables:** 18 KSIs operational
+
+#### Phase 4: Cloud Native & Operations (Week 11-14)
+- [ ] All CNA KSIs (8 total)
+- [ ] All CMT KSIs (5 total)
+- [ ] All RPL KSIs (4 total)
+
+**Deliverables:** 35 KSIs operational
+
+#### Phase 5: Governance & Compliance (Week 15-18)
+- [ ] All AFR KSIs (11 total)
+- [ ] All CED KSIs (4 total)
+- [ ] All PIY KSIs (10 total)
+- [ ] All SVC KSIs (10 total)
+- [ ] All TPR KSIs (4 total)
+
+**Deliverables:** All 72 KSIs operational
+
+#### Phase 6: API & Integration (Week 19-20)
+- [ ] Deploy FRR-ADS API
+- [ ] Integrate with evidence storage
+- [ ] Test with sample queries
+- [ ] Document API for consumers
+
+**Deliverables:** Complete evidence collection and sharing system
+
+### Technology Stack
+
+**Recommended:**
+- **Language:** Python (best Azure SDK support, easiest for ops teams)
+- **Compute:** Azure Functions (serverless, cost-effective)
+- **Storage:** Azure Blob Storage GRS (built-in redundancy)
+- **Secrets:** Azure Key Vault (managed, audited)
+- **Monitoring:** Azure Monitor + Log Analytics
+- **Identity:** Managed Identity (no credentials to manage)
+- **API:** Azure App Service or API Management
+
+**Alternative (PowerShell-focused):**
+- **Language:** PowerShell
+- **Compute:** Azure Automation
+- **Rest:** Same as recommended
+
+### Security Architecture
+
+#### Authentication & Authorization
+```
+Collection Functions
+    ↓ (Managed Identity)
+Azure Resources (RBAC: Reader, Monitoring Reader)
+    ↓
+Evidence Storage (RBAC: Storage Blob Data Contributor)
+    ↓
+FRR-ADS API (OAuth 2.0 / mTLS)
+    ↓
+External Consumers (Per-client permissions)
+```
+
+#### Network Security
+- Private Endpoints for Storage (optional but recommended)
+- Function App: VNet integration if needed
+- API: Application Gateway + WAF for external access
+
+#### Data Security
+- Encryption at rest: Microsoft-managed keys (or BYOK)
+- Encryption in transit: TLS 1.2+
+- Immutability: WORM enabled on evidence containers
+- Access logging: All blob access logged to Log Analytics
+
+### Scaling Considerations
+
+**Small Organization (< 50 resources):**
+- Single Function App
+- Standard Blob Storage
+- Basic monitoring
+
+**Medium Organization (50-500 resources):**
+- Multiple Function Apps (by category)
+- Premium Blob Storage
+- Enhanced monitoring
+
+**Large Organization (500+ resources):**
+- Dedicated Function Apps per category
+- Premium storage with Private Endpoints
+- Application Insights Premium
+- API Management for FRR-ADS API
+
+### Disaster Recovery
+
+- **RTO:** < 4 hours (redeploy Functions from IaC)
+- **RPO:** 0 (evidence written immediately to GRS storage)
+- **Backup:** Evidence stored in GRS (replicated to paired region)
+- **Testing:** Quarterly DR drill (fail over to secondary region)
+
+### Compliance Considerations
+
+**FedRAMP Requirements Met:**
+- ✅ Automated evidence collection (FRD-ALL-07)
+- ✅ Immutable storage (FRR-AFR-09)
+- ✅ Authorization Data Sharing API (FRR-ADS)
+- ✅ Continuous monitoring (FRR-CCM)
+- ✅ Audit logging (KSI-MLA-02)
+
+### Next Steps
+
+1. **Assess Current State**
+   - What evidence is already being collected?
+   - What infrastructure exists?
+   - What gaps need to be filled?
+
+2. **Plan Implementation**
+   - Choose implementation order (by priority or category)
+   - Allocate resources (team, budget, time)
+   - Set milestones and deadlines
+
+3. **Deploy Foundation**
+   - Use `get_infrastructure_code_for_ksi` for Bicep templates
+   - Deploy core infrastructure first
+   - Test with one KSI before scaling
+
+4. **Implement KSIs**
+   - Use `get_evidence_collection_code` for each KSI
+   - Start with high-priority KSIs
+   - Test thoroughly before production
+
+5. **Integrate & Test**
+   - Deploy FRR-ADS API
+   - Test end-to-end evidence flow
+   - Conduct security review
+
+6. **Document & Train**
+   - Update System Security Plan
+   - Train operations team
+   - Create runbooks for troubleshooting
+
+*Generated by FedRAMP 20x MCP Server - Evidence Automation Architecture Tool*
+"""
+    
+    return result
+
+
+def main():
+    """Run the FedRAMP 20x MCP server."""
+    logger.info("Starting FedRAMP 20x MCP Server")
+    mcp.run(transport="stdio")