# Test Plan: get_vulnerability Tool

## Overview

This test plan provides comprehensive testing guidance for the `get_vulnerability` MCP tool. This tool retrieves detailed information about a specific vulnerability by ID, including remediation guidance, stack traces, and vulnerable library information.

### Migration Notes

**This plan replaces:**
- `test-plan-get_vulnerability.md` (original at root level)

The tool signature and behavior remain unchanged; this is a format/location update.

### Tool Signature

**MCP Tool Name:** `get_vulnerability`

**Parameters:**
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `vulnId` | String | **Yes** | - | Vulnerability ID (use search_vulnerabilities to find) |
| `appId` | String | **Yes** | - | Application ID (use search_applications to find) |

### Response Structure

**Returns:** `SingleToolResponse<Vulnerability>`

```java
SingleToolResponse {
    Vulnerability data,          // Full vulnerability details (null if not found)
    String message,              // Warnings or "not found" message
    boolean found                // Whether vulnerability was found
}

Vulnerability {
    String hint,                 // AI-generated remediation hint
    String vulnID,               // Vulnerability identifier
    String title,                // Human-readable vulnerability name
    String type,                 // Vulnerability type (e.g., sql-injection)
    String howToFix,             // Official Contrast remediation recommendation
    List<StackLib> stackTrace,   // Stack frames with library mappings
    List<LibraryExtended> vulnerableLibraries,  // Libraries with CVEs
    String httpRequest,          // HTTP request text (if captured)
    String status,               // Current vulnerability status
    Long firstTimeSeen,          // Epoch timestamp of first detection
    Long lastTimeSeen,           // Epoch timestamp of last detection
    Long closedTime,             // Epoch timestamp when closed (nullable)
    List<String> environments    // All environments where seen
}

StackLib {
    String stackTraceLine,       // Code location/method info
    String libraryHash           // Hash of associated library (null if app code)
}

LibraryExtended {
    String hash,                 // Library hash identifier
    String name,                 // Library name
    String version,              // Library version
    List<Vulnerability> vulnerabilities  // CVEs/vulnerabilities in this library
}
```

### Critical Behavioral Notes

| Behavior | Description |
|----------|-------------|
| **Both IDs Required** | Tool requires both vulnId AND appId |
| **Graceful Degradation** | Optional data (recommendation, http request, stacktrace) may be null with warnings |
| **Library Matching** | Stack frames matched to vulnerable libraries by hash |
| **Not Found** | Returns `found: false` with message if vulnerability doesn't exist |
| **Hint Generation** | AI-generated hint based on vulnerability type |

---

## 1. Required Parameter Tests

### Test Case 1.1: Missing vulnId (HARD FAILURE)

**Objective:** Verify tool fails without vulnId.

**Test Steps:**
1. Call `get_vulnerability` with only `appId="xyz"`

**Expected Results:**
- **HARD FAILURE:** Returns error response
- Error in `message`: "vulnId is required"
- `found: false`

---

### Test Case 1.2: Missing appId (HARD FAILURE)

**Objective:** Verify tool fails without appId.

**Test Steps:**
1. Call `get_vulnerability` with only `vulnId="xyz"`

**Expected Results:**
- **HARD FAILURE:** Returns error response
- Error in `message`: "appId is required"
- `found: false`

---

### Test Case 1.3: Both Parameters Missing (HARD FAILURE)

**Objective:** Verify tool fails without both parameters.

**Test Steps:**
1. Call `get_vulnerability` with no parameters

**Expected Results:**
- **HARD FAILURE:** Returns error response
- Error in `message` about missing parameters
- `found: false`

---

### Test Case 1.4: Valid Parameters - Success

**Objective:** Verify tool succeeds with valid IDs.

**Prerequisites:**
- Valid vulnId from `search_vulnerabilities`
- Valid appId from `search_applications`

**Test Steps:**
1. Call `get_vulnerability(vulnId="valid-id", appId="valid-app-id")`

**Expected Results:**
- `found: true`
- `data` contains Vulnerability object
- All mandatory fields populated

---

## 2. Not Found Scenarios

### Test Case 2.1: Non-Existent vulnId (Valid Format)

**Objective:** Test with UUID that doesn't exist.

**Test Steps:**
1. Call with `vulnId="00000000-0000-0000-0000-000000000000", appId="valid-app-id"`

**Expected Results:**
- `found: false`
- `data: null`
- `message`: "Vulnerability not found"

---

### Test Case 2.2: Non-Existent appId (Valid Format)

**Objective:** Test with application UUID that doesn't exist.

**Test Steps:**
1. Call with `vulnId="valid-vuln-id", appId="00000000-0000-0000-0000-000000000000"`

**Expected Results:**
- `found: false`
- `data: null`
- `message`: indicates not found

---

### Test Case 2.3: Mismatched vulnId and appId

**Objective:** Test when vulnerability exists but not in specified application.

**Prerequisites:**
- vulnId from Application A
- appId from Application B

**Test Steps:**
1. Call with `vulnId` from App A and `appId` from App B

**Expected Results:**
- `found: false`
- `data: null`
- `message`: indicates not found
- No data leakage from wrong application

---

### Test Case 2.4: Invalid ID Format (Malformed)

**Objective:** Test with malformed IDs.

**Test Steps:**
1. Call with `vulnId="not-a-uuid", appId="valid-app-id"`
2. Call with `vulnId="valid-vuln-id", appId="not-a-uuid"`
3. Call with `vulnId="12345", appId="12345"`
4. Call with `vulnId="", appId=""`

**Expected Results:**
- **HARD FAILURE:** Returns error response
- Error in `message` about invalid ID format
- `found: false`

---

## 3. Response Data Tests

### Test Case 3.1: Verify All Mandatory Fields Present

**Objective:** Confirm mandatory fields are always populated.

**Test Steps:**
1. Call with valid vulnId and appId
2. Examine response data

**Expected Results:**
- `vulnID` matches requested ID
- `title` is non-empty string
- `type` is non-empty string (vulnerability type)
- `status` is one of: Reported, Suspicious, Confirmed, Remediated, Fixed
- `firstTimeSeen` is valid epoch timestamp
- `lastTimeSeen` is valid epoch timestamp >= firstTimeSeen
- `environments` is array (may be empty)

---

### Test Case 3.2: Verify hint Field Generation

**Objective:** Confirm AI-generated hint is present.

**Test Steps:**
1. Call with known vulnerability type (e.g., sql-injection)
2. Examine `hint` field

**Expected Results:**
- `hint` field is non-null
- Contains security guidance relevant to vulnerability type
- Hint text is actionable

---

### Test Case 3.3: Verify howToFix Field (Recommendation)

**Objective:** Confirm remediation recommendation is present.

**Prerequisites:**
- Vulnerability with recommendation data

**Test Steps:**
1. Call with vulnerability that has recommendations
2. Examine `howToFix` field

**Expected Results:**
- `howToFix` is non-null
- Contains remediation guidance (typically 50+ characters)
- Text is actionable

---

### Test Case 3.4: Recommendation Data Not Available (Warning)

**Objective:** Test graceful degradation when recommendation unavailable.

**Test Steps:**
1. Test with vulnerability without recommendation data
2. Or simulate API failure for recommendation

**Expected Results:**
- `howToFix` is null
- Warning in `message`: "Recommendation data not available..."
- Rest of response is valid

---

### Test Case 3.5: Verify httpRequest Field

**Objective:** Confirm HTTP request data is present when available.

**Prerequisites:**
- Runtime-detected vulnerability with HTTP request capture

**Test Steps:**
1. Call with vulnerability from web application
2. Examine `httpRequest` field

**Expected Results:**
- `httpRequest` is non-null
- Contains HTTP request details (method, path, headers)
- Request text is readable

---

### Test Case 3.6: HTTP Request Not Available (Warning)

**Objective:** Test graceful degradation when HTTP request unavailable.

**Prerequisites:**
- Vulnerability without HTTP request (e.g., static analysis finding)

**Test Steps:**
1. Call with vulnerability without HTTP data
2. Or simulate API failure for HTTP request

**Expected Results:**
- `httpRequest` is null
- Warning in `message`: "HTTP request data not available..."
- Rest of response is valid

---

### Test Case 3.7: Verify Timestamp Values

**Objective:** Confirm timestamps are valid and consistent.

**Test Steps:**
1. Call with valid vulnerability
2. Examine timestamp fields

**Expected Results:**
- `firstTimeSeen` is valid epoch timestamp > 0
- `lastTimeSeen` >= `firstTimeSeen`
- For closed vulnerabilities: `closedTime` >= `firstTimeSeen`
- For open vulnerabilities: `closedTime` may be null or 0

---

### Test Case 3.8: Verify environments Field

**Objective:** Confirm environments list is populated correctly.

**Test Steps:**
1. Call with vulnerability seen in multiple environments

**Expected Results:**
- `environments` is array of strings
- Contains valid values: DEVELOPMENT, QA, PRODUCTION
- Shows all environments where vulnerability has been seen

---

## 4. Stack Trace Tests

### Test Case 4.1: Verify stackTrace Field Structure

**Objective:** Confirm stack trace data structure.

**Prerequisites:**
- Vulnerability with trigger event and stack trace

**Test Steps:**
1. Call with vulnerability that has stack trace
2. Examine `stackTrace` field

**Expected Results:**
- `stackTrace` is array of StackLib objects
- Each entry has `stackTraceLine` (non-empty string)
- Each entry has `libraryHash` (string or null)
- Stack trace shows method call chain

---

### Test Case 4.2: Stack Trace with Library Matching

**Objective:** Verify stack frames matched to libraries.

**Prerequisites:**
- Vulnerability where stack trace passes through library code

**Test Steps:**
1. Call with vulnerability involving third-party library
2. Examine `stackTrace` and `vulnerableLibraries`

**Expected Results:**
- StackLib entries for library code have non-null `libraryHash`
- Hash matches a library in `vulnerableLibraries`
- Library matching is accurate

---

### Test Case 4.3: Stack Trace in Application Code (No Library Match)

**Objective:** Verify handling of application-only stack traces.

**Prerequisites:**
- Vulnerability in application code (not library)

**Test Steps:**
1. Call with vulnerability in app code
2. Examine `stackTrace` entries

**Expected Results:**
- All `stackTrace` entries have `libraryHash: null`
- `vulnerableLibraries` is empty
- Stack trace still complete

---

### Test Case 4.4: No Stack Trace Available (Warning)

**Objective:** Test graceful degradation when stack trace unavailable.

**Test Steps:**
1. Call with vulnerability without trigger event
2. Or simulate API failure for stack trace

**Expected Results:**
- `stackTrace` is empty array `[]` (not null)
- `vulnerableLibraries` is empty array
- Warning in `message`: "Stack trace data not available..."

---

### Test Case 4.5: Large Stack Trace (20+ Frames)

**Objective:** Test handling of deep call stacks.

**Prerequisites:**
- Vulnerability with deep stack trace

**Test Steps:**
1. Call with vulnerability with 20+ stack frames
2. Verify all frames returned

**Expected Results:**
- All stack frames returned (no truncation)
- Performance acceptable (< 15 seconds)
- Library matching performed on all frames

---

## 5. Vulnerable Libraries Tests

### Test Case 5.1: Verify vulnerableLibraries Structure

**Objective:** Confirm library data structure.

**Prerequisites:**
- Vulnerability involving library with CVEs

**Test Steps:**
1. Call with vulnerability in library code
2. Examine `vulnerableLibraries`

**Expected Results:**
- `vulnerableLibraries` is array of LibraryExtended objects
- Each library has: hash, name, version
- Each library has `vulnerabilities` array with CVE details

---

### Test Case 5.2: Library CVE Data Completeness

**Objective:** Verify CVE data is complete.

**Test Steps:**
1. Examine library vulnerability details

**Expected Results:**
- CVE identifier (e.g., CVE-2023-XXXXX)
- Severity score
- Title or description
- Data matches known CVEs for library version

---

### Test Case 5.3: Multiple Vulnerable Libraries

**Objective:** Test vulnerability with multiple libraries.

**Prerequisites:**
- Vulnerability with stack trace through multiple vulnerable libraries

**Test Steps:**
1. Call with vulnerability involving multiple libs
2. Count libraries returned

**Expected Results:**
- All vulnerable libraries in stack are included
- No duplicates (Set ensures uniqueness)
- Each library has correct CVE data

---

### Test Case 5.4: Library Without CVEs Excluded

**Objective:** Verify libraries without CVEs are not in vulnerableLibraries.

**Test Steps:**
1. Call with vulnerability
2. Compare stack trace libraries to vulnerableLibraries

**Expected Results:**
- Only libraries with CVEs appear in `vulnerableLibraries`
- Libraries without CVEs have `libraryHash: null` in stack trace

---

### Test Case 5.5: No Vulnerable Libraries

**Objective:** Test vulnerability without library involvement.

**Test Steps:**
1. Call with vulnerability purely in application code

**Expected Results:**
- `vulnerableLibraries` is empty array `[]`
- All stack trace entries have `libraryHash: null`
- No errors

---

## 6. Error Handling Tests

### Test Case 6.1: Multiple Warnings Combined

**Objective:** Verify multiple warnings appear in message.

**Test Steps:**
1. Trigger scenario where multiple optional data fetches fail
2. Examine `message` field

**Expected Results:**
- `message` contains multiple warnings
- Each warning is clearly stated
- Response still contains available data

---

### Test Case 6.2: API Timeout Handling

**Objective:** Test handling of slow API responses.

**Prerequisites:**
- Test environment with network delays

**Test Steps:**
1. Configure network delays
2. Call `get_vulnerability`

**Expected Results:**
- Returns within reasonable timeout
- May return partial data with warnings
- No hang or crash

---

### Test Case 6.3: Authentication Error

**Objective:** Test with invalid credentials.

**Prerequisites:**
- Invalid Contrast credentials

**Test Steps:**
1. Configure invalid credentials
2. Call `get_vulnerability`

**Expected Results:**
- Returns error response
- Error message indicates authentication failure
- No sensitive data exposed in error

---

## 7. Consistency Tests

### Test Case 7.1: Data Consistency with search_vulnerabilities

**Objective:** Verify data matches summary from search tool.

**Test Steps:**
1. Call `search_vulnerabilities` to get summary data
2. Note vulnID, title, status, type for a vulnerability
3. Call `get_vulnerability` with that vulnID and appId
4. Compare fields

**Expected Results:**
- `vulnID` matches exactly
- `title` matches exactly
- `status` matches exactly
- `type` matches exactly
- Detailed view contains additional data

---

### Test Case 7.2: Repeated Calls Return Same Data

**Objective:** Verify consistent results across multiple calls.

**Test Steps:**
1. Call `get_vulnerability` with same parameters 3 times
2. Compare all responses

**Expected Results:**
- All responses are identical
- No data variation between calls
- Consistent performance

---

### Test Case 7.3: Different Vulnerability Types

**Objective:** Test across various vulnerability types.

**Test Steps:**
1. Call with SQL Injection vulnerability
2. Call with XSS vulnerability
3. Call with Path Traversal vulnerability
4. Call with Crypto vulnerability

**Expected Results:**
- All return successfully
- Each has appropriate `hint` for its type
- Each has appropriate `howToFix`
- Response structure consistent

---

## 8. Edge Case Tests

### Test Case 8.1: Newly Detected Vulnerability

**Objective:** Test with very recently detected vulnerability.

**Prerequisites:**
- Vulnerability detected in last few minutes

**Test Steps:**
1. Find most recently detected vulnerability
2. Call `get_vulnerability` immediately

**Expected Results:**
- Returns successfully
- All available data returned
- Some optional data may be null if still processing
- No errors

---

### Test Case 8.2: Very Old Vulnerability

**Objective:** Test with long-standing vulnerability.

**Prerequisites:**
- Vulnerability detected years ago

**Test Steps:**
1. Find vulnerability with oldest `firstTimeSeen`
2. Call `get_vulnerability`

**Expected Results:**
- Returns successfully
- All data still accessible
- Historical data complete

---

### Test Case 8.3: Closed/Fixed Vulnerability

**Objective:** Test with vulnerability that has been remediated.

**Prerequisites:**
- Vulnerability with status Fixed or Remediated

**Test Steps:**
1. Call with fixed vulnerability

**Expected Results:**
- Returns successfully
- `status` shows Fixed or Remediated
- `closedTime` is populated (non-null)
- Historical data complete

---

### Test Case 8.4: Vulnerability with No Optional Data

**Objective:** Test vulnerability with minimal data.

**Test Steps:**
1. Call with vulnerability lacking recommendation, http request, stack trace

**Expected Results:**
- Returns successfully
- `howToFix`: null with warning
- `httpRequest`: null with warning
- `stackTrace`: empty array with warning
- `vulnerableLibraries`: empty array
- Mandatory fields still present

---

## Test Execution Guidelines

### Pre-Test Setup
1. Verify MCP server running with valid credentials
2. Use `search_vulnerabilities` to identify test vulnerabilities:
   - Different types (SQL injection, XSS, etc.)
   - Different statuses (open, closed)
   - With and without stack traces
   - With and without library involvement
3. Record vulnId and appId pairs for testing

### Test Data Recommendations
- At least 5 different vulnerability types
- At least 1 vulnerability per status
- Vulnerability with rich stack trace
- Vulnerability with library CVEs
- Vulnerability in application code only
- Recently detected vulnerability
- Old vulnerability

### Success Criteria
Each test passes when:
1. Response structure matches expected format
2. Data is accurate and consistent
3. Warnings appear for unavailable optional data
4. No unexpected exceptions or errors

---

## Test Coverage Summary

| Category | Test Cases | Coverage |
|----------|------------|----------|
| Required Parameters | 4 | Both IDs required validation |
| Not Found Scenarios | 4 | Various not-found cases |
| Response Data | 8 | All response fields |
| Stack Trace | 5 | Stack trace handling |
| Vulnerable Libraries | 5 | Library matching, CVE data |
| Error Handling | 3 | Timeouts, auth, multi-warning |
| Consistency | 3 | Data accuracy |
| Edge Cases | 4 | New, old, closed, minimal |

**Total: 36 test cases**

---

## References

- **Tool Implementation**: `tool/vulnerability/GetVulnerabilityTool.java`
- **Related Tools**: `search_vulnerabilities`, `search_app_vulnerabilities`, `search_applications`
- **Old Test Plan**: `test-plan-get_vulnerability.md` (root level)
