---
phase: 12-osint_iot_cloud_storage
plan: 01
subsystem: recon
tags: [shodan, censys, zoomeye, iot, device-search, osint]

# Dependency graph
requires:
  - phase: 10-osint-code-hosting
    provides: ReconSource interface, shared Client, BuildQueries, LimiterRegistry
provides:
  - ShodanSource implementing recon.ReconSource
  - CensysSource implementing recon.ReconSource
  - ZoomEyeSource implementing recon.ReconSource
affects: [12-osint_iot_cloud_storage, recon-registration]

# Tech tracking
tech-stack:
  added: []
  patterns: [IoT device scanner source pattern with API key/header auth]

key-files:
  created:
    - pkg/recon/sources/shodan.go
    - pkg/recon/sources/censys.go
    - pkg/recon/sources/zoomeye.go
    - pkg/recon/sources/shodan_test.go
    - pkg/recon/sources/censys_test.go
    - pkg/recon/sources/zoomeye_test.go
  modified: []

key-decisions:
  - "Shodan, Censys, ZoomEye use bare keyword queries (default formatQuery case) -- no special syntax needed"
  - "Censys uses POST with JSON body + Basic Auth; Shodan/ZoomEye use GET with key param/header"

patterns-established:
  - "IoT scanner source pattern: GET/POST to device search API, parse JSON matches, emit Finding per hit"

requirements-completed: [RECON-IOT-01, RECON-IOT-02, RECON-IOT-03]

# Metrics
duration: 3min
completed: 2026-04-06
---

# Phase 12 Plan 01: Shodan, Censys, ZoomEye IoT Scanner Sources Summary

**Three IoT device scanner recon sources searching Shodan host/search, Censys v2 hosts/search, and ZoomEye host/search for exposed LLM endpoints**

## Performance

- **Duration:** 3 min
- **Started:** 2026-04-06T09:21:40Z
- **Completed:** 2026-04-06T09:24:28Z
- **Tasks:** 2
- **Files modified:** 6

## Accomplishments
- ShodanSource queries /shodan/host/search with API key param, emits findings per IP:port match
- CensysSource POSTs to /v2/hosts/search with Basic Auth (APIId:APISecret), emits findings per host hit
- ZoomEyeSource queries /host/search with API-KEY header, emits findings per IP:port match
- All three sources disabled when credentials empty, use shared retry Client, respect LimiterRegistry

## Task Commits

Each task was committed atomically:

1. **Task 1: Implement ShodanSource, CensysSource, ZoomEyeSource** - `f5d8470` (feat)
2. **Task 2: Unit tests for Shodan, Censys, ZoomEye sources** - `6443e63` (test)

## Files Created/Modified
- `pkg/recon/sources/shodan.go` - ShodanSource with /shodan/host/search API integration
- `pkg/recon/sources/censys.go` - CensysSource with POST /v2/hosts/search + Basic Auth
- `pkg/recon/sources/zoomeye.go` - ZoomEyeSource with /host/search + API-KEY header
- `pkg/recon/sources/shodan_test.go` - 4 tests: enabled, empty key, sweep findings, ctx cancel
- `pkg/recon/sources/censys_test.go` - 4 tests: enabled, empty creds, sweep findings, ctx cancel
- `pkg/recon/sources/zoomeye_test.go` - 4 tests: enabled, empty key, sweep findings, ctx cancel

## Decisions Made
- Shodan, Censys, ZoomEye use bare keyword queries (default formatQuery case) -- no queries.go changes needed
- Censys uses POST with JSON body and Basic Auth; Shodan uses API key as query param; ZoomEye uses API-KEY header

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered
None

## User Setup Required
None - no external service configuration required.

## Next Phase Readiness
- Three IoT scanner sources ready for RegisterAll wiring in Plan 12-04
- Same pattern applies to remaining Phase 12 sources (FOFA, Netlas, BinaryEdge)

---
*Phase: 12-osint_iot_cloud_storage*
*Completed: 2026-04-06*