@raghulm/aegis-mcp 1.0.3 → 1.0.5

package/README.md

@@ -1,4 +1,5 @@
 <div align="center">
+  <img src="docs/aegis-mcp-logo-v2.svg" width="100%" alt="Aegis MCP logo"/>
   <h1>🛡️ Aegis MCP Server</h1>
   <p><b>Aegis MCP is an open-source, DevSecOps-focused Model Context Protocol server that allows AI agents to safely interact with cloud infrastructure, CI/CD systems, and security tooling.</b></p>
 
@@ -134,12 +135,12 @@ MEDIUM: 7
 
 ## 🚀 Getting Started
 
-### Prerequisites
-
-- **Python 3.12+**
-- **Node.js 18+** (only if you want to run via npm/npx)
-- **Semgrep** — `pip install semgrep` (for SAST scanning)
-- Optional: AWS CLI / `boto3`, `kubectl`, Trivy (for their respective tools)
+### Prerequisites
+
+- **Python 3.12+**
+- **Node.js 18+** (only if you want to run via npm/npx)
+- **Semgrep** — `pip install semgrep` (for SAST scanning)
+- Optional: AWS CLI / `boto3`, `kubectl`, Trivy (for their respective tools)
 
 ### Installation
 
@@ -157,20 +158,20 @@ source .venv/bin/activate
 .venv\Scripts\activate
 
 # Install dependencies
-pip install -r requirements.txt
-```
-
-### Install via npm (Public Package)
-
-```bash
-npm install -g @raghulm/aegis-mcp
-# or run without installing globally:
-npx -y @raghulm/aegis-mcp
-```
-
-On first run, the npm wrapper creates a local Python virtual environment and installs dependencies from `requirements.txt` automatically.
-
----
+pip install -r requirements.txt
+```
+
+### Install via npm (Public Package)
+
+```bash
+npm install -g @raghulm/aegis-mcp
+# or run without installing globally:
+npx -y @raghulm/aegis-mcp
+```
+
+On first run, the npm wrapper creates a local Python virtual environment and installs dependencies from `requirements.txt` automatically.
+
+---
 
 ## 🤖 Usage with AI Agents
 
@@ -178,16 +179,16 @@ On first run, the npm wrapper creates a local Python virtual environment and ins
 
 Add to your MCP config (e.g., `mcp_config.json`):
 
-```json
-{
-  "mcpServers": {
-    "aegis": {
-      "command": "npx",
-      "args": ["-y", "@raghulm/aegis-mcp"]
-    }
-  }
-}
-```
+```json
+{
+  "mcpServers": {
+    "aegis": {
+      "command": "npx",
+      "args": ["-y", "@raghulm/aegis-mcp"]
+    }
+  }
+}
+```
 
 > ✅ **All 12 tools work**, including Semgrep SAST.
 
@@ -197,16 +198,16 @@ Add to `claude_desktop_config.json`:
 - **Windows**: `%LOCALAPPDATA%\Packages\Claude_...\LocalCache\Roaming\Claude\`
 - **Mac**: `~/Library/Application Support/Claude/`
 
-```json
-{
-  "mcpServers": {
-    "aegis": {
-      "command": "npx",
-      "args": ["-y", "@raghulm/aegis-mcp"]
-    }
-  }
-}
-```
+```json
+{
+  "mcpServers": {
+    "aegis": {
+      "command": "npx",
+      "args": ["-y", "@raghulm/aegis-mcp"]
+    }
+  }
+}
+```
 
 > ⚠️ **11 of 12 tools work.** Semgrep SAST does not work due to Windows pipe limitations.
 
@@ -301,41 +302,19 @@ The `@audit_tool_call` decorator emits structured JSON logs for every invocation
 
 ---
 
-## 🛣️ Roadmap
-
-- [ ] Terraform security scanner
-- [ ] IAM policy risk detection
-- [ ] Kubernetes misconfiguration scanner (Basic `k8s_security_audit` implemented!)
-- [ ] GitHub Actions security audit
-- [ ] Cloud cost analysis tools
-
----
-
-## 📦 Publish to npm
-
-```bash
-# 1) Login to npm
-npm login
-
-# 2) Verify package contents
-npm run pack:check
-
-# 3) Publish publicly
-npm publish --access public
-```
-
-For scoped packages like `@raghulm/aegis-mcp`, keep `--access public` in the publish command.
-
----
-
-## 🤝 Contributing
-
-1. Fork the project
-2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Add your tool into `tools/<domain>/`
-4. Register it via `@mcp.tool()` in `server/main.py` with `@audit_tool_call` and auth check
-5. Add tests in `tests/`
-6. Open a Pull Request
+## 🛣️ Roadmap
+
+- [ ] Terraform security scanner
+- [ ] IAM policy risk detection
+- [ ] Kubernetes misconfiguration scanner (Basic `k8s_security_audit` implemented!)
+- [ ] GitHub Actions security audit
+- [ ] Cloud cost analysis tools
+
+---
+
+## 🤝 Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for contribution and maintainer release workflows.
 
 ---
 

package/bin/prepare-python-env.js

@@ -3,21 +3,42 @@
 
 const crypto = require("crypto");
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 const { spawnSync } = require("child_process");
 
 const PROJECT_ROOT = path.resolve(__dirname, "..");
 const REQUIREMENTS_FILE = path.join(PROJECT_ROOT, "requirements.txt");
-const VENV_DIR = path.join(PROJECT_ROOT, ".venv");
-const REQUIREMENTS_STAMP = path.join(VENV_DIR, ".requirements.sha256");
+const RUNTIME_ROOT = process.env.AEGIS_HOME || path.join(os.homedir(), ".aegis-mcp");
+const VENV_DIR = path.join(RUNTIME_ROOT, "venv");
+const REQUIREMENTS_STAMP = path.join(RUNTIME_ROOT, ".requirements.sha256");
 const IS_WINDOWS = process.platform === "win32";
+const DEBUG = process.env.AEGIS_DEBUG === "1";
 
 function run(command, args, options = {}) {
-  return spawnSync(command, args, {
+  const result = spawnSync(command, args, {
     cwd: PROJECT_ROOT,
-    stdio: "inherit",
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
     ...options
   });
+
+  if (DEBUG && result.stdout) {
+    process.stderr.write(result.stdout);
+  }
+  if (DEBUG && result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  return result;
+}
+
+function throwCommandError(result, contextMessage) {
+  const output = `${result?.stdout || ""}\n${result?.stderr || ""}`.trim();
+  if (output) {
+    process.stderr.write(`${output}\n`);
+  }
+  throw new Error(contextMessage);
 }
 
 function candidatePythonCommands() {
@@ -43,10 +64,7 @@ function candidatePythonCommands() {
 
 function findWorkingPython() {
   for (const candidate of candidatePythonCommands()) {
-    const versionCheck = run(candidate.command, [...candidate.prefixArgs, "--version"], {
-      stdio: "pipe",
-      encoding: "utf8"
-    });
+    const versionCheck = run(candidate.command, [...candidate.prefixArgs, "--version"]);
     if (versionCheck.status === 0) {
       return candidate;
     }
@@ -77,29 +95,44 @@ function requirementsHash() {
 }
 
 function ensureVirtualEnvironment(python) {
+  fs.mkdirSync(RUNTIME_ROOT, { recursive: true });
+
   const pythonInVenv = venvPythonPath();
   if (fs.existsSync(pythonInVenv)) {
     return;
   }
 
-  console.error("[aegis-mcp] Creating Python virtual environment...");
   const created = run(python.command, [...python.prefixArgs, "-m", "venv", VENV_DIR]);
   if (created.status !== 0) {
-    throw new Error("Failed to create Python virtual environment.");
+    throwCommandError(created, "Failed to create Python virtual environment.");
   }
 }
 
 function installDependencies(pythonInVenv) {
-  console.error("[aegis-mcp] Installing Python dependencies from requirements.txt...");
-
-  const pipUpgrade = run(pythonInVenv, ["-m", "pip", "install", "--upgrade", "pip"]);
+  const pipUpgrade = run(pythonInVenv, [
+    "-m",
+    "pip",
+    "install",
+    "--disable-pip-version-check",
+    "--quiet",
+    "--upgrade",
+    "pip"
+  ]);
   if (pipUpgrade.status !== 0) {
-    throw new Error("Failed to upgrade pip in virtual environment.");
+    throwCommandError(pipUpgrade, "Failed to upgrade pip in virtual environment.");
   }
 
-  const pipInstall = run(pythonInVenv, ["-m", "pip", "install", "-r", REQUIREMENTS_FILE]);
+  const pipInstall = run(pythonInVenv, [
+    "-m",
+    "pip",
+    "install",
+    "--disable-pip-version-check",
+    "--quiet",
+    "-r",
+    REQUIREMENTS_FILE
+  ]);
   if (pipInstall.status !== 0) {
-    throw new Error("Failed to install Python dependencies.");
+    throwCommandError(pipInstall, "Failed to install Python dependencies.");
   }
 }
 

package/package.json

@@ -1,50 +1,54 @@
-{
-  "name": "@raghulm/aegis-mcp",
-  "version": "1.0.3",
-  "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"
-  }
-}
+{
+  "name": "@raghulm/aegis-mcp",
+  "version": "1.0.5",
+  "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",
+    "jenkins"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@raghulm/aegis-mcp": "^1.0.5"
+  }
+}

package/requirements.txt

@@ -5,3 +5,4 @@ fastapi>=0.111.0
 uvicorn>=0.30.0
 pyyaml>=6.0.1
 semgrep>=1.60.0
+python-jenkins>=1.8.0

package/server/main.py

@@ -10,6 +10,15 @@ 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.cicd.jenkins import (
+    jenkins_list_jobs as _jenkins_list_jobs,
+    jenkins_get_job_info as _jenkins_get_job_info,
+    jenkins_create_job as _jenkins_create_job,
+    jenkins_trigger_build as _jenkins_trigger_build,
+    jenkins_get_build_info as _jenkins_get_build_info,
+    jenkins_get_build_log as _jenkins_get_build_log,
+    jenkins_delete_job as _jenkins_delete_job,
+)
 from tools.git.repo import get_recent_commits
 from tools.kubernetes.pods import list_pods
 from tools.kubernetes.audit import k8s_security_audit
@@ -140,5 +149,64 @@ def security_semgrep_scan(path: str, config: str = "auto", token: str = "") -> d
     return run_semgrep_scan(path, config)
 
 
+# ── Jenkins CI/CD tools ────────────────────────────────────────────
+
+
+@mcp.tool()
+@audit_tool_call("jenkins_list_jobs")
+def jenkins_list_jobs(url: str, username: str, api_token: str, token: str = "") -> list[dict]:
+    """List all jobs on a Jenkins server. Provide the Jenkins URL, username, and API token."""
+    _authorize(token, "jenkins_list_jobs")
+    return _jenkins_list_jobs(url, username, api_token)
+
+
+@mcp.tool()
+@audit_tool_call("jenkins_get_job_info")
+def jenkins_get_job_info(url: str, username: str, api_token: str, job_name: str, token: str = "") -> dict:
+    """Get detailed information about a specific Jenkins job including build history and health."""
+    _authorize(token, "jenkins_get_job_info")
+    return _jenkins_get_job_info(url, username, api_token, job_name)
+
+
+@mcp.tool()
+@audit_tool_call("jenkins_create_job")
+def jenkins_create_job(url: str, username: str, api_token: str, job_name: str, config_xml: str = "", token: str = "") -> dict:
+    """Create a new Jenkins job. Optionally provide config_xml for the job definition; otherwise a minimal freestyle project is created."""
+    _authorize(token, "jenkins_create_job")
+    return _jenkins_create_job(url, username, api_token, job_name, config_xml)
+
+
+@mcp.tool()
+@audit_tool_call("jenkins_trigger_build")
+def jenkins_trigger_build(url: str, username: str, api_token: str, job_name: str, parameters: str = "", token: str = "") -> dict:
+    """Trigger a build for an existing Jenkins job. Optionally pass parameters as a JSON string, e.g. '{"BRANCH": "main"}'."""
+    _authorize(token, "jenkins_trigger_build")
+    return _jenkins_trigger_build(url, username, api_token, job_name, parameters)
+
+
+@mcp.tool()
+@audit_tool_call("jenkins_get_build_info")
+def jenkins_get_build_info(url: str, username: str, api_token: str, job_name: str, build_number: int, token: str = "") -> dict:
+    """Get information about a specific Jenkins build including result, duration, and status."""
+    _authorize(token, "jenkins_get_build_info")
+    return _jenkins_get_build_info(url, username, api_token, job_name, build_number)
+
+
+@mcp.tool()
+@audit_tool_call("jenkins_get_build_log")
+def jenkins_get_build_log(url: str, username: str, api_token: str, job_name: str, build_number: int, token: str = "") -> dict:
+    """Fetch the console output of a Jenkins build."""
+    _authorize(token, "jenkins_get_build_log")
+    return _jenkins_get_build_log(url, username, api_token, job_name, build_number)
+
+
+@mcp.tool()
+@audit_tool_call("jenkins_delete_job")
+def jenkins_delete_job(url: str, username: str, api_token: str, job_name: str, token: str = "") -> dict:
+    """Delete a Jenkins job from the server."""
+    _authorize(token, "jenkins_delete_job")
+    return _jenkins_delete_job(url, username, api_token, job_name)
+
+
 if __name__ == "__main__":
     mcp.run(transport="streamable-http")

package/tools/cicd/jenkins.py

@@ -0,0 +1,256 @@
+"""Jenkins CI/CD integration tools for Aegis MCP.
+
+Provides functions to manage Jenkins jobs and builds via the Jenkins REST API
+using the ``python-jenkins`` library.  Credentials (URL, username, API token)
+are passed per-call so no global state or environment variables are required.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import jenkins
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _client(url: str, username: str, api_token: str) -> jenkins.Jenkins:
+    """Return a configured Jenkins client, raising RuntimeError on failure."""
+    try:
+        server = jenkins.Jenkins(url, username=username, password=api_token)
+        # Verify credentials by fetching the server version header
+        server.get_whoami()
+        return server
+    except jenkins.JenkinsException as exc:
+        raise RuntimeError(
+            f"Cannot connect to Jenkins at '{url}': {exc}"
+        ) from exc
+    except Exception as exc:
+        raise RuntimeError(
+            f"Jenkins connection error: {exc}"
+        ) from exc
+
+
+# ---------------------------------------------------------------------------
+# Tool functions
+# ---------------------------------------------------------------------------
+
+def jenkins_list_jobs(url: str, username: str, api_token: str) -> list[dict]:
+    """List all jobs on a Jenkins server.
+
+    Returns a list of dicts with keys: name, url, color (build status indicator).
+    """
+    server = _client(url, username, api_token)
+    try:
+        jobs = server.get_all_jobs()
+        return [
+            {
+                "name": j.get("name", ""),
+                "url": j.get("url", ""),
+                "color": j.get("color", ""),
+            }
+            for j in jobs
+        ]
+    except jenkins.JenkinsException as exc:
+        raise RuntimeError(f"Failed to list Jenkins jobs: {exc}") from exc
+
+
+def jenkins_get_job_info(
+    url: str, username: str, api_token: str, job_name: str
+) -> dict:
+    """Get detailed information about a Jenkins job.
+
+    Returns build history, health reports, and configuration details.
+    """
+    server = _client(url, username, api_token)
+    try:
+        info = server.get_job_info(job_name)
+        return {
+            "name": info.get("name", ""),
+            "url": info.get("url", ""),
+            "description": info.get("description", ""),
+            "buildable": info.get("buildable", False),
+            "color": info.get("color", ""),
+            "last_build": info.get("lastBuild"),
+            "last_successful_build": info.get("lastSuccessfulBuild"),
+            "last_failed_build": info.get("lastFailedBuild"),
+            "health_report": info.get("healthReport", []),
+            "in_queue": info.get("inQueue", False),
+        }
+    except jenkins.NotFoundException:
+        raise RuntimeError(f"Jenkins job '{job_name}' not found")
+    except jenkins.JenkinsException as exc:
+        raise RuntimeError(
+            f"Failed to get info for job '{job_name}': {exc}"
+        ) from exc
+
+
+def jenkins_create_job(
+    url: str,
+    username: str,
+    api_token: str,
+    job_name: str,
+    config_xml: str = "",
+) -> dict:
+    """Create a new Jenkins job.
+
+    Args:
+        url: Jenkins server URL.
+        username: Jenkins username.
+        api_token: Jenkins API token.
+        job_name: Name for the new job.
+        config_xml: Jenkins job configuration XML.  If empty, a minimal
+            freestyle project config is used.
+
+    Returns:
+        Dict with the created job name and URL.
+    """
+    if not config_xml:
+        config_xml = jenkins.EMPTY_CONFIG_XML
+
+    server = _client(url, username, api_token)
+    try:
+        server.create_job(job_name, config_xml)
+        return {
+            "status": "created",
+            "job_name": job_name,
+            "url": f"{url.rstrip('/')}/job/{job_name}/",
+        }
+    except jenkins.JenkinsException as exc:
+        raise RuntimeError(
+            f"Failed to create job '{job_name}': {exc}"
+        ) from exc
+
+
+def jenkins_trigger_build(
+    url: str,
+    username: str,
+    api_token: str,
+    job_name: str,
+    parameters: str = "",
+) -> dict:
+    """Trigger a build for a Jenkins job.
+
+    Args:
+        url: Jenkins server URL.
+        username: Jenkins username.
+        api_token: Jenkins API token.
+        job_name: Name of the job to build.
+        parameters: Optional JSON string of build parameters,
+            e.g. '{"BRANCH": "main"}'.
+
+    Returns:
+        Dict with the queue item number.
+    """
+    server = _client(url, username, api_token)
+    try:
+        params: dict[str, Any] | None = None
+        if parameters:
+            params = json.loads(parameters)
+
+        queue_item = server.build_job(job_name, parameters=params)
+        return {
+            "status": "triggered",
+            "job_name": job_name,
+            "queue_item": queue_item,
+        }
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(
+            f"Invalid parameters JSON: {exc}"
+        ) from exc
+    except jenkins.JenkinsException as exc:
+        raise RuntimeError(
+            f"Failed to trigger build for '{job_name}': {exc}"
+        ) from exc
+
+
+def jenkins_get_build_info(
+    url: str,
+    username: str,
+    api_token: str,
+    job_name: str,
+    build_number: int,
+) -> dict:
+    """Get information about a specific build.
+
+    Returns build result, duration, timestamp, and other metadata.
+    """
+    server = _client(url, username, api_token)
+    try:
+        info = server.get_build_info(job_name, build_number)
+        return {
+            "job_name": job_name,
+            "build_number": info.get("number"),
+            "result": info.get("result"),
+            "duration_ms": info.get("duration"),
+            "timestamp": info.get("timestamp"),
+            "building": info.get("building", False),
+            "url": info.get("url", ""),
+            "display_name": info.get("displayName", ""),
+        }
+    except jenkins.NotFoundException:
+        raise RuntimeError(
+            f"Build #{build_number} not found for job '{job_name}'"
+        )
+    except jenkins.JenkinsException as exc:
+        raise RuntimeError(
+            f"Failed to get build info for '{job_name}' #{build_number}: {exc}"
+        ) from exc
+
+
+def jenkins_get_build_log(
+    url: str,
+    username: str,
+    api_token: str,
+    job_name: str,
+    build_number: int,
+) -> dict:
+    """Fetch the console output of a Jenkins build.
+
+    Returns the full console log as a string (truncated to 50 000 chars to
+    keep MCP responses manageable).
+    """
+    server = _client(url, username, api_token)
+    try:
+        output = server.get_build_console_output(job_name, build_number)
+        max_len = 50_000
+        truncated = len(output) > max_len
+        return {
+            "job_name": job_name,
+            "build_number": build_number,
+            "log": output[:max_len],
+            "truncated": truncated,
+        }
+    except jenkins.NotFoundException:
+        raise RuntimeError(
+            f"Build #{build_number} not found for job '{job_name}'"
+        )
+    except jenkins.JenkinsException as exc:
+        raise RuntimeError(
+            f"Failed to get build log for '{job_name}' #{build_number}: {exc}"
+        ) from exc
+
+
+def jenkins_delete_job(
+    url: str, username: str, api_token: str, job_name: str
+) -> dict:
+    """Delete a Jenkins job.
+
+    Returns confirmation dict on success.
+    """
+    server = _client(url, username, api_token)
+    try:
+        server.delete_job(job_name)
+        return {
+            "status": "deleted",
+            "job_name": job_name,
+        }
+    except jenkins.NotFoundException:
+        raise RuntimeError(f"Jenkins job '{job_name}' not found")
+    except jenkins.JenkinsException as exc:
+        raise RuntimeError(
+            f"Failed to delete job '{job_name}': {exc}"
+        ) from exc