{"id":51300804,"url":"https://github.com/osintph/falconeye","last_synced_at":"2026-06-30T19:30:55.105Z","repository":{"id":366601848,"uuid":"1276970884","full_name":"osintph/falconeye","owner":"osintph","description":"Continuous threat intelligence and vulnerability watchdog for Philippine digital infrastructure. Part of the OSINT-PH tool suite.","archived":false,"fork":false,"pushed_at":"2026-06-22T13:29:42.000Z","size":24,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-22T15:24:16.497Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/osintph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-22T13:12:54.000Z","updated_at":"2026-06-22T13:30:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/osintph/falconeye","commit_stats":null,"previous_names":["osintph/falconeye"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/osintph/falconeye","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osintph%2Ffalconeye","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osintph%2Ffalconeye/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osintph%2Ffalconeye/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osintph%2Ffalconeye/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osintph","download_url":"https://codeload.github.com/osintph/falconeye/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osintph%2Ffalconeye/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34981389,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-06-30T19:30:54.564Z","updated_at":"2026-06-30T19:30:55.098Z","avatar_url":"https://github.com/osintph.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# FalconEye\n\n**Free, self-hosted OSINT investigator's toolkit.** Twelve modules in one interface: crypto wallet tracing, phishing kit fingerprinting, domain intelligence, Telegram OSINT, IP reputation, email header forensics with LLM-powered scam detection, Google dork generation, suspicious script deobfuscation, and a curated cyber news aggregator with a Philippines-focused threat pulse.\n\nLive instance: [falconeye.osintph.info](https://falconeye.osintph.info)\n\nLicense: AGPL-3.0\n\n---\n\n## What it does\n\nFalconEye is the workbench an OSINT investigator opens when a new lead lands on the desk. Each tab is a focused tool that does one thing well and connects to the others via one-click pivots, so you can move from \"I have a wallet address\" to \"here are the related domains, the email infrastructure, the Telegram channel, and the script the phishing kit runs\" without switching applications.\n\n### The twelve tabs\n\n| Tab | What it does |\n|---|---|\n| **Home** | Landing page with PH Threat Pulse widget, example cards that prefill other tabs, and a curated news strip |\n| **Crypto Workbench** | Trace Bitcoin, Ethereum, and USDT TRC20 addresses with D3 force-directed transaction graphs and labelled clusters |\n| **Phishing Scanner** | Fingerprint phishing kits by URL or pasted HTML, identify the kit family, extract IOCs |\n| **Domain Intelligence** | RDAP, DNS, certificate transparency logs (crt.sh + Cert Spotter fallback), RIPEstat ASN data |\n| **Telegram Inspector** | Scrape public Telegram channels (t.me/s/) for messages and extract IOCs (URLs, wallets, contact details) |\n| **IP Reputation** | Shodan InternetDB, GreyNoise Community, RIPEstat, URLhaus, reverse DNS |\n| **Sandbox History** | URLhaus and MalwareBazaar lookup by URL or file hash |\n| **Email Header** | Authentication checks (SPF/DKIM/DMARC), hop analysis, scam pattern detection in body. LLM-powered classification of advance fee fraud, BEC, romance scams, crypto scams, credential phishing. Supports .eml and .msg file upload. |\n| **Dork Generator** | LLM-powered Google search query generator with eleven preset categories (exposed files, admin panels, credential leaks, cloud buckets, VPN portals, etc) and free-form natural-language input |\n| **Script Decoder** | LLM-powered deobfuscation of suspicious PowerShell, JavaScript, VBA, Base64 blobs, and packed scripts. Returns deobfuscated code, IOCs, MITRE ATT\u0026CK techniques, and detection suggestions |\n| **Contact** | Feedback form for bug reports, feature requests, and new tab suggestions |\n| **News** | Cyber news RSS aggregator with PH-specific feeds (Rappler, Inquirer, GMA, Philstar, Manila Times) and global outlets |\n\n### LLM-powered features\n\nThree tabs use Anthropic's Claude Haiku 4.5 for analysis: **Email Header**, **Dork Generator**, and **Script Decoder**. The model is hardcoded in code (not configurable, intentionally) and protected by four cost safeguards:\n\n1. Anthropic Console spend limits at the API account level\n2. Per-feature, per-IP rate limits (10 generations per 24-hour rolling window)\n3. Environment variable kill switches (`LLM_ANALYSIS_ENABLED`, `LLM_DORKGEN_ENABLED`, `LLM_DECODER_ENABLED`)\n4. Prompt caching on the system prompt (90% input cost discount on repeated calls within 5 minutes)\n\nTypical cost per LLM call: ~$0.003. The live instance runs on $5 of prepaid Anthropic credits with a $4/month hard cap.\n\n---\n\n## Privacy posture\n\nFalconEye does not maintain user accounts and stores only short-lived caches keyed by content hash, not by user identity.\n\n- Input you submit is processed to produce analysis results\n- Results are cached for 24 hours by SHA256 hash of the input\n- The raw input itself is not persisted beyond the moments needed to process it\n- Uploaded .eml and .msg files are parsed in memory and discarded immediately\n- Source IP is stored only for rate-limit enforcement, with automatic cleanup after 48 hours\n- No cookies set by FalconEye (Cloudflare may set its own for security)\n- No third-party advertising or analytics\n- Full privacy policy accessible from the footer link on every tab\n\nWhen you use the LLM-powered tabs, your input is sent to Anthropic's API. See [Anthropic's privacy policy](https://www.anthropic.com/legal/privacy). At time of writing, Anthropic does not use API input to train their models by default.\n\n---\n\n## Stack\n\n- **Backend**: Python 3.11+, FastAPI, Uvicorn, Gunicorn\n- **Database**: SQLite with WAL mode (for caching and rate limits only, no user data)\n- **Frontend**: Tailwind CSS via CDN, vanilla JavaScript, D3.js for graph visualizations\n- **Web server**: nginx with Cloudflare Origin Certificate\n- **CDN / DDoS**: Cloudflare (Free tier, with Cache Rules for static assets)\n- **LLM**: Anthropic Claude Haiku 4.5 via the official Python SDK\n- **Security**: CrowdSec community blocklist + firewall bouncer, fail2ban, ufw, SSH on non-standard port with keys-only auth\n\nMemory footprint at idle: ~120 MB RAM. Disk: ~50 MB for code + ~20 MB SQLite cache that auto-trims.\n\n---\n\n## Self-hosting\n\n### Prerequisites\n\n- Ubuntu 22.04 / 24.04 VPS (1 vCPU, 1 GB RAM minimum, 2 GB recommended)\n- A domain name pointed at the VPS\n- Python 3.11+\n- Optional: Cloudflare account for TLS and DDoS protection\n- Optional: Anthropic API key if you want the LLM-powered tabs to work (free tier of FalconEye runs fine without)\n\n### Install\n\n```bash\n# 1. Clone\nsudo mkdir -p /opt/falconeye\nsudo chown $USER:$USER /opt/falconeye\ncd /opt/falconeye\ngit clone https://github.com/osintph/falconeye.git app_src\ncd app_src\n\n# 2. Create venv and install deps\npython3 -m venv /opt/falconeye/venv\n/opt/falconeye/venv/bin/pip install -r requirements.txt\n\n# 3. Configure environment\ncp .env.example /opt/falconeye/.env\nvi /opt/falconeye/.env\n# Set ANTHROPIC_API_KEY if you want LLM tabs to work\n# Set SHODAN_API_KEY, GREYNOISE_API_KEY for IP Reputation (free tiers available)\n# Set ABUSECH_AUTH_KEY for Sandbox History (free at abuse.ch)\nchmod 600 /opt/falconeye/.env\n\n# 4. Initialize the database\n/opt/falconeye/venv/bin/python -c \"from app.main import app; print('DB ready')\"\n\n# 5. Install systemd unit (sample provided in deploy/)\nsudo cp deploy/falconeye.service /etc/systemd/system/\nsudo systemctl daemon-reload\nsudo systemctl enable --now falconeye\n\n# 6. nginx vhost (sample in deploy/)\nsudo cp deploy/falconeye.nginx /etc/nginx/sites-available/falconeye\nsudo ln -s /etc/nginx/sites-available/falconeye /etc/nginx/sites-enabled/\nsudo nginx -t \u0026\u0026 sudo systemctl reload nginx\n```\n\n### Required API keys\n\nAll free tiers are sufficient for personal use.\n\n| Service | Used by | Get a key |\n|---|---|---|\n| **Anthropic** | Email Header (LLM), Dork Gen, Script Decoder | https://console.anthropic.com |\n| **Shodan** | IP Reputation, Phishing Scanner | https://account.shodan.io |\n| **GreyNoise** | IP Reputation | https://viz.greynoise.io/account |\n| **abuse.ch (URLhaus/MalwareBazaar)** | Sandbox History, IP Reputation | https://auth.abuse.ch |\n\nIf you do not provide a key, the relevant tab degrades gracefully (returns \"API key not configured\" without crashing).\n\n### Optional but recommended\n\n- **CrowdSec** for community-driven IP blocklists (`curl -s https://install.crowdsec.net | sudo sh`)\n- **GoAccess** for nginx log analytics\n- **fail2ban** for SSH brute-force protection\n- **Cloudflare** in front for TLS, DDoS protection, and edge caching\n\n---\n\n## API endpoints\n\nAll endpoints accept JSON POST. Rate limits noted where applicable.\n\n| Endpoint | Method | Rate limit |\n|---|---|---|\n| `/api/crypto/lookup` | POST | None (relies on upstream provider quotas) |\n| `/api/scanner/scan` | POST | None |\n| `/api/domain/intel` | POST | None |\n| `/api/telegram/inspect` | POST | None |\n| `/api/ip/reputation` | POST | None |\n| `/api/sandbox/lookup` | POST | None |\n| `/api/email-header/analyze` | POST | LLM body analysis: 10/IP/24h |\n| `/api/email-header/upload` | POST | None |\n| `/api/dork-generator/generate` | POST | 10/IP/24h |\n| `/api/script-decoder/decode` | POST | 10/IP/24h |\n| `/api/news/feed` | GET | None |\n| `/api/threat-pulse` | GET | None |\n\n---\n\n## Development\n\n```bash\ncd app_src\n/opt/falconeye/venv/bin/uvicorn app.main:app --reload --host 127.0.0.1 --port 8000\n```\n\nThen point your browser at http://127.0.0.1:8000/. Hot reload picks up Python and static file changes automatically.\n\n### Project structure\n\n```\napp_src/\n├── app/\n│   ├── main.py              # FastAPI entrypoint, router registration\n│   ├── config.py            # Environment variable loading\n│   ├── routers/             # One file per tab\n│   │   ├── crypto.py\n│   │   ├── scanner.py\n│   │   ├── domain_intel.py\n│   │   ├── telegram_inspector.py\n│   │   ├── ip_intel.py\n│   │   ├── sandbox.py\n│   │   ├── email_header.py\n│   │   ├── dork_generator.py\n│   │   ├── script_decoder.py\n│   │   ├── news.py\n│   │   └── threat_pulse.py\n│   └── static/\n│       ├── index.html       # Single-page app shell\n│       ├── app.js           # All client-side logic\n│       ├── style.css\n│       ├── favicon.svg\n│       ├── robots.txt\n│       └── sitemap.xml\n├── deploy/                  # Sample systemd unit, nginx vhost\n├── requirements.txt\n├── .env.example\n├── LICENSE\n├── CONTRIBUTING.md\n└── README.md\n```\n\n### Adding a new tab\n\n1. Create `app/routers/your_tab.py` with a FastAPI router\n2. Register it in `app/main.py`\n3. Add the tab button and content section in `app/static/index.html`\n4. Add the JS handler in `app/static/app.js`\n5. Add `'your_tab'` to the `VALID_TABS` array for hash routing\n6. Update this README's tab table and the sitemap\n\nIf your tab uses an LLM, copy the safeguard pattern from `script_decoder.py`: hardcoded model constant, per-feature rate-limit table, environment kill switch, prompt caching, defensive JSON parsing.\n\n---\n\n## Roadmap\n\nThings on the list but not yet built. Pull requests welcome.\n\n- IoC enrichment pipeline (one URL in, full report from all tabs out)\n- Hash-based artifact deduplication across investigation history\n- Maltego transform export for the crypto graph\n- Public API tokens for trusted integrations (with proper rate limits)\n- Webhook support for News and Threat Pulse subscriptions\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\nBug reports, feature requests, and new tab suggestions go to the [Contact tab](https://falconeye.osintph.info/#contact) on the live site or as a GitHub issue.\n\n---\n\n## License\n\nAGPL-3.0. Strong copyleft. If you run a modified version as a network service, you must offer the source code of your modified version to the users of that service. See [LICENSE](LICENSE) for the full text.\n\n---\n\n## Acknowledgments\n\nFalconEye builds on the work of many open services and tools, all linked from the footer of the live site:\n\n- abuse.ch (URLhaus, MalwareBazaar)\n- Shodan, GreyNoise (IP intelligence)\n- crt.sh, Cert Spotter (certificate transparency)\n- RDAP.org (RDAP queries)\n- RIPEstat (ASN data)\n- Blockstream, BlockCypher, TronGrid (blockchain APIs)\n- Anthropic Claude Haiku 4.5 (LLM analysis)\n- D3.js (graph visualization)\n- Tailwind CSS (styling)\n\nBuilt and maintained by [OSINT-PH](https://blog.osintph.info).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosintph%2Ffalconeye","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosintph%2Ffalconeye","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosintph%2Ffalconeye/lists"}