Overview

The correlation engine identifies relationships between Configuration Items (CIs) from different source systems. While collectors discover CIs within their respective sources (Kubernetes, Proxmox, Netbox, Ceph, OpenStack, PostgreSQL), the correlation engine bridges these silos by discovering that a Netbox device "host-01" is the same physical machine running as Proxmox node "host-01" hosting Kubernetes worker "worker-node-01".

This cross-system visibility enables:

Infrastructure walkability across system boundaries
Impact analysis spanning multiple platforms
Unified asset inventory from fragmented sources
Automatic relationship creation with confidence scoring

Architecture

Loading diagram...

Key Concepts

Correlation Rules

Rules define how CIs from different sources should be matched. Each rule specifies:

Field	Description
`source_ci_type`	CI type to match from (e.g., `netbox.device`)
`target_ci_type`	CI type to match against (e.g., `proxmox.node`)
`match_criteria`	Conditions with attribute paths, match types, and weights
`base_confidence`	Starting confidence score (0.0-1.0)
`min_confidence_threshold`	Minimum score to create candidate
`relationship_type`	Relationship to create when confirmed

Correlation Candidates

Candidates are discovered matches awaiting review:

┌─────────────────────────────────────────────────────────────┐
│ Candidate: host-01 (netbox.device) → host-01 (proxmox.node)
├─────────────────────────────────────────────────────────────┤
│ Confidence: 0.92                                            │
│ Status: pending                                             │
│ Matched Factors: 3 of 4                                     │
│   ✓ Name match (fuzzy): 0.95                               │
│   ✓ Primary IP match: 1.00                                 │
│   ✓ Serial number match: 1.00                              │
│   ✗ MAC address: not found                                 │
└─────────────────────────────────────────────────────────────┘

Confidence Scoring

Confidence scores range from 0.0 to 1.0:

Range	Meaning	Action
0.95+	Virtual certainty	Auto-confirmed, relationship created
0.80-0.94	High confidence	Pending review, likely valid
0.70-0.79	Moderate confidence	Pending review, needs verification
Less than 0.70	Below threshold	Not created as candidate

Match Types Reference

Match Type	Description	Use Case
`exact`	Case-insensitive string equality	UUIDs, identifiers
`fuzzy`	Approximate string matching (similarity threshold: 0.8)	Names with variations
`ip_match`	IP address equality (strips CIDR)	Single IP comparison
`ip_in_list`	IP set intersection	Multiple interfaces
`numeric_exact`	Numeric equality	CPU cores, ports
`numeric_tolerance`	Within percentage tolerance	Memory, storage
`contains`	Substring match	UUIDs in compound strings
`match_constant`	Exact match against constant values	Type filtering
`fuzzy_constant`	Fuzzy match against constant values	Flexible type matching

User Workflow

Loading diagram...

API Reference

Rule Management

# List all rules
curl https://your-company.parascope.io/api/v1/correlations/rules

# Create a new rule
curl -X POST https://your-company.parascope.io/api/v1/correlations/rules \
  -H "Content-Type: application/json" \
  -d @rule.json

# Update a rule
curl -X PUT https://your-company.parascope.io/api/v1/correlations/rules/{rule_id} \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Delete a rule
curl -X DELETE https://your-company.parascope.io/api/v1/correlations/rules/{rule_id}

Rule Execution

# Dry-run (preview matches without creating candidates)
curl -X POST https://your-company.parascope.io/api/v1/correlations/rules/{rule_id}/run \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true}'

# Execute rule (create candidates and auto-confirm ≥0.95)
curl -X POST https://your-company.parascope.io/api/v1/correlations/rules/{rule_id}/run \
  -H "Content-Type: application/json" \
  -d '{"dry_run": false}'

Candidate Management

# List pending correlations
curl "https://your-company.parascope.io/api/v1/correlations?status=pending"

# Get correlations for a specific CI
curl "https://your-company.parascope.io/api/v1/correlations/ci/{uuid}"

# Confirm a correlation
curl -X POST https://your-company.parascope.io/api/v1/correlations/{candidate_id}/confirm

# Reject a correlation
curl -X POST https://your-company.parascope.io/api/v1/correlations/{candidate_id}/reject \
  -H "Content-Type: application/json" \
  -d '{"reason": "Different physical machines with same name"}'

Statistics

# Get correlation statistics
curl https://your-company.parascope.io/api/v1/correlations/stats

# Response:
{
  "total_correlations": 156,
  "pending_count": 23,
  "confirmed_count": 128,
  "rejected_count": 5,
  "by_source_type": {
    "netbox.device": 45,
    "kubernetes.node": 32
  },
  "avg_confidence": 0.87,
  "rules_active": 5,
  "rules_total": 7
}

Default Rules

Parascope seeds these default correlation rules:

Rule	Source → Target	Key Factors
Netbox Device → Proxmox Node	`netbox.device` → `proxmox.node`	Name, Serial, Primary IP
Netbox Device → K8s Node	`netbox.device` → `kubernetes.node`	Name, Interface IPs
Proxmox Node → K8s Node	`proxmox.node` → `kubernetes.node`	Name, IP address
Netbox Device → Ceph Host	`netbox.device` → `ceph.host`	Hostname
Proxmox VM → K8s Node	`proxmox.vm` → `kubernetes.node`	Name, IP, CPU, Memory

Frontend Pages

Page	URL	Purpose
Correlation Review	`/correlations`	Review and action pending candidates
Rule Management	`/settings/correlations`	Create, edit, test correlation rules
CI Correlations	`/configuration-items/{id}` (tab)	View correlations for specific CI

Best Practices

Rule Design

Start with high-confidence factors: Serial numbers, UUIDs, and MAC addresses are nearly unique and provide strong correlation signals.
Use multiple factors: A name match alone may be coincidental. Combining name + IP + hardware specs dramatically reduces false positives.
Weight appropriately:
- High weight (0.8-1.0): Unique identifiers (serial, MAC, IP)
- Medium weight (0.5-0.7): Names, hostnames
- Low weight (0.3-0.5): Hardware specs, capacity values
Set appropriate thresholds:
- Use 0.7 for moderate-confidence rules
- Use 0.8+ for stricter matching requirements

Operational Workflow

Create rules in disabled state and run dry-runs first
Review dry-run results before enabling
Monitor the /correlations page for pending reviews
Rejections persist to prevent re-discovery noise
Use the alignment bonus strategically by designing rules with multiple independent factors

API Reference - Correlation API endpoints
Architecture - System design overview

Cross-System Correlation Engine