How 1hehaq/shef works
shef is a single-binary Go CLI tool that lets a user query Shodan “facet” aggregations from the terminal without an API key, returning pipe-friendly stdout (optionally JSON). It’s effectively:
• Terminal user → shef (local process) → Shodan website (public facet endpoint) → parsed facets → stdout
• No persistent storage, no server component, no DB.
• “Integrates” with other tools primarily via Unix pipelines (httpx, amass, klik, yazi, etc.), but those are downstream consumers, not dependencies.
Runtime architecture (user ↔ binary ↔ Shodan)
2) Build/Release architecture (developer/CI ↔ GitHub Actions ↔ Go toolchain ↔ release artifacts)
User / Terminal
• Invokes shef with flags
• Consumes stdout (interactive or piped)
shef CLI binary (Go process)
• Argument/Flag Parser
• Handles -q (required), -f (default ip), -list, -json, -h
• Facet Registry / Facet List Provider
• Returns all supported facet types for -list
• Also supports shell autocomplete (complete -W "$(shef -list)" shef)
• Query Builder
• Encodes Shodan query string + facet parameter(s)
• Produces the final URL(s) to fetch
• User-Agent Rotator
• Selects a random UA per request (and possibly sets headers)
• HTTP Client / Transport
• Performs GET requests to Shodan
• Handles timeouts, redirects, non-200 responses, transient failures
• Response Parser
• Parses the returned content (likely HTML/embedded JSON; confirm via code/deps)
• Extracts the facet buckets/values (ip/domain/port/asn/vuln/etc.)
• Output Renderer
• “clean and pipe friendly output”
• Text mode: one value per line (likely)
• JSON mode: structured output to stdout (-json)
• Error Handling / Exit Codes
• Missing -q, no results, network errors, parse errors
External Service: Shodan Web
• The facet search endpoint(s) on shodan.io
• e.g., httpx, amass, asnmap, klik, yazi
Developer
• Pushes tags / commits
GitHub Actions (Release Workflow)
• Runs Go build
• Produces binaries / checksums / GitHub Release artifacts (depending on workflow)
End User installation
• go install github.com/1hehaq/shef@latest (Go module proxy + build on user machine)
• Optionally GitHub Releases download (if workflow publishes binaries)
Architectural patterns/design principles present (and how to show them)
• CLI-first, Unix philosophy
• “stdin/stdout oriented”, composable with pipes
• Stateless execution
• No DB, no caching (unless code shows otherwise)
• Adapter pattern to external web service
• shef acts as a thin adapter between “user query” and “Shodan facet UI responses”
• Separation of concerns (logical)
Labels
• “CLI args”
• “HTTP GET /search/facet?...”
• “HTML response (facet table)”
• “Extracted facet values”
• “stdout lines / JSON”
• Exact flags in the CLI boundary (-q, -f, -list, -json)
Directionality
• Request → Response
• Parse → Render
• shef → stdout