Platform Documentation

Configuration options control how ClusterHawk analyzes and clusters IP addresses. These configurations can be accessed and modified in the Configurations tab of your Workspace.

Labeling rules help identify and categorize IP addresses based on specific patterns:

• Purpose: Automatically apply labels to IPs matching specific criteria
• Structure: Each rule consists of a name and conditions (with AND/OR logic)
• Usage: Enable labeling when submitting a job and select which rules to apply

You can create custom labeling rules in the Configurations tab:

1. Click the "Add Rule" button to open the rule editor
2. Provide a descriptive name for your rule (e.g., "Actor X", "SSH Infrastructure")
3. Add conditions using the following structure:
   • Condition Groups: Top-level containers joined by AND logic
   • Simple Conditions: Direct text patterns to match (e.g., "nginx", "dropbear")
   • Nested Conditions: Sets of related conditions joined by AND/OR logic
4. Click "Save Rule" when finished

Or a rule to identify SSH infrastructure might look like:

When creating rules, remember:

• Text-based matching: Rules match against text strings found in the IP data
• Focus on IOCs and TTPs: Use specific indicators of compromise or attack techniques rather than generic identifiers like port numbers
• Match actual values: Only the values in the data are searched
• Consider variations: Include common variations of service names and descriptions
• Case insensitivity: Matches are case-insensitive, so "ssh" will match "SSH"

For more accurate threat actor identification, use:

• Specific malware: "Cobalt Strike", "BianLian", "njRAT"
• Attack patterns: "CVE-2023-1234", "XSS", "SQL injection", "bruteforce"
• Unique identifiers: Specific certificate details, unusual protocol configurations, distinctive headers
• Infrastructure indicators: Specific server configurations, backend technologies, or obfuscation techniques

Avoid relying on common ports or generic services, as these can lead to false positives. For instance, searching for "443" alone might match both legitimate HTTPS servers and malicious C2 infrastructure.

After creation, you can:

• Edit: Modify existing rules by clicking the edit icon
• Delete: Remove rules that are no longer needed
• Select for Jobs: When submitting a clustering job, enable labeling and choose which rules to apply

Clustering weights allow you to fine-tune how different features contribute to the similarity calculations between IP addresses. By adjusting these weights, you can emphasize or de-emphasize certain characteristics during the clustering process:

• Feature Weights: Each feature can be assigned a weight from 0 to 10:
  • Vulnerability: Weight for vulnerability information detected in services
  • Certificate: Weight for TLS/SSL certificate characteristics
  • JA3 Fingerprint: Weight for JA3 TLS client fingerprints
  • JARM Fingerprint: Weight for JARM TLS server fingerprints
  • Hash: Weight for cryptographic hash values
  • Hostname: Weight for server hostname information
  • Domain: Weight for domain name information
  • Algorithms: Weight for cryptographic algorithms used
  • Product: Weight for product and version information
  • HTML fields: Weight for HTML structure fields
  • Redirects: Weight for HTTP redirect patterns
  • Tags: Weight for associated tags
  • Chain: Weight for certificate chain relationships

Weight adjustment guidelines:

• Default Value (1.0): All features start with a balanced weight of 1.0
• Higher Values (2.0+): Increase a feature's importance in similarity calculations
• Lower Values (0.1-0.9): Decrease a feature's importance
• Zero (0): Completely ignore a feature in calculations

When running predictions, the system uses feature weights in the following priority order:

1. Model Creation Weights: By default, prediction uses the same weights that were used when the model was created (stored internally with the model)
2. User-Configured Weights: If no weights were specified during model creation, the system uses the weights configured in the Configurations tab
3. Default Weights: If neither of the above are available, the system falls back to default weights

This ensures consistent results between model training and prediction while still allowing customization when needed.

Example use cases for weight adjustments:

• SSL/TLS Focus: Increase weights for cert, ja3, jarm, chain, and algorithms to focus on cryptographic characteristics
• Web Content Focus: Increase weights for html, data, and redirects to emphasize web content patterns
• Threat Detection: Increase weights for vuln and product to prioritize known vulnerabilities and specific software versions

Adjusting these configurations can significantly impact analysis results:

• Lower Weights: De-emphasize a feature so it contributes less to how hosts are grouped together
• Higher Weights: Emphasize a feature so similarities in it pull hosts into the same cluster more strongly
• Weight Adjustments: Emphasize certain characteristics (e.g., increasing TLS weight focuses on encryption patterns)

Important notes about saving and managing your configurations:

• Saved Configurations: Apply to all future jobs unless specifically overridden
• Save Limitations: Configuration saves are rate-limited to prevent accidental changes
• Restore Defaults: You can revert to default configurations using the "Restore Defaults" button, but not to your previous configurations
• Import/Export: Save your custom configurations and share them across different environments or team members