network-forensics

Purpose

This skill enables the AI to investigate network traffic patterns, identify anomalies, and mitigate threats by analyzing packet captures, logs, and real-time data. It focuses on detecting intrusions, malware communications, and unauthorized access.

When to Use

Use this skill during security incidents, routine monitoring, or compliance audits. Apply it when network logs show unusual traffic spikes, unknown IP connections, or potential DDoS attacks. Ideal for blue-team operations in environments with high network activity, such as corporate networks or cloud infrastructures.

Key Capabilities

• Parse PCAP files to extract metadata like source/destination IPs, ports, and protocols.
• Detect anomalies using rulesets, e.g., identifying SYN floods or unusual port scans.
• Generate reports in JSON or CSV format for threat intelligence.
• Integrate with tools like tcpdump for live capture or Zeek for advanced protocol analysis.
• Support real-time monitoring via API hooks to flag threats immediately.

Usage Patterns

To use this skill, first authenticate with an API key via environment variable (e.g., $NETWORK_FORENSICS_API_KEY). Invoke it programmatically in Python scripts or via CLI for analysis tasks. For file-based analysis, provide a PCAP file; for live monitoring, specify a network interface. Always wrap calls in error-handling blocks to manage failures. Chain with other blue-team skills for automated workflows, like feeding results to an intrusion detection system.

Common Commands/API

Use the following CLI commands or API endpoints for core operations:

• CLI: Analyze a PCAP file: openclaw network-forensics analyze --file path/to/capture.pcap --output report.json
• CLI: Monitor live traffic: openclaw network-forensics monitor --interface eth0 --duration 300 --alert-level high
• API Endpoint: POST to /api/network/analyze with JSON body: {"file": "base64_encoded_pcap", "rules": ["syn_flood", "port_scan"]}. Set header: Authorization: Bearer $NETWORK_FORENSICS_API_KEY
• API Endpoint: GET from /api/network/status to check ongoing sessions: Response includes active alerts in JSON format.
• Code Snippet (Python):

  import requests
  api_key = os.environ.get('NETWORK_FORENSICS_API_KEY')
  response = requests.post('https://api.openclaw.com/api/network/analyze', headers={'Authorization': f'Bearer {api_key}'}, json={'file': 'capture.pcap'})
  print(response.json()['threats'])

• Config Format: Use YAML for rulesets, e.g.:

  rules:
    - name: syn_flood
      threshold: 1000 packets/sec
    - name: port_scan
      ports: [80, 443, 22]

Integration Notes

Integrate this skill with other tools by exporting results to SIEM systems like Splunk or ELK Stack. For authentication, always use $NETWORK_FORENSICS_API_KEY in environment variables. In code, handle dependencies like installing scapy for PCAP processing: pip install scapy. To combine with other OpenClaw skills, use the SDK: e.g., call network-forensics output as input to intrusion-detection. Ensure network interfaces are configured for capture, e.g., via sudo setcap cap_net_raw+ep /path/to/openclaw binary. Test integrations in a sandbox environment to avoid production disruptions.

Error Handling

Always check for common errors like invalid PCAP files, network timeouts, or authentication failures. In CLI, errors return exit codes (e.g., 1 for file not found). In API calls, parse HTTP status codes: 401 for unauthorized (check $NETWORK_FORENSICS_API_KEY), 400 for bad requests. Use try-except in code snippets:

try:
    response = requests.post('https://api.openclaw.com/api/network/analyze', ...)
    response.raise_for_status()
except requests.exceptions.HTTPError as err:
    print(f"Error: {err} - Verify API key and input format")
except Exception as e:
    print(f"Unexpected error: {e} - Retry with debug flag")

Log errors with timestamps and retry transient issues up to 3 times. For CLI, add --debug flag to output detailed traces.

Concrete Usage Examples

1. Analyze a captured PCAP file for threats: Suppose you have a file suspicious.pcap from a potential breach. Run: openclaw network-forensics analyze --file suspicious.pcap --rules syn_flood. This outputs a JSON report with detected threats. In code: Use the API to process it and alert if threats > 5, then integrate with email notification.

2. Monitor live traffic for intrusions: On a server with interface eth0, execute: openclaw network-forensics monitor --interface eth0 --duration 600 --alert-level medium. This captures packets for 10 minutes and flags anomalies like port scans. Script it in a loop for continuous monitoring, e.g., in a cron job, and pipe results to a database for long-term analysis.

Graph Relationships

• Related to: "intrusion-detection" (shares threat detection logic)
• Depends on: "log-analysis" (for correlating network logs)
• Complements: "endpoint-security" (for holistic blue-team defense)
• Clusters with: "blue-team" skills like "vulnerability-scanning"