Skip to main content

Platform Documentation

Learn how to use ClusterHawk for IP clustering and threat detection

Search Documentation

1
Submit IPs

Upload your IP addresses of interest through our secure interface. Our platform handles datasets up to 5000 addresses.

2
Analysis

Our deterministic ensemble pipeline analyzes patterns, identifies relationships, and generates threat intelligence automatically — same input, same clusters, same reasoning, every run.

3
Receive reports

Get comprehensive threat intelligence reports with IOCs, YARA rules, and hunting queries.

4
Execute hunting queries

Use our automated hunting query execution service to validate findings and monitor for new threats.

User Guide

Key Metrics


Understanding Key Metrics

Each type of analysis provides specialized metrics that help you assess the quality and reliability of results:

  • Cluster Quality Evaluation: Ratings like "Good," "Very Good," or "OK" indicate how well-defined and separated your clusters are. These are composite scores based on a proprietary evaluation framework.
    • "Very Good" (0.8-1.0): Highly cohesive clusters with clear separation between groups
    • "Good" (0.6-0.79): Well-formed clusters with distinct boundaries and minimal overlap
    • "OK" (0.4-0.59): Recognizable clusters with some overlap between groups
    Higher quality clusters generally represent more meaningful IP groupings and are more likely to identify distinct infrastructure patterns.
  • Consensus Confidence: The average per-host confidence inside a cluster (0-100%). It answers how good a fit the cluster's members are for it, and it rises when a cluster gets tighter. Splitting one broad group into several tighter ones raises this figure rather than lowering it, which is why it leads the Cluster Confidence view.
  • Content Purity: How much a cluster's members agree with one another across the data actually observed on them: the services they run, the certificates they present, and the fingerprints those services produce. A field the members consistently do not carry counts as agreement too, and the lists of shared signals name only what they do carry, so a cluster can score higher than its listed signals alone would suggest. Read the figure relative to the other clusters in the same run rather than as a mark out of a hundred, because it has no fixed scale; it is the spread between clusters in one run that separates a coherent device profile from a grouping whose members happen to sit near each other. Where the two figures diverge is worth a look in its own right. Methods agreeing while the content disagrees usually means the cluster was drawn on something narrower than a shared deployment, and content agreeing while the methods hesitate often points at a real profile the ensemble spread across more than one cluster. A cluster shown as not measured has too few hosts, or members carrying nothing comparable to match on, rather than one that scored low.
  • Separator Strength and Exclusivity: Two facts about what sets a cluster apart. The most discriminating signal is the one the pipeline ranked highest for this cluster, which is often a high-cardinality value like a certificate fingerprint that only part of the cluster carries. The most widely shared signal is the one present in the largest share of members, shown whenever it is a different signal. Each carries the value its members hold, the share of the cluster that holds it, and whether any other cluster is characterised by the same signal. A separator present in every member and found in no other cluster is the strongest evidence that the cluster is a real, distinct deployment rather than an artifact of where the boundaries fell.
  • Method Agreement (ARI/AMI): Several methods group your hosts independently, and the final assignment is a weighted consensus of them. ARI and AMI compare each method's own grouping with that final assignment, and the method weights show how much each one contributed. Read these as a record of how the ensemble decided, not as a quality score: a method that groups more coarsely than the final result scores low here even when the finer result is the better one. That is why they sit in a collapsed panel rather than in the headline.
  • Confidence Scores: In prediction results, these percentages (0-100%) indicate how certain the model is about each IP's cluster assignment:
    • 90%+: Extremely reliable predictions with minimal ambiguity
    • 70-89%: Strong predictions with good reliability
    • 50-69%: Moderate confidence, may warrant additional verification
    • <50%: Low confidence, suggesting potential edge cases or ambiguous patterns
    Higher confidence (>80%) suggests more reliable predictions, while lower scores may warrant additional investigation.
  • Prediction Kind (trust gate): Every prediction row carries a kind discriminator that is the primary signal a SOC / SOAR consumer should key on:
    • Confident (confident_match): Strong fingerprint match. The model is confident in the cluster attribution. Recommended actionable subset for correlation rules.
    • Ambiguous (diffuse) (ambiguous_diffuse): Top-1 leans, but probability mass is spread thin across many candidates. Treat the attribution with softer trust and review the candidate set.
    • Ambiguous (split) (ambiguous_split): Close two-way / few-way tie between candidates. Investigate the candidate set as a unit; the true match is likely one of them.
    • Out of distribution (out_of_distribution): No fingerprint match. The IP does not resemble any trained cluster. predicted_cluster and confidence are intentionally null on these rows; investigate via behavioral evidence rather than the cluster attribution.
    • No readable input (no_input_features): The scan record itself was empty — nothing answered, or everything that answered returned a blank banner — so confidence is intentionally null. Any score would describe the model's response to an empty input, not this host. predicted_cluster is kept (the host does group with the other input-less hosts). This is not the same as out_of_distribution and does not mean the host is quiet or low-risk: it may be running services outside the model's scope. Review the raw scan data directly.
    • Not covered by this model (no_covered_features): The opposite starting point, the same ending. The record does carry content, and none of it is in this model's feature space, so there was nothing for it to weigh and confidence is null while predicted_cluster is kept. What differs from an empty record is the cause, and that is the part you can act on: one says re-check the scan, this one says the model does not read what this host runs. A host answering on an industrial protocol lands here while carrying a product, a version and a banner.
    • Model has no opinion (model_uninformative): The model itself has no opinion about this host. It was built from too little data to tell its own clusters apart, so rather than name one it reports nothing: predicted_cluster and confidence are both null. These rows are re-labelled from out_of_distribution and keep that verdict's suppression unchanged; only the reason differs. It is the one kind that describes the model rather than the host or its record — out_of_distribution asserted that no known fingerprint fits, which a model that cannot discriminate is not in a position to claim. The address and its scan data are fine; a model trained on a larger dataset is what changes the result.
    • Not enriched (not_enriched): No scan record came back for the address, so it never reached the model. predicted_cluster is the -3 sentinel and confidence is null — there is nothing to key on. This is a gap in our data rather than a finding about the host; confirm the address is live and in scope, then re-run.
  • Candidates set: Each row carries the top-K candidate clusters above an entropy-aware confidence floor. For ambiguous rows iterate the set as a whole rather than relying on top-1 alone.
  • top1_minus_top2: The gap between the leading candidate and the runner-up. Large gaps mean a clean win; small gaps indicate ties and pair with ambiguous_split.
  • effective_n: exp(entropy) over the candidate distribution, interpretable as the "number of candidates worth of probability mass." Near 1.0 ⇒ confident, large values ⇒ diffuse hedging.
  • Feature Importance Rankings: Shows which characteristics most strongly define each cluster, with higher-ranked features having greater influence on cluster formation. This helps security analysts understand the primary attributes driving IP groupings.
  • ROC AUC (Receiver Operating Characteristic Area Under Curve): Measures discrimination ability across classification thresholds (0.5-1.0). 0.5 indicates no better than random guessing, 0.7-0.8 shows acceptable discrimination, 0.8-0.9 demonstrates excellent discrimination, and 0.9+ signals outstanding discrimination ability. This metric is particularly valuable for comparing different models' overall performance.
  • Log Loss: Measures prediction uncertainty by heavily penalizing confident but wrong predictions. Lower values indicate better calibrated probability estimates, which matters for risk assessment.
  • Class-specific Metrics: Performance measurements broken down by individual clusters show which types of IP groups the model handles well or poorly. This helps focus refinement efforts.
  • Actor Labels: User-generated rule-based identifiers that flag potential threat patterns based on learned cluster characteristics. They help analysts recognize and categorize suspicious activity quickly, without manual pattern matching.

These metrics form the basis for calculating precision, recall, F1 score, and other performance metrics:

  • Precision = TP / (TP + FP): The proportion of IPs assigned to a cluster that actually belong there. Higher precision means fewer false positives.
  • Recall = TP / (TP + FN): The proportion of IPs that actually belong to a cluster that were correctly assigned there. Higher recall means fewer false negatives.
  • F1 Score = 2 × (Precision × Recall) / (Precision + Recall): The harmonic mean of precision and recall, providing a balance between the two metrics.

In security analysis, these metrics have specific implications:

  • High precision ensures that IPs flagged as part of a potential threat cluster genuinely share characteristics, reducing false alarms.
  • High recall ensures that you capture most IPs belonging to a specific threat pattern, minimizing missed detections.
  • Balanced F1 score indicates a model that effectively identifies threat infrastructure without generating excessive false positives or missing critical indicators.