first working

2025-08-03 20:20:55 -04:00
commit cde56494ec
52 changed files with 1893 additions and 0 deletions
--- a/pyshark_poc/README.md
+++ b/pyshark_poc/README.md
@@ -0,0 +1,146 @@
+# PyShark Proof of Concept for Airstream
+
+This is an alternative implementation of Airstream using PyShark instead of Scapy. PyShark leverages Wireshark's powerful dissector engine for comprehensive protocol support.
+
+## Key Advantages
+
+### 1. **Full Wireshark Protocol Support**
+- Automatically uses ALL installed Wireshark dissectors
+- Supports 2000+ protocols out of the box
+- Better decoding for complex protocols (PTP, IENA, Chapter 10)
+
+### 2. **Custom Dissector Support**
+- Any Lua dissector installed in Wireshark works automatically
+- See `lua_dissectors/` for examples
+- No code changes needed to support new protocols
+
+### 3. **Advanced Filtering**
+- Full Wireshark display filter syntax
+- BPF capture filters for performance
+- Protocol-specific field access
+
+## Installation
+
+```bash
+# Install PyShark (requires tshark/Wireshark)
+pip install pyshark
+
+# On macOS
+brew install wireshark
+
+# On Ubuntu/Debian
+sudo apt-get install tshark
+
+# On RHEL/CentOS
+sudo yum install wireshark
+```
+
+## Usage
+
+```bash
+# Basic PCAP analysis
+./airstream_pyshark.py -p capture.pcap
+
+# Live capture with filter
+./airstream_pyshark.py -i eth0 -c 1000 --filter "tcp.port==443"
+
+# Use BPF filter for efficient capture
+./airstream_pyshark.py -i eth0 --bpf "port 80 or port 443"
+
+# Export results to CSV
+./airstream_pyshark.py -p capture.pcap -o results.csv
+
+# Use PTP-specific statistics
+./airstream_pyshark.py -p ptp_traffic.pcap -s ptp
+```
+
+## Architecture
+
+```
+airstream_pyshark.py         # Main entry point (CLI)
+pyshark_poc/
+├── __init__.py             # Package initialization
+├── analyzer.py             # PySharkAnalyzer class
+├── models.py               # Data models (FlowKey)
+├── stats.py                # Statistics classes
+└── README.md               # This file
+
+lua_dissectors/             # Custom Wireshark dissectors
+├── example_custom_protocol.lua
+└── README.md
+```
+
+## Performance Comparison
+
+| Aspect | Scapy | PyShark |
+|--------|-------|---------|
+| Packet Parsing Speed | Faster | Slower (XML overhead) |
+| Protocol Support | Limited | Comprehensive |
+| Custom Dissectors | Python only | Lua + C |
+| Memory Usage | Lower | Higher |
+| Dependencies | Python only | Requires tshark |
+
+## When to Use PyShark
+
+✅ **Use PyShark when:**
+- You need comprehensive protocol decoding
+- Working with proprietary protocols
+- Need Wireshark's advanced filtering
+- Protocol accuracy is critical
+
+❌ **Use Scapy when:**
+- Performance is critical
+- Need packet crafting/modification
+- Minimal dependencies required
+- Simple protocol analysis
+
+## Custom Protocol Support
+
+To add custom protocol support:
+
+1. Create a Lua dissector (see `lua_dissectors/example_custom_protocol.lua`)
+2. Install in Wireshark plugins directory
+3. PyShark automatically uses it
+
+Example accessing custom fields:
+```python
+# After installing custom dissector
+capture = pyshark.FileCapture('custom_protocol.pcap')
+for packet in capture:
+    if hasattr(packet, 'custom'):
+        print(f"Message type: {packet.custom.msg_type}")
+        print(f"Sequence: {packet.custom.sequence}")
+```
+
+## Limitations
+
+1. **Performance**: Slower than Scapy due to XML parsing overhead
+2. **Dependencies**: Requires Wireshark/tshark installation
+3. **Read-only**: Cannot modify or craft packets
+4. **Platform-specific**: tshark paths may vary
+
+## Future Enhancements
+
+- [ ] Parallel packet processing
+- [ ] Caching for improved performance
+- [ ] Integration with existing frametypes
+- [ ] Protocol-specific analyzers
+- [ ] Real-time streaming analysis
+- [ ] Custom field extractors
+
+## Testing
+
+```bash
+# Test with sample PCAP
+./airstream_pyshark.py -p "1 PTPGM.pcapng"
+
+# List available interfaces
+./airstream_pyshark.py -l
+
+# Verbose mode for debugging
+./airstream_pyshark.py -p capture.pcap -v
+```
+
+## Conclusion
+
+This PyShark implementation provides a powerful alternative when comprehensive protocol support is needed. While it trades performance for functionality, it enables analysis of complex protocols that would be difficult to implement in pure Python.