examples/basic_usage.py

#!/usr/bin/env python3
"""
C2Sentinel Basic Usage Example

Demonstrates loading the model and analyzing network connections
for C2 beacon detection.
"""

from c2sentinel import C2Sentinel

def main():
    # Load the model
    sentinel = C2Sentinel.load('c2_sentinel')

    # Example 1: Analyze a series of connections to a single destination
    # This pattern shows regular 60-second intervals with consistent packet sizes
    # - a common C2 beacon signature

    connections = []
    timestamp = 1705600000  # Starting timestamp

    for i in range(10):
        connections.append({
            'timestamp': timestamp + (i * 60),  # 60-second intervals
            'dst_ip': '10.0.0.100',
            'dst_port': 443,
            'bytes_sent': 200,
            'bytes_recv': 500,
        })

    result = sentinel.analyze(connections)

    print("Example 1: Regular beacon pattern")
    print(f"  Is C2: {result.is_c2}")
    print(f"  Probability: {result.c2_probability:.2f}")
    print(f"  C2 Type: {result.c2_type}")
    print(f"  Detection Method: {result.detection_method}")
    print()

    # Example 2: Legitimate SSH keepalive traffic
    # Small symmetric packets on port 22 at regular intervals

    ssh_connections = []
    timestamp = 1705600000

    for i in range(10):
        ssh_connections.append({
            'timestamp': timestamp + (i * 30),  # 30-second keepalive
            'dst_ip': '192.168.1.50',
            'dst_port': 22,
            'bytes_sent': 48,
            'bytes_recv': 48,
        })

    result = sentinel.analyze(ssh_connections)

    print("Example 2: SSH keepalive pattern")
    print(f"  Is C2: {result.is_c2}")
    print(f"  Matched Pattern: {result.matched_legitimate_pattern}")
    print(f"  Service Type: {result.service_type}")
    print()

    # Example 3: High-confidence C2 on known malicious port

    c2_connections = []
    timestamp = 1705600000

    for i in range(10):
        c2_connections.append({
            'timestamp': timestamp + (i * 30),
            'dst_ip': '45.33.32.156',
            'dst_port': 4444,  # Metasploit default
            'bytes_sent': 150,
            'bytes_recv': 300,
        })

    result = sentinel.analyze(c2_connections)

    print("Example 3: High-confidence C2 port")
    print(f"  Is C2: {result.is_c2}")
    print(f"  C2 Type: {result.c2_type}")
    print(f"  Probability: {result.c2_probability:.2f}")
    print(f"  Immediate Detection: {result.immediate_detection}")
    print(f"  Risk Factors: {result.risk_factors}")
    print()

    # Example 4: Using threshold adjustment

    print("Example 4: Threshold adjustment")

    # Lower threshold for higher sensitivity
    result_low = sentinel.analyze(connections, threshold=0.3)
    print(f"  Low threshold (0.3): is_c2={result_low.is_c2}, prob={result_low.c2_probability:.2f}")

    # Higher threshold for higher precision
    result_high = sentinel.analyze(connections, threshold=0.7)
    print(f"  High threshold (0.7): is_c2={result_high.is_c2}, prob={result_high.c2_probability:.2f}")

    # Strict mode (minimum 0.7 threshold)
    result_strict = sentinel.analyze(connections, strict_mode=True)
    print(f"  Strict mode: is_c2={result_strict.is_c2}, prob={result_strict.c2_probability:.2f}")


if __name__ == '__main__':
    main()