npx skills add mukul975/Anthropic-Cybersecurity-SkillsMITRE ATT&CK
Overview
Scapy is a Python packet manipulation library that enables crafting, sending, sniffing, and dissecting network packets at granular protocol layers. This skill covers using Scapy for security-relevant tasks including TCP/UDP/ICMP packet crafting, pcap file analysis, protocol field extraction, SYN scan implementation, DNS query analysis, and detecting anomalous traffic patterns such as unusually fragmented packets or malformed headers.
When to Use
- When investigating security incidents that require analyzing network packets with scapy
- When building detection rules or threat hunting queries for this domain
- When SOC analysts need structured procedures for this analysis type
- When validating security monitoring coverage for related attack techniques
Prerequisites
- Python 3.8+ with
scapylibrary installed (pip install scapy) - Root/administrator privileges for raw socket operations (sniffing, sending)
- Npcap (Windows) or libpcap (Linux) for packet capture
- Authorization to perform packet operations on target network
Steps
- Read and parse pcap/pcapng files with
rdpcap()for offline analysis - Extract protocol layers (IP, TCP, UDP, DNS, HTTP) and field values
- Compute traffic statistics: top talkers, protocol distribution, port frequency
- Detect SYN flood patterns by analyzing TCP flag ratios
- Identify DNS exfiltration indicators via query length and entropy analysis
- Craft custom probe packets for authorized network testing
- Export findings as structured JSON report
Expected Output
JSON report containing packet statistics, protocol distribution, top source/destination IPs, detected anomalies (SYN floods, DNS tunneling indicators, fragmentation attacks), and per-flow summaries.
References and resources
Everything below is rendered for inspection. Script files are read-only and never run.
References 1
api-reference.md2.1 KB
Scapy Network Packet Analysis API Reference
Core Scapy Functions
Reading Packets
from scapy.all import rdpcap, sniff, wrpcap
# Read pcap file
packets = rdpcap("capture.pcap")
# Live sniff with BPF filter (requires root)
packets = sniff(filter="tcp port 80", count=100, iface="eth0")
# Write packets to pcap
wrpcap("output.pcap", packets)Packet Layer Access
from scapy.all import IP, TCP, UDP, DNS, DNSQR, ICMP
pkt = packets[0]
pkt.haslayer(IP) # Check if layer exists
pkt[IP].src # Source IP
pkt[IP].dst # Destination IP
pkt[TCP].sport # Source port
pkt[TCP].dport # Destination port
pkt[TCP].flags # TCP flags: S, SA, A, FA, R, PA
pkt[DNS].qd.qname # DNS query name
pkt[ICMP].type # ICMP type (8=echo request, 0=echo reply)Packet Crafting
from scapy.all import IP, TCP, sr1, send
# SYN probe (authorized testing only)
syn = IP(dst="192.168.1.1") / TCP(dport=80, flags="S")
response = sr1(syn, timeout=2, verbose=0)
# ICMP ping
ping = IP(dst="192.168.1.1") / ICMP()
send(ping, verbose=0)
# Custom DNS query
dns = IP(dst="8.8.8.8") / UDP(dport=53) / DNS(rd=1, qd=DNSQR(qname="example.com"))Protocol Fields Reference
TCP Flags
| Flag | Value | Meaning |
|---|---|---|
| S | 0x02 | SYN |
| SA | 0x12 | SYN-ACK |
| A | 0x10 | ACK |
| F | 0x01 | FIN |
| R | 0x04 | RST |
| P | 0x08 | PSH |
ICMP Types
| Type | Meaning |
|---|---|
| 0 | Echo Reply |
| 3 | Destination Unreachable |
| 8 | Echo Request |
| 11 | Time Exceeded |
BPF Filter Syntax
tcp port 443 # TCP traffic on port 443
host 10.0.0.1 # All traffic to/from IP
src net 192.168.0.0/24 # Source from subnet
udp and port 53 # DNS traffic
tcp[tcpflags] & tcp-syn != 0 # SYN packets onlyCLI Usage
# Analyze pcap file for anomalies
python agent.py --pcap capture.pcap --output report.json
# Custom thresholds
python agent.py --pcap traffic.pcapng --syn-threshold 50 --dns-length 30
# Port scan detection sensitivity
python agent.py --pcap scan.pcap --scan-threshold 10Scripts 1
agent.py6.7 KB
#!/usr/bin/env python3
"""Network packet analysis agent using Scapy for pcap parsing and anomaly detection."""
import json
import math
import argparse
from collections import defaultdict, Counter
from datetime import datetime
from scapy.all import rdpcap, IP, TCP, UDP, DNS, DNSQR, ICMP
def load_pcap(filepath):
"""Load packets from a pcap/pcapng file."""
packets = rdpcap(filepath)
print(f"[+] Loaded {len(packets)} packets from {filepath}")
return packets
def extract_packet_info(packets):
"""Extract structured info from each packet with IP layer."""
records = []
for pkt in packets:
if not pkt.haslayer(IP):
continue
info = {
"src_ip": pkt[IP].src,
"dst_ip": pkt[IP].dst,
"proto": pkt[IP].proto,
"ttl": pkt[IP].ttl,
"length": len(pkt),
"flags": str(pkt[IP].flags),
"timestamp": float(pkt.time),
}
if pkt.haslayer(TCP):
info["src_port"] = pkt[TCP].sport
info["dst_port"] = pkt[TCP].dport
info["tcp_flags"] = str(pkt[TCP].flags)
info["protocol"] = "TCP"
elif pkt.haslayer(UDP):
info["src_port"] = pkt[UDP].sport
info["dst_port"] = pkt[UDP].dport
info["protocol"] = "UDP"
elif pkt.haslayer(ICMP):
info["icmp_type"] = pkt[ICMP].type
info["icmp_code"] = pkt[ICMP].code
info["protocol"] = "ICMP"
else:
info["protocol"] = str(pkt[IP].proto)
if pkt.haslayer(DNS) and pkt.haslayer(DNSQR):
info["dns_query"] = pkt[DNSQR].qname.decode("utf-8", errors="ignore").rstrip(".")
info["dns_type"] = pkt[DNSQR].qtype
records.append(info)
return records
def compute_traffic_stats(records):
"""Compute overall traffic statistics."""
src_ips = Counter(r["src_ip"] for r in records)
dst_ips = Counter(r["dst_ip"] for r in records)
protocols = Counter(r["protocol"] for r in records)
dst_ports = Counter(r.get("dst_port", 0) for r in records if r.get("dst_port"))
total_bytes = sum(r["length"] for r in records)
return {
"total_packets": len(records),
"total_bytes": total_bytes,
"unique_src_ips": len(src_ips),
"unique_dst_ips": len(dst_ips),
"top_src_ips": src_ips.most_common(10),
"top_dst_ips": dst_ips.most_common(10),
"protocol_distribution": dict(protocols),
"top_dst_ports": dst_ports.most_common(10),
}
def detect_syn_flood(records, threshold=100):
"""Detect SYN flood by counting SYN-only packets per destination IP."""
syn_counts = defaultdict(int)
synack_counts = defaultdict(int)
for r in records:
if r.get("tcp_flags") == "S":
syn_counts[r["dst_ip"]] += 1
elif r.get("tcp_flags") == "SA":
synack_counts[r["dst_ip"]] += 1
alerts = []
for ip, count in syn_counts.items():
ack_count = synack_counts.get(ip, 0)
ratio = ack_count / count if count > 0 else 1.0
if count >= threshold and ratio < 0.3:
alerts.append({
"detection": "SYN Flood",
"target_ip": ip,
"syn_count": count,
"synack_count": ack_count,
"synack_ratio": round(ratio, 4),
"severity": "critical",
})
return alerts
def calculate_entropy(data):
"""Calculate Shannon entropy of a string."""
if not data:
return 0.0
freq = Counter(data)
length = len(data)
return -sum((c / length) * math.log2(c / length) for c in freq.values())
def detect_dns_tunneling(records, length_threshold=50, entropy_threshold=3.5):
"""Detect DNS tunneling via long/high-entropy query names."""
alerts = []
for r in records:
query = r.get("dns_query", "")
if not query:
continue
subdomain = query.split(".")[0] if "." in query else query
if len(subdomain) >= length_threshold or calculate_entropy(subdomain) >= entropy_threshold:
alerts.append({
"detection": "DNS Tunneling Indicator",
"query": query,
"subdomain_length": len(subdomain),
"entropy": round(calculate_entropy(subdomain), 4),
"src_ip": r["src_ip"],
"severity": "high",
})
return alerts
def detect_port_scan(records, threshold=20):
"""Detect port scanning by counting unique destination ports per source IP."""
src_ports = defaultdict(set)
for r in records:
if r.get("tcp_flags") == "S" and r.get("dst_port"):
src_ports[r["src_ip"]].add(r["dst_port"])
alerts = []
for ip, ports in src_ports.items():
if len(ports) >= threshold:
alerts.append({
"detection": "Port Scan",
"source_ip": ip,
"unique_ports_probed": len(ports),
"sample_ports": sorted(list(ports))[:20],
"severity": "high",
})
return alerts
def main():
parser = argparse.ArgumentParser(description="Network Packet Analysis Agent (Scapy)")
parser.add_argument("--pcap", required=True, help="Path to pcap/pcapng file")
parser.add_argument("--syn-threshold", type=int, default=100, help="SYN flood detection threshold")
parser.add_argument("--dns-length", type=int, default=50, help="DNS tunneling subdomain length threshold")
parser.add_argument("--scan-threshold", type=int, default=20, help="Port scan unique ports threshold")
parser.add_argument("--output", default="packet_analysis_report.json", help="Output report path")
args = parser.parse_args()
packets = load_pcap(args.pcap)
records = extract_packet_info(packets)
print(f"[+] Extracted {len(records)} IP-layer records")
stats = compute_traffic_stats(records)
syn_alerts = detect_syn_flood(records, args.syn_threshold)
dns_alerts = detect_dns_tunneling(records, args.dns_length)
scan_alerts = detect_port_scan(records, args.scan_threshold)
report = {
"analysis_time": datetime.utcnow().isoformat() + "Z",
"pcap_file": args.pcap,
"traffic_stats": stats,
"anomalies": {
"syn_flood": syn_alerts,
"dns_tunneling": dns_alerts,
"port_scan": scan_alerts,
},
"total_anomalies": len(syn_alerts) + len(dns_alerts) + len(scan_alerts),
}
with open(args.output, "w") as f:
json.dump(report, f, indent=2, default=str)
print(f"[+] SYN flood alerts: {len(syn_alerts)}")
print(f"[+] DNS tunneling indicators: {len(dns_alerts)}")
print(f"[+] Port scan detections: {len(scan_alerts)}")
print(f"[+] Report saved to {args.output}")
if __name__ == "__main__":
main()