{"id":49250646,"url":"https://github.com/solomonneas/bro-hunter","last_synced_at":"2026-04-25T00:03:31.009Z","repository":{"id":336925949,"uuid":"1150751092","full_name":"solomonneas/bro-hunter","owner":"solomonneas","description":"Zeek/Bro IDS log analysis and threat detection","archived":false,"fork":false,"pushed_at":"2026-04-20T22:55:39.000Z","size":749,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T00:39:01.926Z","etag":null,"topics":["blue-team","cybersecurity","detection-engineering","ids","network-security","python","security-tools","threat-hunting","zeek"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/solomonneas.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"solomonneas","ko_fi":"solomonneas","buy_me_a_coffee":"solomonneas"}},"created_at":"2026-02-05T16:41:44.000Z","updated_at":"2026-04-20T22:55:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/solomonneas/bro-hunter","commit_stats":null,"previous_names":["solomonneas/bro-hunter"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/solomonneas/bro-hunter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solomonneas%2Fbro-hunter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solomonneas%2Fbro-hunter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solomonneas%2Fbro-hunter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solomonneas%2Fbro-hunter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solomonneas","download_url":"https://codeload.github.com/solomonneas/bro-hunter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solomonneas%2Fbro-hunter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32245157,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"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":["blue-team","cybersecurity","detection-engineering","ids","network-security","python","security-tools","threat-hunting","zeek"],"created_at":"2026-04-25T00:03:28.782Z","updated_at":"2026-04-25T00:03:31.002Z","avatar_url":"https://github.com/solomonneas.png","language":"TypeScript","funding_links":["https://github.com/sponsors/solomonneas","https://ko-fi.com/solomonneas","https://buymeacoffee.com/solomonneas"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/React-18-61DAFB?style=flat-square\u0026logo=react\u0026logoColor=white\" alt=\"React\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/TypeScript-5-3178C6?style=flat-square\u0026logo=typescript\u0026logoColor=white\" alt=\"TypeScript\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Python-3.9+-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white\" alt=\"Python\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/FastAPI-0.100+-009688?style=flat-square\u0026logo=fastapi\u0026logoColor=white\" alt=\"FastAPI\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Tailwind_CSS-3-06B6D4?style=flat-square\u0026logo=tailwindcss\u0026logoColor=white\" alt=\"Tailwind CSS\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Vite-7-646CFF?style=flat-square\u0026logo=vite\u0026logoColor=white\" alt=\"Vite\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/License-MIT-green?style=flat-square\" alt=\"MIT License\" /\u003e\n\n  \u003ca href=\"https://solomonneas.dev/projects/bro-hunter\"\u003e\u003cimg src=\"https://img.shields.io/badge/Portfolio-solomonneas.dev-22c55e?style=flat-square\" alt=\"Portfolio\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# 🎯 Solomon's Bro Hunter\n\n**Hunt threats in network traffic with explainable scoring and MITRE ATT\u0026CK mapping.**\n\nBro Hunter is a threat hunting platform that processes Zeek and Suricata network logs to identify threats, score them with explainable AI, and correlate indicators across MITRE ATT\u0026CK techniques. Built for network forensics teams who need to see the evidence.\n\n![Bro Hunter](docs/screenshots/dashboard.png)\n\n---\n\n## Features\n\n- **Zeek \u0026 Suricata Log Analysis** - Parse network logs and extract threat indicators\n- **Explainable Threat Scoring** - AI-powered scores with reasoning chain included\n- **MITRE ATT\u0026CK Mapping** - Automatic technique and tactic correlation\n- **Beaconing Detection** - Identify periodic C2 communication patterns\n- **DNS Threat Analysis** - Detect DGA, tunneling, and fast-flux networks\n- **Network Forensics** - Drill into flow data, DNS queries, and SSL certificates\n- **5 Visual Themes** - Tactical, Analyst, Terminal, Command, Cyber variants\n- **Offline-First** - Works with archived logs, no live streaming required\n\n---\n\n## Quick Start\n\n```bash\n# Clone the repo\ngit clone https://github.com/solomonneas/bro-hunter.git\ncd bro-hunter\n\n# Install and run frontend\nnpm install\nnpm run dev\n\n# In another terminal, start the backend\ncd api\npip install -r requirements.txt\npython main.py\n```\n\nFrontend runs on **http://localhost:5174**\nBackend API on **http://localhost:8000**\n\n---\n\n## Tech Stack\n\n| Layer | Technology | Purpose |\n|-------|-----------|---------|\n| **Frontend** | React 18 | Interactive dashboards |\n| **Language** | TypeScript 5 | Type safety |\n| **Styling** | Tailwind CSS 3 | Utility-first CSS |\n| **Charts** | Recharts | Threat visualization and timeline graphs |\n| **Data** | TanStack Query | Async data fetching and caching |\n| **Bundler** | Vite 7 | Dev server and build |\n| **Backend** | FastAPI | REST API and log processing |\n| **Compute** | Python 3.9+ | Threat scoring algorithms |\n| **Icons** | Lucide React | Consistent icon set |\n\n---\n\n## Threat Scoring\n\nBro Hunter uses a multi-factor scoring system:\n\n1. **Indicator Confidence** - IOC reputation across sources\n2. **Behavior Match** - Pattern recognition (beaconing, tunneling, etc.)\n3. **Evidence Weight** - How much supporting data backs the score\n4. **MITRE Alignment** - Technique frequency and criticality\n\nScores range from 0 (benign) to 100 (critical threat) with a clear reasoning chain explaining each component.\n\n---\n\n## Project Structure\n\n```text\nbro-hunter/\n├── web/                      # React frontend\n│   ├── src/\n│   │   ├── components/       # Reusable UI components\n│   │   ├── pages/            # Page views (Dashboard, Threats, Analysis)\n│   │   ├── store/            # Zustand state store\n│   │   ├── utils/            # Helpers (scoring, parsing, formatting)\n│   │   └── variants/         # 5 theme variants\n│   ├── package.json\n│   └── vite.config.ts\n├── api/                      # FastAPI backend\n│   ├── main.py               # Entry point\n│   ├── parsers/              # Log parsers (Zeek, Suricata)\n│   ├── scoring/              # Threat scoring module\n│   ├── mitre/                # ATT\u0026CK correlation\n│   └── requirements.txt\n├── data/                     # Sample logs and fixtures\n└── README.md\n```\n\n---\n\n## Logs Ingestion\n\nPlace Zeek or Suricata logs in the `data/` directory and import them via the dashboard:\n\n**Zeek logs:** `conn.log`, `dns.log`, `ssl.log`, `http.log`\n**Suricata:** `eve.json` (JSON output format)\n\nThe backend parses and indexes them for fast querying.\n\n---\n\n## Rate Limiting\n\nPCAP uploads are rate-limited by default to prevent abuse on public deployments:\n\n- **5 uploads per hour** per IP\n- **15 uploads per day** per IP\n\n### Configuration\n\nControl rate limiting via environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `BROHUNTER_RATE_LIMIT_ENABLED` | `true` | Set to `false` to disable rate limiting entirely |\n| `BROHUNTER_RATE_LIMIT_HOURLY` | `5` | Max uploads per hour per IP |\n| `BROHUNTER_RATE_LIMIT_DAILY` | `15` | Max uploads per day per IP |\n\n### Self-Hosted / Cloned Deployments\n\nIf you're running Bro Hunter on your own infrastructure and don't need rate limiting:\n\n```bash\n# Disable rate limiting entirely\nexport BROHUNTER_RATE_LIMIT_ENABLED=false\n\n# Or increase the limits\nexport BROHUNTER_RATE_LIMIT_HOURLY=100\nexport BROHUNTER_RATE_LIMIT_DAILY=500\n```\n\nIn Docker / Railway, set these as environment variables in your deployment config.\n\n---\n\n## Integrations (Phase 7)\n\nBro Hunter now includes initial external integration endpoints for TheHive, Wazuh, and MISP.\n\n### Environment Variables\n\nSet these on the API service:\n\n```bash\n# TheHive\nTHEHIVE_URL=https://thehive.example.com\nTHEHIVE_API_KEY=your_thehive_api_key\nTHEHIVE_AUTH_SCHEME=Bearer\n\n# Wazuh\nWAZUH_URL=https://wazuh.example.com\nWAZUH_API_KEY=your_wazuh_api_key\nWAZUH_AUTH_SCHEME=Bearer\nWAZUH_ALERTS_PATH=/alerts\n\n# MISP\nMISP_URL=https://misp.example.com\nMISP_API_KEY=your_misp_api_key\nMISP_SEARCH_PATH=/attributes/restSearch\n```\n\n### Endpoints\n\n- `GET /api/v1/integrations/status`\n- `POST /api/v1/integrations/thehive/cases/from-case/{case_id}`\n- `POST /api/v1/integrations/wazuh/correlate/case/{case_id}?limit_per_ioc=25`\n- `POST /api/v1/integrations/misp/enrich/case/{case_id}?limit_per_ioc=25`\n\n### Example cURL\n\n```bash\n# Check integration config status\ncurl -s http://localhost:8000/api/v1/integrations/status\n\n# Export a case to TheHive\ncurl -X POST \"http://localhost:8000/api/v1/integrations/thehive/cases/from-case/\u003ccase_id\u003e\" \\\n  -H \"X-API-Key: $BROHUNTER_API_KEY\"\n\n# Correlate case IOCs with Wazuh alerts\ncurl -X POST \"http://localhost:8000/api/v1/integrations/wazuh/correlate/case/\u003ccase_id\u003e?limit_per_ioc=25\" \\\n  -H \"X-API-Key: $BROHUNTER_API_KEY\"\n\n# Enrich case IOCs from MISP\ncurl -X POST \"http://localhost:8000/api/v1/integrations/misp/enrich/case/\u003ccase_id\u003e?limit_per_ioc=25\" \\\n  -H \"X-API-Key: $BROHUNTER_API_KEY\"\n```\n\n## Live Operations API (Phase 8)\n\nReal-time log ingestion and incremental event streaming for live dashboards.\n\n### Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/v1/live/status` | Get ingest statistics and health status |\n| POST | `/api/v1/live/ingest/zeek` | Ingest Zeek JSON lines (conn, dns) |\n| POST | `/api/v1/live/ingest/suricata` | Ingest Suricata EVE JSON lines |\n| GET | `/api/v1/live/events?since=\u003ciso\u003e\u0026limit=500` | Get incremental events for auto-refresh |\n\n### Example cURL\n\n```bash\n# Check live operations status\ncurl -s http://localhost:8000/api/v1/live/status\n\n# Ingest Zeek conn.log events\ncurl -X POST \"http://localhost:8000/api/v1/live/ingest/zeek?log_type=conn\" \\\n  -H \"X-API-Key: $BROHUNTER_API_KEY\" \\\n  -H \"Content-Type: text/plain\" \\\n  -d '{\"ts\":1700000000.0,\"uid\":\"C1\",\"id_orig_h\":\"10.0.0.1\",\"id_orig_p\":12345,\"id_resp_h\":\"192.168.1.1\",\"id_resp_p\":80,\"proto\":\"tcp\",\"conn_state\":\"SF\"}'\n\n# Ingest Suricata EVE events\ncurl -X POST \"http://localhost:8000/api/v1/live/ingest/suricata\" \\\n  -H \"X-API-Key: $BROHUNTER_API_KEY\" \\\n  -H \"Content-Type: text/plain\" \\\n  -d '{\"timestamp\":\"2024-01-01T00:00:00.000Z\",\"event_type\":\"alert\",\"src_ip\":\"10.0.0.1\",\"dest_ip\":\"192.168.1.1\",\"src_port\":12345,\"dest_port\":80,\"proto\":\"TCP\",\"alert\":{\"signature\":\"Test Alert\",\"signature_id\":123,\"category\":\"test\",\"severity\":3,\"action\":\"allowed\"}}'\n\n# Get incremental events since a timestamp (for dashboard auto-refresh)\ncurl -s \"http://localhost:8000/api/v1/live/events?since=2024-01-01T00:00:00Z\u0026limit=100\" \\\n  -H \"X-API-Key: $BROHUNTER_API_KEY\"\n```\n\n## License\n\nMIT - see [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolomonneas%2Fbro-hunter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolomonneas%2Fbro-hunter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolomonneas%2Fbro-hunter/lists"}