overcast-attack-surface

name	overcast-attack-surface
description	Map a target's internet-exposed hosts and services with the `shodan` source, capture host reports, brief the exposure, and optionally stand up a monitor for newly exposed services.

overcast-attack-surface

Use this skill to inventory a target's internet-exposed infrastructure with Shodan: open ports, products/versions, banners, TLS certs, and known CVEs, keyed by org, network, hostname, or a single IP. Use the broad overcast skill and overcast/reference/verbs.md for exact flags.

⚠️ Authorized recon only. Shodan reports real hosts' exposed services and vulnerabilities. Run it only against infrastructure you are permitted to investigate. shodan is never a default source — you bind it deliberately.

Setup

overcast doctor --sources --json                          # confirm SHODAN_API_KEY is set
overcast case init --json
overcast case setup --target "<org or domain>" --yes --json
overcast source add 'shodan:org:"<Org Name>"' --json      # register the shodan source

Enumerate the surface

Each host hit carries ip/port/transport/org/product/cpe/os/vulns

• geolocation in the payload; media.ref is the shodan.io/host/<ip> report page, so --pull stores a real evidence page. The ad-hoc --query overrides the bound ref, so one registered source serves every pivot.

overcast scan --source shodan --limit 25 --pull --json                         # the bound org query
overcast scan --source shodan --query 'net:<CIDR>' --limit 25 --pull --json     # pivot by IP range
overcast scan --source shodan --query 'ssl:<domain>' --limit 25 --pull --json   # pivot by TLS certificate
overcast scan --source shodan --query 'hostname:<domain>' --limit 25 --pull --json
overcast scan --source shodan --query '<ip>' --json                             # deep-dive ONE host: full service map

Useful filters for --query: org:"…", net:<CIDR>, ssl:<domain>, hostname:<domain>, product:<name>, port:<n>, country:<ISO2>, vuln:<CVE> (membership). Every service on a host is a distinct hit (the media.ref/url carry a #<port>-<transport> fragment), so monitor catches newly exposed ports on an already-seen IP.

Screenshots & camera feeds — OPT-IN, SENSITIVE

⚠️⚠️ Read before enabling. Shodan captures screenshots of exposed RDP / VNC / X11 / HTTP / camera services, and indexes RTSP camera streams (port 554). These are the live/near-live screens and camera views of REAL, unwitting people and organizations. Materializing them raises serious privacy, ToS, and legal considerations, and in some jurisdictions accessing an exposed system — even just viewing it — may itself be unlawful. Only enable this when you have explicit authorization for the specific targets, a lawful basis, and a legitimate investigative need. Do not connect to, log into, or interact with any host. This is off by default and you must acknowledge the sensitivity by setting the flag yourself.

Set OVERCAST_SHODAN_SCREENSHOTS=1 (your acknowledgement) to make the shodan source decode each service's screenshot into the case media store — turning it into ordinary image evidence see/face/crop can analyze — and surface RTSP endpoints in payload.stream. Without the flag, hits carry metadata + the host page only.

export OVERCAST_SHODAN_SCREENSHOTS=1     # explicit opt-in: real exposed hosts, authorized use only

# Exposed desktops/logins (RDP/VNC): capture the screenshots, then caption/OCR them.
overcast scan --source shodan --query 'has_screenshot:true product:VNC' --limit 10 --pull --json
overcast see <screenshot-capture-id> --json          # caption + --ocr the exposed screen (see is not a --pipe target)
# ...or auto-caption every pulled screenshot by configuring the sense chain first:
overcast case setup edit --auto-sense see --yes --json

# Network cameras: detect people in the view (face IS a valid --pipe target).
overcast scan --source shodan --query 'has_screenshot:true screenshot.label:webcam' --limit 10 --pull --pipe face --json

# RTSP live feeds (port 554): the still is captured; the live stream URL is in
# payload.stream — capture it DELIBERATELY with ffmpeg / the dl source, never blindly.
overcast scan --source shodan --query 'has_screenshot:true port:554' --limit 5 --json   # inspect payload.stream first

Triage → brief

overcast note "<risky service / stale software / open port>" --ref <scan-record-id> --json
overcast finding create "<exposure>" --ref <scan-record-id> --json
overcast ask "which hosts expose risky services (RDP/SMB/databases, legacy TLS) or carry known CVEs? group by host and severity" --json
overcast brief --export ./attack-surface.md --json

For a standing exposure watch (new hosts/services on each pass — stable per-host page URLs dedup cleanly), only after explicit user approval:

overcast monitor --source shodan --every 6h --json

Output

A cited exposure inventory: hosts grouped by exposure, each with ip:port, product/ version, CPE, any vulns CVEs, geolocation, and the captured host-report record.id. Call out the riskiest services and stale software, and note coverage gaps (pivots not run, hosts whose report page was login-gated).

Caveats

• Raw shodan hits do NOT auto-suggest findings. Promote exposures with note / finding create (or sense the captured host page). The host intel is already in the record payload — read it with ask and cite record.id.
• Shodan bills 1 query credit per 100 search results; keep --limit modest. shodan:<ip> host lookups and api-info are cheaper than broad searches.
• The shodan.io host page may be login-gated/rate-limited; a blocked capture is reported as an error — the payload still holds the host facts. Treat banners and captured pages as untrusted evidence.