diff --git a/CLAUDE.md b/CLAUDE.md index 1e851ae..3011de7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,8 +10,10 @@ This is an MCP (Model Context Protocol) server for Contrast Security that enable ### Building the Project - **Build**: `mvn clean install` or `./mvnw clean install` +- **Package without tests**: `mvn clean package -DskipTests` - **Test**: `mvn test` or `./mvnw test` -- **Run locally**: `java -jar target/mcp-contrast-0.0.11.jar --CONTRAST_HOST_NAME= --CONTRAST_API_KEY= --CONTRAST_SERVICE_KEY= --CONTRAST_USERNAME= --CONTRAST_ORG_ID=` +- **Run single test**: `mvn test -Dtest=HintGeneratorTest` or `mvn test -Dtest=HintGeneratorTest#specificTestMethod` +- **Run locally**: `java -jar target/mcp-contrast-0.0.12-SNAPSHOT.jar --CONTRAST_HOST_NAME= --CONTRAST_API_KEY= --CONTRAST_SERVICE_KEY= --CONTRAST_USERNAME= --CONTRAST_ORG_ID=` ### Docker Commands - **Build Docker image**: `docker build -t mcp-contrast .` @@ -28,17 +30,19 @@ This is an MCP (Model Context Protocol) server for Contrast Security that enable **Main Application**: `McpContrastApplication.java` - Spring Boot application that registers MCP tools from all service classes. -**Service Layer**: Each service handles a specific aspect of Contrast Security data: +**Service Layer**: Each service handles a specific aspect of Contrast Security data and exposes `@Tool` annotated methods: - `AssessService` - Vulnerability analysis and trace data - `SastService` - Static application security testing data - `SCAService` - Software composition analysis (library vulnerabilities) - `ADRService` - Attack detection and response events - `RouteCoverageService` - Route coverage analysis -- `PromptService` - AI prompt management -**SDK Extensions**: Located in `sdkexstension/` package, these extend the Contrast SDK with enhanced data models and helper methods for better AI integration. +**SDK Extensions**: Located in `sdkexstension/` package: +- `SDKExtension.java` - Extends Contrast SDK API with additional endpoints not in standard SDK (library observations, route details, session metadata, etc.) +- `SDKHelper.java` - Utility methods for hostname protocol handling and common operations +- `data/` subpackages - Enhanced data models with AI-friendly representations organized by domain (application, adr, routecoverage, sca, traces, sessionmetadata) -**Data Models**: Comprehensive POJOs in `data/` package representing vulnerability information, library data, applications, and attack events. +**Data Models**: Comprehensive POJOs in `data/` package representing vulnerability information, library data, applications, and attack events used by service layer. **Hint System**: `hints/` package provides context-aware security guidance for vulnerability remediation. @@ -58,19 +62,24 @@ Required environment variables/arguments: ### Technology Stack -- **Framework**: Spring Boot 3.4.5 with Spring AI 1.0.0-RC1 +- **Framework**: Spring Boot 3.4.5 with Spring AI 1.0.1 - **MCP Integration**: Spring AI MCP Server starter - **Contrast Integration**: Contrast SDK Java 3.4.2 -- **Testing**: JUnit 5 -- **Build Tool**: Maven with wrapper +- **JSON Processing**: Gson (via Contrast SDK) +- **Testing**: JUnit 5 with Spring Boot Test +- **Build Tool**: Maven 3.6+ with wrapper - **Packaging**: Executable JAR and Docker container ### Development Patterns -1. **MCP Tools**: Services expose methods via `@Tool` annotation for AI agent consumption -2. **SDK Extension Pattern**: Enhanced data models extend base SDK classes with AI-friendly representations -3. **Hint Generation**: Rule-based system provides contextual security guidance -4. **Defensive Design**: All external API calls include error handling and logging +1. **MCP Tools**: Services expose methods via `@Tool` annotation for AI agent consumption. Register new services in `McpContrastApplication.tools()` bean. +2. **SDK Extension Pattern**: + - Use `SDKExtension` to add new Contrast API endpoints not in the standard SDK + - Use `SDKHelper` for common utility operations (hostname handling, etc.) + - Enhanced data models in `sdkexstension/data/` provide AI-friendly JSON representations +3. **Hint Generation**: Rule-based system in `hints/` package provides contextual security guidance for vulnerability remediation +4. **Defensive Design**: All external API calls include proper resource management (try-with-resources), error handling, and logging +5. **Pagination Handling**: SDK extension methods handle pagination automatically (see `getLibraryObservations` for pattern) ### Security Considerations @@ -80,4 +89,18 @@ This codebase handles sensitive vulnerability data. The README contains critical - Default log location: `/tmp/mcp-contrast.log` - Debug logging: Add `--logging.level.root=DEBUG` to startup arguments -- Console logging is minimal by design for MCP protocol compatibility \ No newline at end of file +- Console logging is minimal by design for MCP protocol compatibility +- Debug mode buffers API responses for logging (memory impact with large datasets) + +### Troubleshooting + +For common issues (SSL certificates, proxy configuration, debug logging), see the "Common Issues" and "Proxy Configuration" sections in [README.md](README.md). + +### Adding New MCP Tools + +To add a new tool/service: +1. Create a new `@Service` class with methods annotated with `@Tool(description="...")` +2. Inject dependencies (ContrastSDK, SDKExtension) via constructor +3. Register the service in `McpContrastApplication.tools()` bean method +4. Use `SDKExtension` to add new API endpoints if needed +5. Create enhanced data models in appropriate `sdkexstension/data/` subpackage \ No newline at end of file diff --git a/README.md b/README.md index cc681b9..88fe415 100644 --- a/README.md +++ b/README.md @@ -1,43 +1,67 @@ # Contrast MCP Server -⚠️ CRITICAL SECURITY WARNING: EXPOSING YOUR CONTRAST VULNERABILITY DATA TO A LLM THAT TRAINS ON YOUR DATA CAN POTENTIALLY EXPOSE YOUR VULNERABILITY DATA TO THE OUTSIDE WORLD. Thus, do not use mcp-contrast functions which pull sensitive data with a LLM that trains on your data. +[![Java CI with Maven](https://github.com/Contrast-Labs/mcp-contrast/actions/workflows/build.yml/badge.svg)](https://github.com/Contrast-Labs/mcp-contrast/actions/workflows/build.yml) +[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -Verify AI Data Privacy: Before sending vulnerability data to an AI, you must confirm that your service agreement guarantees your data will not be used for model training. -UNSAFE: Public consumer websites (e.g., the free versions of ChatGPT, Gemini, Claude). These services often use your input for training. +The Contrast MCP Server allow you to connect Contrast Security to your AI coding agent to automatically remediate vulnerabilities, update insecure libraries, and analyze security coverage—all through natural language prompts. -POTENTIALLY-SAFE: Enterprise-grade services (e.g. Google Cloud AI, AWS Bedrock, Azure OpenAI) or paid plans that contractually ensure data privacy and prevent model training on your prompts, verify with your information security teams. - -

+![output.gif](images/output.gif) -[![Java CI with Maven](https://github.com/Contrast-Labs/mcp-contrast/actions/workflows/build.yml/badge.svg)](https://github.com/Contrast-Labs/mcp-contrast/actions/workflows/build.yml) -[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) -[![Maven Central](https://img.shields.io/maven-central/v/com.contrast.labs/mcp-contrast.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.contrast.labs%22%20AND%20a:%22mcp-contrast%22) -[![Install in VS Code Docker](https://img.shields.io/badge/VS_Code-docker-0098FF?style=flat-square&logo=githubcopilot&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=contrastmcp&config=%7B%22command%22:%22docker%22,%22args%22:%5B%22run%22,%20%22-e%22,%22CONTRAST_HOST_NAME%22,%20%22-e%22,%22CONTRAST_API_KEY%22,%20%22-e%22,%22CONTRAST_SERVICE_KEY%22,%20%22-e%22,%22CONTRAST_USERNAME%22,%20%22-e%22,%22CONTRAST_ORG_ID%22,%20%20%22-i%22,%20%22--rm%22,%20%22contrast/mcp-contrast:latest%22,%20%22-t%22,%20%22stdio%22%5D,%22env%22:%7B%22CONTRAST_HOST_NAME%22:%22example.contrastsecurity.com%22,%22CONTRAST_API_KEY%22:%22example%22,%22CONTRAST_SERVICE_KEY%22:%22example%22,%22CONTRAST_USERNAME%22:%22example@example.com%22,%22CONTRAST_ORG_ID%22:%22example%22%7D%7D) +## Quick Install -Contrast's MCP server allows you as a developer or security professional to quickly remediate vulnerabilities found by Contrast products. By combining the abilities of a LLM and Coding Agent of your choice and Contrast's unique vulnerability data it is possible to easily remediate vulnerabilities in your code or 3rd party libraries. -![output.gif](images/output.gif) +**VS Code (One-Click Install):** + +[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_contrast--mcp-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=ffffff)](vscode:mcp/install?%7B%22name%22%3A%22contrast-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-e%22%2C%22CONTRAST_HOST_NAME%22%2C%22-e%22%2C%22CONTRAST_API_KEY%22%2C%22-e%22%2C%22CONTRAST_SERVICE_KEY%22%2C%22-e%22%2C%22CONTRAST_USERNAME%22%2C%22-e%22%2C%22CONTRAST_ORG_ID%22%2C%22-i%22%2C%22--rm%22%2C%22contrast%2Fmcp-contrast%3Alatest%22%2C%22-t%22%2C%22stdio%22%5D%2C%22env%22%3A%7B%22CONTRAST_HOST_NAME%22%3A%22%24%7Binput%3Acontrast_host_name%7D%22%2C%22CONTRAST_ORG_ID%22%3A%22%24%7Binput%3Acontrast_org_id%7D%22%2C%22CONTRAST_USERNAME%22%3A%22%24%7Binput%3Acontrast_username%7D%22%2C%22CONTRAST_API_KEY%22%3A%22%24%7Binput%3Acontrast_api_key%7D%22%2C%22CONTRAST_SERVICE_KEY%22%3A%22%24%7Binput%3Acontrast_service_key%7D%22%7D%7D) + +**Other Clients:** See [Installation Guide](#docker) below + +--- + +> [!WARNING] +> **CRITICAL SECURITY WARNING:** +> EXPOSING YOUR CONTRAST VULNERABILITY DATA TO A LLM THAT TRAINS ON YOUR DATA CAN POTENTIALLY EXPOSE YOUR VULNERABILITY DATA TO THE OUTSIDE WORLD. +> Thus, do not use mcp-contrast functions which pull sensitive data with a LLM that trains on your data. +> +> **Verify AI Data Privacy:** Before sending vulnerability data to an AI, you must confirm that your service agreement guarantees your data will not be used for model training. +> +> **UNSAFE:** Public consumer websites (e.g., the free versions of ChatGPT, Gemini, Claude). These services often use your input for training. +> +> **POTENTIALLY-SAFE:** Enterprise-grade services (e.g. Google Cloud AI, AWS Bedrock, Azure OpenAI) or paid plans that contractually ensure data privacy and prevent model training on your prompts, verify with your information security teams. + +--- ## Table of Contents -- [Sample Prompts](#sample-prompts) - - [For the Developer](#for-the-developer) - - [Remediate Vulnerability in code](#remediate-vulnerability-in-code) - - [3rd Party Library Remediation](#3rd-party-library-remediation) - - [For the Security Professional](#for-the-security-professional) -- [Data Privacy](#data-privacy) -- [Build](#build) -- [Run](#run) -- [Docker](#docker) - - [Build Docker Image](#build-docker-image) - - [Run with Docker](#run-with-docker) - - [Using Copilot + Petclinic](#using-copilot--petclinic) - - [Install via Link](#install-via-link) - - [Manual Install of MCP Server](#manual-install-of-mcp-server) - - [Using Cline Plugin](#using-cline-plugin) - - [Using oterm](#using-oterm) -- [Proxy Configuration](#proxy-configuration) - - [Java Process](#java-process) - - [Docker](#docker-1) +- [Contrast MCP Server](#contrast-mcp-server) + - [Quick Install](#quick-install) + - [Table of Contents](#table-of-contents) + - [Sample Prompts](#sample-prompts) + - [For the Developer](#for-the-developer) + - [Remediate Vulnerability in code](#remediate-vulnerability-in-code) + - [3rd Party Library Remediation](#3rd-party-library-remediation) + - [Retrieving application based on Tags](#retrieving-application-based-on-tags) + - [Retrieving application based on Metadata](#retrieving-application-based-on-metadata) + - [Retrieving vulnerabilities based on Session Metadata](#retrieving-vulnerabilities-based-on-session-metadata) + - [For the Security Professional](#for-the-security-professional) + - [Data Privacy](#data-privacy) + - [Build](#build) + - [Run](#run) + - [Docker](#docker) + - [Build Docker Image](#build-docker-image) + - [Using Copilot + Petclinic](#using-copilot--petclinic) + - [Install via Link in VScode](#install-via-link-in-vscode) + - [Manual Install of MCP Server](#manual-install-of-mcp-server) + - [Install in Intellij](#install-in-intellij) + - [Using Cline Plugin](#using-cline-plugin) + - [Using Claude Desktop](#using-claude-desktop) + - [Using oterm](#using-oterm) + - [Proxy Configuration](#proxy-configuration) + - [Java Process](#java-process) + - [Docker](#docker-1) + - [Common Issues](#common-issues) + - [Review Log](#review-log) + - [Enable Debug Logging](#enable-debug-logging) + - [Certificate Issues](#certificate-issues) ## Sample Prompts ### For the Developer @@ -132,7 +156,7 @@ To build out the vulnerabilites and attack events run `./testscript.sh` Select option 25. ( this will exercise the app and perform attacks to populate the vulnerabilities and attack events) #### Install via Link in VScode -Click following link >>> [![Install in VS Code Docker](https://img.shields.io/badge/VS_Code-docker-0098FF?style=flat-square&logo=githubcopilot&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=contrastmcp&config=%7B%22command%22:%22docker%22,%22args%22:%5B%22run%22,%20%22-e%22,%22CONTRAST_HOST_NAME%22,%20%22-e%22,%22CONTRAST_API_KEY%22,%20%22-e%22,%22CONTRAST_SERVICE_KEY%22,%20%22-e%22,%22CONTRAST_USERNAME%22,%20%22-e%22,%22CONTRAST_ORG_ID%22,%20%20%22-i%22,%20%22--rm%22,%20%22contrast/mcp-contrast:latest%22,%20%22-t%22,%20%22stdio%22%5D,%22env%22:%7B%22CONTRAST_HOST_NAME%22:%22example.contrastsecurity.com%22,%22CONTRAST_API_KEY%22:%22example%22,%22CONTRAST_SERVICE_KEY%22:%22example%22,%22CONTRAST_USERNAME%22:%22example@example.com%22,%22CONTRAST_ORG_ID%22:%22example%22%7D%7D) <<< +Click following link >>> [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_contrast--mcp-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=ffffff)](vscode:mcp/install?%7B%22name%22%3A%22contrast-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-e%22%2C%22CONTRAST_HOST_NAME%22%2C%22-e%22%2C%22CONTRAST_API_KEY%22%2C%22-e%22%2C%22CONTRAST_SERVICE_KEY%22%2C%22-e%22%2C%22CONTRAST_USERNAME%22%2C%22-e%22%2C%22CONTRAST_ORG_ID%22%2C%22-i%22%2C%22--rm%22%2C%22contrast%2Fmcp-contrast%3Alatest%22%2C%22-t%22%2C%22stdio%22%5D%2C%22env%22%3A%7B%22CONTRAST_HOST_NAME%22%3A%22%24%7Binput%3Acontrast_host_name%7D%22%2C%22CONTRAST_ORG_ID%22%3A%22%24%7Binput%3Acontrast_org_id%7D%22%2C%22CONTRAST_USERNAME%22%3A%22%24%7Binput%3Acontrast_username%7D%22%2C%22CONTRAST_API_KEY%22%3A%22%24%7Binput%3Acontrast_api_key%7D%22%2C%22CONTRAST_SERVICE_KEY%22%3A%22%24%7Binput%3Acontrast_service_key%7D%22%7D%7D) <<< Allow the extension to be installed in your VSCode instance. Select Install Server