feat(ecs): Add ECS Security Analysis Tool - Core Infrastructure (PR #1) #1589

nzuresh · 2025-10-27T17:14:51Z

Summary

Changes

This PR adds the foundational infrastructure for the ECS Security Analysis Tool. It establishes the core module structure, region validation, and cluster listing functionality.

New Features:

Region validation with helpful error messages for invalid regions
ECS cluster listing with comprehensive metadata (status, running tasks, services, tags)
Interactive workflow foundation for multi-step security analysis
Proper module registration in the ECS MCP Server

Files Added:

awslabs/ecs_mcp_server/api/security_analysis.py (223 lines) - Core business logic for region validation and cluster operations
awslabs/ecs_mcp_server/modules/security_analysis.py (155 lines) - FastMCP tool registration and user-facing interface
tests/unit/test_security_analysis_api.py (168 lines) - Comprehensive API unit tests
tests/unit/test_security_analysis_module.py (147 lines) - Module integration tests

Files Modified:

awslabs/ecs_mcp_server/main.py - Added security_analysis module registration

Total: 693 lines (378 production + 315 tests)

User experience

Before this change:
Users had no way to analyze ECS cluster security configurations through the MCP server. Security analysis required manual inspection of AWS Console or CLI commands.

After this change:
Users can now:

List all ECS clusters in their default region: analyze_ecs_security()
List clusters in a specific region: analyze_ecs_security(region='us-west-2')
View cluster metadata including status, running tasks, active services, and tags
Receive helpful error messages for invalid regions with suggestions

Example Usage:

# List clusters in default region
analyze_ecs_security()

# List clusters in specific region
analyze_ecs_security(region='us-west-2')

Example Output:

Available ECS Clusters in us-east-1
====================================

Cluster: production-cluster
  Status: ACTIVE
  Running Tasks: 25
  Active Services: 8
  Container Instances: 10
  Tags: Environment=Production, Team=Platform

Cluster: staging-cluster
  Status: ACTIVE
  Running Tasks: 5
  Active Services: 3
  Container Instances: 3
  Tags: Environment=Staging, Team=Platform

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:

✅ 14 unit tests with 91% coverage (with branch coverage)
✅ 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
✅ Copyright headers on all files

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 first phase of a multi-PR plan for the ECS Security Analysis Tool:

PR feature: add continuous integration #1 (This PR): Core infrastructure and cluster listing ✅
PR feat(security): add CODEOWNERS #2 (Next): Cluster validation and configuration collection
PR feat(doc): update initial documentation #3 (Final): Security analysis and AI agent integration

The modular design allows for incremental development while maintaining stability and testability at each phase.

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.

Add foundational security analysis tool with cluster listing functionality. This PR establishes the core infrastructure and module registration. Features: - Region validation and selection - ECS cluster listing with metadata - Interactive workflow for cluster selection - Comprehensive error handling - Module registration in main.py Files Added: - awslabs/ecs_mcp_server/api/security_analysis.py (223 lines) - awslabs/ecs_mcp_server/modules/security_analysis.py (155 lines) - tests/unit/test_security_analysis_api.py (168 lines) - tests/unit/test_security_analysis_module.py (147 lines) Files Modified: - awslabs/ecs_mcp_server/main.py (module registration) Testing: - 14 unit tests with 91% coverage (with branch coverage) - All tests pass - Follows all coding patterns from existing codebase Usage: analyze_ecs_security() # List clusters in default region analyze_ecs_security(region='us-west-2') # List in specific region Total: 693 lines (378 production + 315 tests)

codecov · 2025-10-27T17:15:50Z

Codecov Report

❌ Patch coverage is 90.47619% with 8 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.52%. Comparing base (1512d91) to head (b07dea0).
⚠️ Report is 173 commits behind head on main.

Files with missing lines	Patch %	Lines
...wslabs/ecs_mcp_server/modules/security_analysis.py	81.39%	8 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1589      +/-   ##
==========================================
+ Coverage   89.45%   89.52%   +0.07%     
==========================================
  Files         724      280     -444     
  Lines       50959    20745   -30214     
  Branches     8144     3348    -4796     
==========================================
- Hits        45585    18572   -27013     
+ Misses       3465     1403    -2062     
+ Partials     1909      770    -1139

☔ 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.

matthewgoodman13 · 2025-10-27T22:21:59Z

src/ecs-mcp-server/awslabs/ecs_mcp_server/api/security_analysis.py

+    pass
+
+
+def validate_region(region: str) -> None:


See previous PR comments on region.

The server currently only works configured to one region, can we just use the env. variable instead of the tool requesting region as a parameter?

Why do we need to validate the region?

See previous PR comments on region.

The server currently only works configured to one region, can we just use the env. variable instead of the tool requesting region as a parameter?

Good catch! You're absolutely right. The tool now uses the AWS_REGION environment variable (via get_target_region()) instead of requiring region as a parameter. This is consistent with how the rest of the MCP server operates - the region is configured at the server level when it starts, not per-tool-call.

The workflow is:

Server configured with AWS_REGION environment variable
Tool called without region parameter → uses configured region
Keeps the tool interface simple and consistent with other ECS tools in the server
Changes made:

Removed region parameter from tool signature
Tool uses get_target_region() which reads from AWS_REGION env var (defaults to 'us-east-1')
Updated documentation to clarify region comes from environment configuration

matthewgoodman13 · 2025-10-27T22:23:18Z

src/ecs-mcp-server/awslabs/ecs_mcp_server/api/security_analysis.py

+    Get the target AWS region for security analysis.
+
+    If region is provided, validates it and returns it.
+    If region is None, uses AWS_REGION environment variable (defaults to 'us-east-1').


Lets just use the env. var as the region. Lets eliminate the region parameter.

Done! ✅ The region parameter has been eliminated. The tool now uses get_target_region() which reads from the AWS_REGION environment variable (defaults to 'us-east-1'). This keeps it consistent with how the rest of the MCP server operates.

matthewgoodman13 · 2025-10-27T22:28:31Z

src/ecs-mcp-server/awslabs/ecs_mcp_server/api/security_analysis.py

+
+    try:
+        # List cluster ARNs
+        list_response = await ecs_api_operation(api_operation="ListClusters", api_params={})


Commented on prev PR.

Lets use the get_aws_config from utils/aws.py

Updated the EC2 client creation to use get_aws_config() from utils/aws.py. This ensures the client includes the proper user-agent tag (awslabs/mcp/ecs-mcp-server/{version}) for AWS API tracking, consistent with other clients in the codebase.

Why are we still calling ecs_api_operation here? The ecs_api_operation is part of the resource management tool, but we dont want this tool to be dependent on other tools.

Lets use be using aws.py tools.

ecs = await get_aws_client("ecs") ecs.list_clusters(...)

These clients automatically grab the region, and therefore we do not need to pass around the region param

Removed get_target_region() function (no longer needed)

Replaced ecs_api_operation() with get_aws_client() from aws.py

Removed dependency on resource_management tool

get_aws_client() automatically uses AWS_REGION from environment

Removed region parameter from all functions

get_clusters_with_metadata() now has no parameters

format_clusters_for_display() now has no parameters

Region is read directly from environment where needed

Update all tests to match new signatures

Maintain 90%+ test coverage

matthewgoodman13 · 2025-10-27T22:30:24Z

src/ecs-mcp-server/awslabs/ecs_mcp_server/api/security_analysis.py

+        raise Exception(f"Failed to list clusters in region '{region}': {str(e)}") from e
+
+
+def format_cluster_list(clusters: list[Dict[str, Any]], region: str) -> str:


naming of this method feels weird here for what it returns?

Supposed to return Formatted string with cluster information?

Renamed the functions to better reflect what they return:

list_clusters_in_region() → get_clusters_with_metadata() (returns list of dicts)
format_cluster_list() → format_clusters_for_display() (returns formatted string)
The naming now clearly distinguishes between data retrieval and formatting operations. Updated all imports, usages, and tests accordingly.

matthewgoodman13 · 2025-10-27T22:33:12Z

src/ecs-mcp-server/awslabs/ecs_mcp_server/modules/security_analysis.py

+           - Call with region parameter to list clusters in specific region
+           - Returns formatted list of available clusters with metadata
+
+        Step 2: User Selects Clusters (Future)


That comment was noting a potential future enhancement to add a region parameter to the tool. However, as discussed in other comments, we've decided to keep the current approach where the region is configured at the server level via the AWS_REGION environment variable. This keeps the tool interface simple and consistent with how the rest of the MCP server operates. I've removed the "Future" comment to avoid confusion.

- Remove region parameter (use AWS_REGION env var instead) - Rename functions for clarity: - list_clusters_in_region() -> get_clusters_with_metadata() - format_cluster_list() -> format_clusters_for_display() - Remove region validation functions (no longer needed) - Update all tests and imports accordingly - Simplify tool interface to use environment configuration

src/ecs-mcp-server/awslabs/ecs_mcp_server/api/security_analysis.py

matthewgoodman13 · 2025-10-31T18:39:43Z

src/ecs-mcp-server/awslabs/ecs_mcp_server/api/security_analysis.py

+
+    try:
+        # List cluster ARNs
+        list_response = await ecs_api_operation(api_operation="ListClusters", api_params={})


Why are we still calling ecs_api_operation here? The ecs_api_operation is part of the resource management tool, but we dont want this tool to be dependent on other tools.

Lets use be using aws.py tools.

ecs = await get_aws_client("ecs") ecs.list_clusters(...)

These clients automatically grab the region, and therefore we do not need to pass around the region param

- Remove get_target_region() function (no longer needed) - Replace ecs_api_operation() with get_aws_client() from aws.py - Removes dependency on resource_management tool - get_aws_client() automatically uses AWS_REGION from environment - Remove region parameter from all functions - get_clusters_with_metadata() now has no parameters - format_clusters_for_display() now has no parameters - Region is read directly from environment where needed - Update all tests to match new signatures - Maintain 90%+ test coverage

github-actions · 2025-11-27T01:34:53Z

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.

nzuresh requested review from a team, biagic, guitar80ep, matthewgoodman13, nineonine and tusharbabbar as code owners October 27, 2025 17:14

github-project-automation bot moved this to To triage in awslabs/mcp Project Oct 27, 2025

github-project-automation bot added this to awslabs/mcp Project Oct 27, 2025

scottschreckengaust changed the title ~~feat: Add ECS Security Analysis Tool - Core Infrastructure (PR #1)~~ feat(ecs): Add ECS Security Analysis Tool - Core Infrastructure (PR #1) Oct 27, 2025

matthewgoodman13 requested changes Oct 27, 2025

View reviewed changes

scottschreckengaust added the hold-merging Signals to hold the PR from merging label Oct 28, 2025

scottschreckengaust self-assigned this Oct 28, 2025

matthewgoodman13 requested changes Oct 31, 2025

View reviewed changes

github-actions bot added stale These are items that have been around for a long time without progress and removed stale These are items that have been around for a long time without progress labels Nov 27, 2025

		raise Exception(f"Failed to list clusters in region '{region}': {str(e)}") from e


		def format_cluster_list(clusters: list[Dict[str, Any]], region: str) -> str:

feat(ecs): Add ECS Security Analysis Tool - Core Infrastructure (PR #1) #1589

Are you sure you want to change the base?

feat(ecs): Add ECS Security Analysis Tool - Core Infrastructure (PR #1) #1589

Conversation

nzuresh commented Oct 27, 2025

Summary

Changes

User experience

Checklist

Architecture Notes

Acknowledgment

Uh oh!

codecov bot commented Oct 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Nov 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

codecov bot commented Oct 27, 2025 •

edited

Loading