feat(ecs): add cluster validation and configuration collection (PR #2)

[nzuresh]

Summary

Changes

This PR adds cluster validation and comprehensive configuration collection capabilities to the ECS Security Analysis Tool. It extends PR #1 by enabling the tool to collect detailed cluster configurations for security analysis.

Commit: 7cce872

New Features:

• Cluster validation to ensure specified clusters exist before analysis
• Comprehensive configuration collection for ECS clusters including:
  • Cluster metadata (settings, statistics, tags, configuration)
  • Service configurations (network, load balancers, capacity providers)
  • Task definition details (containers, IAM roles, volumes, security settings)
  • Security group rules (ingress/egress permissions)
  • IAM role references
• Graceful error handling with partial failure support
• Batch processing for services (handles API limits)
• Deduplication of security groups across services

Files Modified:

• src/ecs-mcp-server/awslabs/ecs_mcp_server/api/security_analysis.py (+375 lines) - Added ClusterNotFoundError, validate_clusters() and collect_cluster_configuration() functions
• src/ecs-mcp-server/awslabs/ecs_mcp_server/modules/security_analysis.py (+107 lines, -22 lines) - Updated tool to accept cluster_names parameter and handle both list and collect modes
• src/ecs-mcp-server/tests/unit/test_security_analysis_api.py (+439 lines, -1 line) - Comprehensive tests for new functions
• src/ecs-mcp-server/tests/unit/test_security_analysis_module.py (+132 lines, -2 lines) - Tests for updated module functionality

Total: 1,078 lines changed (1,053 additions, 25 deletions)

User experience

Before this change:
Users could only list available ECS clusters. No way to collect detailed configuration data for security analysis.

After this change:
Users can now:

1. Validate that specific clusters exist before analysis
2. Collect comprehensive configuration data for one or more clusters
3. Receive structured JSON with all security-relevant information
4. Handle partial failures gracefully (some data collected even if errors occur)

Example Usage:

# List clusters (from PR #1)
analyze_ecs_security()

# Collect configuration for a single cluster
analyze_ecs_security(cluster_names=["prod-cluster"])

# Collect configuration for multiple clusters in specific region
analyze_ecs_security(
    region="eu-west-1", 
    cluster_names=["web-cluster", "api-cluster"]
)

Example Output:

{
  "analysis_type": "ecs_security_configuration",
  "region": "us-east-1",
  "clusters_analyzed": 1,
  "cluster_configurations": [
    {
      "cluster_name": "prod-cluster",
      "region": "us-east-1",
      "cluster_metadata": {
        "status": "ACTIVE",
        "running_tasks_count": 25,
        "active_services_count": 8,
        "tags": {"Environment": "Production"}
      },
      "services": [
        {
          "service_name": "web-service",
          "desired_count": 3,
          "running_count": 3,
          "task_definition": "arn:aws:ecs:...",
          "security_groups": [...]
        }
      ],
      "task_definitions": [...],
      "security_groups": [...],
      "collection_errors": []
    }
  ],
  "collection_timestamp": "2025-10-27T17:30:00Z"
}

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented

Testing:

• ✅ 23 unit tests (14 new tests added for validation and configuration collection)
• ✅ Tests cover success paths, error handling, and partial failures
• ✅ All tests pass
• ✅ All pre-commit checks pass (ruff, pyright, license headers)

Code Quality:

• ✅ Follows all patterns from CODING_PATTERNS.txt
• ✅ Complete type hints on all functions
• ✅ Comprehensive docstrings with Args, Returns, Raises
• ✅ Proper error handling with exception chaining
• ✅ Structured logging throughout
• ✅ Graceful handling of partial failures

New Functions:

• validate_clusters() - Validates cluster existence and returns ARNs
• collect_cluster_configuration() - Collects comprehensive cluster configuration
  • Step 1: Cluster metadata collection
  • Step 2: Service configurations (with security groups)
  • Step 3: Task definition configurations
  • Step 4: Security group deduplication

Is this a breaking change? N

RFC issue number: N/A

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

---

Architecture Notes

This PR implements the second phase of the multi-PR plan:

• PR feature: add continuous integration #1: Core infrastructure and cluster listing ✅
• PR feat(security): add CODEOWNERS #2 (This PR): Cluster validation and configuration collection ✅
• PR feat(doc): update initial documentation #3 (Next): Security analysis orchestrator and Knowledge Base integration
• PR feat(doc): initial documentation #4: AI agent instructions and report generation

The configuration collection is designed to gather all security-relevant data in a single pass, minimizing API calls while providing comprehensive information for security analysis.

Implementation Details

New Exception:

• ClusterNotFoundError - Raised when one or more clusters cannot be found during validation

New Functions:

1. validate_clusters(cluster_names: list[str], region: str) -> list[str]

   • Validates that specified clusters exist in the region
   • Returns list of validated cluster ARNs
   • Raises ClusterNotFoundError if any cluster is not found
   • Handles partial failures (some clusters found, others missing)

2. collect_cluster_configuration(region: str, cluster_name: str) -> Dict[str, Any]

   • Collects comprehensive configuration for a single ECS cluster
   • Four-step collection process:
     • Step 1: Cluster metadata (settings, statistics, tags, configuration)
     • Step 2: Service configurations (network, load balancers, security groups)
     • Step 3: Task definition configurations (containers, IAM roles, volumes)
     • Step 4: Security group deduplication
   • Graceful error handling with partial failure support
   • Batch processing for services (handles API limits of 10 services per call)
   • Direct EC2 API calls for security group details

Module Updates:

The analyze_ecs_security tool now supports two modes:

1. List Mode (cluster_names=None): Lists all available clusters
2. Collect Mode (cluster_names provided): Collects configuration for specified clusters

Returns JSON with:

• analysis_type: "ecs_security_configuration"
• region: Target AWS region
• clusters_analyzed: Number of clusters processed
• cluster_configurations: Array of cluster configuration objects
• collection_timestamp: ISO 8601 timestamp

Error Handling:

• Partial failures are captured in collection_errors array
• Configuration collection continues even if some steps fail
• Each cluster gets its own error tracking

Dependencies

This PR builds on PR #1 and must be merged after PR #1 is approved.

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of the project license.

[codecov]

Codecov Report

❌ Patch coverage is 91.73554% with 20 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.54%. Comparing base (1512d91) to head (7552d2d).
⚠️ Report is 80 commits behind head on main.

Files with missing lines	Patch %	Lines
...er/awslabs/ecs_mcp_server/api/security_analysis.py	93.18%	11 Missing and 1 partial ⚠️
...wslabs/ecs_mcp_server/modules/security_analysis.py	87.69%	8 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1592      +/-   ##
==========================================
+ Coverage   89.45%   89.54%   +0.08%     
==========================================
  Files         724      728       +4     
  Lines       50959    51585     +626     
  Branches     8144     8261     +117     
==========================================
+ Hits        45585    46191     +606     
- Misses       3465     3479      +14     
- Partials     1909     1915       +6     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

This pull request is now marked as stale because it hasn't seen activity for a while. Add a comment or it will be closed soon. If you wish to exclude this issue from being marked as stale, add the "backlog" label.