Skip to main content

CI Relationship System Documentation

Overview​

The CI Relationship System in Tripl-i v3 provides intelligent mapping of network connections between Configuration Items (CIs) to automatically discover and maintain service dependencies. The system uses a bidirectional relationship architecture that ensures data consistency and accurate direction determination.

Core Concepts​

Bidirectional Relationships​

Unlike traditional systems that create separate relationship records from each CI's perspective, Tripl-i uses a single relationship object for each connection pair. This approach:

  • Prevents duplicate relationships between the same CIs
  • Maintains consistency across multiple scans
  • Reduces data redundancy in the CMDB
  • Provides dual perspectives through sourceView and targetView attributes

Direction Determination​

The system uses a hierarchical approach to determine the correct direction of relationships:

  1. ListeningService Registry (Highest Priority)
  2. Connection State Analysis (LISTEN state)
  3. Well-Known Port Detection
  4. Port Range Classification (Ephemeral vs Registered)
  5. Deterministic Fallback (Lower port number)
  6. Alphabetical Ordering (Last resort)

Architecture​

Data Model​

Each CI Relationship tracks the following information:

Connection Identification:

  • Source CI and target CI (or unknown device identifiers)
  • Relationship type (typically "Connected To")
  • Connection protocol (TCP/UDP)

Source Perspective:

  • Process name and ID initiating the connection
  • Local and remote ports used
  • Connection count and last update time

Target Perspective:

  • Process receiving the connection
  • Process ID
  • Local and remote ports
  • Connection count and metadata

Direction Determination:

  • Confidence level (high/medium/low/guess)
  • Explanation of why the direction was determined
  • Whether the connection is bidirectional
  • Which CI last updated the relationship

Processing Flow​

Direction Determination Algorithm​

1. ListeningService Check​

The system first checks if either port is registered as a listening service. For example, if a custom SQL Server instance is configured to listen on port 1440 or 1488, those ports are registered in the system.

Result: CI with listening port becomes the target (receiver)

2. Connection State Analysis​

For connections with state information:

  • State = 2 (LISTEN): CI is the target
  • State = 5 (ESTABLISHED): Further analysis needed
  • State = 11 (TIME_WAIT): CI was likely the source

3. Well-Known Ports​

Common service ports indicate the server side. These include:

  • Port 21 (FTP)
  • Port 22 (SSH)
  • Port 80 (HTTP)
  • Port 443 (HTTPS)
  • Port 1433 (SQL Server)
  • Port 1521 (Oracle)
  • Port 3306 (MySQL)
  • Port 5432 (PostgreSQL)
  • And many others

Result: CI with well-known port becomes the target

4. Port Range Classification​

  • Registered Ports (1024-49151): Likely services
  • Ephemeral Ports (49152-65535): Client connections

Example:

  • CI1 using port 50123 (ephemeral) → CI2 using port 8080 (registered)
  • Direction: CI1 is source, CI2 is target

5. Non-Listener Connections​

For peer-to-peer or RPC connections where neither side is listening, the system applies fallback rules. For example:

  • Two CIs connecting via ports 48765 and 49123 (both ephemeral)
  • No listening service detected on either side
  • System assumes the lower port number (48765) represents the service
  • Direction is determined as: CI with port 49123 is source, CI with port 48765 is target
  • Confidence is marked as "low" or "guess"

Implementation Details​

Key Functions​

Direction Determination Function​

The system uses a main function that analyzes two CIs and their connection data to implement the hierarchical direction determination rules.

Information Analyzed:

  • First CI object and its connection data
  • Second CI object (if known) and its connection data
  • Tenant ID for service lookup

Output Provided:

  • Identified source CI
  • Identified target CI
  • Confidence level (high, medium, low, or guess)
  • Explanation of why the direction was determined
  • Indication if the connection is bidirectional

findOrCreateRelationship(sourceCI, targetCI, type, identifier)​

Finds existing relationship or creates new one, ensuring single record per connection pair.

Key Logic:

  • Searches for relationship in both directions
  • Corrects direction if existing relationship is reversed
  • Handles unknown devices with identifiers

updateRelationshipView(relationship, scanningCI, connectionData, isSource, appInfo)​

Updates the appropriate view (sourceView or targetView) based on scanning CI's role.

Features:

  • Aggregates multiple connections to same endpoint
  • Preserves historical data (ports, processes)
  • Maintains connection counts
  • Stores recent connection details (last 100)
  • Enriches with application information
  • Adds software family metadata

Connection History: The system maintains a history of up to 100 recent connections for each relationship. Each connection record captures:

  • Local and remote addresses
  • Local and remote ports used
  • Protocol (TCP/UDP)
  • Connection state
  • Process name and ID
  • Timestamp of the connection

Unknown Device Handling​

When a remote CI cannot be found, the system creates an unknown device entry with the IP address and port information. This allows tracking connections to:

  • External services
  • Unscanned devices
  • Temporary connections
  • Cloud services

Real-World Scenarios​

Scenario 1: Database Connection​

Application Server (KTPRDISOMS) → Database Server (KCTSDB01)
Port 52456 → Port 1440 (SQL Server)

Analysis:
1. Port 1440 found in ListeningService
2. KCTSDB01 identified as target
3. Relationship: KTPRDISOMS (source) → KCTSDB01 (target)
4. Confidence: high

Scenario 2: Web Service​

Load Balancer → Web Server
Port 54321 → Port 443 (HTTPS)

Analysis:
1. Port 443 is well-known HTTPS port
2. Web Server identified as target
3. Relationship: Load Balancer (source) → Web Server (target)
4. Confidence: high

Scenario 3: RPC/Peer Connection​

Service A ↔ Service B
Port 45123 ↔ Port 45678 (both RPC)

Analysis:
1. No listening service detected
2. Both ports in registered range
3. Lower port (45123) assumed as service
4. Relationship: Service B (source) → Service A (target)
5. Confidence: guess
6. Marked as bidirectional

Scenario 4: Unknown External Service​

Internal Server → External API
Port 53421 → 34.102.136.180:443

Analysis:
1. External IP not in CMDB
2. Port 443 indicates HTTPS service
3. Creates UnknownDevice target
4. Relationship: Internal Server (source) → Unknown:34.102.136.180:443 (target)
5. Confidence: medium

Configuration​

ListeningService Management​

Add custom service ports for accurate direction detection. You can register listening services that your organization uses (such as custom applications listening on specific ports). This helps the system correctly identify which CI is the server and which is the client in each connection.

Relationship Type Configuration​

The system uses "Connected To" relationship type by default to represent network connections between CIs. This is categorized as a Dependency relationship type in the system.

Troubleshooting​

Common Issues​

1. Incorrect Relationship Direction​

Symptom: Database showing as source instead of target

Solution:

  • Verify port is in ListeningService registry
  • Check connection state values
  • Review confidence level in relationship attributes

2. Duplicate Relationships​

Symptom: Multiple relationships between same CIs

Solution:

  • Run cleanup script to merge duplicates
  • Verify both CIs update same relationship object
  • Check tenant isolation isn't creating separate records

3. Unknown Device Proliferation​

Symptom: Many UnknownDevice entries

Solution:

  • Ensure network discovery covers all devices
  • Check IP resolution in ServerNetworkAdapter
  • Verify tenant boundaries aren't blocking CI discovery

Debugging​

When investigating relationship direction issues:

  1. Check the relationship attributes for the direction reasoning
  2. Review the confidence level (high/medium/low/guess)
  3. Verify that custom services are registered correctly if the direction seems incorrect

Migration from Previous Version​

Identifying Duplicates​

The system has tools to identify duplicate relationships between the same pair of CIs. When duplicates are found, they appear as multiple relationship records between the same source and target.

Cleanup Process​

When duplicates are identified, the system can merge the views from multiple duplicate relationships into a single relationship record, then remove the duplicate entries. This consolidation process helps maintain data integrity and prevents relationship inconsistencies.

Best Practices​

1. Service Registration​

Always register custom service ports in ListeningService:

  • Improves direction accuracy
  • Reduces "guess" confidence relationships
  • Helps with service discovery

2. Scan Frequency​

Regular scanning ensures:

  • Both sides update relationship views
  • Connection state changes are captured
  • Unknown devices get identified when scanned

3. Tenant Isolation​

Maintain proper tenant boundaries:

  • Services should be in same tenant as their dependencies
  • Cross-tenant relationships need special handling
  • Global services can use null tenant

4. Performance Optimization​

Caching Strategy​

Port Cache:

  • Well-known ports are cached with a 5-minute refresh interval
  • Cache entries are tenant-specific
  • Reduces repeated ListeningService lookups

Application Cache:

  • In-memory caching is recommended for frequent lookups
  • 10-minute cache refresh interval balances performance with freshness

Processing Optimizations​

  1. Skip Rule Processing: The system can bypass unnecessary post-save hooks for relationships that don't need additional processing.

  2. Connection Aggregation:

    • Groups by remote address
    • Finds most common port combinations
    • Reduces duplicate processing

  3. Batch Operations:

    • Process multiple CIs in parallel
    • Use MongoDB bulk operations for cleanup

  4. Query Optimization: The system uses database indexes on source/target pairs, service ports, and listening service configurations to optimize relationship queries and lookups.

Statistics and Monitoring​

The system tracks relationship processing metrics including:

  • Number of relationships created and updated
  • Unknown devices created and updated
  • Processing errors
  • Duplicates found and merged
  • Skipped connections

Use these metrics to:

  • Monitor processing efficiency
  • Identify data quality issues
  • Track unknown device discovery
  • Measure deduplication effectiveness

Viewing Relationships​

You can view CI relationships through the web interface:

Relationship Queries:

  • View all relationships for a specific CI
  • Filter relationships by direction (source or target)
  • Filter by confidence level (high, medium, low, guess)

Relationship Information: Each relationship displays:

  • Source and target CIs
  • Connection type
  • Service ports involved
  • Protocol used
  • Confidence level and direction reasoning
  • Source perspective (local and remote ports, connection count)
  • Target perspective (local and remote ports, connection count)

Future Enhancements​

Planned Features​

  1. Machine Learning Direction Detection

    • Train model on confirmed relationships
    • Improve accuracy for ambiguous connections
    • Pattern recognition for complex services

  2. Service Discovery Enhancement

    • Automatic service type detection
    • Protocol analysis beyond port numbers
    • Application fingerprinting

  3. Relationship Lifecycle Management

    • Automatic cleanup of stale relationships
    • Historical relationship tracking
    • Change impact analysis

  4. Cross-Tenant Relationships

    • Secure cross-tenant dependency mapping
    • Service provider/consumer models
    • Multi-tenant service catalogs