conmap 0.5.0

Subnet MCP endpoint discovery and vulnerability analysis toolkit with CLI and API interfaces.

Conmap

Conmap discovers Model Context Protocol (MCP) endpoints on the local network and evaluates them against the safe-mcp guidance. It ships with a feature-rich command line interface and an HTTP API suitable for enterprise automation pipelines.

Features

• Subnet discovery – Detects local subnets automatically and probes HTTP/HTTPS endpoints for MCP support.
• Target-aware JSON-RPC probing – When you supply explicit MCP URLs, Conmap issues the standard initialize, tools/list, resources/list, and prompts/list JSON-RPC calls as well as GET requests so nothing is missed.
• SAFE‑MCP coverage – Reports SAFE-MCP technique matches alongside a 0 → 100 risk score that reflects the severity and detection source of every finding.
• Vulnerability analysis – Applies Schema Inspector, Chain Attack Detector, and LLM Analyzer heuristics inspired by the safe-mcp framework.
• OpenAI integration – Uses GPT-4o for semantic reviews of tool descriptions with transparent caching and configurable batch sizing.
• Layered depth – Choose basic, standard, or deep analysis (deep enables AI semantics and richer chain detection with privilege paths).
• Automation-ready output – Produces structured JSON reports grouped by endpoint, tool, resource, and prompt, including SAFE-MCP technique summaries and the cumulative risk score.
• Interfaces – Provides both a Typer-based CLI and FastAPI server for flexible deployments.

Quick Start

pip install conmap
conmap scan --output report.json
# Run a deeper AI-assisted assessment
conmap scan --depth deep --output deep-report.json
# Scan a specific MCP server with larger LLM batches
conmap scan --url https://mcp.example.com --llm-batch-size 10 --depth deep

To run the web service:

conmap api --host 0.0.0.0 --port 8080

Development

Using uv (recommended)

uv sync --extra dev
uv run pre-commit install
uv run pre-commit run --all-files --show-diff-on-failure
uv run pytest --cov=conmap
uv run conmap scan --output report.json

This will create an isolated .venv managed by uv and install both runtime and development dependencies.

Using pip

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pre-commit install
pre-commit run --all-files --show-diff-on-failure
pytest --cov=conmap

Versioning

Conmap derives its version from annotated Git tags via setuptools_scm. When you are ready to cut a release, create a tag such as v0.2.0; the version embedded in the build will match the tag.

Configuration

• Set OPENAI_API_KEY for GPT-4o analysis.
• Use CONMAP_MAX_CONCURRENCY and CONMAP_TIMEOUT (legacy MCP_SCANNER_*) to tune scanning behavior.
• Control automation flags with CONMAP_ENABLE_LLM_ANALYSIS and analysis depth with CONMAP_ANALYSIS_DEPTH (basic, standard, deep).
• Supply explicit targets with CONMAP_TARGET_URLS (comma-separated) or the CLI flag --url.
• Tune OpenAI payload size with CONMAP_LLM_BATCH_SIZE (or CLI --llm-batch-size, API llm_batch_size).
• The HTTP API accepts analysis_depth (basic|standard|deep), enable_ai, llm_batch_size, and url fields in the body of POST /scan.

Publishing

Releases are driven by annotated tags. Create and push a tag in the form vX.Y.Z to trigger the Release workflow:

git tag -a v0.1.0 -m "release v0.1.0"
git push origin v0.1.0

The workflow will:

1. Install dependencies, lint, and run tests.
2. Build the project with setuptools_scm pinned to the tag version.
3. Upload artifacts to PyPI via pypa/gh-action-pypi-publish and create a GitHub release.

Ensure the repository secret PYPI_API_TOKEN contains a valid PyPI API token before pushing tags.

For a manual (local) release:

export VERSION=0.1.0
git tag -a "v$VERSION" -m "release v$VERSION"
git push origin "v$VERSION"
export SETUPTOOLS_SCM_PRETEND_VERSION="$VERSION"
uv run python -m build
python -m pip install --upgrade twine
python -m twine upload dist/*

Trust Center

• Signed releases & provenance – GitHub Actions builds run from annotated v* tags with immutable execution logs.
• Continuous assurance – CI enforces linting, tests, and 90% line coverage before a build is published.
• Security automation – Bandit and pip-audit workflows scan every push & pull request for code and dependency vulnerabilities.
• Supply chain transparency – CycloneDX SBOMs are generated for each release and uploaded as artifacts.
• Responsible disclosure – See SECURITY.md for vulnerability reporting guidelines and response timelines.
• Dependency hygiene – Dependabot monitors both Python packages and GitHub Actions for outdated or vulnerable components.
• Operational support – SUPPORT.md documents response targets and contact processes for assistance.
• Community standards – Participation is governed by our Code of Conduct.