- Scripts to run workflows from a YAML context or run inputs (kab_run_workflow.py, with --input name=@file), store per-project discovery connections, bootstrap agent MCP keys, refresh the KAB token, publish reports and build estate snapshots. - Hyperscaler discovery servers extended in place; cloud-knowledge folded into them. - deploy/crucible-kab-dev.yaml: the Discovery package agent and the Assessment agents. - Platform issue write-ups and current-wiring notes under docs/platform-issues/. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1464 lines
69 KiB
Python
1464 lines
69 KiB
Python
"""AWS Discovery
|
|
=============
|
|
|
|
Read-only discovery of a customer's AWS estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Trusted Advisor findings.
|
|
|
|
Generated by Agent Builder Platform - MCP Server Builder
|
|
Version: 0.1.2
|
|
Template: mcp-server-template 1.1.0
|
|
|
|
Features:
|
|
- JSON-RPC 2.0 over HTTP (MCP standard)
|
|
- Bearer token authentication
|
|
- Health check endpoint
|
|
- Structured logging (JSON, one object per line)
|
|
|
|
Environment Variables:
|
|
- MCP_REGISTRATION_API_KEY: Authentication key for Gateway registration (required)
|
|
- MCP_SERVER_PORT: Server port (default: 8112)
|
|
- MCP_SERVER_NAME: Display name for the server
|
|
- LOG_LEVEL: Logging level (default: INFO)
|
|
- LOG_FORMAT: json (default) or console
|
|
"""
|
|
|
|
import os
|
|
import re
|
|
import sys
|
|
import json
|
|
import inspect
|
|
import time
|
|
import traceback
|
|
import asyncio
|
|
import logging
|
|
import secrets
|
|
from typing import Dict, Any, List, Optional, Union # noqa: F401
|
|
from collections import OrderedDict
|
|
from contextlib import asynccontextmanager
|
|
from datetime import datetime, timezone
|
|
|
|
import structlog
|
|
from fastapi import FastAPI, HTTPException, Depends, Request
|
|
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
|
|
from pydantic import BaseModel, Field, StrictInt, StrictStr
|
|
|
|
import mcp_connection
|
|
|
|
# Additional imports from tool implementations
|
|
import base64
|
|
import hashlib
|
|
import boto3
|
|
from botocore.config import Config as BotoConfig
|
|
|
|
TEMPLATE_VERSION = '1.1.0'
|
|
|
|
# What this server needs to reach its upstream, advertised to the gateway on initialize (None: nothing)
|
|
CONNECTION_SCHEMA = {'type': 'object',
|
|
'title': 'AWS Discovery',
|
|
'description': "Read-only discovery of a customer's AWS estate - servers, workloads, "
|
|
'Kubernetes clusters, networks, data stores, policies and Trusted '
|
|
'Advisor findings.',
|
|
'properties': {'access_key_id': {'type': 'string',
|
|
'title': 'Access key ID',
|
|
'description': 'The broker identity that assumes the '
|
|
'read-only role.'},
|
|
'secret_access_key': {'type': 'string',
|
|
'title': 'Secret access key',
|
|
'description': "The broker identity's secret "
|
|
'key.',
|
|
'writeOnly': True,
|
|
'format': 'password'},
|
|
'role_arn': {'type': 'string',
|
|
'title': 'Role ARN',
|
|
'description': "The customer's read-only role."},
|
|
'external_id': {'type': 'string',
|
|
'title': 'External ID',
|
|
'description': "The external id on the role's trust "
|
|
'policy.',
|
|
'writeOnly': True,
|
|
'format': 'password'},
|
|
'regions': {'type': 'string',
|
|
'title': 'Regions',
|
|
'description': 'Comma-separated regions that may be read. '
|
|
'The first is the default.'},
|
|
'account_ids': {'type': 'string',
|
|
'title': 'Account IDs',
|
|
'description': 'Comma-separated member accounts that '
|
|
'may be read.'},
|
|
'member_role_name': {'type': 'string',
|
|
'title': 'Member role name',
|
|
'description': "The read-only role's name in "
|
|
'member accounts.'},
|
|
'aggregator_name': {'type': 'string',
|
|
'title': 'Config aggregator',
|
|
'description': 'An AWS Config aggregator for '
|
|
'organisation-wide queries.'}},
|
|
'required': ['access_key_id',
|
|
'secret_access_key',
|
|
'role_arn',
|
|
'external_id',
|
|
'regions'],
|
|
'additionalProperties': False}
|
|
VERIFY_TOOL = 'verify_connection'
|
|
|
|
# ============================================
|
|
# Configuration
|
|
# ============================================
|
|
|
|
def _load_env_file() -> None:
|
|
"""Read the `.env` next to this file, so `cp .env.example .env` and `python server.py` work.
|
|
|
|
Variables that are already set win, so a container's or a pipeline's settings are never overridden.
|
|
The image does not contain a `.env`, so this does nothing there.
|
|
"""
|
|
path = globals().get("__file__")
|
|
if not path:
|
|
return
|
|
try:
|
|
from dotenv import load_dotenv
|
|
except ImportError:
|
|
return
|
|
load_dotenv(os.path.join(os.path.dirname(os.path.abspath(path)), ".env"))
|
|
|
|
|
|
_load_env_file()
|
|
|
|
|
|
class Config:
|
|
"""Server configuration from environment variables"""
|
|
|
|
# Server Identity
|
|
SERVER_ID = os.getenv("MCP_SERVER_ID", 'aws-discovery')
|
|
SERVER_NAME = os.getenv("MCP_SERVER_NAME", 'AWS Discovery')
|
|
SERVER_VERSION = os.getenv("MCP_SERVER_VERSION", '0.1.2')
|
|
# MCP_SERVER_PORT, or SERVER_PORT as the ConfigMaps in the tools repo name it
|
|
SERVER_PORT = int(os.getenv("MCP_SERVER_PORT") or os.getenv("SERVER_PORT") or "8112")
|
|
|
|
# Authentication (REQUIRED for MCP Gateway registration)
|
|
# Generate secure key: openssl rand -hex 32
|
|
MCP_REGISTRATION_API_KEY = os.getenv("MCP_REGISTRATION_API_KEY", "").strip()
|
|
# The placeholder from .env.example is not a key: a server started with it unchanged has no key.
|
|
if MCP_REGISTRATION_API_KEY.startswith("<"):
|
|
MCP_REGISTRATION_API_KEY = ""
|
|
|
|
# Feature Flags
|
|
REQUIRE_AUTH = os.getenv("REQUIRE_AUTH", "true").lower() == "true"
|
|
# Applies when CONNECTION_SCHEMA is set: refuse a call that arrives without the tenant's connection
|
|
# instead of falling back to this server's own environment. Set to false only for local runs.
|
|
REQUIRE_VAULT_CONNECTION = os.getenv("REQUIRE_VAULT_CONNECTION", "true").lower() == "true"
|
|
|
|
# Logging: LOG_FORMAT is "json" (one object per line, for log stores) or "console" (for reading by eye)
|
|
LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
|
|
LOG_FORMAT = os.getenv("LOG_FORMAT", "json").lower()
|
|
|
|
config = Config()
|
|
|
|
# ============================================
|
|
# Logging Configuration
|
|
# ============================================
|
|
|
|
def sanitize_log(value: Any, max_length: int = 200) -> str:
|
|
"""Make a caller-supplied value safe to log: one line, no control characters, bounded."""
|
|
if not isinstance(value, str):
|
|
value = str(value)
|
|
# Written with .replace() because that is the pattern CodeQL recognises as a
|
|
# barrier for py/log-injection (CWE-117).
|
|
value = value.replace("\n", "").replace("\r", "")
|
|
return re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]", "", value)[:max_length]
|
|
|
|
|
|
def _add_server_identity(_logger, _method, event_dict):
|
|
event_dict.setdefault("server_id", config.SERVER_ID)
|
|
event_dict.setdefault("server_name", config.SERVER_NAME)
|
|
event_dict.setdefault("server_version", config.SERVER_VERSION)
|
|
return event_dict
|
|
|
|
|
|
_LEADING_KEYS = (
|
|
"timestamp", "level", "event", "logger", "server_id", "server_name", "server_version",
|
|
"request_id", "method", "tool",
|
|
)
|
|
|
|
|
|
def _scrub_secrets(_logger, _method, event_dict):
|
|
"""The last step before a line is written: no credential reaches the log, whoever logged it."""
|
|
return mcp_connection.scrub(event_dict)
|
|
|
|
|
|
def _lead_with_common_keys(_logger, _method, event_dict):
|
|
"""Every line starts with the same fields in the same order; the event's own follow."""
|
|
lead = {key: event_dict.pop(key) for key in _LEADING_KEYS if key in event_dict}
|
|
lead.update(event_dict)
|
|
return lead
|
|
|
|
|
|
def configure_logging() -> None:
|
|
"""Send every log line, ours and the libraries', to stdout in one format."""
|
|
level = getattr(logging, config.LOG_LEVEL, logging.INFO)
|
|
shared = [
|
|
structlog.contextvars.merge_contextvars,
|
|
structlog.stdlib.add_logger_name,
|
|
structlog.stdlib.add_log_level,
|
|
structlog.processors.TimeStamper(fmt="iso", utc=True),
|
|
_add_server_identity,
|
|
]
|
|
renderer = (
|
|
structlog.dev.ConsoleRenderer(colors=False)
|
|
if config.LOG_FORMAT == "console"
|
|
else structlog.processors.JSONRenderer()
|
|
)
|
|
structlog.configure(
|
|
processors=shared + [
|
|
structlog.stdlib.PositionalArgumentsFormatter(),
|
|
structlog.processors.StackInfoRenderer(),
|
|
structlog.processors.format_exc_info,
|
|
structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
|
|
],
|
|
logger_factory=structlog.stdlib.LoggerFactory(),
|
|
wrapper_class=structlog.stdlib.BoundLogger,
|
|
cache_logger_on_first_use=True,
|
|
)
|
|
handler = logging.StreamHandler(sys.stdout)
|
|
handler.mcp_server_handler = True
|
|
handler.setFormatter(structlog.stdlib.ProcessorFormatter(
|
|
foreign_pre_chain=shared,
|
|
processors=[
|
|
structlog.stdlib.ProcessorFormatter.remove_processors_meta,
|
|
structlog.processors.format_exc_info,
|
|
_lead_with_common_keys,
|
|
_scrub_secrets,
|
|
renderer,
|
|
],
|
|
))
|
|
root = logging.getLogger()
|
|
root.handlers = [h for h in root.handlers if not getattr(h, "mcp_server_handler", False)] + [handler]
|
|
root.setLevel(level)
|
|
# httpx logs every request URL at INFO, and an upstream URL often carries a key: keep those lines for DEBUG
|
|
for name in ("httpx", "httpcore"):
|
|
logging.getLogger(name).setLevel(level if level <= logging.DEBUG else logging.WARNING)
|
|
# uvicorn installs its own handlers; route them through ours so every line has the same shape
|
|
for name in ("uvicorn", "uvicorn.error", "uvicorn.access"):
|
|
uvicorn_logger = logging.getLogger(name)
|
|
uvicorn_logger.handlers.clear()
|
|
uvicorn_logger.propagate = True
|
|
|
|
|
|
configure_logging()
|
|
logger = structlog.get_logger(__name__)
|
|
|
|
# ============================================
|
|
# Per-request connection
|
|
# ============================================
|
|
|
|
CONNECTION_METHODS = ("tools/call", "resources/read", "prompts/get")
|
|
|
|
|
|
def get_connection() -> Dict[str, Any]:
|
|
"""The connection fields the gateway sent with this request; empty when it sent none."""
|
|
return dict(mcp_connection.active() or {})
|
|
|
|
|
|
_client_cache: "OrderedDict[str, Any]" = OrderedDict()
|
|
_CLIENT_CACHE_MAX = 32
|
|
|
|
|
|
def get_upstream_client(kind, build):
|
|
"""The upstream client of type `kind` for this request's connection.
|
|
|
|
`build(connection)` runs once per distinct (kind, connection), so two tools that talk to different
|
|
upstreams with the same tenant connection each get their own client.
|
|
"""
|
|
if not isinstance(kind, str) or not kind:
|
|
raise TypeError("get_upstream_client needs a client kind, for example get_upstream_client('jira', build)")
|
|
key = f"{kind}:{mcp_connection.fingerprint(mcp_connection.active())}"
|
|
client = _client_cache.get(key)
|
|
if client is None:
|
|
client = build(get_connection())
|
|
_client_cache[key] = client
|
|
while len(_client_cache) > _CLIENT_CACHE_MAX:
|
|
_close_client(_client_cache.popitem(last=False)[1])
|
|
else:
|
|
_client_cache.move_to_end(key)
|
|
return client
|
|
|
|
|
|
_closing_tasks: set = set()
|
|
|
|
|
|
def _close_client(client) -> None:
|
|
"""Release the connections of a client that left the cache (an httpx client holds a pool of sockets).
|
|
|
|
Closes with `aclose()`, `close()` or `dispose()` (an httpx client, most clients, a SQLAlchemy engine); a client
|
|
with none of them is left to the garbage collector. A failure to close is logged and never reaches the
|
|
request that happened to evict it.
|
|
"""
|
|
close = getattr(client, "aclose", None) or getattr(client, "close", None) or getattr(client, "dispose", None)
|
|
if close is None:
|
|
return
|
|
try:
|
|
result = close()
|
|
if inspect.isawaitable(result):
|
|
try:
|
|
task = asyncio.get_running_loop().create_task(result)
|
|
except RuntimeError: # no loop to run it on
|
|
result.close()
|
|
return
|
|
_closing_tasks.add(task) # a task nobody refers to can be collected before it finishes
|
|
task.add_done_callback(_closing_tasks.discard)
|
|
except Exception as error:
|
|
logger.warning("client_close_failed", error_type=type(error).__name__, error=sanitize_log(error))
|
|
|
|
|
|
async def _close_all_clients() -> None:
|
|
"""On shutdown: close every cached client and wait for the closes already under way."""
|
|
while _client_cache:
|
|
_close_client(_client_cache.popitem(last=False)[1])
|
|
if _closing_tasks:
|
|
await asyncio.gather(*list(_closing_tasks), return_exceptions=True)
|
|
|
|
|
|
def check_connection(profile: Optional[Dict[str, Any]]) -> None:
|
|
"""Refuse a call with no connection (unless the environment may be used) or with an incomplete one."""
|
|
if not profile:
|
|
if config.REQUIRE_VAULT_CONNECTION:
|
|
raise ValueError(
|
|
"No connection was sent with this request: no credential is stored for this tenant. "
|
|
"Store one under Credentials, or set REQUIRE_VAULT_CONNECTION=false to use this "
|
|
"server's own environment."
|
|
)
|
|
return
|
|
missing = mcp_connection.missing_fields(profile, CONNECTION_SCHEMA)
|
|
if missing:
|
|
raise ValueError("The connection sent with this request is missing: " + ", ".join(missing))
|
|
|
|
|
|
def render_prompt(template: str, values: Dict[str, Any]) -> str:
|
|
"""Fill {{name}} markers in a prompt template; a marker with no value is left as written."""
|
|
return re.sub(
|
|
r"\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}",
|
|
lambda m: str(values[m.group(1)]) if m.group(1) in values else m.group(0),
|
|
template,
|
|
)
|
|
|
|
# ============================================
|
|
# Authentication
|
|
# ============================================
|
|
|
|
security = HTTPBearer(auto_error=False)
|
|
|
|
async def verify_mcp_registration_key(
|
|
credentials: Optional[HTTPAuthorizationCredentials] = Depends(security)
|
|
) -> bool:
|
|
"""
|
|
Verify MCP registration API key for /messages endpoint.
|
|
|
|
This is the industry-standard Bearer token authentication pattern.
|
|
"""
|
|
# Skip auth if disabled (for testing only!)
|
|
if not config.REQUIRE_AUTH:
|
|
logger.warning("auth_disabled", detail="testing mode only")
|
|
return True
|
|
|
|
if not credentials:
|
|
logger.warning("auth_missing_credentials")
|
|
raise HTTPException(
|
|
status_code=401,
|
|
detail="Missing authentication credentials. Include 'Authorization: Bearer <token>' header.",
|
|
headers={"WWW-Authenticate": "Bearer"}
|
|
)
|
|
|
|
provided_key = credentials.credentials
|
|
expected_key = config.MCP_REGISTRATION_API_KEY
|
|
|
|
if not expected_key:
|
|
logger.error("auth_key_not_configured")
|
|
raise HTTPException(
|
|
status_code=500,
|
|
detail="Server authentication not configured"
|
|
)
|
|
|
|
if not secrets.compare_digest(provided_key.encode("utf-8"), expected_key.encode("utf-8")):
|
|
logger.warning("auth_invalid_key")
|
|
raise HTTPException(
|
|
status_code=401,
|
|
detail="Invalid authentication credentials",
|
|
headers={"WWW-Authenticate": "Bearer"}
|
|
)
|
|
|
|
return True
|
|
|
|
# ============================================
|
|
# MCP Protocol Models
|
|
# ============================================
|
|
|
|
class MCPRequest(BaseModel):
|
|
"""JSON-RPC 2.0 request (MCP standard)"""
|
|
jsonrpc: str = "2.0"
|
|
id: Union[StrictStr, StrictInt] # JSON-RPC allows a string or a number; the reply echoes it unchanged
|
|
method: str
|
|
params: Dict[str, Any] = Field(default_factory=dict)
|
|
|
|
class MCPResponse(BaseModel):
|
|
"""JSON-RPC 2.0 response (MCP standard)"""
|
|
jsonrpc: str = "2.0"
|
|
id: Union[StrictStr, StrictInt]
|
|
result: Optional[Dict[str, Any]] = None
|
|
error: Optional[Dict[str, Any]] = None
|
|
|
|
# ============================================
|
|
# Tool Definitions
|
|
# ============================================
|
|
|
|
TOOLS_REGISTRY = [
|
|
{
|
|
"name": 'aws_check_connection',
|
|
"description": 'Test the stored connection: assume the role and read its identity. Returns no customer data.',
|
|
"inputSchema": {'type': 'object', 'properties': {}, 'required': []}
|
|
},
|
|
{
|
|
"name": 'aws_list_accounts',
|
|
"description": "List the organisation's accounts or organizational units. Needs the management or a delegated administrator account.",
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string', 'description': 'One of: accounts, roots.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'aws_list_resources',
|
|
"description": 'List resources of one type that AWS Config has recorded.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'resource_type': {'type': 'string',
|
|
'description': 'A Config type, such as '
|
|
'AWS::EC2::Instance.'},
|
|
'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': ['resource_type']}
|
|
},
|
|
{
|
|
"name": 'aws_query_resources',
|
|
"description": 'Run a read-only AWS Config advanced query. Uses the organisation aggregator when the connection names one.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'query': {'type': 'string',
|
|
'description': 'A Config SELECT expression.'},
|
|
'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': ['query']}
|
|
},
|
|
{
|
|
"name": 'aws_get_resource_metadata',
|
|
"description": 'Read-only provider metadata for one resource, from AWS Config.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'resource_type': {'type': 'string', 'description': 'A Config type.'},
|
|
'resource_id': {'type': 'string', 'description': 'The resource id.'},
|
|
'scope_entry_id': {'type': 'string',
|
|
'description': 'The scope entry this answers, '
|
|
'echoed in the reply.'},
|
|
'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'}},
|
|
'required': ['resource_type', 'resource_id']}
|
|
},
|
|
{
|
|
"name": 'aws_list_servers',
|
|
"description": 'List EC2 instances, Auto Scaling groups or EBS volumes.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: instances, auto_scaling_groups, '
|
|
'volumes.'},
|
|
'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'aws_list_workloads',
|
|
"description": 'List Lambda functions, ECS clusters, App Runner services or Elastic Beanstalk environments. Environment variables are removed.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: lambda_functions, ecs_clusters, '
|
|
'app_runner_services, '
|
|
'elastic_beanstalk_environments.'},
|
|
'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'aws_list_kubernetes_clusters',
|
|
"description": 'List EKS clusters with version, node groups and networking. Stops at the cloud control plane.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'aws_get_network_topology',
|
|
"description": 'List VPCs, subnets, route tables, security groups, NAT or internet gateways, transit gateways, peerings, endpoints or load balancers.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: vpcs, subnets, route_tables, '
|
|
'security_groups, nat_gateways, '
|
|
'internet_gateways, transit_gateways, '
|
|
'vpc_peering, vpc_endpoints, load_balancers.'},
|
|
'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'aws_list_data_stores',
|
|
"description": 'List RDS instances, DynamoDB tables or S3 buckets. Metadata only, never rows or objects.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: rds_instances, dynamodb_tables, '
|
|
's3_buckets.'},
|
|
'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'aws_list_organization_policies',
|
|
"description": 'List Organizations policies with their documents, or Config rule compliance.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: service_control_policies, '
|
|
'resource_control_policies, tag_policies, '
|
|
'backup_policies, config_rule_compliance.'},
|
|
'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'aws_list_resource_policies',
|
|
"description": 'List resource-based policies: S3 buckets, KMS keys, Lambda functions, SQS queues, SNS topics, or IAM role trust policies. People are anonymised.',
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: s3_buckets, kms_keys, '
|
|
'lambda_functions, sqs_queues, sns_topics, '
|
|
'iam_role_trust.'},
|
|
'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'aws_list_recommendations',
|
|
"description": "List Trusted Advisor recommendations, each with a common Well-Architected pillar, or the customer's existing Well-Architected Tool reviews.",
|
|
"inputSchema": {'type': 'object',
|
|
'properties': {'kind': {'type': 'string',
|
|
'description': 'One of: trusted_advisor, '
|
|
'well_architected_reviews.'},
|
|
'account_id': {'type': 'string',
|
|
'description': "An account from the connection's list. "
|
|
"Default: the connection's own."},
|
|
'region': {'type': 'string',
|
|
'description': "A region from the connection's list. "
|
|
'Default: the first.'},
|
|
'page_size': {'type': 'integer',
|
|
'description': 'Items per page, up to 200. Default 50.'},
|
|
'page_token': {'type': 'string',
|
|
'description': 'next_page_token from the previous '
|
|
'reply.'}},
|
|
'required': []}
|
|
},
|
|
{
|
|
"name": 'verify_connection',
|
|
"description": (
|
|
"Check that the connection sent with this request works against the upstream, and say who it "
|
|
"authenticated as. Makes no change."
|
|
),
|
|
"inputSchema": {'type': 'object', 'properties': {}, 'required': []}
|
|
}
|
|
]
|
|
|
|
# ============================================
|
|
# Resource Definitions
|
|
# ============================================
|
|
|
|
RESOURCES_REGISTRY = []
|
|
|
|
# ============================================
|
|
# Prompt Definitions
|
|
# ============================================
|
|
|
|
PROMPT_TEMPLATES = {}
|
|
|
|
PROMPTS_REGISTRY = [
|
|
{
|
|
"name": name,
|
|
"description": prompt["description"],
|
|
"arguments": [
|
|
{"name": a["name"], "description": a["description"], "required": a["required"]}
|
|
for a in prompt["arguments"]
|
|
],
|
|
}
|
|
for name, prompt in PROMPT_TEMPLATES.items()
|
|
]
|
|
|
|
# ============================================
|
|
# Tool Implementations
|
|
# ============================================
|
|
|
|
DEFAULT_PAGE_SIZE = 50
|
|
|
|
MAX_PAGE_SIZE = 200
|
|
|
|
MAX_RESPONSE_BYTES = 200000
|
|
|
|
RETRY_ATTEMPTS = 5
|
|
|
|
RETRY_MAX_WAIT_SECONDS = 20
|
|
|
|
RETRY_BUDGET_SECONDS = 60
|
|
|
|
SECRET_KEYS = (
|
|
"userdata", "customdata", "customscript", "protectedsettings", "connectionstring", "connectionstrings",
|
|
"appsettings", "env", "envvars", "environmentvariables", "variables", "password", "adminpassword", "secret",
|
|
"secretvalue", "sastoken", "accesskey", "primarykey", "secondarykey", "privatekey", "kubeconfig", "credentials",
|
|
)
|
|
|
|
SCALAR_SAFE_KEYS = ("env",)
|
|
|
|
PERSON_KEYS = (
|
|
"createdby", "lastmodifiedby", "updatedby", "creator", "owner", "owneremail", "contact", "contactemail", "email",
|
|
"objectid", "principalid", "principalname", "userprincipalname",
|
|
)
|
|
|
|
PRINCIPAL_KINDS = {"user": "[user]", "group": "[group]", "domain": "[domain]", "principal": "[user]",
|
|
"principalSet": "[group]", "deleted": "[user]"}
|
|
|
|
NON_PERSON_EMAIL_DOMAINS = ("gserviceaccount.com",)
|
|
|
|
def _clean_text(text: str) -> str:
|
|
"""Anonymise people inside a string: emails, AWS IAM users, and session names, which are often emails."""
|
|
def email(match):
|
|
return match.group(0) if match.group(0).lower().endswith(NON_PERSON_EMAIL_DOMAINS) else "[email]"
|
|
|
|
text = re.sub(r"arn:aws[a-z-]*:iam::\d{12}:user/[^\s\"',]+", "[user]", text)
|
|
text = re.sub(r"(arn:aws[a-z-]*:sts::\d{12}:assumed-role/[^/\s\"',]+)/[^\s\"',]+", r"\1/[session]", text)
|
|
# Bounded, and skipped without an @: an unbounded pattern takes minutes on one long string.
|
|
if "@" not in text:
|
|
return text
|
|
return re.sub(r"[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,255}\.[A-Za-z]{2,24}", email, text)
|
|
|
|
def _anonymise_member(value: str) -> str:
|
|
"""One IAM member, such as user:a@b.example. Service accounts stay: Discovery shows what can reach what."""
|
|
kind = value.split(":", 1)[0]
|
|
if ":" in value and kind == "serviceAccount":
|
|
return value
|
|
if ":" in value and kind in PRINCIPAL_KINDS:
|
|
return PRINCIPAL_KINDS[kind]
|
|
return _clean_text(value)
|
|
|
|
def _scalar(value) -> bool:
|
|
return value is None or isinstance(value, (str, bool, int, float))
|
|
|
|
def _scrub(value, key: str = ""):
|
|
"""Drop secrets and anonymise people, however deep. Every tool's reply passes through here."""
|
|
lowered = key.lower().replace("_", "").replace("-", "")
|
|
if lowered in SECRET_KEYS and not (lowered in SCALAR_SAFE_KEYS and _scalar(value)):
|
|
return "[redacted]"
|
|
if lowered in PERSON_KEYS:
|
|
return "[user]"
|
|
if isinstance(value, dict):
|
|
tag = str(value.get("Key", value.get("key", ""))).lower().replace("_", "").replace("-", "")
|
|
cleaned = {k: _scrub(v, str(k)) for k, v in value.items()}
|
|
for name in ("Value", "value"):
|
|
if name in cleaned and tag in PERSON_KEYS:
|
|
cleaned[name] = "[user]"
|
|
elif name in cleaned and tag in SECRET_KEYS and not (tag in SCALAR_SAFE_KEYS and _scalar(cleaned[name])):
|
|
cleaned[name] = "[redacted]"
|
|
return cleaned
|
|
if isinstance(value, (list, tuple)):
|
|
return [_scrub(v, "members" if lowered == "members" else "") for v in value]
|
|
if isinstance(value, str):
|
|
return _anonymise_member(value) if lowered == "members" else _clean_text(value)
|
|
if value is None or isinstance(value, (bool, int, float)):
|
|
return value
|
|
return str(value)
|
|
|
|
def _retry_delay(response, attempt: int) -> float:
|
|
"""How long the provider asked us to wait: Retry-After, or Resource Graph's hh:mm:ss quota reset."""
|
|
reset = response.headers.get("x-ms-user-quota-resets-after", "")
|
|
if reset.count(":") == 2:
|
|
hours, minutes, seconds = reset.split(":")
|
|
return int(hours) * 3600 + int(minutes) * 60 + float(seconds)
|
|
try:
|
|
return float(response.headers.get("retry-after", ""))
|
|
except ValueError:
|
|
return float(2 ** attempt)
|
|
|
|
async def _with_backoff(send):
|
|
"""Send, waiting when the provider throttles. The waits stay well inside the 120-second limit on an MCP call."""
|
|
waited = 0.0
|
|
response = await send()
|
|
for attempt in range(RETRY_ATTEMPTS):
|
|
if response.status_code not in (429, 503):
|
|
return response
|
|
delay = min(_retry_delay(response, attempt), RETRY_MAX_WAIT_SECONDS)
|
|
if waited + delay > RETRY_BUDGET_SECONDS:
|
|
return response
|
|
logger.info("upstream_throttled", status=response.status_code, wait_seconds=delay)
|
|
await asyncio.sleep(delay)
|
|
waited += delay
|
|
response = await send()
|
|
return response
|
|
|
|
def _page_size(arguments: Dict[str, Any]) -> int:
|
|
try:
|
|
size = int(arguments.get("page_size") or DEFAULT_PAGE_SIZE)
|
|
except (TypeError, ValueError):
|
|
return DEFAULT_PAGE_SIZE
|
|
return max(1, min(size, MAX_PAGE_SIZE))
|
|
|
|
def _read_page(arguments: Dict[str, Any]):
|
|
"""(upstream token, items of that upstream page already returned)."""
|
|
token = arguments.get("page_token")
|
|
if not token:
|
|
return None, 0
|
|
state = json.loads(base64.urlsafe_b64decode(str(token).encode()).decode())
|
|
return state["u"], int(state["s"])
|
|
|
|
def _write_page(upstream, skip: int) -> str:
|
|
return base64.urlsafe_b64encode(json.dumps({"u": upstream, "s": skip}).encode()).decode()
|
|
|
|
def _evidence_ref(tool: str, arguments: Dict[str, Any], payload) -> str:
|
|
asked = {k: v for k, v in arguments.items() if k != "page_token"}
|
|
blob = json.dumps([tool, asked, payload], sort_keys=True, default=str)
|
|
return "sha256:" + hashlib.sha256(blob.encode()).hexdigest()
|
|
|
|
def _collected_at() -> str:
|
|
return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
|
|
|
|
def _refuse(code: str, message: str) -> Dict[str, Any]:
|
|
return {"success": False, "error": {"code": code, "message": message}}
|
|
|
|
def _upstream_failed(provider: str, error: Exception) -> Dict[str, Any]:
|
|
"""Name the failure and never its text: an upstream error can quote a request or an identity."""
|
|
status = getattr(getattr(error, "response", None), "status_code", None)
|
|
code = getattr(error, "response", None)
|
|
if isinstance(code, dict):
|
|
status = code.get("Error", {}).get("Code")
|
|
logger.warning("upstream_call_failed", provider=provider, error_type=type(error).__name__, status=status)
|
|
detail = f" ({status})" if status else ""
|
|
return _refuse("upstream_failed", f"{provider} refused or failed the call: {type(error).__name__}{detail}")
|
|
|
|
def _page_result(provider: str, tool: str, arguments: Dict[str, Any], items: List[Any], used, upstream_next,
|
|
skip: int = 0, extra: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
|
|
"""One page of scrubbed items, cut at MAX_RESPONSE_BYTES; the token resumes exactly where the cut fell."""
|
|
remaining = [_scrub(item) for item in items[skip:]]
|
|
kept, size = [], 0
|
|
for item in remaining:
|
|
size += len(json.dumps(item, default=str))
|
|
if kept and size > MAX_RESPONSE_BYTES:
|
|
break
|
|
kept.append(item)
|
|
if len(kept) < len(remaining):
|
|
next_token = _write_page(used, skip + len(kept))
|
|
else:
|
|
next_token = _write_page(upstream_next, 0) if upstream_next else None
|
|
data = {"provider": provider, "items": kept, "count": len(kept), "next_page_token": next_token,
|
|
"collected_at": _collected_at(), "evidence_ref": _evidence_ref(tool, arguments, kept)}
|
|
data.update(extra or {})
|
|
return {"success": True, "data": data}
|
|
|
|
def _one_result(provider: str, tool: str, arguments: Dict[str, Any], metadata: Any) -> Dict[str, Any]:
|
|
clean = _scrub(metadata)
|
|
return {"success": True, "data": {"provider": provider, "metadata": clean, "collected_at": _collected_at(),
|
|
"evidence_ref": _evidence_ref(tool, arguments, clean)}}
|
|
|
|
AWS_SESSIONS = {}
|
|
|
|
AWS_SERVERS = {
|
|
"instances": ("ec2", "describe_instances", "Reservations", "NextToken", "NextToken", {}),
|
|
"auto_scaling_groups": ("autoscaling", "describe_auto_scaling_groups", "AutoScalingGroups", "NextToken", "NextToken", {}),
|
|
"volumes": ("ec2", "describe_volumes", "Volumes", "NextToken", "NextToken", {}),
|
|
}
|
|
|
|
AWS_WORKLOADS = {
|
|
"lambda_functions": ("lambda", "list_functions", "Functions", "Marker", "NextMarker", {}),
|
|
"ecs_clusters": ("ecs", "list_clusters", "clusterArns", "nextToken", "nextToken", {}),
|
|
"app_runner_services": ("apprunner", "list_services", "ServiceSummaryList", "NextToken", "NextToken", {}),
|
|
"elastic_beanstalk_environments": ("elasticbeanstalk", "describe_environments", "Environments", "NextToken", "NextToken", {}),
|
|
}
|
|
|
|
AWS_NETWORK = {
|
|
"vpcs": ("ec2", "describe_vpcs", "Vpcs", "NextToken", "NextToken", {}),
|
|
"subnets": ("ec2", "describe_subnets", "Subnets", "NextToken", "NextToken", {}),
|
|
"route_tables": ("ec2", "describe_route_tables", "RouteTables", "NextToken", "NextToken", {}),
|
|
"security_groups": ("ec2", "describe_security_groups", "SecurityGroups", "NextToken", "NextToken", {}),
|
|
"nat_gateways": ("ec2", "describe_nat_gateways", "NatGateways", "NextToken", "NextToken", {}),
|
|
"internet_gateways": ("ec2", "describe_internet_gateways", "InternetGateways", "NextToken", "NextToken", {}),
|
|
"transit_gateways": ("ec2", "describe_transit_gateways", "TransitGateways", "NextToken", "NextToken", {}),
|
|
"vpc_peering": ("ec2", "describe_vpc_peering_connections", "VpcPeeringConnections", "NextToken", "NextToken", {}),
|
|
"vpc_endpoints": ("ec2", "describe_vpc_endpoints", "VpcEndpoints", "NextToken", "NextToken", {}),
|
|
"load_balancers": ("elbv2", "describe_load_balancers", "LoadBalancers", "Marker", "NextMarker", {}),
|
|
}
|
|
|
|
AWS_DATA = {
|
|
"rds_instances": ("rds", "describe_db_instances", "DBInstances", "Marker", "Marker", {}),
|
|
"dynamodb_tables": ("dynamodb", "list_tables", "TableNames", "ExclusiveStartTableName", "LastEvaluatedTableName", {}),
|
|
"s3_buckets": ("s3", "list_buckets", "Buckets", "ContinuationToken", "ContinuationToken", {}),
|
|
}
|
|
|
|
AWS_ORG_POLICY_TYPES = {"service_control_policies": "SERVICE_CONTROL_POLICY", "resource_control_policies": "RESOURCE_CONTROL_POLICY",
|
|
"tag_policies": "TAG_POLICY", "backup_policies": "BACKUP_POLICY"}
|
|
|
|
AWS_PILLARS = {"cost_optimizing": "cost", "security": "security", "fault_tolerance": "reliability",
|
|
"performance": "performance", "operational_excellence": "operations", "service_limits": "reliability"}
|
|
|
|
def _aws_csv(connection: Dict[str, Any], field: str) -> List[str]:
|
|
return [v.strip() for v in str(connection.get(field) or "").split(",") if v.strip()]
|
|
|
|
def _aws_session(connection: Dict[str, Any], account_id: Optional[str]):
|
|
"""A session on the customer's read-only role, or on the member account's when one is named."""
|
|
key = hashlib.sha256(json.dumps([connection, account_id], sort_keys=True).encode()).hexdigest()
|
|
cached = AWS_SESSIONS.get(key)
|
|
now = time.time()
|
|
if cached and cached[1] > now + 60:
|
|
return cached[0]
|
|
|
|
def assume(session, role_arn, external_id=None):
|
|
region = _aws_csv(connection, "regions")[0]
|
|
request = {"RoleArn": role_arn, "RoleSessionName": "kab-discovery", "DurationSeconds": 3600}
|
|
if external_id:
|
|
request["ExternalId"] = external_id
|
|
found = session.client("sts", region_name=region).assume_role(**request)["Credentials"]
|
|
return boto3.Session(aws_access_key_id=found["AccessKeyId"], aws_secret_access_key=found["SecretAccessKey"],
|
|
aws_session_token=found["SessionToken"])
|
|
|
|
base = boto3.Session(aws_access_key_id=connection["access_key_id"], aws_secret_access_key=connection["secret_access_key"])
|
|
session = assume(base, connection["role_arn"], connection.get("external_id"))
|
|
if account_id:
|
|
partition = str(connection["role_arn"]).split(":")[1]
|
|
session = assume(session, f"arn:{partition}:iam::{account_id}:role/{connection['member_role_name']}")
|
|
AWS_SESSIONS[key] = (session, now + 3000)
|
|
return session
|
|
|
|
def _aws_target(arguments: Dict[str, Any]):
|
|
"""(account, region) or a refusal. Nothing outside the connection's accounts and regions is ever reached."""
|
|
connection = get_connection()
|
|
regions = _aws_csv(connection, "regions")
|
|
region = arguments.get("region") or regions[0]
|
|
if region not in regions:
|
|
return None, None, _refuse("outside_scope", "region isn't in this connection's regions")
|
|
account = arguments.get("account_id")
|
|
if account and (account not in _aws_csv(connection, "account_ids") or not connection.get("member_role_name")):
|
|
return None, None, _refuse("outside_scope", "account_id isn't in this connection's accounts")
|
|
return account, region, None
|
|
|
|
async def _aws_call(arguments: Dict[str, Any], service: str, operation: str, region: Optional[str] = None, **request):
|
|
connection = get_connection()
|
|
account = arguments.get("account_id")
|
|
where = region or arguments.get("region") or _aws_csv(connection, "regions")[0]
|
|
|
|
def run():
|
|
# Adaptive mode slows the client down when AWS throttles it, on top of retrying.
|
|
retries = BotoConfig(retries={"max_attempts": 6, "mode": "adaptive"}, read_timeout=60, connect_timeout=10)
|
|
client = _aws_session(connection, account).client(service, region_name=where, config=retries)
|
|
return getattr(client, operation)(**request)
|
|
|
|
return await asyncio.to_thread(run)
|
|
|
|
async def _aws_kind(tool: str, arguments: Dict[str, Any], kinds: Dict[str, tuple], default: str) -> Dict[str, Any]:
|
|
kind = arguments.get("kind") or default
|
|
if kind not in kinds:
|
|
return _refuse("unknown_kind", "kind must be one of: " + ", ".join(kinds))
|
|
account, region, refused = _aws_target(arguments)
|
|
if refused:
|
|
return refused
|
|
service, operation, result_key, token_in, token_out, fixed = kinds[kind]
|
|
try:
|
|
upstream, skip = _read_page(arguments)
|
|
except (ValueError, KeyError, TypeError):
|
|
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
|
request = dict(fixed)
|
|
if upstream:
|
|
request[token_in] = upstream
|
|
try:
|
|
body = await _aws_call(arguments, service, operation, region, **request)
|
|
except Exception as error:
|
|
return _upstream_failed("aws", error)
|
|
extra = {"account_id": account, "region": region, "kind": kind}
|
|
return _page_result("aws", tool, arguments, body.get(result_key, []), upstream, body.get(token_out), skip, extra)
|
|
|
|
async def _aws_each(tool: str, arguments: Dict[str, Any], list_kind: tuple, read) -> Dict[str, Any]:
|
|
"""List one page of things, then read a detail for each. A detail that's absent or refused is reported."""
|
|
account, region, refused = _aws_target(arguments)
|
|
if refused:
|
|
return refused
|
|
service, operation, result_key, token_in, token_out, fixed = list_kind
|
|
try:
|
|
upstream, skip = _read_page(arguments)
|
|
except (ValueError, KeyError, TypeError):
|
|
return _refuse("invalid_page_token", "page_token isn't one this server issued")
|
|
request = dict(fixed)
|
|
if upstream:
|
|
request[token_in] = upstream
|
|
try:
|
|
body = await _aws_call(arguments, service, operation, region, **request)
|
|
except Exception as error:
|
|
return _upstream_failed("aws", error)
|
|
items = []
|
|
for entry in body.get(result_key, [])[skip:skip + _page_size(arguments)]:
|
|
try:
|
|
items.append(await read(entry, region))
|
|
except Exception as error:
|
|
items.append({"resource": entry, "unread": type(error).__name__})
|
|
consumed = skip + len(items)
|
|
more = consumed < len(body.get(result_key, []))
|
|
next_upstream = upstream if more else body.get(token_out)
|
|
result = _page_result("aws", tool, arguments, items, None, None, 0, {"account_id": account, "region": region})
|
|
if more or next_upstream:
|
|
result["data"]["next_page_token"] = _write_page(next_upstream, consumed if more else 0)
|
|
return result
|
|
|
|
def _aws_document(text: Any) -> Any:
|
|
"""A policy document, parsed when it arrives as a JSON string, so its principals can be scrubbed."""
|
|
try:
|
|
return json.loads(text) if isinstance(text, str) else text
|
|
except ValueError:
|
|
return text
|
|
|
|
async def aws_check_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
try:
|
|
who = await _aws_call(arguments, "sts", "get_caller_identity")
|
|
except Exception as error:
|
|
return {"ok": False, "message": _upstream_failed("aws", error)["error"]["message"]}
|
|
return {"ok": True, "account": who.get("Account"), "message": "Assumed the read-only role."}
|
|
|
|
async def aws_list_accounts(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
kinds = {"accounts": ("organizations", "list_accounts", "Accounts", "NextToken", "NextToken", {}), "roots": ("organizations", "list_roots", "Roots", "NextToken", "NextToken", {})}
|
|
return await _aws_kind("aws_list_accounts", arguments, kinds, "accounts")
|
|
|
|
async def aws_list_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
resource_type = str(arguments.get("resource_type") or "")
|
|
if not re.fullmatch(r"AWS::[A-Za-z0-9]+::[A-Za-z0-9]+", resource_type):
|
|
return _refuse("invalid_argument", "resource_type must be a Config type, such as AWS::EC2::Instance")
|
|
kinds = {"config": ("config", "list_discovered_resources", "resourceIdentifiers", "nextToken", "nextToken", {"resourceType": resource_type})}
|
|
return await _aws_kind("aws_list_resources", {**arguments, "kind": "config"}, kinds, "config")
|
|
|
|
async def aws_query_resources(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
query = str(arguments.get("query") or "").strip()
|
|
if not query.upper().startswith("SELECT ") or len(query) > 4000:
|
|
return _refuse("invalid_argument", "query must be a SELECT, up to 4000 characters")
|
|
aggregator = get_connection().get("aggregator_name")
|
|
if aggregator:
|
|
kinds = {"q": ("config", "select_aggregate_resource_config", "Results", "NextToken", "NextToken", {"Expression": query, "ConfigurationAggregatorName": aggregator})}
|
|
else:
|
|
kinds = {"q": ("config", "select_resource_config", "Results", "NextToken", "NextToken", {"Expression": query})}
|
|
result = await _aws_kind("aws_query_resources", {**arguments, "kind": "q"}, kinds, "q")
|
|
if result.get("success"):
|
|
result["data"]["items"] = [_scrub(_aws_document(i)) for i in result["data"]["items"]]
|
|
return result
|
|
|
|
async def aws_get_resource_metadata(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
account, region, refused = _aws_target(arguments)
|
|
if refused:
|
|
return refused
|
|
try:
|
|
body = await _aws_call(arguments, "config", "get_resource_config_history", region, resourceType=arguments.get("resource_type"), resourceId=arguments.get("resource_id"), limit=1)
|
|
except Exception as error:
|
|
return _upstream_failed("aws", error)
|
|
items = body.get("configurationItems", [])
|
|
if not items:
|
|
return _refuse("not_found", "AWS Config holds no record of this resource")
|
|
return _one_result("aws", "aws_get_resource_metadata", arguments, _aws_document(items[0]))
|
|
|
|
async def aws_list_servers(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _aws_kind("aws_list_servers", arguments, AWS_SERVERS, "instances")
|
|
|
|
async def aws_list_workloads(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _aws_kind("aws_list_workloads", arguments, AWS_WORKLOADS, "lambda_functions")
|
|
|
|
async def aws_list_kubernetes_clusters(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
async def read(name, region):
|
|
cluster = (await _aws_call(arguments, "eks", "describe_cluster", region, name=name))["cluster"]
|
|
groups = await _aws_call(arguments, "eks", "list_nodegroups", region, clusterName=name)
|
|
return {**cluster, "nodegroups": groups.get("nodegroups", [])}
|
|
return await _aws_each("aws_list_kubernetes_clusters", arguments, ("eks", "list_clusters", "clusters", "nextToken", "nextToken", {}), read)
|
|
|
|
async def aws_get_network_topology(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _aws_kind("aws_get_network_topology", arguments, AWS_NETWORK, "vpcs")
|
|
|
|
async def aws_list_data_stores(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
return await _aws_kind("aws_list_data_stores", arguments, AWS_DATA, "rds_instances")
|
|
|
|
async def aws_list_organization_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
kind = arguments.get("kind") or "service_control_policies"
|
|
if kind == "config_rule_compliance":
|
|
kinds = {kind: ("config", "describe_compliance_by_config_rule", "ComplianceByConfigRules", "NextToken", "NextToken", {})}
|
|
return await _aws_kind("aws_list_organization_policies", arguments, kinds, kind)
|
|
if kind not in AWS_ORG_POLICY_TYPES:
|
|
return _refuse("unknown_kind", "kind must be one of: " + ", ".join(AWS_ORG_POLICY_TYPES) + ", config_rule_compliance")
|
|
|
|
async def read(entry, region):
|
|
policy = (await _aws_call(arguments, "organizations", "describe_policy", region, PolicyId=entry["Id"]))["Policy"]
|
|
targets = await _aws_call(arguments, "organizations", "list_targets_for_policy", region, PolicyId=entry["Id"])
|
|
return {"policy_id": entry["Id"], "name": entry.get("Name"), "type": entry.get("Type"), "layer": "organisation", "aws_managed": entry.get("AwsManaged"), "attached_to": targets.get("Targets", []), "document": _aws_document(policy.get("Content"))}
|
|
return await _aws_each("aws_list_organization_policies", arguments, ("organizations", "list_policies", "Policies", "NextToken", "NextToken", {"Filter": AWS_ORG_POLICY_TYPES[kind]}), read)
|
|
|
|
async def aws_list_resource_policies(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
kind = arguments.get("kind") or "s3_buckets"
|
|
|
|
def shaped(name, document, resource_type):
|
|
return {"name": name, "type": resource_type, "layer": "resource", "document": _aws_document(document)}
|
|
|
|
async def bucket(entry, region):
|
|
body = await _aws_call(arguments, "s3", "get_bucket_policy", region, Bucket=entry["Name"])
|
|
return shaped(entry["Name"], body.get("Policy"), "s3_bucket")
|
|
|
|
async def key(entry, region):
|
|
body = await _aws_call(arguments, "kms", "get_key_policy", region, KeyId=entry["KeyId"], PolicyName="default")
|
|
return shaped(entry["KeyId"], body.get("Policy"), "kms_key")
|
|
|
|
async def function(entry, region):
|
|
body = await _aws_call(arguments, "lambda", "get_policy", region, FunctionName=entry["FunctionName"])
|
|
return shaped(entry["FunctionName"], body.get("Policy"), "lambda_function")
|
|
|
|
async def queue(url, region):
|
|
body = await _aws_call(arguments, "sqs", "get_queue_attributes", region, QueueUrl=url, AttributeNames=["Policy"])
|
|
return shaped(url, body.get("Attributes", {}).get("Policy"), "sqs_queue")
|
|
|
|
async def topic(entry, region):
|
|
body = await _aws_call(arguments, "sns", "get_topic_attributes", region, TopicArn=entry["TopicArn"])
|
|
return shaped(entry["TopicArn"], body.get("Attributes", {}).get("Policy"), "sns_topic")
|
|
|
|
async def role(entry, region):
|
|
return shaped(entry["RoleName"], entry.get("AssumeRolePolicyDocument"), "iam_role_trust")
|
|
|
|
kinds = {"s3_buckets": (("s3", "list_buckets", "Buckets", "ContinuationToken", "ContinuationToken", {}), bucket),
|
|
"kms_keys": (("kms", "list_keys", "Keys", "Marker", "NextMarker", {}), key),
|
|
"lambda_functions": (("lambda", "list_functions", "Functions", "Marker", "NextMarker", {}), function),
|
|
"sqs_queues": (("sqs", "list_queues", "QueueUrls", "NextToken", "NextToken", {}), queue),
|
|
"sns_topics": (("sns", "list_topics", "Topics", "NextToken", "NextToken", {}), topic),
|
|
"iam_role_trust": (("iam", "list_roles", "Roles", "Marker", "Marker", {}), role)}
|
|
if kind not in kinds:
|
|
return _refuse("unknown_kind", "kind must be one of: " + ", ".join(kinds))
|
|
return await _aws_each("aws_list_resource_policies", arguments, kinds[kind][0], kinds[kind][1])
|
|
|
|
async def aws_list_recommendations(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
kind = arguments.get("kind") or "trusted_advisor"
|
|
if kind == "well_architected_reviews":
|
|
async def read(entry, region):
|
|
lenses = await _aws_call(arguments, "wellarchitected", "list_lens_reviews", region, WorkloadId=entry["WorkloadId"])
|
|
return {"workload": entry, "lens_reviews": lenses.get("LensReviewSummaries", [])}
|
|
return await _aws_each("aws_list_recommendations", arguments, ("wellarchitected", "list_workloads", "WorkloadSummaries", "NextToken", "NextToken", {}), read)
|
|
if kind != "trusted_advisor":
|
|
return _refuse("unknown_kind", "kind must be trusted_advisor or well_architected_reviews")
|
|
|
|
async def read(entry, region):
|
|
pillars = entry.get("pillars") or []
|
|
return {**entry, "pillar": [AWS_PILLARS.get(p, "other") for p in pillars], "provider_category": pillars}
|
|
return await _aws_each("aws_list_recommendations", arguments, ("trustedadvisor", "list_recommendations", "recommendationSummaries", "nextToken", "nextToken", {}), read)
|
|
|
|
async def verify_connection(arguments: Dict[str, Any]) -> Dict[str, Any]:
|
|
"""Check that the connection sent with this request works against the upstream. Makes no change."""
|
|
connection = get_connection()
|
|
if not connection:
|
|
return {"ok": False, "message": "No connection was sent with this request."}
|
|
missing = mcp_connection.missing_fields(connection, CONNECTION_SCHEMA)
|
|
if missing:
|
|
return {"ok": False, "message": "The connection is missing: " + ", ".join(missing)}
|
|
|
|
return await aws_check_connection(arguments)
|
|
|
|
|
|
# Tool function registry
|
|
TOOL_FUNCTIONS = {
|
|
'aws_check_connection': aws_check_connection,
|
|
'aws_list_accounts': aws_list_accounts,
|
|
'aws_list_resources': aws_list_resources,
|
|
'aws_query_resources': aws_query_resources,
|
|
'aws_get_resource_metadata': aws_get_resource_metadata,
|
|
'aws_list_servers': aws_list_servers,
|
|
'aws_list_workloads': aws_list_workloads,
|
|
'aws_list_kubernetes_clusters': aws_list_kubernetes_clusters,
|
|
'aws_get_network_topology': aws_get_network_topology,
|
|
'aws_list_data_stores': aws_list_data_stores,
|
|
'aws_list_organization_policies': aws_list_organization_policies,
|
|
'aws_list_resource_policies': aws_list_resource_policies,
|
|
'aws_list_recommendations': aws_list_recommendations,
|
|
'verify_connection': verify_connection,
|
|
}
|
|
|
|
# ============================================
|
|
# Resource Implementations
|
|
# ============================================
|
|
|
|
|
|
# Resource read handlers by uri
|
|
RESOURCE_HANDLERS = {
|
|
|
|
}
|
|
|
|
# ============================================
|
|
# FastAPI Application
|
|
# ============================================
|
|
|
|
@asynccontextmanager
|
|
async def lifespan(app: FastAPI):
|
|
"""Application lifespan manager"""
|
|
logger.info(
|
|
"server_starting",
|
|
port=config.SERVER_PORT,
|
|
auth_required=config.REQUIRE_AUTH,
|
|
tools=len(TOOLS_REGISTRY),
|
|
resources=len(RESOURCES_REGISTRY),
|
|
prompts=len(PROMPTS_REGISTRY),
|
|
template_version=TEMPLATE_VERSION,
|
|
)
|
|
|
|
# Validate configuration
|
|
if config.REQUIRE_AUTH and not config.MCP_REGISTRATION_API_KEY:
|
|
logger.error(
|
|
"registration_key_not_set",
|
|
hint="Set MCP_REGISTRATION_API_KEY before starting the server",
|
|
)
|
|
|
|
yield
|
|
|
|
await _close_all_clients()
|
|
logger.info("server_stopping")
|
|
|
|
app = FastAPI(
|
|
title=config.SERVER_NAME,
|
|
version=config.SERVER_VERSION,
|
|
description="Read-only discovery of a customer's AWS estate - servers, workloads, Kubernetes clusters, networks, data stores, policies and Trusted Advisor findings.",
|
|
lifespan=lifespan
|
|
)
|
|
|
|
|
|
# FastAPI's default answer to an invalid request repeats it, and the request can carry the tenant's connection
|
|
mcp_connection.install_invalid_request_handler(
|
|
app, lambda fields: logger.warning("invalid_request", fields=sanitize_log(fields))
|
|
)
|
|
|
|
# ============================================
|
|
# Health Check Endpoint
|
|
# ============================================
|
|
|
|
@app.get("/health")
|
|
async def health_check():
|
|
"""
|
|
Health check endpoint (no authentication required).
|
|
|
|
Used by:
|
|
- MCP Gateway health monitoring
|
|
- Kubernetes liveness/readiness probes
|
|
- Load balancers
|
|
"""
|
|
# Answers without a key, so it says only what a probe needs: not how authentication is set up
|
|
return {
|
|
"status": "healthy" if config.MCP_REGISTRATION_API_KEY else "degraded",
|
|
"server_id": config.SERVER_ID,
|
|
"server_name": config.SERVER_NAME,
|
|
"version": config.SERVER_VERSION,
|
|
"timestamp": datetime.now(timezone.utc).isoformat(),
|
|
}
|
|
|
|
# ============================================
|
|
# MCP Authentication Info Endpoint
|
|
# ============================================
|
|
|
|
@app.get("/.well-known/mcp-auth")
|
|
async def mcp_auth_info():
|
|
"""
|
|
MCP Authentication Information Endpoint (PUBLIC - no auth required).
|
|
|
|
Exposes authentication requirements for Gateway registration.
|
|
"""
|
|
return {
|
|
"auth_required": config.REQUIRE_AUTH,
|
|
"auth_type": "bearer",
|
|
"description": "Include 'Authorization: Bearer <MCP_REGISTRATION_API_KEY>' header",
|
|
"env_var": "MCP_REGISTRATION_API_KEY"
|
|
}
|
|
|
|
# ============================================
|
|
# MCP Protocol /messages Endpoint
|
|
# ============================================
|
|
|
|
class _MethodNotFound(Exception):
|
|
"""The JSON-RPC method is not one this server answers."""
|
|
|
|
|
|
async def dispatch_mcp_request(request: MCPRequest) -> MCPResponse:
|
|
"""Run one JSON-RPC request; every outcome, errors included, is an MCPResponse."""
|
|
# The tenant's connection, bound for this request only so tools reach the right account
|
|
connection_token = mcp_connection.bind(mcp_connection.from_params(request.params))
|
|
try:
|
|
if CONNECTION_SCHEMA is not None and request.method in CONNECTION_METHODS:
|
|
check_connection(mcp_connection.active())
|
|
|
|
if request.method == "initialize":
|
|
result = {
|
|
"protocolVersion": "1.0.0",
|
|
"serverInfo": {
|
|
"name": config.SERVER_NAME,
|
|
"version": config.SERVER_VERSION,
|
|
"server_id": config.SERVER_ID
|
|
},
|
|
"capabilities": {
|
|
"tools": True,
|
|
"resources": False,
|
|
"prompts": False
|
|
},
|
|
"authentication": {
|
|
"type": "bearer",
|
|
"description": "Requires MCP_REGISTRATION_API_KEY in Authorization header"
|
|
}
|
|
}
|
|
if CONNECTION_SCHEMA is not None:
|
|
result["_meta"] = mcp_connection.schema_meta(CONNECTION_SCHEMA, verify_tool=VERIFY_TOOL)
|
|
return MCPResponse(id=request.id, result=result)
|
|
|
|
elif request.method == "tools/list":
|
|
return MCPResponse(id=request.id, result={"tools": TOOLS_REGISTRY})
|
|
|
|
elif request.method == "tools/call":
|
|
tool_name = request.params.get("name")
|
|
arguments = request.params.get("arguments")
|
|
if arguments is None:
|
|
arguments = {}
|
|
|
|
if not tool_name:
|
|
raise ValueError("Missing 'name' in params")
|
|
if not isinstance(tool_name, str):
|
|
raise ValueError("'name' must be a string")
|
|
if not isinstance(arguments, dict):
|
|
raise ValueError("'arguments' must be an object")
|
|
|
|
structlog.contextvars.bind_contextvars(tool=sanitize_log(tool_name))
|
|
tool_func = TOOL_FUNCTIONS.get(tool_name)
|
|
if not tool_func:
|
|
raise ValueError(f"Unknown tool: {tool_name}")
|
|
|
|
result = await tool_func(arguments)
|
|
if isinstance(result, dict) and result.get("success") is False and isinstance(result.get("error"), str):
|
|
# A failed call's message often quotes the upstream URL, which may carry a key
|
|
result = {**result, "error": mcp_connection.scrub(result["error"])}
|
|
|
|
reply = {
|
|
"content": [
|
|
{
|
|
"type": "text",
|
|
"text": json.dumps(result) if isinstance(result, dict) else str(result)
|
|
}
|
|
]
|
|
}
|
|
if isinstance(result, dict) and result.get("success") is False:
|
|
# A tool that reports failure is an error to the caller too (MCP: isError), not a normal result
|
|
reply["isError"] = True
|
|
return MCPResponse(id=request.id, result=reply)
|
|
|
|
elif request.method == "resources/list":
|
|
return MCPResponse(id=request.id, result={"resources": RESOURCES_REGISTRY})
|
|
|
|
elif request.method == "resources/read":
|
|
uri = request.params.get("uri")
|
|
if not uri:
|
|
raise ValueError("Missing 'uri' in params")
|
|
structlog.contextvars.bind_contextvars(resource=sanitize_log(uri))
|
|
handler = RESOURCE_HANDLERS.get(uri)
|
|
if not handler:
|
|
raise ValueError(f"Unknown resource: {uri}")
|
|
content = await handler(uri)
|
|
mime_type = next((r["mimeType"] for r in RESOURCES_REGISTRY if r["uri"] == uri), "text/plain")
|
|
text = content if isinstance(content, str) else json.dumps(content)
|
|
return MCPResponse(id=request.id, result={
|
|
"contents": [{"uri": uri, "mimeType": mime_type, "text": text}]
|
|
})
|
|
|
|
elif request.method == "prompts/list":
|
|
return MCPResponse(id=request.id, result={"prompts": PROMPTS_REGISTRY})
|
|
|
|
elif request.method == "prompts/get":
|
|
prompt_name = request.params.get("name")
|
|
prompt = PROMPT_TEMPLATES.get(prompt_name) if isinstance(prompt_name, str) else None
|
|
if prompt is None:
|
|
raise ValueError(f"Unknown prompt: {prompt_name}")
|
|
structlog.contextvars.bind_contextvars(prompt=sanitize_log(prompt_name))
|
|
supplied = request.params.get("arguments") or {}
|
|
values = {a["name"]: a["default"] for a in prompt["arguments"] if a["default"] is not None}
|
|
values.update(supplied)
|
|
missing = [a["name"] for a in prompt["arguments"] if a["required"] and a["name"] not in values]
|
|
if missing:
|
|
raise ValueError("Missing prompt argument(s): " + ", ".join(missing))
|
|
return MCPResponse(id=request.id, result={
|
|
"description": prompt["description"],
|
|
"messages": [{
|
|
"role": "user",
|
|
"content": {"type": "text", "text": render_prompt(prompt["template"], values)},
|
|
}],
|
|
})
|
|
|
|
else:
|
|
raise _MethodNotFound(f"Unknown method: {request.method}")
|
|
|
|
except _MethodNotFound as e:
|
|
logger.warning("mcp_method_not_found", error=sanitize_log(mcp_connection.redact(e)))
|
|
return MCPResponse(id=request.id, error={"code": -32601, "message": mcp_connection.redact(e)})
|
|
except NotImplementedError as e:
|
|
message = mcp_connection.redact(e)
|
|
logger.warning("tool_not_implemented", error=sanitize_log(message))
|
|
return MCPResponse(id=request.id, error={"code": -32601, "message": message})
|
|
except ValueError as e:
|
|
message = mcp_connection.redact(e)
|
|
logger.warning("mcp_client_error", error=sanitize_log(message))
|
|
return MCPResponse(id=request.id, error={"code": -32602, "message": message})
|
|
except Exception as e:
|
|
# The message of an unexpected error is not shown to the caller and is redacted before it is logged;
|
|
# a tool may have put the connection's credential in it.
|
|
logger.error(
|
|
"mcp_unexpected_error",
|
|
error_type=type(e).__name__,
|
|
error=sanitize_log(mcp_connection.redact(e)),
|
|
traceback=sanitize_log(mcp_connection.redact(traceback.format_exc())),
|
|
)
|
|
return MCPResponse(id=request.id, error={"code": -32603, "message": "Internal server error"})
|
|
finally:
|
|
mcp_connection.unbind(connection_token)
|
|
|
|
|
|
@app.post("/messages")
|
|
async def handle_mcp_message(
|
|
request: MCPRequest,
|
|
http_request: Request,
|
|
authenticated: bool = Depends(verify_mcp_registration_key)
|
|
) -> MCPResponse:
|
|
"""
|
|
MCP protocol message handler (JSON-RPC 2.0 over HTTP).
|
|
|
|
This is the STANDARD MCP endpoint for Gateway integration.
|
|
Requires Bearer token authentication (MCP_REGISTRATION_API_KEY).
|
|
|
|
Supported Methods:
|
|
- initialize: Protocol handshake and capability exchange
|
|
- tools/list: Discover available tools
|
|
- tools/call: Execute a specific tool
|
|
- resources/list: List available resources
|
|
- prompts/list: List available prompts
|
|
"""
|
|
started = time.monotonic()
|
|
structlog.contextvars.clear_contextvars()
|
|
structlog.contextvars.bind_contextvars(
|
|
request_id=sanitize_log(http_request.headers.get("x-request-id") or str(request.id)),
|
|
method=sanitize_log(request.method),
|
|
)
|
|
try:
|
|
response = await dispatch_mcp_request(request)
|
|
completed = {}
|
|
if CONNECTION_SCHEMA is not None and request.method in CONNECTION_METHODS:
|
|
# Which connection served the call: a short id, never the credential
|
|
completed["connection"] = mcp_connection.fingerprint(mcp_connection.from_params(request.params))
|
|
logger.info(
|
|
"mcp_request_completed",
|
|
outcome="error" if response.error else ("tool_error" if (response.result or {}).get("isError") else "ok"),
|
|
error_code=(response.error or {}).get("code"),
|
|
duration_ms=round((time.monotonic() - started) * 1000, 1),
|
|
**completed,
|
|
)
|
|
return response
|
|
finally:
|
|
structlog.contextvars.clear_contextvars()
|
|
|
|
# ============================================
|
|
# Entry Point
|
|
# ============================================
|
|
|
|
if __name__ == "__main__":
|
|
import uvicorn
|
|
uvicorn.run(
|
|
"server:app",
|
|
host="0.0.0.0",
|
|
port=config.SERVER_PORT,
|
|
log_level=logging.getLevelName(getattr(logging, config.LOG_LEVEL, logging.INFO)).lower(),
|
|
log_config=None, # configure_logging() owns the format
|
|
access_log=True,
|
|
reload=False # Set to True for development
|
|
)
|