Cross-System Correlation Engine

OverviewCopy Anchor Link

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

ArchitectureCopy Anchor Link

Key ConceptsCopy Anchor Link

Correlation RulesCopy Anchor Link

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

Conditions or booster paths that reference raw_data (for example raw_data.arp_observed_ips) require the raw_data:read permission to create or change. Existing rules keep running, and editing a rule without changing its conditions or boosters, such as renaming it, needs no extra permission.

Conditions and booster paths cannot reach a CI's change history. A path such as changes, changes.new_values, or one that walks back onto a CI (source_relationships[*].target_ci.changes) is rejected when the rule is saved, whatever your permissions: anyone who can read correlations sees a candidate's matched values, and change history has its own permission.

Correlation CandidatesCopy Anchor Link

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
    [x] Name match (fuzzy):  0.95
    [x] Primary IP match:    1.00
    [x] Serial number match: 1.00
    [ ] MAC address:         not found

Confidence ScoringCopy Anchor Link

Confidence scores range from 0.0 to 1.0:

Auto-Confirm Requires Strong EvidenceCopy Anchor Link

A high score alone does not auto-confirm a candidate. Auto-confirmation also requires at least one strong factor, an exact identifier match such as an IP address (ip_match / ip_in_list), serial number, MAC address, or UUID-class identifier matched exactly.

Name-derived fields (name, hostname, FQDN) never count as strong evidence, and matching name-family factors that derive from the same string (for example web01 and web01.example.com) count as a single factor when scoring. Candidates that score 0.95+ without a strong factor are still created and suggested, but stay pending so you can review and confirm them manually.

When a Candidate No Longer MatchesCopy Anchor Link

Each rule run, except a dry run, re-scores the pending and confirmed candidates it reaches and records when it did, shown as Last evaluated on the Correlation Review page and on a CI's Correlations tab. Rejected candidates are not re-scored. If a pending or confirmed candidate now scores below its rule's threshold (say a host released the IP address the match relied on, or a manual boost expired), it keeps its status and shows a No longer matches badge with the current score. The run does not reject the candidate or remove a confirmed relationship; that decision stays with you. A candidate the run did not reach, for example because one of its CIs is no longer active, keeps its previous score and evaluation time.

Match Types ReferenceCopy Anchor Link

User WorkflowCopy Anchor Link

API ReferenceCopy Anchor Link

Rule ManagementCopy Anchor Link

# 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 ExecutionCopy Anchor Link

# 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; auto-confirm needs ≥0.95 + a strong factor)
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 ManagementCopy Anchor Link

# 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"}'

StatisticsCopy Anchor Link

# 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 RulesCopy Anchor Link

Parascope seeds these default correlation rules:

Frontend PagesCopy Anchor Link

Best PracticesCopy Anchor Link

Rule DesignCopy Anchor Link

1. Start with high-confidence factors: Serial numbers, UUIDs, and MAC addresses are nearly unique and provide strong correlation signals.

2. Use multiple factors: A name match alone may be coincidental. Combining name + IP + hardware specs dramatically reduces false positives.

3. 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

4. Set appropriate thresholds:

   • Use 0.7 for moderate-confidence rules
   • Use 0.8+ for stricter matching requirements

Operational WorkflowCopy Anchor Link

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

Related DocumentationCopy Anchor Link

• API Reference - Correlation API endpoints
• Architecture - System design overview