AIML-228: Add appID and appName to VulnLight record [STACKED]

[ChrisEdwards]

Rebased onto main after #31 (AIML-226) merged.

---

Summary

This PR adds application identification fields (appID and appName) to vulnerability responses, eliminating the need for users to perform additional API calls to determine which application owns a vulnerability.

Why

Problem: When listing vulnerabilities across an organization or filtering by various criteria, users received vulnerability data without any indication of which application each vulnerability belonged to. This forced users to either:

1. Query vulnerabilities app-by-app to maintain context
2. Make additional API calls to correlate vulnerability IDs back to applications
3. Manually cross-reference vulnerability data with application lists

Impact: This created unnecessary complexity for AI agents and users trying to understand their security posture, especially when working with vulnerabilities across multiple applications.

What

Added two new fields to the VulnLight record:

• appID: Application UUID that owns the vulnerability
• appName: Human-readable application display name

These fields are now populated in all vulnerability listing tool responses:

• list_all_vulnerabilities - Org-wide vulnerability queries
• list_vulnerabilities - App-specific vulnerability queries
• list_vulns_by_app_and_metadata - Session metadata filtered queries
• list_vulns_by_app_latest_session - Latest session filtered queries

How

Technical Approach:

1. Extended the VulnLight record (VulnLight.java:24-25) with appID and appName fields, including comprehensive JavaDoc
2. Modified VulnerabilityMapper (VulnerabilityMapper.java:51-55) to safely extract application data from Trace objects, with null-safe handling
3. Updated all vulnerability queries to request APPLICATION expansion via the Contrast SDK's TraceExpandValue.APPLICATION enum:
   • AssessService.java:201 - listVulnsByAppId()
   • AssessService.java:281 - listVulnsInAppByNameAndSessionMetadata()
   • AssessService.java:499 - getAllVulnerabilities()

Design Decision: Used the SDK's native expansion mechanism rather than performing separate lookups, ensuring efficient single-request retrieval of application context.

Code Walkthrough

1. VulnLight Record Enhancement (VulnLight.java)

public record VulnLight(
    String title,
    String type,
    String vulnID,
    String severity,
    String appID,        // NEW: Application UUID
    String appName,      // NEW: Application display name
    List<SessionMetadata> sessionMetadata,
    ...
)

Added comprehensive JavaDoc explaining all fields, making the record self-documenting for API consumers.

2. VulnerabilityMapper Changes (VulnerabilityMapper.java:49-66)

// Extract application info safely, handling null cases
String appId = null;
String appName = null;
if (trace.getApplication() != null) {
    appId = trace.getApplication().getId();
    appName = trace.getApplication().getName();
}

Null-safe extraction ensures backward compatibility if APPLICATION expansion is missing from a query.

3. Service Layer Updates (AssessService.java)

Added TraceExpandValue.APPLICATION to all three vulnerability query methods:

• Line 201: listVulnsByAppId() - Already had SESSION_METADATA and SERVER_ENVIRONMENTS expand
• Line 281: listVulnsInAppByNameAndSessionMetadata() - Added APPLICATION to SESSION_METADATA expand
• Line 499: getAllVulnerabilities() - Added APPLICATION to existing SERVER_ENVIRONMENTS and SESSION_METADATA expand

This ensures the SDK includes application objects in the trace responses.

Testing

Unit Tests (VulnerabilityMapperTest.java):

• ✅ toVulnLight_BasicTrace_TransformsCorrectly - Updated to verify appID and appName extraction (lines 64-66, 90-91)
• ✅ toVulnLight_TraceWithNullApplication_HandlesGracefully - NEW test verifying null safety (lines 411-438)
• ✅ toVulnLight_TraceWithApplication_ExtractsAppData - NEW test verifying correct extraction (lines 440-475)

Integration Tests (AssessServiceIntegrationTest.java):

• ✅ Updated testListAllVulnerabilities() to assert appID and appName are non-null and non-empty (lines 202-206)
• ✅ Enhanced output to display application context: "App: My App (app-123)" (line 207)

Test Results:

• All 250 tests pass (unit + integration)
• Build: ✅ SUCCESS
• No regressions introduced

Manual Verification: Tested against live Contrast instance, confirmed appID and appName appear correctly in all vulnerability listing responses.

Benefits

1. Improved User Experience: Users immediately see which application owns each vulnerability
2. Reduced API Calls: No need for separate application lookup queries
3. Better AI Agent Performance: AI can make informed decisions about vulnerabilities without additional context gathering
4. Simplified Debugging: Developers can quickly identify app context when troubleshooting
5. Backwards Compatible: Only adds new fields, no breaking changes to existing API contracts

Documentation Updates

Also includes comprehensive updates to CLAUDE.md:

• Added stacked PR workflow documentation
• Added coding standards (prefer var, use isEmpty())
• Added detailed AI development workflow guidance
• Added promotion workflow for stacked PRs to ready-for-review

These documentation changes improve the development process for all contributors working with AI assistance.

---

Related:

• Jira: AIML-228
• Depends on: AIML-226: Fix tool names exceeding Claude API 64-char limit #31 (AIML-226) - ✅ Merged

[Copilot]

Pull Request Overview

This PR adds appID and appName fields to the VulnLight record, enabling direct correlation of vulnerabilities to their owning applications without requiring additional API calls. This enhancement improves usability for AI agents and users working with application-specific vulnerability tools.

Key Changes:

• Added appID and appName fields to VulnLight record with comprehensive JavaDoc
• Updated VulnerabilityMapper to safely extract application data from trace objects
• Added APPLICATION expand parameter to all vulnerability query operations in AssessService

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
VulnLight.java	Added appID and appName fields with detailed JavaDoc documentation
VulnerabilityMapper.java	Added null-safe extraction of application ID and name from traces
AssessService.java	Added APPLICATION expand to vulnerability queries
VulnerabilityMapperTest.java	Added comprehensive unit tests for null and populated application cases
AssessServiceIntegrationTest.java	Enhanced integration tests to verify application fields
CLAUDE.md	Documentation updates for coding standards and AI workflow improvements

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[seschis]

lgtm