sica-fondt/knowledge/cyber-skills/skills/performing-cloud-native-forensics-with-falco/scripts/agent.py

#!/usr/bin/env python3
"""Agent for managing Falco rules and parsing alerts for container forensics."""

import json
import argparse
import os
from collections import defaultdict
from datetime import datetime
from pathlib import Path

import yaml
import requests


FALCO_RULES = [
    {
        "rule": "Shell Spawned in Container",
        "desc": "Detect shell process started in a container",
        "condition": "spawned_process and container and proc.name in (bash, sh, zsh, dash) "
                     "and not proc.pname in (docker-entrypo, supervisord, crond)",
        "output": "Shell spawned (user=%user.name command=%proc.cmdline "
                  "container=%container.name image=%container.image.repository)",
        "priority": "WARNING",
        "tags": ["container", "shell", "mitre_execution"],
    },
    {
        "rule": "Sensitive File Access in Container",
        "desc": "Detect read of sensitive files in container",
        "condition": "open_read and container and fd.name in (/etc/shadow, /etc/passwd, "
                     "/etc/sudoers) and not proc.name in (su, sudo, login)",
        "output": "Sensitive file read (file=%fd.name user=%user.name "
                  "container=%container.name)",
        "priority": "WARNING",
        "tags": ["container", "filesystem", "mitre_credential_access"],
    },
    {
        "rule": "Outbound Connection from Container",
        "desc": "Detect unexpected outbound network connections from containers",
        "condition": "evt.type=connect and fd.typechar=4 and fd.ip != 0.0.0.0 "
                     "and container and not fd.snet in (10.0.0.0/8, 172.16.0.0/12, "
                     "192.168.0.0/16)",
        "output": "Outbound connection (command=%proc.cmdline dest=%fd.name "
                  "container=%container.name)",
        "priority": "NOTICE",
        "tags": ["container", "network", "mitre_command_and_control"],
    },
    {
        "rule": "Privilege Escalation in Container",
        "desc": "Detect setuid/setgid calls in container",
        "condition": "evt.type in (setuid, setgid) and container "
                     "and not user.name=root",
        "output": "Privilege escalation attempt (user=%user.name command=%proc.cmdline "
                  "container=%container.name)",
        "priority": "CRITICAL",
        "tags": ["container", "privilege_escalation", "mitre_privilege_escalation"],
    },
    {
        "rule": "Container Escape Attempt via Mount",
        "desc": "Detect mount syscall in container indicating escape attempt",
        "condition": "evt.type=mount and container",
        "output": "Mount in container (user=%user.name command=%proc.cmdline "
                  "container=%container.name)",
        "priority": "CRITICAL",
        "tags": ["container", "escape", "mitre_privilege_escalation"],
    },
]


def generate_falco_rules(output_path, custom_rules=None):
    """Generate Falco rules YAML file."""
    rules = custom_rules or FALCO_RULES
    with open(output_path, "w") as f:
        yaml.dump(rules, f, default_flow_style=False, sort_keys=False)
    return len(rules)


def parse_falco_alerts(alert_file):
    """Parse Falco JSON alert output file."""
    alerts = []
    with open(alert_file) as f:
        for line in f:
            line = line.strip()
            if not line:
                continue
            try:
                alert = json.loads(line)
                alerts.append({
                    "time": alert.get("time", ""),
                    "rule": alert.get("rule", ""),
                    "priority": alert.get("priority", ""),
                    "output": alert.get("output", ""),
                    "output_fields": alert.get("output_fields", {}),
                    "source": alert.get("source", ""),
                    "tags": alert.get("tags", []),
                })
            except json.JSONDecodeError:
                continue
    return alerts


def summarize_alerts(alerts):
    """Generate alert summary statistics."""
    by_rule = defaultdict(int)
    by_priority = defaultdict(int)
    by_container = defaultdict(int)
    for alert in alerts:
        by_rule[alert["rule"]] += 1
        by_priority[alert["priority"]] += 1
        container = alert.get("output_fields", {}).get("container.name", "unknown")
        by_container[container] += 1
    return {
        "total_alerts": len(alerts),
        "by_rule": dict(by_rule),
        "by_priority": dict(by_priority),
        "by_container": dict(sorted(by_container.items(), key=lambda x: -x[1])[:20]),
    }


def check_falco_health(falco_url=None):
    falco_url = falco_url or os.environ.get("FALCO_URL", "http://localhost:8765")
    """Check Falco health via HTTP endpoint."""
    try:
        resp = requests.get(f"{falco_url}/healthz", timeout=5)
        return {"status": "healthy" if resp.status_code == 200 else "unhealthy",
                "code": resp.status_code}
    except requests.RequestException as e:
        return {"status": "unreachable", "error": str(e)}


def get_falco_version(falco_url=None):
    falco_url = falco_url or os.environ.get("FALCO_URL", "http://localhost:8765")
    """Get Falco version information."""
    try:
        resp = requests.get(f"{falco_url}/version", timeout=5)
        return resp.json()
    except requests.RequestException as e:
        return {"error": str(e)}


def correlate_alerts_with_k8s(alerts, suspicious_images=None):
    """Correlate Falco alerts with known suspicious container images."""
    if not suspicious_images:
        suspicious_images = []
    correlated = []
    for alert in alerts:
        fields = alert.get("output_fields", {})
        image = fields.get("container.image.repository", "")
        if any(s in image for s in suspicious_images):
            alert["correlation"] = "suspicious_image"
            correlated.append(alert)
        elif alert["priority"] in ("CRITICAL", "ERROR"):
            correlated.append(alert)
    return correlated


def main():
    parser = argparse.ArgumentParser(description="Falco Cloud Native Forensics Agent")
    parser.add_argument("--alert-file", help="Path to Falco JSON alert log")
    parser.add_argument("--rules-output", default="custom_falco_rules.yaml")
    parser.add_argument("--falco-url", default=os.environ.get("FALCO_URL", "http://localhost:8765"))
    parser.add_argument("--output", default="falco_report.json")
    parser.add_argument("--action", choices=[
        "generate_rules", "parse_alerts", "health", "full_analysis"
    ], default="full_analysis")
    args = parser.parse_args()

    report = {"generated_at": datetime.utcnow().isoformat(), "findings": {}}

    if args.action in ("generate_rules", "full_analysis"):
        count = generate_falco_rules(args.rules_output)
        report["findings"]["rules_generated"] = count
        print(f"[+] Generated {count} Falco rules to {args.rules_output}")

    if args.action in ("parse_alerts", "full_analysis") and args.alert_file:
        alerts = parse_falco_alerts(args.alert_file)
        summary = summarize_alerts(alerts)
        report["findings"]["alert_summary"] = summary
        report["findings"]["critical_alerts"] = [
            a for a in alerts if a["priority"] in ("CRITICAL", "ERROR")
        ]
        print(f"[+] Parsed {summary['total_alerts']} alerts")
        print(f"    Critical: {summary['by_priority'].get('CRITICAL', 0)}")

    if args.action in ("health", "full_analysis"):
        health = check_falco_health(args.falco_url)
        report["findings"]["falco_health"] = health
        print(f"[+] Falco health: {health['status']}")

    with open(args.output, "w") as f:
        json.dump(report, f, indent=2, default=str)
    print(f"[+] Report saved to {args.output}")


if __name__ == "__main__":
    main()