Skip to content

Instantly share code, notes, and snippets.

@jwmatthews

jwmatthews/ENTERPRISE_FAILURE_POINTS_ANALYSIS.md

Created December 4, 2025 15:39
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save jwmatthews/8b251d81b02327996c5503f47f788ce3 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save jwmatthews/8b251d81b02327996c5503f47f788ce3 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
ENTERPRISE_FAILURE_POINTS_ANALYSIS.md

Deep Dive Technical Analysis: MTA Extension Enterprise Failure Points

Executive Summary

The Migration Toolkit for Applications (MTA) VS Code extension is a complex multi-component system with several potential failure points in restricted enterprise environments. The architecture involves multiple communication protocols, binary executables, and external dependencies that can be blocked or restricted by enterprise security policies.

System Architecture Overview

Core Components

  1. VS Code Extension (TypeScript) - Main extension running in the VS Code process
  2. Analyzer RPC Server (Go binary) - Spawned child process for code analysis
  3. Java Language Server (JDTLS) - Red Hat Java extension dependency
  4. GenAI Model Providers - External AI services (OpenAI, Azure, AWS Bedrock, etc.)
  5. Solution Server (MCP) - Optional Model Context Protocol server for solution storage
  6. Webview UI - React-based UI for analysis results

Communication Mechanisms & Failure Points

1. Named Pipe Communication (Analyzer RPC Server)

Location: vscode/src/client/analyzerClient.ts:112

How it works:

const pipeName = rpc.generateRandomPipeName();
// Windows: \\.\pipe\vscode-jsonrpc-<random>-sock
// Unix: /tmp/vscode-<random>.sock or $XDG_RUNTIME_DIR/vscode-ipc-<random>.sock

Enterprise Failure Scenarios:

a) Windows WDAC (Windows Defender Application Control) / AppLocker Restrictions

  • Issue: WDAC policies can block unnamed/dynamically named pipe creation
  • Manifestation: Extension fails to start the analyzer server with "Access Denied" or pipe creation failures
  • Code Reference: node_modules/vscode-jsonrpc/lib/node/main.js:159-160
  • Why it fails: Named pipes on Windows (\\.\pipe\*) require specific permissions that may be denied under strict WDAC policies
  • Error messages:
    • "Unable to connect after multiple retries"
    • "Analyzer RPC server failed to start"
    • Socket connection timeout errors

b) Unix Socket Path Length Limits

  • Issue: Socket paths exceeding 107 chars (Linux) or 103 chars (macOS) cause failures
  • Code Reference: node_modules/vscode-jsonrpc/lib/node/main.js:153-172
  • Manifestation: Warnings in logs: WARNING: IPC handle "..." is longer than X characters
  • Risk: Deep workspace paths in enterprise network shares

c) Temporary Directory Restrictions

  • Issue: Some enterprise environments restrict write access to temp directories
  • Impact: Cannot create Unix socket files in /tmp or %TEMP%
  • Fallback: Uses XDG_RUNTIME_DIR on Linux if available

Mitigation in Code:

  • Retry logic with 5 attempts, 2-second delays (analyzerClient.ts:256-274)
  • Configurable analyzer path (mta-vscode-extension.analyzerPath setting)

2. HTTP/2 vs HTTP/1.1 Communication (GenAI Providers)

Location: vscode/src/utilities/tls.ts, vscode/src/modelProvider/modelCreator.ts

Recent Fix: Commit d6bc675 - "Address ECONNRESET when http2 blocked"

How it works:

  • Default: HTTP/1.1 (firewall-compatible)
  • Optional: HTTP/2 (better performance)
  • Configuration: mta-vscode-extension.genai.httpProtocol setting

Enterprise Failure Scenarios:

a) HTTP/2 Protocol Blocking

  • Issue: Deep packet inspection firewalls block HTTP/2 (ALPN negotiation failures)
  • Symptoms:
    • ECONNRESET errors when connecting to AI providers
    • Connection timeouts
    • "fetch failed" errors
  • Providers affected: OpenAI, Azure OpenAI, DeepSeek, Ollama, AWS Bedrock

Technical Details:

// tls.ts:139 - ALPN protocol negotiation
ALPNProtocols: httpVersion === "2.0" ? ["h2", "http/1.1"] : ["http/1.1"]

When HTTP/2 is enabled but blocked:

  1. Client attempts ALPN handshake with h2 protocol
  2. Firewall drops or resets connection during TLS negotiation
  3. No automatic fallback to HTTP/1.1 in undici/fetch

Solution Implemented:

  • User-configurable protocol selection (defaults to HTTP/1.1)
  • Explicit dispatcher configuration to disable HTTP/2 when not needed
  • Custom handlers for AWS Bedrock (NodeHttpHandler vs NodeHttp2Handler)

b) Corporate Proxy Issues

  • Location: vscode/src/utilities/tls.ts:29-44
  • Environment Variables: HTTPS_PROXY, HTTP_PROXY, https_proxy, http_proxy
  • HTTP/2 + Proxy Limitation: 
    // tls.ts:152-158 - Cannot use HTTP/2 with proxy in AWS SDK
if (httpVersion === "2.0") {
  logger.warn("HTTP/2 with proxy is not supported via NodeHttp2Handler. " +
              "Falling back to HTTP/1.1 with proxy support.");
}
  • Risk: Enterprises requiring proxies cannot use HTTP/2 with AWS Bedrock

c) TLS Certificate Validation

  • Custom CA Bundles: Supported via environment variables
    • CA_BUNDLE, AWS_CA_BUNDLE (Bedrock)
    • PROVIDER_ENV_CA_BUNDLE (other providers)
  • Insecure Mode: ALLOW_INSECURE=true or NODE_TLS_REJECT_UNAUTHORIZED=0
  • Code: tls.ts:16-54 - Merges system certs with custom CA bundle

Failure Scenarios:

  • Self-signed certificates in corporate environments
  • Man-in-the-middle SSL inspection appliances
  • Certificate pinning conflicts

3. Binary Executable Restrictions

Location: vscode/src/paths.ts:82-257

Binaries Used:

  1. kai-analyzer-rpc - Platform-specific analyzer binary
    • Windows: kai-analyzer-rpc.exe
    • Linux/macOS: kai-analyzer-rpc
  2. fernflower.jar - Java decompiler
  3. JDTLS bundles - Java language server JARs

Enterprise Failure Scenarios:

a) Executable Whitelisting (WDAC/AppLocker)

  • Issue: Binaries not signed or not in approved list
  • Symptoms:
    • Binary fails to spawn
    • "Access Denied" errors
    • Process exits immediately with code 1
  • Code Reference: analyzerClient.ts:296-319 - spawn() call
  • Mitigation:
    • Allow users to configure custom analyzer path
    • Extension checks if user-provided binary is executable (fileUtils.ts)

b) Download Restrictions

  • Fallback Download: If binary missing, downloads from developers.redhat.com
  • Code: paths.ts:130-257
  • Failure Points:
    • Blocked access to external URLs
    • SHA256 verification failures
    • Zip extraction permissions
  • URLs:
    • https://developers.redhat.com/content-gateway/rest/browse/pub/mta/8.0.0/
    • Platform-specific zip files (e.g., mta-8.0.0-analyzer-rpc-windows-amd64.zip)

c) Executable Permissions (Unix)

  • Code: paths.ts:249-251 
    if (platform !== "win32") {
  await chmod(kaiAnalyzerPath, 0o755);
}
  • Risk: Mounted network shares with noexec flag
  • Symptom: "Permission denied" when spawning analyzer

4. Java Language Server Dependency

Extension Dependency: redhat.java (vscode/package.json:36)

Communication:

  • Uses VS Code command API: java.execute.workspaceCommand
  • Code: analyzerClient.ts:203-214

Enterprise Failure Scenarios:

a) Missing Java Extension

  • Health Check: analyzerClient.ts:225-250
  • Command: java.project.getAll
  • Error: "Java Language Server is not running or the project configuration is not set up correctly"
  • Impact: Degraded analysis results for Java projects

b) Java Extension Failures

  • JDK version requirements
  • Workspace trust issues
  • Project configuration errors
  • JDTLS bundle loading failures

Code Reference:

// paths.ts:63-66 - JDTLS bundles
const jdtlsBundleJars = globbySync("**/*.jar", {
  cwd: assetPaths.jdtlsBundles,
  onlyFiles: true,
});

5. Solution Server (MCP) Communication

Location: agentic/src/clients/solutionServerClient.ts

Protocol: HTTP/HTTPS with Model Context Protocol

Enterprise Failure Scenarios:

a) Network Connectivity

  • Default URL: http://localhost:8000
  • Configurable: mta-vscode-extension.solutionServer.url
  • Connection Errors Detected:
    • ECONNRESET
    • ECONNREFUSED
    • ETIMEDOUT
    • "fetch failed"
  • Code: Lines 388-419 - Connection error detection and graceful degradation

b) Keycloak Authentication

  • Enabled via: mta-vscode-extension.solutionServer.auth.enabled
  • Token Endpoint: ${serverUrl}/auth/realms/${realm}/protocol/openid-connect/token
  • Code: solutionServerClient.ts:991-1044
  • Failure Points:
    • Invalid credentials
    • Keycloak server unreachable
    • Token refresh failures (lines 1046-1177)
    • Realm configuration errors

c) SSL/TLS Issues

  • Insecure Mode: mta-vscode-extension.solutionServer.auth.insecure
  • Code: Lines 1234-1253 - Bypasses SSL verification
  • Risk: Self-signed certificates, corporate SSL inspection

d) URL Trailing Slash Issues

  • Retry Logic: Lines 225-268 - Tries with and without trailing slash
  • Issue: Some MCP servers sensitive to URL format

6. File System Operations

Potential Restrictions:

a) Workspace Repository Access

  • Pattern Exclusions: .gitignore, .konveyorignore support
  • Default Ignores: .git, .vscode, target, node_modules
  • Code: paths.ts:329-420

b) Data Storage Locations

  • Workspace Scope: .vscode/mta-vscode-extension/ (analysis data)
  • Global Scope: Extension global storage (settings, cached responses)
  • Server Working Directory: Workspace storage kai-rpc-server/
  • Logs: Extension log URI
  • Code: paths.ts:259-309

Failure Scenarios:

  • Read-only mounted workspaces
  • Network share permissions
  • Virus scanner file locking
  • Multi-root workspace limitations (only first folder analyzed)

Summary of Enterprise Restrictions & Mitigations

Restriction Type Affected Component Failure Symptom Mitigation Strategy Configuration
HTTP/2 Blocking AI Providers ECONNRESET errors Default to HTTP/1.1 genai.httpProtocol: "http1"
Corporate Proxy AI Providers Connection timeouts Auto-detect proxy env vars HTTPS_PROXY environment
WDAC/AppLocker Analyzer Binary Access Denied Custom binary path analyzerPath setting
Named Pipe Restrictions RPC Communication Server start failure Retry logic (5x, 2s delay) Built-in retry mechanism
SSL Inspection HTTPS Connections Certificate errors Custom CA bundle support CA_BUNDLE environment
Executable Download Blocking Binary Installation Missing binary Manual binary placement analyzerPath setting
Java Extension Missing Java Analysis Degraded results Health check warning Install redhat.java
Keycloak Auth Solution Server Authentication failures Optional authentication solutionServer.auth.enabled: false
Read-only Filesystems Data Storage Write failures Error handling None (fundamental requirement)
Socket Path Length Unix Systems Pipe creation failure Use XDG_RUNTIME_DIR XDG_RUNTIME_DIR environment

Critical Code Paths for Enterprise Debugging

1. Analyzer Server Startup

  • analyzerClient.ts:98-223 - Start sequence
  • analyzerClient.ts:252-283 - Socket connection with retry logic
  • analyzerClient.ts:285-320 - Binary spawn

2. HTTP/AI Communication

  • tls.ts:16-54 - Dispatcher creation with proxy/cert support
  • tls.ts:94-191 - AWS Bedrock HTTP handler
  • modelCreator.ts:249-279 - Fetch function creation

3. Error Detection & Recovery

  • analyzerClient.ts:114-136 - Process error/exit handling
  • solutionServerClient.ts:378-424 - MCP connection error detection
  • solutionServerClient.ts:1115-1173 - Token refresh retry logic

4. Binary Management

  • paths.ts:82-257 - Download and verification
  • client/paths.ts:57-61 - Platform-specific binary selection

Recommendations for Enterprise Deployments

1. Pre-deployment Checklist

  • Test HTTP/1.1 vs HTTP/2 connectivity to AI providers
  • Verify corporate proxy environment variables are set
  • Whitelist analyzer binaries in WDAC/AppLocker
  • Test named pipe creation permissions
  • Configure custom CA bundles if using SSL inspection
  • Pre-download and place analyzer binaries manually if needed
  • Ensure Java extension can be installed
  • Test workspace write permissions

2. Configuration for Restricted Environments

{
  "mta-vscode-extension.genai.httpProtocol": "http1",
  "mta-vscode-extension.analyzerPath": "C:\\custom\\path\\kai-analyzer-rpc.exe",
  "mta-vscode-extension.solutionServer.auth.insecure": true,  // Only if needed
  "mta-vscode-extension.genai.enabled": false  // Disable if AI blocked
}

3. Environment Variables

# Proxy configuration
HTTPS_PROXY=http://proxy.company.com:8080
NO_PROXY=localhost,127.0.0.1

# Certificate handling
CA_BUNDLE=/path/to/corporate-ca-bundle.crt
NODE_TLS_REJECT_UNAUTHORIZED=0  # Last resort only

# Socket path (Unix)
XDG_RUNTIME_DIR=/shorter/path/for/sockets

4. Monitoring & Diagnostics

  • Log Level: Set to debug for troubleshooting
    • mta-vscode-extension.logLevel: "debug"
  • Output Channel: View logs in VS Code Output panel
  • Server Logs: Check ${workspaceStorage}/kai-rpc-server/analyzer.log
  • Debug Archive: Use "MTA: Generate Debug Archive" command

Conclusion

The MTA extension has multiple potential failure points in enterprise environments, with the most common being:

  1. HTTP/2 blocking (fixed in recent release with configurable protocol)
  2. Named pipe restrictions on Windows (WDAC/AppLocker)
  3. Binary execution blocking (code signing, whitelisting)
  4. Corporate proxy/SSL inspection (partially mitigated with environment variables)

The extension has reasonable error handling and fallback mechanisms, but enterprise deployments should pre-test in the target environment and configure appropriately for local restrictions.

Analysis Metadata

  • Analysis Date: 2025-12-04
  • Extension Version: 8.0.0
  • Branch: release-8.0.3
  • Key Commit Referenced: d6bc675 (ECONNRESET fix)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment