diff --git a/cmd/cencli/e2e/fixtures/golden/aggregate_help.out b/cmd/cencli/e2e/fixtures/golden/aggregate_help.out index 010e466..767432d 100644 --- a/cmd/cencli/e2e/fixtures/golden/aggregate_help.out +++ b/cmd/cencli/e2e/fixtures/golden/aggregate_help.out @@ -6,8 +6,8 @@ Usage: Examples: censys aggregate "host.services.protocol=SSH" "host.services.port" - censys aggregate -c "services.service_name:HTTP" "services.port" - censys aggregate "services.service_name:HTTP" "services.port" --output-format json + censys aggregate -c "host.services.protocol=HTTP" "host.location.country" + censys aggregate "host.services.protocol=HTTP" "host.location.country" --output-format json Flags: -c, --collection-id string collection to aggregate within (optional) diff --git a/cmd/cencli/e2e/fixtures/golden/search_help.out b/cmd/cencli/e2e/fixtures/golden/search_help.out index 4af8eff..dbd5541 100644 --- a/cmd/cencli/e2e/fixtures/golden/search_help.out +++ b/cmd/cencli/e2e/fixtures/golden/search_help.out @@ -6,7 +6,7 @@ Usage: Examples: censys search "host.ip: '1.1.1.1/16'" - censys search --fields host.ip,host.location "host.services: (protocol=SSH and not port: 22)" + censys search --fields host.ip,host.location.country "host.services: (protocol=SSH and not port: 22)" censys search --collection-id "host.services.protocol=SSH" censys search --page-size 50 --max-pages 5 "cert.names=censys.com" censys search --max-pages -1 "host.services.port: 443 and host.location.country: Germany" diff --git a/docs/commands/AGGREGATE.md b/docs/commands/AGGREGATE.md index 46f35f3..88a619c 100644 --- a/docs/commands/AGGREGATE.md +++ b/docs/commands/AGGREGATE.md @@ -12,7 +12,7 @@ The aggregate command takes two required arguments: ```bash $ censys aggregate "host.services.protocol=SSH" "host.services.port" # aggregate SSH services by port -$ censys aggregate "services.service_name:HTTP" "services.port" -n 10 # top 10 HTTP ports +$ censys aggregate "host.services.protocol=HTTP" "host.location.country" -n 10 # top 10 HTTP countries ``` ## Flags @@ -27,7 +27,7 @@ Aggregate within a specific collection instead of globally. **Default:** none (aggregates globally) ```bash -$ censys aggregate "services.port: 443" "services.tls.version" --collection-id 550e8400-e29b-41d4-a716-446655440000 +$ censys aggregate "host.services.port: 443" "host.location.country" --collection-id 550e8400-e29b-41d4-a716-446655440000 ``` ### `--org-id` @@ -38,7 +38,7 @@ Specify the organization ID to use for the request. This overrides the default o **Default:** Uses the configured organization ID (or the free-user wallet if not configured) ```bash -$ censys aggregate "services.port: 443" "services.tls.version" --org-id 00000000-0000-0000-0000-000000000001 +$ censys aggregate "host.services.port: 443" "host.location.country" --org-id 00000000-0000-0000-0000-000000000001 ``` ### `--num-buckets`, `-n` @@ -52,7 +52,7 @@ The number of buckets (unique values) to return in the aggregation results. This ```bash $ censys aggregate "host.services.protocol=SSH" "host.services.port" --num-buckets 10 -$ censys aggregate "services.service_name:HTTP" "services.port" -n 50 +$ censys aggregate "host.services.protocol=HTTP" "host.location.country" -n 50 ``` ### `--count-by-level`, `-l` diff --git a/docs/commands/SEARCH.md b/docs/commands/SEARCH.md index 68c8da5..8c3e2e7 100644 --- a/docs/commands/SEARCH.md +++ b/docs/commands/SEARCH.md @@ -8,8 +8,8 @@ The `search` command allows you to perform search queries across hosts, certific ```bash $ censys search "host.services: (protocol=SSH and not port: 22)" # complex query -$ censys search "services.port: 443" --fields host.ip,host.location # specify fields to return -$ censys search "services.service_name: HTTP" --max-pages -1 # fetch all pages +$ censys search "host.services.port: 443" --fields host.ip,host.location # specify fields to return +$ censys search "host.services.protocol: 'HTTP'" --max-pages -1 # fetch all pages ``` ## Query Syntax @@ -31,7 +31,7 @@ Search within a specific collection instead of globally. **Default:** none (searches globally) ```bash -$ censys search "services.port: 443" --collection-id 550e8400-e29b-41d4-a716-446655440000 +$ censys search "host.services.port: 443" --collection-id 550e8400-e29b-41d4-a716-446655440000 ``` ### `--org-id` @@ -42,7 +42,7 @@ Specify the organization ID to use for the request. This overrides the default o **Default:** Uses the configured organization ID (or the free-user wallet if not configured) ```bash -$ censys search "services.port: 443" --org-id 00000000-0000-0000-0000-000000000001 +$ censys search "host.services.port: 443" --org-id 00000000-0000-0000-0000-000000000001 ``` ### `--fields`, `-f` @@ -53,8 +53,8 @@ Specify which fields to return in the response. This allows you to filter the ou **Default:** none (returns all fields) ```bash -$ censys search "host.services: (protocol=SSH)" --fields host.ip,host.location -$ censys search "services.port: 443" -f host.ip,services.port,services.service_name +$ censys search "host.services.protocol=SSH" --fields host.ip,host.location.country +$ censys search "host.services.port: 443" -f host.services.port,host.ip,host.services.protocol ``` ### `--page-size`, `-n` @@ -66,7 +66,7 @@ The number of results to return per page. Larger page sizes reduce the number of **Minimum:** `1` ```bash -$ censys search "services.port: 443" --page-size 50 +$ censys search "host.services.port: 443" --page-size 50 ``` ### `--max-pages`, `-p` @@ -78,8 +78,8 @@ The maximum number of pages to fetch. Use `-1` to fetch all available pages. **Special Values:** `-1` fetches all pages ```bash -$ censys search "services.port: 443" --max-pages 5 -$ censys search "services.service_name: HTTP" --max-pages -1 # fetch all results +$ censys search "host.services.port: 443" --max-pages 5 +$ censys search "host.services.protocol: HTTP" --max-pages -1 # fetch all results ``` **Note:** Using `--max-pages -1` will fetch all available results, which may result in many API calls and take considerable time depending on the query. @@ -103,17 +103,17 @@ The `search` command defaults to **`json`** output format (or the global config ```bash # Default: JSON output -$ censys search "services.port: 443" +$ censys search "host.services.port: 443" # Short format: concise summary -$ censys search "services.port: 443" --output-format short -$ censys search "services.port: 443" -O short +$ censys search "host.services.port: 443" --output-format short +$ censys search "host.services.port: 443" -O short # Template format: custom Handlebars rendering -$ censys search "services.port: 443" --output-format template +$ censys search "host.services.port: 443" --output-format template # YAML output -$ censys search "services.port: 443" --output-format yaml +$ censys search "host.services.port: 443" --output-format yaml ``` For more information on customizing templates, see the [view command templates documentation](VIEW.md#templates). @@ -131,13 +131,13 @@ When using `--streaming` (or `-S`), results are **streamed immediately** as NDJS ```bash # Stream all SSH hosts to a file -$ censys search "services.port: 22" --max-pages -1 --streaming > ssh_hosts.jsonl +$ censys search "host.services.port: 22" --max-pages -1 --streaming > ssh_hosts.jsonl # Process results as they arrive using jq -$ censys search "services.port: 443" --max-pages 10 -S | jq -r '.host.ip' +$ censys search "host.services.port: 443" --max-pages 10 -S | jq -r '.host.ip' # Count results without storing them all in memory -$ censys search "services.service_name: HTTP" --max-pages -1 -S | wc -l +$ censys search "host.services.protocol: HTTP" --max-pages -1 -S | wc -l ``` ### When to Use Streaming diff --git a/docs/commands/VIEW.md b/docs/commands/VIEW.md index ccf6464..6307999 100644 --- a/docs/commands/VIEW.md +++ b/docs/commands/VIEW.md @@ -144,7 +144,7 @@ To use templates, specify `--output-format template` (or `-O template`) when run ```bash $ censys view 8.8.8.8 --output-format template $ censys view example.com:443 -O template -$ censys search "services.port: 443" -O template +$ censys search "host.services.port: 443" -O template ``` ### Customizing Templates diff --git a/internal/command/aggregate/aggregate.go b/internal/command/aggregate/aggregate.go index fb6f501..9f88548 100644 --- a/internal/command/aggregate/aggregate.go +++ b/internal/command/aggregate/aggregate.go @@ -84,8 +84,8 @@ func (c *Command) Args() command.PositionalArgs { func (c *Command) Examples() []string { return []string{ `"host.services.protocol=SSH" "host.services.port"`, - `-c "services.service_name:HTTP" "services.port"`, - `"services.service_name:HTTP" "services.port" --output-format json`, + `-c "host.services.protocol=HTTP" "host.location.country"`, + `"host.services.protocol=HTTP" "host.location.country" --output-format json`, } } diff --git a/internal/command/search/search.go b/internal/command/search/search.go index f64face..1bd8bae 100644 --- a/internal/command/search/search.go +++ b/internal/command/search/search.go @@ -97,7 +97,7 @@ func (c *Command) SupportsStreaming() bool { func (c *Command) Examples() []string { return []string{ `"host.ip: '1.1.1.1/16'"`, - `--fields host.ip,host.location "host.services: (protocol=SSH and not port: 22)"`, + `--fields host.ip,host.location.country "host.services: (protocol=SSH and not port: 22)"`, `--collection-id "host.services.protocol=SSH"`, `--page-size 50 --max-pages 5 "cert.names=censys.com"`, `--max-pages -1 "host.services.port: 443 and host.location.country: Germany"`,