abhishek0412/PentestToolbox

Electric Blue MCP Server (Defensive-Focused Assessment Toolkit)

This project provides a Model Context Protocol (MCP) server exposing common web penetration testing utilities inside an isolated Kali-based Docker container. It is intended ONLY for ethical testing against systems you own or are explicitly authorized to assess.

Why “Electric Blue”?

Blue evokes defensive cybersecurity (“Blue Team”). The Electric Blue MCP server reframes the tooling set for controlled, authorized reconnaissance and vulnerability exposure mapping, with input sanitization and capability minimization.

Included Tools

• nmap
• nikto
• sqlmap
• wpscan
• dirb (with automatic URL normalization when a file path like /login.php is provided)
• searchsploit (exploitdb)
• dnsrecon
• grype (vulnerability scanning)
• syft (SBOM generation)

Environment Variables

Build & Run

# Build image
docker build -t electric-blue-mcp .

# Run container (no privileged mode; network tools need raw sockets which we set via setcap)
docker run --rm -it \
  -e PENTEST_TIMEOUT=2000 \
  -e PENTEST_MAX_OUTPUT=60000 \
  electric-blue-mcp

The server starts automatically and listens via stdio as per MCP expectations.

Using a Prebuilt Image (Docker Hub)

If you don't want to build locally, pull the published image instead (replace latest with a version tag if available):

docker pull abhishekchoudharry/electric-blue-mcp:latest

Then run it exactly as before, but reference the remote image name:

docker run --rm -it \
  -e PENTEST_TIMEOUT=300 \
  -e PENTEST_MAX_OUTPUT=60000 \
  abhishekchoudharry/electric-blue-mcp:latest

Benefits of using the registry image:

• No local build toolchain or large base image download during build.
• Consistent, reproducible environment (everyone pulls the same layers).
• Faster onboarding for new users.

When you update locally and want to publish:

docker build -t electric-blue-mcp .
docker tag electric-blue-mcp:latest abhishekchoudharry/electric-blue-mcp:0.1.0
docker tag electric-blue-mcp:latest abhishekchoudharry/electric-blue-mcp:latest
docker push abhishekchoudharry/electric-blue-mcp:0.1.0
docker push abhishekchoudharry/electric-blue-mcp:latest

(Optional) Scan the pushed image for vulnerabilities:

docker pull abhishekchoudharry/electric-blue-mcp:latest
grype abhishekchoudharry/electric-blue-mcp:latest

To force an update (bypass local cache):

docker pull --quiet --disable-content-trust=false abhishekchoudharry/electric-blue-mcp:latest

If you need to pin a specific version in your MCP config (recommended for stability), use a tag: abhishekchoudharry/electric-blue-mcp:0.1.0 instead of latest.

MCP Client Integration (Example)

Configure your MCP-capable client (e.g. an AI assistant supporting Model Context Protocol) to launch the container. You can use either a locally built image or the published Docker Hub image.

Option A: Local Image

command: docker
args: ["run","--rm","-e","PENTEST_TIMEOUT=300","-e","PENTEST_MAX_OUTPUT=60000","electric-blue-mcp"]

Option B: Docker Hub Image (Pinned or Latest)

command: docker
args: ["run","--rm","-e","PENTEST_TIMEOUT=300","-e","PENTEST_MAX_OUTPUT=60000","abhishekchoudharry/electric-blue-mcp:latest"]

Pin a specific version for reproducibility:

args: ["run","--rm","-e","PENTEST_TIMEOUT=300","-e","PENTEST_MAX_OUTPUT=60000","abhishekchoudharry/electric-blue-mcp:0.1.0"]

Available Tool Functions

Use tool_info for a runtime listing.

Input Sanitization

Inputs are restricted with regex filtering; only simple, length-limited flags are passed. Potentially dangerous constructs (shell metacharacters, command chaining, redirection) and overlong inputs are rejected. dirb_scan additionally normalizes URLs: if you supply a path ending in a probable file (e.g. /login.php) it trims to the parent directory and appends a trailing /.

Large outputs are truncated to PENTEST_MAX_OUTPUT bytes with a trailing marker.

Execution Model & Capabilities

The Docker image creates a dedicated non-root user pentest (home: /home/pentest) and switches to it before launching the MCP server (USER pentest). This least‑privilege default reduces blast radius if a wrapped tool is compromised.

Capabilities (setcap) are applied narrowly to nmap binaries so certain scan types (e.g., SYN scans) can run without full root:

setcap cap_net_raw,cap_net_admin,cap_net_bind_service+eip /usr/bin/nmap
setcap cap_net_raw,cap_net_bind_service+eip /usr/lib/nmap/nmap

If you explicitly pass --user root in your local MCP client config (as shown in one example), you are overriding this safety default. Remove --user root unless you have a specific reason (e.g., debugging a capability edge case). Most operations should work as the pentest user.

Summary:

• Default container execution: non-root (pentest).
• Elevated usage: only if you run the container with --user root manually.
• Recommendation: keep non-root except for temporary diagnostics.

Vulnerability & SBOM Scanning

Two supply-chain focused tools are bundled:

• grype_scan: Quickly enumerates known vulnerabilities in an image or directory (severity up to negligible; fails none by default in wrapper, but uses --fail-on negligible internally for consistent exit codes).
• syft_scan: Generates a Software Bill of Materials (SBOM) in allowed formats (table, json, spdx-json).

Example (from your MCP client):

grype_scan target: electric-blue-mcp:latest

syft_scan target: electric-blue-mcp:latest format: spdx-json

Assumptions & Scope (Proof of Concept)

This implementation is intentionally minimal and carries several explicit assumptions:

If any of these assumptions change (e.g., need for performance tuning, image hardening, or private tooling), the architecture and Dockerfile should be revisited.

Ethical & Legal Notice

You must only scan or test assets you own or have written permission to test. Unauthorized access or probing may violate laws and policies. The maintainers and authors assume no liability for misuse.

Troubleshooting

• Very large scans may truncate output per PENTEST_MAX_OUTPUT.
• Extended scans may time out; adjust PENTEST_TIMEOUT.
• WPScan API enhancements require WPSCAN_API_TOKEN.

Development

Update dependencies / rebuild without cache:

docker build --no-cache -t electric-blue-mcp .

GitHub Copilot MCP Integration

GitHub Copilot Chat (with MCP support) can launch this server via Docker. Copy mcp.json to your local Copilot MCP config location and adjust if needed.

Typical user-level config path examples (create the directory if it doesn't exist):

• Windows: %UserProfile%\\AppData\\Roaming\\GitHub Copilot\\mcp.json
• macOS: ~/Library/Application Support/GitHub Copilot/mcp.json
• Linux: ~/.config/github-copilot/mcp.json

Current reference configuration (mirrors .vscode/mcp.json):

{
  "servers": {
    "electric-blue": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e","PENTEST_TIMEOUT=2000",
        "-e","PENTEST_MAX_OUTPUT=60000",
        "--user","root",
        "electric-blue-mcp"
      ]
    }
  }
}

Notes:

• -i ensures interactive STDIN for MCP JSON-RPC over stdio.
• --user root matches local development config; most tools function unprivileged but capabilities for nmap may require root/context specifics. You can drop this and rely on the container's default non-root user if preferred.
• Adjust PENTEST_TIMEOUT downward (e.g., 300) for faster-return constraints in agent contexts.

Alternative (pull the remote image instead of local build):

{
  "servers": {
    "electric-blue": {
      "command": "docker",
      "args": [
        "run","--rm","-i",
        "-e","PENTEST_TIMEOUT=300",
        "-e","PENTEST_MAX_OUTPUT=60000",
        "--user","root",
        "abhishekchoudharry/electric-blue-mcp:latest"
      ]
    }
  }
}

If you pin a version tag, replace latest with (e.g.) 0.1.0.

After saving the config, restart Copilot Chat / VS Code to have it discover the new MCP server. Then ask Copilot for tool_info under the electric-blue server context.

Updating the Image

If you modify code, rebuild:

docker build -t electric-blue-mcp .

FastMCP Import Issues

If inside the container you see an error like ModuleNotFoundError: No module named 'fastmcp':

1. Confirm the virtual environment path: /opt/venv/bin/python -c "import sys; print(sys.executable)"
2. Ensure requirements.txt still lists the pinned version.
3. Rebuild without cache:

   docker build --no-cache -t electric-blue-mcp .
   

4. Run a quick validation:

   docker run --rm electric-blue-mcp python -c "import fastmcp, platform; print('fastmcp OK on', platform.python_version())"
   

If that fails, check network access for dependency download and that the base image still supports python3-venv.

Continuous Integration / Docker Publish

A GitHub Actions workflow (.github/workflows/docker-publish.yml) builds the image on every pull request targeting main (or master). It conditionally pushes the latest tag to Docker Hub only when the pull request originates from the base repository (not from a fork) to avoid leaking secrets.

Trigger Conditions

• Event: pull_request (branches: main, master)
• Paths filtered: Dockerfile, key source files, requirements, and the workflow file itself
• Manual trigger: workflow_dispatch

Tags

Currently the workflow emits exactly one tag: latest. (You can later extend with version tags using git refs or conventional commits.)

Required Secrets

Add these in the repository Settings → Secrets and variables → Actions:

• DOCKERHUB_USERNAME – Your Docker Hub account name (owner of the repo abhishekchoudharry/electric-blue-mcp)
• DOCKERHUB_TOKEN – A Docker Hub access token (NOT your password)

Safety Controls

• Forked PRs build but do not push (login & push steps are skipped via conditional check on head.repo.full_name).
• Layer caching via actions/cache reduces rebuild time.
• Single job keeps the pipeline simple; no privileged runners required.

Minimal Local Test Before Push

(Optional) Reproduce the build locally:

docker build -t electric-blue-mcp .

If that succeeds, open or update a PR—CI will mirror the build.

Extending (Future Ideas)

• Add a push on merge to main for automatic release of latest.
• Introduce semantic version tagging (derive from git tag) and push both vx.y.z and latest.
• Add a grype scan job to fail on Critical vulns (policy dependent).
• Publish a Software Bill of Materials artifact using syft and upload via actions/upload-artifact.
• Attach image digest summary to PR via job step output.

Troubleshooting

• Secret not found: Ensure both secrets are defined (case-sensitive).
• Authentication failure: Regenerate Docker Hub token and update secret.
• Build cache misses every run: Check that cache path /tmp/.buildx-cache persists within the job (it should); verify the cache key isn’t changing unexpectedly.
• No push occurred: Confirm PR is from the base repo; fork PRs intentionally skip pushing.

License

For educational usage only. Verify legal compliance before use.