@raghulm/aegis-mcp 1.0.2 → 1.0.4

package/package.json

@@ -1,39 +1,53 @@
-{
-  "name": "@raghulm/aegis-mcp",
-  "version": "1.0.2",
-  "description": "🛡️ Open-source DevSecOps MCP server — gives AI agents real hands in your cloud infrastructure",
-  "homepage": "https://github.com/raghulvj01/aegis-mcp",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/raghulvj01/aegis-mcp.git"
-  },
-  "bugs": {
-    "url": "https://github.com/raghulvj01/aegis-mcp/issues"
-  },
-  "author": "Raghul VJ <raghulvj01@gmail.com>",
-  "license": "MIT",
-  "keywords": [
-    "mcp",
-    "devsecops",
-    "aws",
-    "kubernetes",
-    "security",
-    "ai-agents",
-    "claude",
-    "trivy",
-    "semgrep",
-    "open-source",
-    "fastmcp",
-    "docker",
-    "cloud-security"
-  ],
-  "bin": {
-    "aegis-mcp": "./bin/aegis-mcp.js"
-  },
-  "engines": {
-    "node": ">=16.0.0"
-  },
-  "files": [
-    "bin/"
-  ]
-}
+{
+  "name": "@raghulm/aegis-mcp",
+  "version": "1.0.4",
+  "description": "DevSecOps-focused MCP server for AWS, Kubernetes, CI/CD, and security tooling.",
+  "license": "MIT",
+  "author": "Raghul M",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/raghulvj01/aegis-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/raghulvj01/aegis-mcp/issues"
+  },
+  "homepage": "https://github.com/raghulvj01/aegis-mcp#readme",
+  "type": "commonjs",
+  "bin": {
+    "aegis-mcp": "bin/aegis-mcp.js"
+  },
+  "scripts": {
+    "setup:python": "node ./bin/prepare-python-env.js",
+    "start": "node ./bin/aegis-mcp.js",
+    "pack:check": "npm pack --dry-run"
+  },
+  "files": [
+    "audit/**/*.py",
+    "bin/*.js",
+    "policies/*.yaml",
+    "server/**/*.py",
+    "tools/**/*.py",
+    "requirements.txt",
+    "run_stdio.py",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "devsecops",
+    "security",
+    "aws",
+    "kubernetes",
+    "claude"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@raghulm/aegis-mcp": "^1.0.3"
+  }
+}

package/policies/roles.yaml

@@ -0,0 +1,34 @@
+roles:
+  viewer:
+    - aws_list_ec2_instances
+    - k8s_list_pods
+    - git_recent_commits
+    - security_check_ssl_certificate
+    - security_check_http_headers
+    - network_port_scan
+    - security_semgrep_scan
+  security:
+    - k8s_security_audit
+    - security_run_trivy_scan
+    - git_recent_commits
+    - security_scan_secrets
+    - security_check_ssl_certificate
+    - security_check_dependencies
+    - security_check_http_headers
+    - security_semgrep_scan
+    - aws_check_s3_public_access
+    - network_port_scan
+  admin:
+    - aws_list_ec2_instances
+    - k8s_list_pods
+    - k8s_security_audit
+    - security_run_trivy_scan
+    - git_recent_commits
+    - cicd_pipeline_status
+    - security_scan_secrets
+    - security_check_ssl_certificate
+    - security_check_dependencies
+    - security_check_http_headers
+    - security_semgrep_scan
+    - aws_check_s3_public_access
+    - network_port_scan

package/policies/scope_rules.yaml

@@ -0,0 +1,16 @@
+scopes:
+  aegis.read:
+    - aws_list_ec2_instances
+    - k8s_list_pods
+    - git_recent_commits
+    - cicd_pipeline_status
+    - security_check_ssl_certificate
+    - security_check_http_headers
+    - network_port_scan
+    - aws_check_s3_public_access
+    - security_semgrep_scan
+  aegis.security:
+    - security_run_trivy_scan
+    - security_scan_secrets
+    - security_check_dependencies
+    - security_semgrep_scan

package/requirements.txt

@@ -0,0 +1,7 @@
+mcp>=1.0.0
+boto3>=1.34.0
+requests>=2.32.0
+fastapi>=0.111.0
+uvicorn>=0.30.0
+pyyaml>=6.0.1
+semgrep>=1.60.0

package/run_stdio.py

@@ -0,0 +1,22 @@
+"""Launcher script for Claude Desktop — ensures the project root is on sys.path."""
+import sys
+import os
+
+# Set working directory and sys.path to the project root so that
+# relative policy file paths (policies/roles.yaml etc.) resolve correctly
+PROJECT_ROOT = os.path.dirname(os.path.abspath(__file__))
+os.chdir(PROJECT_ROOT)
+sys.path.insert(0, PROJECT_ROOT)
+
+# Disable JWT auth for local stdio sessions (Claude Desktop cannot supply tokens)
+os.environ.setdefault("MCP_AUTH_DISABLED", "true")
+
+# Ensure the venv Scripts dir is on PATH so pysemgrep / semgrep-core are found
+venv_scripts = os.path.join(PROJECT_ROOT, ".venv", "Scripts")
+if os.path.isdir(venv_scripts) and venv_scripts not in os.environ.get("PATH", ""):
+    os.environ["PATH"] = venv_scripts + os.pathsep + os.environ.get("PATH", "")
+
+from server.main import mcp
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")

package/server/auth.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+
+from server.config import Settings
+
+
+@dataclass(frozen=True)
+class Principal:
+    subject: str
+    role: str
+    scopes: list[str]
+
+
+class AuthorizationError(PermissionError):
+    pass
+
+
+
+def _decode_jwt_payload(token: str) -> dict:
+    parts = token.split(".")
+    if len(parts) < 2:
+        return {}
+    payload = parts[1]
+    padding = "=" * ((4 - len(payload) % 4) % 4)
+    decoded = base64.urlsafe_b64decode(payload + padding)
+    return json.loads(decoded.decode("utf-8"))
+
+
+
+def decode_bearer_token(token: str, settings: Settings) -> Principal:
+    """Decode claims from a bearer token payload.
+
+    This implementation parses JWT payload claims and is intended as a scaffold.
+    Replace with strict signature/JWKS validation in production.
+    """
+    claims = _decode_jwt_payload(token)
+
+    if settings.oidc_issuer and claims.get("iss") != settings.oidc_issuer:
+        raise AuthorizationError("token issuer mismatch")
+    if settings.oidc_audience and settings.oidc_audience not in str(claims.get("aud", "")):
+        raise AuthorizationError("token audience mismatch")
+
+    role = str(claims.get("role", "viewer"))
+    scope_claim = claims.get("scope", "")
+    scopes = scope_claim.split() if isinstance(scope_claim, str) else []
+    return Principal(subject=str(claims.get("sub", "unknown")), role=role, scopes=scopes)
+
+
+
+def authorize_tool(
+    principal: Principal,
+    tool_name: str,
+    role_policies: dict[str, list[str]],
+    scope_policies: dict[str, list[str]],
+) -> None:
+    allowed_by_role = set(role_policies.get(principal.role, []))
+    allowed_by_scope: set[str] = set()
+    for scope in principal.scopes:
+        allowed_by_scope.update(scope_policies.get(scope, []))
+
+    if tool_name in allowed_by_role or tool_name in allowed_by_scope:
+        return
+
+    raise AuthorizationError(
+        f"principal '{principal.subject}' with role '{principal.role}' is not allowed to call '{tool_name}'"
+    )

package/server/config.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class Settings:
+    """Runtime configuration for the MCP service."""
+
+    service_name: str = "aegis"
+    environment: str = "dev"
+    policy_roles_path: Path = Path("policies/roles.yaml")
+    policy_scopes_path: Path = Path("policies/scope_rules.yaml")
+    oidc_issuer: str | None = None
+    oidc_audience: str | None = None
+
+
+
+def _parse_simple_yaml(raw: str) -> dict[str, Any]:
+    """Very small YAML subset parser for key/list policy files."""
+    root: dict[str, Any] = {}
+    current_section: dict[str, list[str]] | None = None
+    current_key: str | None = None
+    for line in raw.splitlines():
+        stripped = line.rstrip()
+        if not stripped or stripped.lstrip().startswith("#"):
+            continue
+        if not line.startswith(" ") and stripped.endswith(":"):
+            section = stripped[:-1]
+            root[section] = {}
+            current_section = root[section]
+            current_key = None
+        elif current_section is not None and line.startswith("  ") and stripped.endswith(":"):
+            current_key = stripped[:-1]
+            current_section[current_key] = []
+        elif current_section is not None and current_key and line.strip().startswith("-"):
+            value = line.split("-", maxsplit=1)[1].strip().strip('"')
+            current_section[current_key].append(value)
+    return root
+
+
+
+def _load_yaml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    content = path.read_text(encoding="utf-8")
+    try:
+        import yaml  # type: ignore
+
+        return yaml.safe_load(content) or {}
+    except Exception:
+        return _parse_simple_yaml(content)
+
+
+
+def load_settings() -> Settings:
+    return Settings(
+        service_name=os.getenv("MCP_SERVICE_NAME", "aegis"),
+        environment=os.getenv("MCP_ENV", "dev"),
+        policy_roles_path=Path(os.getenv("MCP_ROLES_FILE", "policies/roles.yaml")),
+        policy_scopes_path=Path(os.getenv("MCP_SCOPES_FILE", "policies/scope_rules.yaml")),
+        oidc_issuer=os.getenv("OIDC_ISSUER"),
+        oidc_audience=os.getenv("OIDC_AUDIENCE"),
+    )
+
+
+
+def load_role_policies(settings: Settings) -> dict[str, list[str]]:
+    raw = _load_yaml(settings.policy_roles_path)
+    roles = raw.get("roles", {})
+    return {str(k): [str(v) for v in values] for k, values in roles.items()}
+
+
+
+def load_scope_policies(settings: Settings) -> dict[str, list[str]]:
+    raw = _load_yaml(settings.policy_scopes_path)
+    scopes = raw.get("scopes", {})
+    return {str(k): [str(v) for v in values] for k, values in scopes.items()}

package/server/health.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+from fastapi.responses import JSONResponse
+from mcp.server.fastmcp import FastMCP
+
+from server.config import load_settings
+
+settings = load_settings()
+mcp = FastMCP(settings.service_name, json_response=True)
+app = FastAPI(title="aegis-mcp")
+
+
+@app.get("/health")
+def health() -> JSONResponse:
+    return JSONResponse({"status": "ok", "service": settings.service_name})
+
+
+app.mount("/mcp", mcp.streamable_http_app())

package/server/logging.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+from typing import Any
+
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload: dict[str, Any] = {
+            "timestamp": datetime.now(tz=timezone.utc).isoformat(),
+            "level": record.levelname,
+            "message": record.getMessage(),
+            "logger": record.name,
+        }
+        extra = getattr(record, "extra_payload", None)
+        if isinstance(extra, dict):
+            payload.update(extra)
+        return json.dumps(payload, default=str)
+
+
+def get_logger(name: str = "mcp.aegis") -> logging.Logger:
+    logger = logging.getLogger(name)
+    if logger.handlers:
+        return logger
+    logger.setLevel(logging.INFO)
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(JsonFormatter())
+    logger.addHandler(handler)
+    logger.propagate = False
+    return logger

package/server/main.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import os
+
+from mcp.server.fastmcp import FastMCP
+
+from audit.audit_logger import audit_tool_call
+from server.auth import authorize_tool, decode_bearer_token
+from server.config import load_role_policies, load_scope_policies, load_settings
+from tools.aws.ec2 import list_ec2_instances
+from tools.aws.s3 import check_s3_public_access
+from tools.cicd.pipeline import pipeline_status
+from tools.git.repo import get_recent_commits
+from tools.kubernetes.pods import list_pods
+from tools.kubernetes.audit import k8s_security_audit
+from tools.network.headers import check_http_headers
+from tools.network.port_scanner import port_scan
+from tools.network.ssl_checker import check_ssl_certificate
+from tools.security.deps import check_dependencies
+from tools.security.secrets import scan_secrets
+from tools.security.semgrep import run_semgrep_scan
+from tools.security.trivy import run_trivy_scan
+
+settings = load_settings()
+role_policies = load_role_policies(settings)
+scope_policies = load_scope_policies(settings)
+
+mcp = FastMCP(settings.service_name, json_response=True)
+
+AUTH_DISABLED = os.getenv("MCP_AUTH_DISABLED", "false").lower() == "true"
+
+
+def _authorize(token: str, tool_name: str) -> None:
+    if AUTH_DISABLED or not token:
+        return
+    principal = decode_bearer_token(token, settings)
+    authorize_tool(principal, tool_name, role_policies, scope_policies)
+
+
+@mcp.tool()
+@audit_tool_call("aws_list_ec2_instances")
+def aws_list_ec2_instances(region: str, token: str = "") -> list[dict]:
+    _authorize(token, "aws_list_ec2_instances")
+    return list_ec2_instances(region)
+
+
+@mcp.tool()
+@audit_tool_call("k8s_list_pods")
+def k8s_list_pods(namespace: str = "default", token: str = "") -> list[dict]:
+    _authorize(token, "k8s_list_pods")
+    return list_pods(namespace)
+
+
+@mcp.tool()
+@audit_tool_call("k8s_security_audit")
+def k8s_security_audit_tool(namespace: str = "", token: str = "") -> list[dict]:
+    """Audit Kubernetes clusters for misconfigurations and security risks (privileged containers, hostNetwork, exposed NodePorts, cluster-admin service accounts)."""
+    _authorize(token, "k8s_security_audit")
+    return k8s_security_audit(namespace)
+
+
+@mcp.tool()
+@audit_tool_call("security_run_trivy_scan")
+def security_run_trivy_scan(image: str, token: str = "") -> dict:
+    _authorize(token, "security_run_trivy_scan")
+    return run_trivy_scan(image)
+
+
+@mcp.tool()
+@audit_tool_call("git_recent_commits")
+def git_recent_commits(limit: int = 10, token: str = "") -> list[dict[str, str]]:
+    _authorize(token, "git_recent_commits")
+    return get_recent_commits(limit)
+
+
+@mcp.tool()
+@audit_tool_call("cicd_pipeline_status")
+def cicd_pipeline_status(base_url: str, pipeline_id: str, api_token: str, token: str = "") -> dict:
+    """Fetch the status of a CI/CD pipeline."""
+    _authorize(token, "cicd_pipeline_status")
+    return pipeline_status(base_url, pipeline_id, api_token)
+
+
+# ── New zero-install tools ─────────────────────────────────────────
+
+
+@mcp.tool()
+@audit_tool_call("security_scan_secrets")
+def security_scan_secrets(path: str, token: str = "") -> list[dict]:
+    """Scan local files or directories for exposed secrets (API keys, tokens, passwords). This tool runs locally and has full access to the user's local filesystem (e.g. C:\\... paths)."""
+    _authorize(token, "security_scan_secrets")
+    return scan_secrets(path)
+
+
+@mcp.tool()
+@audit_tool_call("security_check_ssl_certificate")
+def security_check_ssl_certificate(hostname: str, port: int = 443, token: str = "") -> dict:
+    """Check SSL/TLS certificate details and expiry for a domain."""
+    _authorize(token, "security_check_ssl_certificate")
+    return check_ssl_certificate(hostname, port)
+
+
+@mcp.tool()
+@audit_tool_call("security_check_dependencies")
+def security_check_dependencies(file_path: str, token: str = "") -> list[dict]:
+    """Scan dependency files (requirements.txt, package.json) for known vulnerabilities via OSV.dev."""
+    _authorize(token, "security_check_dependencies")
+    return check_dependencies(file_path)
+
+
+@mcp.tool()
+@audit_tool_call("security_check_http_headers")
+def security_check_http_headers(url: str, token: str = "") -> dict:
+    """Audit HTTP security headers (HSTS, CSP, X-Frame-Options, etc.) for a URL."""
+    _authorize(token, "security_check_http_headers")
+    return check_http_headers(url)
+
+
+@mcp.tool()
+@audit_tool_call("aws_check_s3_public_access")
+def aws_check_s3_public_access(region: str = "us-east-1", token: str = "") -> list[dict]:
+    """Audit S3 buckets for public access settings."""
+    _authorize(token, "aws_check_s3_public_access")
+    return check_s3_public_access(region)
+
+
+@mcp.tool()
+@audit_tool_call("network_port_scan")
+def network_port_scan(host: str, ports: str = "", token: str = "") -> list[dict]:
+    """Perform a TCP port scan on common service ports for a host."""
+    _authorize(token, "network_port_scan")
+    return port_scan(host, ports)
+
+
+@mcp.tool()
+@audit_tool_call("security_semgrep_scan")
+def security_semgrep_scan(path: str, config: str = "auto", token: str = "") -> dict:
+    """Run a Semgrep SAST scan on a local directory or file. This tool runs locally and has full access to the user's local filesystem (e.g. C:\\... paths). Config can be 'auto', 'p/python', 'p/javascript', etc."""
+    _authorize(token, "security_semgrep_scan")
+    return run_semgrep_scan(path, config)
+
+
+if __name__ == "__main__":
+    mcp.run(transport="streamable-http")

package/server/stdio.py

@@ -0,0 +1,7 @@
+"""Stdio entry-point for Claude Desktop and other MCP clients that launch the server as a subprocess."""
+from __future__ import annotations
+
+from server.main import mcp
+
+if __name__ == "__main__":
+    mcp.run(transport="stdio")

package/tools/aws/ec2.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def list_ec2_instances(region: str) -> list[dict[str, Any]]:
+    import boto3
+    from botocore.exceptions import BotoCoreError, ClientError
+
+    try:
+        client = boto3.client("ec2", region_name=region)
+        reservations = client.describe_instances().get("Reservations", [])
+    except (BotoCoreError, ClientError) as exc:
+        raise RuntimeError(f"AWS EC2 error in region '{region}': {exc}") from exc
+
+    output: list[dict[str, Any]] = []
+    for reservation in reservations:
+        for instance in reservation.get("Instances", []):
+            output.append(
+                {
+                    "instance_id": instance.get("InstanceId"),
+                    "state": instance.get("State", {}).get("Name"),
+                    "type": instance.get("InstanceType"),
+                }
+            )
+    return output

package/tools/aws/s3.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def check_s3_public_access(region: str = "us-east-1") -> list[dict[str, Any]]:
+    """Audit S3 buckets for public access settings.
+
+    Args:
+        region: AWS region for the S3 client (default us-east-1).
+
+    Returns:
+        List of buckets with their public access block configuration.
+    """
+    import boto3
+    from botocore.exceptions import BotoCoreError, ClientError
+
+    try:
+        s3 = boto3.client("s3", region_name=region)
+        buckets_resp = s3.list_buckets()
+    except (BotoCoreError, ClientError) as exc:
+        raise RuntimeError(f"AWS S3 error: {exc}") from exc
+
+    results: list[dict[str, Any]] = []
+    for bucket in buckets_resp.get("Buckets", []):
+        name = bucket["Name"]
+        entry: dict[str, Any] = {"bucket": name, "public_access_block": None, "is_potentially_public": False}
+
+        try:
+            pab = s3.get_public_access_block(Bucket=name)
+            config = pab.get("PublicAccessBlockConfiguration", {})
+            entry["public_access_block"] = {
+                "block_public_acls": config.get("BlockPublicAcls", False),
+                "ignore_public_acls": config.get("IgnorePublicAcls", False),
+                "block_public_policy": config.get("BlockPublicPolicy", False),
+                "restrict_public_buckets": config.get("RestrictPublicBuckets", False),
+            }
+            all_blocked = all(entry["public_access_block"].values())
+            entry["is_potentially_public"] = not all_blocked
+        except ClientError as exc:
+            error_code = exc.response.get("Error", {}).get("Code", "")
+            if error_code == "NoSuchPublicAccessBlockConfiguration":
+                entry["public_access_block"] = "not_configured"
+                entry["is_potentially_public"] = True
+            elif error_code == "AccessDenied":
+                entry["public_access_block"] = "access_denied"
+                entry["is_potentially_public"] = "unknown"
+            else:
+                entry["public_access_block"] = f"error: {error_code}"
+                entry["is_potentially_public"] = "unknown"
+
+        results.append(entry)
+
+    return results

package/tools/cicd/pipeline.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import requests
+
+
+def pipeline_status(base_url: str, pipeline_id: str, api_token: str) -> dict:
+    """Fetch the status of a CI/CD pipeline by its ID.
+
+    Args:
+        base_url: Base URL of the CI/CD service API.
+        pipeline_id: Unique identifier of the pipeline.
+        api_token: API token for authenticating with the CI/CD service.
+
+    Returns:
+        Pipeline status as a JSON-compatible dict.
+    """
+    try:
+        response = requests.get(
+            f"{base_url.rstrip('/')}/pipelines/{pipeline_id}",
+            headers={"Authorization": f"Bearer {api_token}"},
+            timeout=15,
+        )
+        response.raise_for_status()
+    except requests.ConnectionError as exc:
+        raise RuntimeError(f"Cannot connect to CI/CD service at '{base_url}': {exc}") from exc
+    except requests.HTTPError as exc:
+        raise RuntimeError(
+            f"CI/CD API error for pipeline '{pipeline_id}': {exc.response.status_code}"
+        ) from exc
+    except requests.Timeout as exc:
+        raise RuntimeError(f"CI/CD API request timed out for pipeline '{pipeline_id}'") from exc
+
+    return response.json()