airstream/pyshark_poc/README.md

# 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.