{"id":28524497,"url":"https://github.com/alexhraber/flowhawk","last_synced_at":"2026-03-12T16:10:51.989Z","repository":{"id":298059007,"uuid":"998709365","full_name":"alexhraber/flowhawk","owner":"alexhraber","description":"Real-time eBPF-powered network security monitor with AI-driven threat detection. Surfaces port scans, DDoS attacks, botnet activity, and anomalies at 100Gbps+ speeds with sub-microsecond latency (~150 million packets/sec).","archived":false,"fork":false,"pushed_at":"2025-08-18T14:07:51.000Z","size":194,"stargazers_count":45,"open_issues_count":1,"forks_count":6,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-18T16:07:58.731Z","etag":null,"topics":["anomaly-detection","cybersecurity","ddos-protection","ebpf","golang","intrusion-detection","machine-learning","network-analysis","network-security","packet-processing","real-time-monitoring","threat-detection","xdp","zero-day-detection"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alexhraber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-09T06:00:08.000Z","updated_at":"2025-08-18T14:03:21.000Z","dependencies_parsed_at":"2025-06-09T07:44:27.795Z","dependency_job_id":null,"html_url":"https://github.com/alexhraber/flowhawk","commit_stats":null,"previous_names":["alexhraber/flowhawk"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/alexhraber/flowhawk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexhraber%2Fflowhawk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexhraber%2Fflowhawk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexhraber%2Fflowhawk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexhraber%2Fflowhawk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexhraber","download_url":"https://codeload.github.com/alexhraber/flowhawk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexhraber%2Fflowhawk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30431881,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-12T14:34:45.044Z","status":"ssl_error","status_checked_at":"2026-03-12T14:09:33.793Z","response_time":114,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anomaly-detection","cybersecurity","ddos-protection","ebpf","golang","intrusion-detection","machine-learning","network-analysis","network-security","packet-processing","real-time-monitoring","threat-detection","xdp","zero-day-detection"],"created_at":"2025-06-09T11:00:37.170Z","updated_at":"2026-03-12T16:10:51.955Z","avatar_url":"https://github.com/alexhraber.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FlowHawk\n\n```text\n ███████ ██       ██████  ██     ██ ██   ██  █████  ██     ██ ██   ██ \n ██      ██      ██    ██ ██     ██ ██   ██ ██   ██ ██     ██ ██  ██  \n █████   ██      ██    ██ ██  █  ██ ███████ ███████ ██  █  ██ █████   \n ██      ██      ██    ██ ██ ███ ██ ██   ██ ██   ██ ██ ███ ██ ██  ██  \n ██      ███████  ██████   ███ ███  ██   ██ ██   ██  ███ ███  ██   ██ \n\n          🦅 eBPF-POWERED NETWORK SECURITY MONITOR 🦅\n```\n\n## Modern Network Security Platform\n\n**FlowHawk** is a **modern open-source eBPF-powered Network Security Monitoring Platform** engineered for mission-critical infrastructure protection. Leveraging advanced kernel-space packet processing and machine learning threat detection, FlowHawk delivers unparalleled visibility into network traffic patterns and security anomalies.\n\n\u003e **\"Strike fast, see everything. FlowHawk soars above your network, detecting threats with the precision of a hunting raptor.\"**\n\n### Core Technology Stack\n\n- **🔥 eBPF Kernel Integration**: Zero-copy packet processing at wire speed\n- **⚡ XDP High-Performance Path**: Sub-microsecond latency packet analysis\n- **🧠 Machine Learning Engine**: Adaptive behavioral anomaly detection\n- **🌐 Cross-Platform Compatibility**: Universal Unix deployment via containerization\n\n![License](https://img.shields.io/badge/license-MIT-blue.svg)\n![Go Version](https://img.shields.io/badge/go-1.23+-blue.svg)\n![Platform](https://img.shields.io/badge/platform-Unix%20%7C%20macOS%20%7C%20Linux-green.svg)\n![eBPF](https://img.shields.io/badge/eBPF-enabled-orange.svg)\n\n## What Makes FlowHawk Special\n\n**FlowHawk** combines the **keen eyesight of a hunting hawk** with **eBPF's lightning-fast packet processing** to deliver unparalleled network security monitoring.\n\n### Lightning Speed\n\n- **10M+ packets per second** processing capability\n- **Sub-microsecond latency** with XDP (eXpress Data Path)\n- **Zero-copy** packet analysis directly in kernel space\n\n### Eagle-Eyed Detection\n\n- **Multi-engine threat detection** (rule-based + ML)\n- **Real-time anomaly scoring** with adaptive thresholds\n- **Custom rule engine** with flexible pattern matching\n\n### Precision Hunting\n\n- **Port scan detection** (rapid, stealth, horizontal)\n- **DDoS attack identification** (volumetric + amplification)\n- **Botnet activity tracking** (C2 beaconing patterns)\n- **Data exfiltration monitoring** (traffic anomalies)\n\n## Quick Start\n\n### Prerequisites\n\n- **Unix-based Operating System**: Linux, macOS, FreeBSD, or other Unix variants\n- **Containerization**: Docker or compatible container runtime\n- **Go 1.23+** (for source builds)\n- **eBPF Support**: Modern kernel with eBPF capabilities (Linux 4.15+, or containerized deployment)\n\n### Hunt Begins\n\nBuild FlowHawk\n```bash\ndocker build -t flowhawk:latest .\n```\n\n## Security Modes\n\nFlowHawk operates in two distinct hunting modes:\n\n### 🟢 **Training Mode** (Recommended)\n*Safe for development and demonstrations*\n\nLaunch in training mode (safe, simulated data) and access the eyrie (dashboard)\n```bash\ndocker run -d \\\n  --name flowhawk \\\n  -p 8080:8080 \\\n  -e SKIP_ROOT_CHECK=1 \\\n  flowhawk:latest\n\nopen http://localhost:8080\n```\n\n**Training Mode Features:**\n- ✅ **Safe**: No system privileges required\n- ✅ **Isolated**: Cannot affect host system  \n- ✅ **Functional**: Complete UI/API testing\n- ✅ **Realistic**: Dynamic simulated data\n- ⚠️ **Limited**: No real network monitoring\n\n---\n\n### 🔴 **Hunt Mode** - ⚠️ **SECURITY RISKS**\n\n\u003e **🚨 WARNING: Hunt mode enables real eBPF with significant security implications!**\n\u003e\n\u003e **Before unleashing the hawk, understand these risks:**\n\u003e\n\u003e 1. **🔥 Kernel-Level Access**: Direct kernel memory access\n\u003e    - Risk: System crashes or kernel panics\n\u003e    - Risk: Access to sensitive kernel data\n\u003e\n\u003e 2. **👁️ Total Network Visibility**: Sees ALL host traffic\n\u003e    - Risk: Exposure to passwords, API keys, private data\n\u003e    - Risk: Privacy violations and data interception\n\u003e\n\u003e 3. **🔓 Container Escape**: Privileged mode = near-root access\n\u003e    - Risk: Host filesystem access and kernel module loading\n\u003e    - Risk: Breaking container isolation barriers\n\u003e\n\u003e 4. **💥 Resource Exhaustion**: Unlimited consumption potential\n\u003e    - Risk: Memory exhaustion from BPF map growth\n\u003e    - Risk: CPU spikes from processing loops\n\u003e\n\u003e **Only unleash hunt mode if:**\n\u003e - You fully understand and accept these security risks\n\u003e - You have implemented appropriate security mitigations\n\u003e - You need real network monitoring (not just testing)\n\u003e - You're running in a controlled, isolated environment\n\n⚠️ SECURITY WARNING: Unleash the hawk responsibly! ⚠️\n```bash\ndocker run -d \\\n  --name flowhawk \\\n  --privileged \\\n  --user root \\\n  -p 8080:8080 \\\n  flowhawk:latest\n```\n\n**Hunt Mode Features:**\n- ✅ **Real Monitoring**: Actual network traffic analysis\n- ✅ **Full eBPF**: Complete high-performance capabilities\n- ⚠️ **High Risk**: Significant security implications\n- ⚠️ **Privileged**: Requires root and privileged container\n\n## 🔐 Security Mitigations\n\nIf you must use hunt mode, implement these hawk-training measures:\n\n### Minimal Privileges\nUse specific capabilities instead of --privileged\n```bash\ndocker run -d \\\n  --name flowhawk \\\n  --cap-add=BPF \\\n  --cap-add=NET_ADMIN \\\n  --cap-add=SYS_ADMIN \\\n  --cap-drop=ALL \\\n  --read-only \\\n  --tmpfs /tmp \\\n  --device=/dev/bpf \\\n  -p 8080:8080 \\\n  flowhawk:latest\n```\n\n### Resource Constraints\nLimit the hawk's appetite\n```bash\ndocker run -d \\\n  --name flowhawk \\\n  --memory=512m \\\n  --cpus=1.0 \\\n  --pids-limit=100 \\\n  # ... other security flags\n```\n\n## ⚙️ Configuration\n\n### Basic Hunt Configuration\n\n```yaml\n# Network interface and eBPF settings\nebpf:\n  xdp:\n    interface: \"eth0\"\n    mode: \"native\"  # native, skb, hw\n    enable: true\n  tc:\n    direction: \"both\"  # ingress, egress, both\n    enable: true\n\n# Monitoring parameters\nmonitoring:\n  sampling_rate: 1000      # 1 in N packets\n  flow_timeout: 300s       # Flow expiration\n  max_flows: 1000000       # Memory limit\n\n# Threat detection configuration\nthreats:\n  enable: true\n  port_scan:\n    enable: true\n    threshold: 100         # connections per minute\n  ddos:\n    enable: true\n    pps_threshold: 100000  # packets per second\n    bps_threshold: 1000000000  # 1 Gbps\n\n# Alert configuration\nalerts:\n  enable: true\n  webhook_url: \"https://hooks.slack.com/...\"\n  severity_threshold: \"medium\"\n\n# Dashboard settings\ndashboard:\n  listen_addr: \":8080\"\n  enable_auth: false\n  retention_days: 7\n```\n\n## 🎯 Real-World Hunt Examples\n\n### Port Scan Detection\n```bash\n# FlowHawk spots scanning patterns instantly:\n\n2024-01-15 10:30:15 THREAT: Port Scan from 192.168.1.100\n- Pattern: Rapid scanning (127 ports in 30s)\n- Severity: High\n- Targets: 192.168.1.10\n```\n\n### DDoS Attack Detection\n```bash\n# Volumetric attack spotted:\n2024-01-15 11:15:33 THREAT: DDoS Attack targeting 192.168.1.10\n- Type: Distributed attack (1.2M PPS from 500 sources)\n- Severity: Critical\n- Protocol: UDP (DNS amplification)\n```\n\n### ML Anomaly Detection\n```bash\n# Behavioral anomaly detected:\n2024-01-15 12:20:45 THREAT: ML Anomaly from 10.0.1.25\n- Anomaly score: 4.7 (threshold: 2.5)\n- Pattern: Unusual packet sizes and timing\n- Confidence: 89%\n```\n\n## 📊 Performance Metrics\n\n### Hunt Statistics\n- **XDP Native Mode**: 10M+ PPS on modern hardware\n- **Memory Usage**: \u003c100MB userspace footprint  \n- **CPU Overhead**: \u003c5% at 1Gbps sustained traffic\n- **Latency**: \u003c1μs packet processing time\n\n### Scalability\n- **Flow Tracking**: 1M+ concurrent flows\n- **Threat Detection**: Real-time analysis up to 10Gbps\n- **Dashboard**: 1000+ concurrent WebSocket connections\n\n## 🛠️ Development\n\n### Developer Setup\n\nFlowHawk includes comprehensive CI/CD workflows and development tools:\n\nSet up development environment (includes git hooks)\n```bash\nmake dev-setup\n```\n\nRun tests\n```bash\nmake test\n```\n\nRun all tests including integration\n```bash\nmake test-all\n```\n\nRun tests with coverage\n```bash\nmake test-coverage\n```\n\nRun linting\n```bash\nmake lint\n```\n\nFormat code\n```bash\nmake format\n```\n\n### Git Hooks\n\nFlowHawk includes pre-commit hooks that automatically:\n- Format Go code with `gofmt`\n- Run `go vet` for static analysis\n- Execute linting with `golangci-lint`\n- Run the full test suite\n- Check for common issues (debug statements, large files)\n\nTo set up git hooks:\nInitialize git repository (if not done)\n```bash\ngit init\n```\n\nSet up git hooks\n```bash\n./scripts/setup-git-hooks.sh\n```\n\nOr use make target\n```bash\nmake dev-setup\n```\n\n### CI/CD Workflows\n\nFlowHawk includes GitHub Actions workflows for:\n\n- **Continuous Integration** (`.github/workflows/ci.yml`)\n  - Multi-version Go testing (1.23+)\n  - Linting with golangci-lint\n  - Security scanning with Gosec and Trivy\n  - Code coverage reporting to Codecov\n  - Docker build verification\n\n- **Release Management** (`.github/workflows/release.yml`)\n  - Automated binary builds for multiple platforms\n  - Docker image publishing to GitHub Container Registry\n  - GitHub Releases with checksums\n\n- **Dependency Management** (`.github/workflows/dependabot-automerge.yml`)\n  - Automated dependency updates via Dependabot\n  - Auto-merge for minor/patch updates after testing\n\n### Testing Strategy\n\nFlowHawk follows a comprehensive testing approach:\n\n- **Unit Tests**: Located in `tests/unit/` with package-specific subdirectories\n- **Integration Tests**: End-to-end testing of major components\n- **Benchmark Tests**: Performance validation for critical paths\n- **Security Tests**: Vulnerability scanning and secure coding validation\n\nCoverage targets:\n- Overall: 80%+ statement coverage\n- Core packages: 90%+ statement coverage\n- Critical security components: 95%+ statement coverage\n\n### Building from Source\nPrepare the env\n```bash\ngo mod download\n```\n\nBuild the image\n```bash\ngo build -o flowhawk ./cmd/flowhawk\n```\n\nRelease the hawk\n```bash\nsudo ./flowhawk -config ./configs/development.yaml\n```\n\n### Hunt Commands\nShow version\n```bash\nflowhawk -version\n```\n\nCustom interface\n```bash\nflowhawk -interface eth1\n```\n\nCustom config\n```bash\nflowhawk -config /etc/flowhawk/config.yaml\n```\n\n## 🌐 Dashboard Access\n\n**Open your browser to: http://localhost:8080**\n\n### Features:\n- **🔴 Live threat feed** - Real-time security alerts\n- **📊 Network flow analysis** - Traffic patterns and statistics  \n- **⚡ Performance metrics** - System health monitoring\n- **🎯 Threat timeline** - Historical attack analysis\n- **🔍 Flow search** - Drill down into specific connections\n\n## 🦅 The FlowHawk Philosophy\n\n*\"A hawk doesn't just see movement - it sees patterns, predicts behavior, and strikes with precision. FlowHawk brings this same predatory intelligence to network security.\"*\n\n- **🎯 Precision**: Every packet matters, every threat is tracked\n- **⚡ Speed**: Strike before threats can establish themselves  \n- **👁️ Vision**: See the entire network landscape from above\n- **🧠 Intelligence**: Learn, adapt, and improve over time\n\n## 🤝 Contributing\n\nWe welcome fellow hunters! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Development Roadmap\n- [ ] IPv6 support\n- [ ] Hardware timestamping\n- [ ] GPU-accelerated ML inference\n- [ ] Multi-node cluster deployment\n- [ ] Mobile app for alerts\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- **eBPF Community** - For the incredible eBPF ecosystem\n- **Cilium Project** - For excellent Go eBPF libraries\n- **Linux Kernel Developers** - For making eBPF possible\n- **Security Researchers** - For threat intelligence and patterns\n\n## 📞 Support \u0026 Community\n\n- **🏠 Home**: [FlowHawk Documentation](docs/)\n- **🐛 Issues**: [GitHub Issues](https://github.com/alexhraber/flowhawk/issues)  \n- **💬 Discussions**: [GitHub Discussions](https://github.com/alexhraber/flowhawk/discussions)\n- **🔒 Security**: alexhraber@gmail.com\n\n---\n\n**🦅 Built with the precision of a hunting hawk and the power of eBPF**\n\n*Hunt wisely. Monitor precisely. Strike swiftly.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexhraber%2Fflowhawk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexhraber%2Fflowhawk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexhraber%2Fflowhawk/lists"}