{"id":51300799,"url":"https://github.com/osintph/bantay-eye","last_synced_at":"2026-06-30T19:30:52.542Z","repository":{"id":365845368,"uuid":"1274031998","full_name":"osintph/bantay-eye","owner":"osintph","description":"Defensive internet exposure survey utility. Part of the OSINT-PH tool suite.","archived":false,"fork":false,"pushed_at":"2026-06-19T05:49:08.000Z","size":31,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-19T07:26:24.618Z","etag":null,"topics":["attack-surface","attack-surface-management","censys","cli","osint","osint-ph","osintph","phillipines","python","responsible-disclosure","shodan","zoomeye"],"latest_commit_sha":null,"homepage":"https://www.osintph.info","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","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-19T05:44:56.000Z","updated_at":"2026-06-19T05:55:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/osintph/bantay-eye","commit_stats":null,"previous_names":["osintph/bantay-eye"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/osintph/bantay-eye","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osintph%2Fbantay-eye","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osintph%2Fbantay-eye/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osintph%2Fbantay-eye/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osintph%2Fbantay-eye/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/osintph","download_url":"https://codeload.github.com/osintph/bantay-eye/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/osintph%2Fbantay-eye/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":["attack-surface","attack-surface-management","censys","cli","osint","osint-ph","osintph","phillipines","python","responsible-disclosure","shodan","zoomeye"],"created_at":"2026-06-30T19:30:52.434Z","updated_at":"2026-06-30T19:30:52.532Z","avatar_url":"https://github.com/osintph.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bantay-Eye\n\n\u003e Defensive internet exposure survey utility. Part of the [OSINT-PH](https://blog.osintph.info) tool suite.\n\nBantay-Eye runs the [Operation Liwanag](https://blog.osintph.info) methodology end-to-end: it queries Shodan, Censys, and ZoomEye for a country's exposed attack surface across seven categories, deduplicates findings across engines, flags likely honeypots, and generates ready-to-send disclosure templates for NCERT-PH, the asset owner, and the National Privacy Commission.\n\nIt does not include exploit code, does not connect to discovered devices, and does not enumerate targets in any way beyond what the three upstream search engines already index publicly.\n\n`Bantay` is Tagalog for \"watch\" or \"guard\". `Eye` is a deliberate nod to [HackingPassion's](https://hackingpassion.com) \"Eye\" suite, on whose practitioner-first publishing style this tool's documentation is modelled.\n\n## What it does\n\n- **Seven categories of exposure**: ICS/SCADA, government, remote access, telecom, banking (reserved), IoT, and cloud-hosted misconfigurations.\n- **Three engines, one query layer**: every query is expressed for all three engines using the validated syntax for each (Shodan, Censys Search v2 with `host.` prefix, ZoomEye REST with quoted values and `\u0026\u0026`).\n- **Cross-engine deduplication**: findings on the same `(ip, port, category)` are merged into one record with the union of sources.\n- **Honeypot annotation**: Shodan's own `honeypot` tag, ASN matching against known commercial cloud honeypot ranges, and single-engine observation are surfaced as signals.\n- **Polite rate limiting**: configurable per-engine minimum delay between calls so you do not torch your free-tier quotas.\n- **Disclosure templates**: Jinja-rendered NCERT-PH, owner-direct, and NPC notification templates pre-filled from finding data.\n- **JSON output**: every survey writes a structured report you can diff between runs.\n\n## What it does not do\n\n- It does not connect to discovered devices.\n- It does not query device registers, attempt authentication, or trigger any service.\n- It does not include CVE lookups, exploit code, or vulnerability proof-of-concepts.\n- It does not enumerate targets by name. The country filter and category queries are the only selectors.\n\nThe intent is captured in the LICENSE file: a defensive survey utility for responsible disclosure work. Use it for that.\n\n## Requirements\n\n- Python 3.10 or newer\n- API access to at least one of the three search engines\n\n### API tiers, with prices\n\n| Engine | Free-tier viability | What you actually need |\n| --- | --- | --- |\n| **Shodan** | Limited. The truly free tier restricts searches significantly. | A one-time **Membership** purchase (~$59 USD, often discounted to ~$5 during Black Friday) gives 100 result pages per query, 10,000 result credits per month, and is the practical \"working tier\" for survey work. Tag filters (`tag:ics`, etc.) require enterprise and are not used by Bantay-Eye for that reason. |\n| **Censys** | Genuinely free. | A free account gives 250 search queries per month, sufficient for several full Bantay-Eye runs. Sign up at [search.censys.io](https://search.censys.io). |\n| **ZoomEye** | Genuinely free. | A free account gives ~10,000 query points per month. Sign up at [zoomeye.org](https://zoomeye.org). |\n\nYou can run Bantay-Eye with any subset of engines configured; engines without credentials are skipped silently. Recommended minimum: Censys + ZoomEye, which are both truly free.\n\n## Installation\n\n### Option A: pipx (recommended for end users)\n\n```\npipx install git+https://github.com/osintph/bantay-eye.git\n```\n\n### Option B: pip in a virtualenv (recommended for development)\n\n```\ngit clone https://github.com/osintph/bantay-eye.git\ncd bantay-eye\npython3 -m venv .venv\nsource .venv/bin/activate\npip install -e .\n```\n\n### Option C: direct install from GitHub\n\n```\npip install --user git+https://github.com/osintph/bantay-eye.git\n```\n\n## Quickstart\n\n```\n# 1. Create a starter config in the current directory\nbantay-eye init\n\n# 2. Edit bantay_eye.toml and add your API keys\nvi bantay_eye.toml\n\n# 3. Verify your installation and credentials\nbantay-eye doctor\n\n# 4. List available categories\nbantay-eye categories\n\n# 5. Run a survey of all categories with queries defined\nbantay-eye survey --all\n\n# 6. Or run a single category, e.g. ICS\nbantay-eye survey --category ics\n\n# 7. Generate a disclosure template for one finding\nbantay-eye disclose 203.0.113.42-502-ics \\\n    --report findings/survey-20260617T093000.json \\\n    --template ncert \\\n    --output disclosures/ncert-203.0.113.42.md\n```\n\n## Configuration\n\nBantay-Eye looks for `bantay_eye.toml` in this order:\n\n1. The path passed to `--config`.\n2. `./bantay_eye.toml` in the current working directory.\n3. The platform user-config directory (run `bantay-eye config-path` to see).\n\nRun `bantay-eye init --location user` to drop a starter config in the user-config directory if you prefer system-wide settings.\n\nSee `bantay_eye.toml.example` for every available knob.\n\n## Country support\n\nThe default country is the Philippines (`PH`). The tool is country-agnostic and ships with name mappings for the rest of ASEAN, the major East-Asian economies, Australia, New Zealand, the US, and the UK. Add new countries to `COUNTRY_NAMES` in `src/bantay_eye/categories.py` and they immediately work across all three engines.\n\n## Output structure\n\n```\nfindings/\n├── survey-20260617T093000.json    # full survey report\ndisclosures/\n├── ncert-203.0.113.42.md          # rendered disclosure templates\n├── owner-198.51.100.7.md\n└── npc-198.51.100.7.md\n```\n\n## Methodology\n\nThe seven categories and their queries are described in detail in the Operation Liwanag post on [blog.osintph.info](https://blog.osintph.info). Read that first; this tool is the operationalisation of that essay, not a replacement for understanding why the queries are what they are.\n\n## Contributing\n\nPull requests welcome on:\n\n- New country mappings\n- New categories of exposure (the schema is open; add to `categories.py`)\n- Better honeypot heuristics\n- Translations of the disclosure templates (Filipino, Bahasa Indonesia, Vietnamese welcome)\n- ASN mappings for new commercial cloud providers\n\nPull requests will be declined for:\n\n- Anything that adds active connection to discovered devices\n- Vulnerability scanning, fingerprinting, or fuzzing\n- Credential enumeration\n- Anything that makes this useful as an offensive tool\n\n## License\n\nMIT, with an ethical-use notice. See LICENSE.\n\n## Acknowledgements\n\n- The [Shodan](https://shodan.io), [Censys](https://censys.io), and [ZoomEye](https://zoomeye.org) teams for the underlying data.\n- [HackingPassion](https://hackingpassion.com) for the documentation style and the practitioner-first publishing tradition.\n- NCERT-PH for accepting disclosures even when they cannot publicly acknowledge them.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosintph%2Fbantay-eye","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fosintph%2Fbantay-eye","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fosintph%2Fbantay-eye/lists"}